Writing functions and files
Four ways to put your own functions, advancements and tags into the pack: static files loaded by beet.yml, the native beet API, StewBeet's helper functions, and Bolt. Most packs use the helpers for their logic and static files for the rest.
Your code runs in a user plugin, after the definitions are set up and before finalisation.
Write all of this with the commands checked as you type. Every approach below ends with commands inside a Python string, inside a
.boltmodule, or both. The StewBeet extension for VSCode reads them as what they are: completion, errors, ctrl+click, and a link from each block to the function your build wrote from it. See Editor support.
Complete files to read alongside this page:
- extensive/src/link.py, the template
- SimplEnergy/src/utils/machines.py, a published pack
- StardustFragment/src/utils/remaining.py, a published pack
Which approach to use
| Approach | Best for | Effort |
|---|---|---|
Static files (beet.yml) | Hand-written functions and JSON that never change | Lowest |
| Native beet API | Unusual file types, full control over every object | Highest |
| StewBeet helpers (recommended) | Logic generated from your definitions, load and clock functions | Low |
| Bolt | Command-heavy logic, loops and arithmetic around commands | Medium, a second language |
Approach 1: Static File Loading (beet.yml)
Beet loads hand-written files from a folder before any plugin runs.
# In beet.yml
data_pack:
name: "datapack"
load: ["src"] # Loads all .mcfunction and .json files from src/
resource_pack:
name: resource_pack
load: ["src"] # Loads all texture, model, and sound files from src/How it works:
- Place
.mcfunctionfiles insrc/data/<namespace>/function/ - Place
.jsonfiles insrc/data/<namespace>/advancement/,src/data/<namespace>/recipe/, etc. - Beet automatically loads them into the correct pack locations
- Files are loaded before any plugin code runs
Example structure:
src/
├── data/
│ └── my_namespace/
│ ├── function/
│ │ ├── load.mcfunction
│ │ └── tick.mcfunction
│ ├── advancement/
│ │ └── my_advancement.json
│ └── recipe/
│ └── my_recipe.json
└── assets/
└── my_namespace/
└── textures/
└── item/
└── my_item.png| Folder | Holds |
|---|---|
data/ | All datapack content: functions, advancements, recipes, tags |
function/ | Minecraft commands, as .mcfunction files |
advancement/ | Achievements and technical triggers, as .json |
recipe/ | Crafting, smelting and other recipes, as .json |
assets/ | All resource pack content: textures, models, sounds |
textures/ | PNG images for items, blocks and the rest |
Use it when:
- You have static files that don't need dynamic generation
- You're organizing pre-written commands and data
- You want simple, straightforward file structure
Avoid it when:
- You need to generate content based on definitions
- You need to combine multiple sources of data
- You need conditional file generation
Approach 2: Native Beet API
Beet's own object API, used directly from a plugin.
from beet import Context, Function, Advancement, FunctionTag
from stouputils.typing import JsonDict
def beet_default(ctx: Context):
# Writing a function
ctx.data["my_namespace"].functions["my_folder/my_function"] = Function("""
# This is my function
say Hello World!
scoreboard players add @a points 1
""")
# Writing an advancement
advancement_data: JsonDict = {
"criteria": {
"requirement": {
"trigger": "minecraft:inventory_changed"
}
},
"rewards": {
"function": "my_namespace:rewards/give_item"
}
}
ctx.data["my_namespace"].advancements["my_advancement"] = Advancement(advancement_data)
# Writing a function tag
tag_data: JsonDict = {
"values": [
"my_namespace:my_folder/my_function",
"my_namespace:another_function"
]
}
ctx.data["my_namespace"].function_tags["minecraft:load"] = FunctionTag(tag_data)Use it when:
- You need full control over file objects
- You're working with complex nested structures
- You want type safety with beet's object model
Avoid it when:
- You want simple, quick file writes
- You're dealing with many small functions
- You need automatic path handling
Approach 3: StewBeet Helper Functions (Recommended)
StewBeet helpers take a path and a string, create the file or add to it, and know where the load, tick and clock functions live.
from stewbeet import write_function, write_load_file, write_tick_file, Mem
def beet_default(ctx: Context):
ns = ctx.project_id
# Write a simple function
write_function(f"{ns}:my_folder/my_function", """
# This is my function
say Hello World!
scoreboard players add @a points 1
""")
# Append to load file (runs when datapack loads: "your_namespace:v{version}/load/confirm_load")
write_load_file("""
# Initialize scoreboards
scoreboard objectives add points dummy
scoreboard objectives add data dummy
""")
# Append to tick file (runs every game tick: "your_namespace:v{version}/tick")
write_tick_file("""
# Check for players with high scores
execute as @a[scores={points=100..}] run function my_namespace:rewards/high_score
""")
# Write versioned functions (automatic clock: "your_namespace:v{version}/second", etc.)
write_versioned_function("second", """
# Runs every second (20 ticks)
execute as @a run title @s actionbar {"score":{"name":"@s","objective":"points"}}
""")
write_versioned_function("minute", """
# Runs every minute (1200 ticks)
say One minute has passed!
""")Use it when:
- You want simple, readable code
- You need automatic path management
- You're using StewBeet's conventions (versioned functions, load/tick files)
- You want to append/prepend content easily
Avoid it when:
- You need non-standard file organization
- You're not using StewBeet framework
Approach 4: Bolt
Bolt is mecha's scripting layer, and it inverts the three approaches above.
Instead of Python writing a string that happens to hold commands, the commands are the syntax: in a .bolt file, item = 3 is Python and item modify entity @s weapon.mainhand set value ... is a command, at the same indentation, in the same scope.
All of it runs at build time. Nothing Python reaches the datapack.
# In beet.yml
require:
- "stewbeet"
- "bolt"
pipeline:
- "mecha" # bolt needs mecha to compile what it produced
meta:
bolt:
entrypoint: "*" # let any function file use bolt, not only modulesTwo kinds of file:
- Modules,
.boltunderdata/<namespace>/module/. Importable, and they write a function only where they ask for one. - Function files,
.mcfunctioncovered byentrypoint. The file is one function, written in bolt.
Writing a function
# src/data/voltaic/module/gui.bolt
MACHINES = ["pulverizer", "furnace", "smelter"]
for machine in MACHINES:
function f"voltaic:gui/{machine}/open":
playsound minecraft:block.barrel.open block @s ~ ~ ~ 0.6 1.4
data modify entity @s equipment.head set from storage voltaic:gui Icon
tag @s add voltaic.watchingThree functions out of one loop. The f-string is the path, and the indented block is the body.
A path is a value like any other, so it can be named, imported and passed around. Two shorthands keep the namespace out of it:
| Written | Resolves to |
|---|---|
./load | <namespace>:<module path>/load |
~/init | A child of the function being written at that point |
SERVER_LOAD = ./load
prepend function_tag minecraft:load {"values": [SERVER_LOAD]}
function SERVER_LOAD:
forceload add 0 0
scoreboard objectives add voltaic.energy dummyNesting and implicit execute
An execute that ends in a colon writes its own function and the call that reaches it:
execute as @a[tag=voltaic.using] at @s:
particle minecraft:electric_spark ~ ~1 ~
playsound minecraft:block.beacon.ambient block @s ~ ~ ~ 0.4 2.0Conditions read as conditions, with if, else and the run return shapes folded in:
if score @s voltaic.energy matches 1..:
scoreboard players remove @s voltaic.energy 1
else:
function voltaic:machines/shutdownAdding to a function another module owns
from voltaic:core import SERVER_LOAD
append function SERVER_LOAD:
team add builder "Builder"
team modify builder color blackfunction, append function and prepend function are the three ways a module contributes to a path.
Several modules can append to the same load function without knowing about each other, which is what makes one file per feature work.
It is Python, so the whole language is there
Imports take a resource location where Python takes a dotted path:
from lib:helpers import ticks # a module in another namespace
from ./items import team_flag # a sibling module
from dataclasses import dataclass # plain Python, from your environment
from functools import cacheClasses and decorators work, and a method can write functions:
from functools import cached_property
class Gui:
""" One machine's interface, opened by right clicking it. """
def __init__(self, machine):
self.path = f"voltaic:gui/{machine}"
@cached_property
def open(self):
function f"{self.path}/open":
playsound minecraft:block.barrel.open block @s ~ ~ ~ 0.6 1.4
tag @s add voltaic.watching
return f"{self.path}/open"
gui = Gui("pulverizer")
function voltaic:gui/pulverizer/tick:
execute as @a[tag=voltaic.using] run function gui.opencached_property is doing real work there: the function is written the first time something asks for its path, and never twice.
JSON files are literals, with Python values dropped straight into them:
ON_KILL = ./on_kill
advancement ON_KILL {
"criteria": {"kill": {"trigger": "minecraft:player_killed_entity"}},
"rewards": {"function": ON_KILL}
}
function ON_KILL:
advancement revoke @s only ON_KILLScoreboards and storage as variables
bolt_expressions (pip install bolt-expressions, then add it to require) turns arithmetic into the commands that perform it:
from bolt_expressions import Scoreboard, Data
Energy = Scoreboard("voltaic.energy")
Temp = Data.storage("voltaic:temp")
Energy["@s"] -= 20
Energy["#total"] = Energy["@s"] * 3 + Energy["#buffer"]
Temp.display.text = Energy["#total"]Each line compiles to the scoreboard players operation sequence it needs, temporaries included.
It is the same job as Equations on the StewBeet side, expressed in the file that uses it.
Bolt and StewBeet in the same pack
Nothing forces a choice. A pack can declare its items with Item(...), let the plugins generate recipes and the manual, write most of its logic with write_function, and keep one .bolt module for the part where the commands are the hard bit.
The demo pack the extension records its showcases from is exactly that: one small pack written three ways.
Use it when:
- The commands are the complicated part, not the data behind them
- You want loops, conditions and classes around commands without an f-string between you and them
- You are doing scoreboard or storage arithmetic and want to read it as arithmetic
- You want nesting (
execute ...:) instead of hand-splitting functions
Avoid it when:
- The work is generating many near-identical functions from your definitions.
write_functionin a plugin seesMem.definitionsand is the shorter road - You need a StewBeet plugin to see what you wrote. Plugins run on the pack, and mecha compiles after them
- Your collaborators do not want a second language in the project
In the editor
The StewBeet extension gives .bolt its own language, with completion and ctrl+click on the commands and a lens per function the module writes.
It also keeps Spyglass from underlining a .mcfunction holding bolt, which Spyglass reads as vanilla mcfunction. See Editor support.
Best practices
Do's
File Organization:
- Use meaningful folder structures (e.g.,
machines/,items/,utils/) - Group related functions together
- Separate logic into small, reusable functions
Code Quality:
- Use f-strings for dynamic paths:
f"{ns}:folder/{item}" - Use multi-line strings (triple quotes) for command content
- Add descriptive comments in generated functions
- Use
prepend=Truefor initialization code in files that must run first
Performance:
- Use versioned functions (second, second_5, minute) instead of tick when possible
- Batch operations together in single functions
- Use predicates instead of complex execute conditions
- Avoid unnecessary function calls in tick
StewBeet Conventions:
- Always use
Mem.ctx.project_idfor namespace - Use
write_load_file()for initialization - Use
write_versioned_function()for clock functions - Call StewBeet helpers instead of direct beet API when available
Don'ts
File Management:
- Don't hardcode namespace strings (use
ctx.project_idornsvariable) - Don't mix static files with dynamic generation for the same path
- Don't overwrite files unless intentional
- Don't create circular function calls (infinite loops)
Code Quality:
- Don't use
ctx.data["namespace"].functions["path"]when StewBeet helpers exist - Don't forget to handle edge cases (empty checks, score limits)
- Don't write monolithic functions (break into smaller pieces)
- Don't duplicate code across multiple functions
Performance:
- Don't run expensive operations in tick file
- Don't create functions that call themselves recursively without limits
- Don't use many small functions when one would suffice
- Don't check complex conditions every tick
Organization:
- Don't mix different concerns in same function
- Don't use generic names like
temp,test,function - Don't nest folders too deeply
- Don't create files that are never called
Which one to pick, in short
- Static files for configuration, fixed recipes and small functions that never change.
- StewBeet helpers for most datapack logic, and anything generated from your definitions.
- The native beet API only when no helper covers the file you need.
- Bolt where the commands, not the data, are the hard part.
Whichever you use, group functions in folders by feature, and put periodic work in versioned clock functions rather than in tick.
Glossary
| Term | Meaning |
|---|---|
| Static file loading | Pre-plugin loading of files declared in beet.yml (data_pack.load and resource_pack.load). |
| Native Beet API writing | Creating files through ctx.data/ctx.assets objects in plugin code. |
| StewBeet helper writing | Utility functions like write_function, write_tag, and related helpers for faster generation. |
| Bolt | Mecha's scripting layer. Python and commands share one syntax, compiled at build time. |
| Module | A .bolt file under data/<namespace>/module/, imported by others and writing functions only where it asks to. |
| Nesting | An execute or if ending in a colon, which mecha turns into its own function and the call reaching it. |
Next steps
- Helper function reference: every helper and the arguments it takes.
- Editor support: the extension that checks every block on this page.
- Cookbook: complete worked examples.
- Equations: build scoreboard arithmetic instead of hand-writing it.
- Configuring the build: control when your code runs in the pipeline.