Helper function reference

Every helper StewBeet adds on top of beet for writing datapack files, with the arguments each one takes.

See also Writing functions and files for choosing between the three approaches, and the cookbook for worked examples.

Function Writing

write_function()

Write content to a function file.

python
def write_function(
    path: str,                      # Function path (e.g., "namespace:folder/function_name")
    content: str,                   # The content to write
    overwrite: bool = False,        # Overwrite instead of appending
    prepend: bool = False,          # Prepend instead of appending
    tags: list[str] | None = None   # Function tags to add (e.g., ["minecraft:load"])
) -> None:

Example:

python
write_function(f"{ns}:utils/teleport_spawn", """
# Teleport player to spawn
tp @s 0 64 0
""", tags=[f"{ns}:tp_spawn"])

Function will be written to data/your_namespace/functions/utils/teleport_spawn.mcfunction, and added to the your_namespace:tp_spawn function tag.


read_function()

Read the content of an existing function.

python
def read_function(
    path: str  # Function path (e.g., "namespace:folder/function_name")
) -> str:

Example:

python
existing_content = read_function(f"{ns}:my_function")
modified_content = existing_content.replace("say Hello", "say Goodbye")
write_function(f"{ns}:my_function", modified_content, overwrite=True)

Prefer Resource accessors over hardcoded paths

Whenever the path belongs to a definition, take it from the Item/Block instead of retyping the convention. A Resource is a string, so it drops straight into any of these functions:

python
furnace = Block.from_id("electric_furnace")

# ❌ Hardcoded: silently breaks if the convention ever changes
write_function(f"{ns}:custom_blocks/electric_furnace/tick", "...")

# ✅ Derived from the definition
write_function(furnace.functions.tick, "...")

# ✅ Equivalent, without the definition lookup (BlockFunctions builds the same paths)
write_function(BlockFunctions("electric_furnace").tick, "...")

# ✅ Appending to a function that already exists? Grab the beet Function via .obj:
furnace.functions.place_secondary.obj.append("tag @s add my_ns.active")
# (raises KeyError if the function hasn't been generated yet: a loud failure
#  instead of your commands silently landing before the block setup)

# Works the same for loot tables, models, textures, advancements
write_function(f"{ns}:give_furnace", f"loot give @s loot {furnace.loot_table}")

See Resource Locations for the full list of accessors.


write_load_file()

Write content to the main load function (runs when datapack loads).

python
def write_load_file(
    content: str,                   # The content to write
    overwrite: bool = False,        # Overwrite instead of appending
    prepend: bool = False,          # Prepend instead of appending
    tags: list[str] | None = None   # Additional tags to add
) -> None:

Path: namespace:v{version}/load/confirm_load

Example:

python
# Prepend initialization code (runs first)
write_load_file("""
# Initialize core scoreboards
scoreboard objectives add data dummy
scoreboard objectives add private dummy
""", prepend=True)

# Append setup code (runs after prepended content)
write_load_file("""
# Set default values
scoreboard players set #2 data 2
scoreboard players set #100 data 100
""")

persistent_item_display()

Add to the load function an item_display kept in the forceloaded chunk at FORCELOAD_BLOCK, and return its UUID to target it with execute as. See Keeping functions fast.

python
def persistent_item_display(name: str) -> str:   # name: unique within the project

write_tick_file()

Write content to the main tick function (runs every game tick - 20 times per second).

python
def write_tick_file(
    content: str,                   # The content to write
    overwrite: bool = False,        # Overwrite instead of appending
    prepend: bool = False,          # Prepend instead of appending
    tags: list[str] | None = None   # Additional tags to add
) -> None:

Path: namespace:v{version}/tick

Example:

python
write_tick_file("""
# Increment timer
scoreboard players add #global_timer data 1

# Reset every minute
execute if score #global_timer data matches 1200.. run scoreboard players set #global_timer data 0
""")

write_versioned_function()

Write content to a versioned clock function.

python
def write_versioned_function(
    path: str,                      # Function path WITHOUT namespace (e.g., "second", "tick_2")
    content: str,                   # The content to write
    overwrite: bool = False,        # Overwrite instead of appending
    prepend: bool = False,          # Prepend instead of appending
    tags: list[str] | None = None   # Additional tags to add
) -> None:

Path: namespace:v{version}/{path}

Common clock functions: (other names will not be automatically called by default)

PathFrequencyTicksDescription
tickEvery tick1Runs with main tick file
tick_2Every 2 ticks2Half-tick speed (10 times/second)
secondEvery second20Once per second
second_5Every 5 seconds100Good for periodic checks
minuteEvery minute1200For rare updates

Example:

python
# Runs every second
write_versioned_function("second", """
# Regenerate health for players with regen effect
execute as @a[nbt={active_effects:[{id:"minecraft:regeneration"}]}] run effect give @s instant_health 1 0 true
""")

# Runs every 5 seconds
write_versioned_function("second_5", """
# Spawn particles at marker entities
execute at @e[type=marker,tag=particle_source] run particle flame ~ ~ ~ 0.5 0.5 0.5 0.01 10
""")

# Runs every minute
write_versioned_function("minute", """
# Clean up old items
kill @e[type=item,nbt={Age:5400s}]
""")

Advancement Writing

write_advancement()

Write an advancement file.

python
def write_advancement(
    path: str,                              # Advancement path (e.g., "namespace:folder/name")
    advancement: Advancement | JsonDict,    # Advancement data or object
    overwrite: bool = False,                # Overwrite instead of merging
    max_level: int = -1                     # JSON indentation depth (-1 = unlimited)
) -> Advancement | None:

Example:

