Configuring the build

Every option of the beet configuration file, and what StewBeet does with it. The file is read at the start of every build and decides how the whole project is processed.

If beet, bolt and mecha are new names to you, this is who makes what:

beet, bolt, mecha and StewBeet beet runs the build. Everything else plugs into it. bolt and mecha are made by the beet team. StewBeet is a separate project by Stoupy. pip install stewbeet brings beet, bolt and mecha along. beet, bolt, mecha and StewBeet Who does what when you build a Minecraft pack beetThe build tool: runs the plugins in order and writesthe datapack and the resource pack. datapack + resource pack, ready for Minecraft boltPython-like syntax (loops,variables) inside functions mechaParses, checks and compilesevery command you write mcbeet, the beet team StewBeetA framework made of beet plugins. Declare an item in Pythonand get its models, recipes, loot tables and manual page.independent projectruns inside beet, as plugins IN SHORT beet runs the build.Everything else plugs into it.bolt and mecha are made bythe beet team. StewBeet is aseparate project by Stoupy.pip install stewbeet bringsbeet, bolt and mecha along. stewbeet.paralya.fr

The examples use YAML (beet.yml). Every option works the same in beet.yaml, beet.json or pyproject.toml. The file lives at the project root.

Complete files to read alongside this page:

Project identity

id

The namespace root of generated functions, tags and storage keys. Lowercase and underscores only.

yaml
id: "_your_namespace"

name

The human-readable name, shown in pack.mcmeta, item lore and in-game messages.

yaml
name: "Extensive Template"

author

One or more creators, shown in pack.mcmeta. Separate several names with ", ".

yaml
author: "Stoupy51"
author: "Player1, Player2, Player3"  # Multiple authors

Players whose in-game name matches an author automatically receive the convention.debug tag, which unlocks development tools.

version

Semantic version (major.minor.patch), used for dependency checks and versioned function paths.

yaml
version: "3.0.0"

minecraft

The target game version, which decides the available commands and resource formats. Omit it to target the latest version.

yaml
minecraft: "1.21.11"

Directories

directory and output

directory is the base for relative paths. output is where the built packs are written.

yaml
directory: "."
output: "build"

ignore

Files and patterns beet watch ignores, which prevents rebuild loops and speeds up watching.

yaml
ignore: ["build", "manual_cache", "definitions_debug.json"]

require

Python packages imported before the build, which makes their plugins available to the pipeline.

yaml
require:
    - "stewbeet"
    - "bolt"
PackageRole
stewbeetThe framework (required)
boltPython-like syntax inside functions
beet.contrib.vanillaVanilla data generators
mechaCommand compiler (usually loaded automatically)

Packs

data_pack

Loads .mcfunction and JSON files from src/data/your_namespace/ into the datapack.

yaml
data_pack:
    name: "datapack"
    load: ["src"]

resource_pack

Loads assets from src/assets/ into the resource pack.

yaml
resource_pack:
    name: "resource_pack"
    load: ["src"]

pipeline

The plugins that run after the packs are loaded, in order. Each one works on the result of the previous one:

