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.
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:
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.
def read_function(
path: str # Function path (e.g., "namespace:folder/function_name")
) -> str:Example:
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:
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).
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:
# 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.
def persistent_item_display(name: str) -> str: # name: unique within the projectwrite_tick_file()
Write content to the main tick function (runs every game tick - 20 times per second).
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:
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.
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)
| Path | Frequency | Ticks | Description |
|---|---|---|---|
tick | Every tick | 1 | Runs with main tick file |
tick_2 | Every 2 ticks | 2 | Half-tick speed (10 times/second) |
second | Every second | 20 | Once per second |
second_5 | Every 5 seconds | 100 | Good for periodic checks |
minute | Every minute | 1200 | For rare updates |
Example:
# 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.
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:
# 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.
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.
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).
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:
# 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).
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:
# 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.
def super_merge_dict(
dict1: JsonDict, # First dictionary
dict2: JsonDict # Second dictionary (overrides dict1)
) -> JsonDict:Example:
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.
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:
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.
def convert_to_serializable(
obj: Any # Object to convert
) -> Any:Example:
from stewbeet import Item, convert_to_serializable
item = Item.from_id("ruby_sword")
serializable_data = convert_to_serializable(item)
# Now can be written to JSONtexture_mcmeta()
Create a Texture object with mcmeta file if it exists.
def texture_mcmeta(
source_path: str # Path to texture file (e.g., "assets/textures/my_texture.png")
) -> Texture:Example:
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"] = textureNext steps
- Writing functions and files: which approach to reach for, and why.
- Cookbook. These helpers used in complete, working files.
- Equations: build scoreboard arithmetic to embed in what you write.