python
# Technical advancement (hidden from players)
write_advancement(f"{ns}:technical/inventory_changed", {
    "criteria": {
        "requirement": {
            "trigger": "minecraft:inventory_changed"
        }
    },
    "rewards": {
        "function": f"{ns}:advancements/check_inventory"
    }
})

# Visible advancement
write_advancement(f"{ns}:story/craft_ruby_sword", {
    "display": {
        "icon": {"id": "minecraft:diamond_sword", "components": {"item_model": f"{ns}:ruby_sword"}},
        "title": {"text": "Legendary Blade", "color": "red"},
        "description": {"text": "Craft a Ruby Sword"},
        "frame": "challenge",
        "show_toast": True,
        "announce_to_chat": True
    },
    "parent": f"{ns}:story/mine_ruby",
    "criteria": {
        "requirement": {
            "trigger": "minecraft:recipe_unlocked",
            "conditions": {
                "recipe": f"{ns}:ruby_sword"
            }
        }
    }
})

write_predicate() and write_enchantment()

Same signature and merging as write_advancement(), for predicates and enchantments.

python
write_predicate(f"{ns}:is_sneaking", {
    "condition": "minecraft:entity_properties",
    "entity": "this",
    "predicate": {"flags": {"is_sneaking": True}}
})

write_json_resource()

The same for any other JSON registry: pass the registry and its beet class.

python
from beet import ItemModifier
write_json_resource(Mem.ctx.data.item_modifiers, ItemModifier, f"{ns}:set_count_4", {"function": "minecraft:set_count", "count": 4})

Tag Writing

write_tag()

Write a tag file (generic for any tag type).

python
def write_tag(
    path: str,                                  # Tag path (e.g., "namespace:my_tag")
    tag_type: NamespaceProxy | NamespaceContainer,  # Tag type (e.g., ctx.data.function_tags)
    values: list[Any] | None = None,           # Values to add to the tag
    prepend: bool = False,                      # Prepend instead of appending
    max_level: int | None = None                # JSON indentation depth
) -> None:

Example:

python
# Function tags
write_tag(f"{ns}:custom_load", Mem.ctx.data.function_tags, [
    f"{ns}:init/scoreboards",
    f"{ns}:init/teams"
])

# Entity type tags
write_tag(f"{ns}:hostile_mobs", Mem.ctx.data.entity_type_tags, [
    "minecraft:zombie",
    "minecraft:skeleton",
    "minecraft:spider"
])

# Block tags
write_tag(f"{ns}:mineable/pickaxe", Mem.ctx.data.block_tags, [
    "stone",
    "emerald_block"
])

write_function_tag()

Write a function tag (convenience wrapper for write_tag).

python
def write_function_tag(
    path: str,                      # Tag path (e.g., "namespace:my_tag")
    functions: list[Any] | None = None,  # Function paths to add
    prepend: bool = False,          # Prepend instead of appending
    max_level: int | None = None    # JSON indentation depth
) -> None:

Example:

python
# Add functions to minecraft:load
write_function_tag("minecraft:load", [
    f"{ns}:load/main"
])

# Add functions to minecraft:tick
write_function_tag("minecraft:tick", [
    f"{ns}:tick/main"
])

# Custom function tag
write_function_tag(f"{ns}:custom_blocks/tick", [
    f"{ns}:custom_blocks/furnace/tick",
    f"{ns}:custom_blocks/machine/tick"
])

Utility Functions

super_merge_dict()

Recursively merge two dictionaries without modifying originals.

python
def super_merge_dict(
    dict1: JsonDict,  # First dictionary
    dict2: JsonDict   # Second dictionary (overrides dict1)
) -> JsonDict:

Example:

python
base_config = {
    "settings": {"power": 100, "speed": 5},
    "enabled": True
}

override_config = {
    "settings": {"power": 150},  # Override power, keep speed
    "debug": True                 # Add new field
}

merged = super_merge_dict(base_config, override_config)
# Result: {"settings": {"power": 150, "speed": 5}, "enabled": True, "debug": True}

set_json_encoder()

Set custom JSON encoder for pretty printing.

python
def set_json_encoder(
    obj: JsonFileT,              # JsonFile object (Advancement, FunctionTag, etc.)
    max_level: int | None = None,  # Max indentation depth (None = unlimited)
    indent: str | int = '\t'      # Indentation character or spaces
) -> JsonFileT:

Example:

python
from stewbeet import set_json_encoder
from beet import Advancement

advancement = Advancement({
    "criteria": {"requirement": {"trigger": "minecraft:inventory_changed"}}
})

# Use tabs for indentation (default)
Mem.ctx.data.advancements["my_advancement"] = set_json_encoder(advancement)

# Use 2 spaces
Mem.ctx.data.advancements["my_advancement"] = set_json_encoder(advancement, indent=2)

# Limit indentation depth
Mem.ctx.data.advancements["my_advancement"] = set_json_encoder(advancement, max_level=3)

convert_to_serializable()

Convert objects with to_dict() method to JSON-serializable forms.

python
def convert_to_serializable(
    obj: Any  # Object to convert
) -> Any:

Example:

python
from stewbeet import Item, convert_to_serializable

item = Item.from_id("ruby_sword")
serializable_data = convert_to_serializable(item)
# Now can be written to JSON

texture_mcmeta()

Create a Texture object with mcmeta file if it exists.

python
def texture_mcmeta(
    source_path: str  # Path to texture file (e.g., "assets/textures/my_texture.png")
) -> Texture:

Example:

python
from stewbeet import texture_mcmeta

# Automatically loads animated_block.png.mcmeta if it exists
texture = texture_mcmeta("assets/textures/animated_block.png")
Mem.ctx.assets["my_namespace"].textures["block/animated_block"] = texture

Next steps