yaml
pipeline:
    - "src.setup_definitions"                              # User setup code
    - "stewbeet.plugins.resource_pack.sounds"              # Process custom sounds
    - "stewbeet.plugins.resource_pack.item_models"         # Generate item models
    - "stewbeet.plugins.resource_pack.check_power_of_2"    # Validate texture dimensions
    - "stewbeet.plugins.custom_recipes"                    # Generate custom recipes
    - "stewbeet.plugins.custom_paintings"                  # Process custom paintings
    - "stewbeet.plugins.ingame_manual"                     # Generate in-game manual
    - "stewbeet.plugins.datapack.loading"                  # Setup datapack loading
    - "stewbeet.plugins.datapack.custom_blocks"            # Process custom blocks
    - "stewbeet.plugins.datapack.loot_tables"              # Generate loot tables
    - "stewbeet.plugins.datapack.sorters"                  # Setup item sorters
    - "stewbeet.plugins.compatibilities.simpledrawer"      # SimpleDrawer compatibility
    - "stewbeet.plugins.compatibilities.neo_enchant"       # NeoEnchant compatibility
    - "src.link"                                           # User linking code
    - "mecha"                                              # Mecha paired with Bolt
    - "stewbeet.plugins.finalyze.custom_blocks_ticking"    # Setup block ticking
    - "stewbeet.plugins.finalyze.basic_datapack_structure" # Create basic structure
    - "stewbeet.plugins.finalyze.dependencies"             # Handle dependencies
    - "stewbeet.plugins.finalyze.last_final"               # Final cleanup
    - "stewbeet.plugins.auto.lang_file"                    # Auto-generate lang files
    - "stewbeet.plugins.auto.text_renders"                 # Turn "render" keys into item glyphs
    - "stewbeet.plugins.auto.headers"                      # Add file headers
    - "stewbeet.plugins.check_unused_textures"             # Find unused textures
    - "stewbeet.plugins.archive"                           # Create ZIP archives
    - "stewbeet.plugins.merge_smithed_weld.datapack"       # Merge Smithed Weld libs into the datapack
    - "stewbeet.plugins.merge_smithed_weld.resource_pack"  # Merge Smithed Weld libs into the resource pack
    - "stewbeet.plugins.copy_to_destination"               # Copy to game folders
    - "stewbeet.plugins.compute_sha1"                      # Compute file hashes

The order follows eight phases:

PhasePluginsWhat happens
1. Setupsrc.setup_definitionsYour code declares items, blocks and recipes
2. Resource packresource_pack.sounds, resource_pack.item_models, resource_pack.check_power_of_2Models and sounds are generated
3. Contentcustom_recipes, custom_paintings, ingame_manualRecipes, paintings and the manual
4. Datapack coredatapack.loading, datapack.custom_blocks, datapack.loot_tablesLoading, blocks, loot tables
5. User codesrc.linkYour functions, which can use everything above
6. CompilationmechaBolt and mecha compile every function
7. Finalisationfinalyze.custom_blocks_ticking, finalyze.basic_datapack_structure, finalyze.dependenciesClock functions and dependency checks
8. Packagingauto.lang_file, auto.text_renders, archive, copy_to_destinationLang file, archives, copies, hashes

Keep the recommended order. Your code goes in setup_definitions and link, mecha comes after it, and the finalisation plugins are not optional: they write the clock functions and the dependency checks the rest relies on.

meta

mc_supports

The versions declared to Modrinth and Smithed on upload. "infinite" declares forward compatibility. It also sets the supported formats written to pack.mcmeta.

yaml
mc_supports: ["1.21.11", "26.1-snapshot-1", "infinite"]

model_resolver

Caches resolved item models in .beet_cache/model_resolver/, which makes rebuilds 80 to 90% faster.

yaml
model_resolver:
    use_cache: true

mecha

How commands are parsed and formatted during compilation.

yaml
mecha:
    multiline: true
    formatting: preserve

multiline: true accepts commands split over several lines:

mcfunction
execute
    as @a[scores={health=1..10}]
    at @s
    run function my_namespace:fn

formatting: preserve keeps your own formatting in the output.

meta.stewbeet

Source folders

Where StewBeet reads textures, sounds, jukebox records and libraries.

yaml
stewbeet:
    textures_folder: "assets/textures"
    sounds_folder: "assets/sounds"
    records_folder: "assets/records"
    libs_folder: "libs"
    libs_exclude_patterns: []

build_copy_destinations

Folders the packs are copied to after each build. Combined with beet watch, the game always has the latest build.

yaml
build_copy_destinations:
    datapack: ["D:/latest_snapshot/world/datapacks"]
    resource_pack: ["D:/minecraft/snapshot/resourcepacks"]

source_lore and source_lore_color

A line appended to the lore of every custom item. "auto" is the project icon and name, both drawn with the generated {id}:tooltip font.

yaml
source_lore: "auto" # TextComponents format
source_lore_color: "auto" # "auto" | any color | false

source_lore_color sets that font's colour. "auto" takes the dominant colour of your pack.png, any Pillow colour forces it ("#55FFFF", "gold", [85, 255, 255]), and false keeps the packaged gold. An assets/tooltip.png placed next to pack.png replaces the character atlas entirely and is never recoloured.

A source lore is a plain text component, so it also accepts the render key of the auto.text_renders plugin, to show an item image next to the project name:

yaml
source_lore: [{"text":"ICON"}, " ", {"text":"My Pack", "color":"white", "italic":false, "font":"my_pack:tooltip"}, " ", {"render":"steel_ingot", "height":10}]

iso_renders_path and text_renders

Where the per-item PNGs live, and how the render key of text components is drawn.

yaml
iso_renders_path: "iso_renders"
text_renders:
    default_height: 16
    font: "renders"
    # allow_oversized: true   # unset asks once in the terminal, and remembers the answer

iso_renders_path holds one PNG per item, as <folder>/<namespace>/<item>.png. Project items are rendered from their model, minecraft: items are downloaded, and items from other packs are the ones you put there yourself. It is shared by ingame_manual and auto.text_renders, so an item is only rendered once.

A picture larger than the 256x256 that fits in one glyph is cut into a grid of glyphs joined with negative spacing, at the cost of one texture per tile. The first build that meets one asks in the terminal and remembers the answer in .beet_cache. allow_oversized answers up front, and false shrinks such renders to a single glyph.

Deprecated: manual.cache_path is replaced by iso_renders_path. Projects that still set it keep working (renders are read from <cache_path>/items), and everything else the manual caches lives in beet's .beet_cache folder.

load_dependencies

Datapacks checked when your pack loads. A missing or outdated one prints an error in chat with a download link.

yaml
load_dependencies:
    "energy":
        version: [1, 8, 0]
        name: "DatapackEnergy"
        url: "https://github.com/ICY105/DatapackEnergy"

This only works with datapacks that follow the LanternLoad convention.

manual

Rendering, caching, layout and interaction of the generated in-game manual.

yaml
manual:
    debug_mode: false
    manual_overrides: "assets/manual_overrides"
    high_resolution: true
    cache_assets: true
    cache_pages: false
    name: ""
    max_items_per_row: 5
    max_rows_per_page: 5
    first_page_text: [{"text":"...", "color":"#505050"}]
    showcase_image: 3
    use_dialog: 1
OptionEffect
debug_modetrue draws a grid overlay to debug the layout
manual_overridesFolder of files that replace the default manual assets by name. See the overridable assets
high_resolutionRenders item images at high resolution
cache_assetsCaches Minecraft textures and models (about 90% faster builds)
cache_pagesCaches every page. Leave it false on small projects
nameManual title. Empty means generated from the project name
max_items_per_rowItems per row, 1 to 6
max_rows_per_pageRows per page, 1 to 7. The default grid is 5x5, so 25 items a page
first_page_textWelcome text, as text components
showcase_image0 off, 1 manual items only, 2 all custom items, 3 both (recommended)
use_dialog0 book only (no server restart needed), 1 book that opens a dialog (recommended, needs a server restart), 2 dialog only (needs a server restart)

Generated glyph images are cached in beet's .beet_cache folder. Item renders live in iso_renders_path, above.

Example welcome text:

yaml
first_page_text: [{"text":"The following manual will guide you through recipes and energy statistics about devices.", "color": "#505050"}]

Minimal configuration

A beet project that only uses the auto.headers plugin:

yaml
# Path to a folder for beet to output
output: "build"

# A list of importable plugin strings
require:
    - "bolt"

# Takes a nested pack config
data_pack:
    name: "datapack"
    load: ["src"]

pipeline:
    - "mecha"
    - "stewbeet.plugins.auto.headers"

Glossary

TermMeaning
Beet configuration fileThe project config (beet.yml, beet.yaml, beet.json or pyproject.toml) loaded at the start of a build
PipelineThe ordered list of plugins that transform and package the project
Meta sectionThe meta container for plugin settings, used by StewBeet and related tools

Next steps

Questions go to the Discord community.