Tutorial: build your first datapack
In this tutorial you create a StewBeet project, build it, load it in Minecraft, then add a custom item and a full ruby ore tier with a working custom block. It takes about 20 minutes. Already have a datapack? Migrate it instead.
You need three things:
- uv, the Python package manager from Astral. It installs Python for you, so it is the only thing on this list you set up by hand.
- A text editor. VS Code with the Python extension pack and the StewBeet extension gives you completion inside your commands.
- Minecraft Java Edition, to test the result.
You do not install Python yourself. StewBeet needs 3.14, every template says so in its pyproject.toml, and uv downloads a matching version the first time you build.
Install uv
Run the line for your system:
Other ways to install it (winget, Homebrew, pipx, a standalone binary) are listed on the uv installation page.
Close and reopen your terminal, then check that uv is on your PATH:
Already have Python 3.14 and prefer pip?
pip install stewbeetworks too, and everyuv run stewbeet ...below becomes plainstewbeet .... The rest of the tutorial is identical.
# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"# macOS and Linux
curl -LsSf https://astral.sh/uv/install.sh | shuv --versionCreate the project
StewBeet ships three templates. This tutorial uses Basic: every plugin is configured and commented, and there is no example content to delete.
| Template | For | What you get |
|---|---|---|
| Minimal | Learning beet on its own | One StewBeet plugin, nothing else |
| Basic | Most projects | Every plugin, commented, no example content |
| Extensive | Reading real examples | Every feature, with working items, ores and a manual |
-
Create a folder for the project, for example
C:/MyDatapacks/AwesomeOres/. -
Open it in VS Code (right-click the folder and pick "Open with Code", or File, Open Folder).
-
Open a terminal with Terminal, New Terminal. It starts in the project folder.
-
Run:
Terminaluvx stewbeet init basic
uvx downloads StewBeet, runs it once and discards the copy, so nothing is installed globally. The folder now looks like this:
What pyproject.toml does
It makes the project self-contained:
requires-python tells uv which interpreter to fetch.
The [tool.uv.sources] section is temporary: the smithed release on PyPI mixes Pydantic V1 and V2 models, which makes Smithed Weld merging fail on recent Python. Drop that section and the smithed dependency once it is fixed upstream.
To use another library in your definitions (requests, pillow), run uv add requests. It lands in this file, in your .venv, and in the lock file your collaborators reuse.
AwesomeOres/
├── .beet_cache/ # Build cache (generated)
├── build/ # Output folder (generated)
├── .venv/ # Project environment (created by uv on the first build)
├── assets/ # Your textures and sounds
├── src/ # Your source code
│ ├── data/ # Datapack functions and data
│ │ └── basic_template/ # Your namespace (rename this)
│ ├── definitions/ # Definition modules
│ │ ├── additions.py # Custom items and blocks
│ │ └── ores.py # Ore and equipment tiers
│ ├── link.py # Code that runs after the definitions
│ └── setup_definitions.py # Entry point for the definitions
├── .gitignore
├── pyproject.toml # Python dependencies (StewBeet and anything you add)
├── beet.yml # Main configuration file
└── definitions_debug.json # What your definitions produced, for debugging[project]
name = "template"
version = "0.0.1"
requires-python = ">=3.14"
dependencies = [
"stewbeet>=3.16.0",
]
[tool.uv]
package = falseName your pack
Open beet.yml. These fields identify the pack and are reused in pack.mcmeta, item lore, archive names and the manual:
| Field | Rule | Example |
|---|---|---|
id | Lowercase and underscores, no spaces. Must match the folder in src/data/ | awesome_ores |
name | Free text | "Awesome Ores & Gems" |
version | Semantic versioning, major.minor.patch | 1.0.0 |
Rename src/data/basic_template/ to src/data/awesome_ores/ so it matches id.
# Project identifier - MUST match your namespace in src/data/
id: "awesome_ores"
# Project name for display
name: "Awesome Ores"
# Your name (shows up in pack.mcmeta and item lore)
author: "YourName"
# Version using semantic versioning
version: "1.0.0"
# Brief description
description: "My first StewBeet datapack with custom ores!"Build it
In the terminal, run uv run stewbeet (or uv run stewbeet build, which is the same).
The first run does the setup: uv reads pyproject.toml, downloads Python 3.14 if it is missing, creates .venv/ and installs StewBeet. It takes about a minute. Later runs start building immediately.
The output looks like this. The warnings are expected on an empty project:
build/ now contains:
| Path | What it is |
|---|---|
datapack/ | The generated datapack, unzipped |
resource_pack/ | The generated resource pack, unzipped |
AwesomeOres_datapack.zip | The datapack, ready to drop into a world |
AwesomeOres_resource_pack.zip | The resource pack, ready to enable |
sha1_hashes.json | Hashes of the archives, for server admins |
Building project...
[WARNING 19:05:57] Error during generate_custom_records(): (FileNotFoundError) [WinError 3] The system cannot find the path specified: 'assets/records'
[DEBUG 19:05:58] Mem.definitions exported to 'definitions_debug.json'
[PROGRESS 19:05:58] Execution time of 'stewbeet.plugins.resource_pack.sounds': 0.070ms (69900ns)
[PROGRESS 19:05:58] Execution time of 'stewbeet.plugins.resource_pack.item_models': 0.246ms (245700ns)
[PROGRESS 19:05:58] Execution time of 'stewbeet.plugins.resource_pack.check_power_of_2': 0.250ms (249700ns)
[PROGRESS 19:05:58] Execution time of 'stewbeet.plugins.custom_recipes': 0.021ms (20700ns)
[PROGRESS 19:05:58] Execution time of 'stewbeet.plugins.custom_paintings': 0.007ms (7400ns)
[WARNING 19:05:58] Database is empty, skipping manual generation.
[PROGRESS 19:05:58] Execution time of 'stewbeet.plugins.ingame_manual': 0.075ms (74600ns)
[PROGRESS 19:05:58] Execution time of 'stewbeet.plugins.datapack.loading': 0.150ms (150300ns)
[PROGRESS 19:05:58] Execution time of 'stewbeet.plugins.datapack.custom_blocks': 0.108ms (108200ns)
[PROGRESS 19:05:58] Execution time of 'stewbeet.plugins.datapack.loot_tables': 0.187ms (187300ns)
[PROGRESS 19:05:58] Execution time of 'stewbeet.plugins.datapack.sorters': 0.031ms (31300ns)
[PROGRESS 19:05:58] Execution time of 'stewbeet.plugins.compatibilities.simpledrawer': 0.003ms (2700ns)
[PROGRESS 19:05:58] Execution time of 'stewbeet.plugins.compatibilities.neo_enchant': 0.003ms (2800ns)
[PROGRESS 19:05:58] Execution time of 'stewbeet.plugins.finalyze.custom_blocks_ticking': 0.045ms (45100ns)
[PROGRESS 19:05:58] Execution time of 'stewbeet.plugins.finalyze.basic_datapack_structure': 0.062ms (61600ns)
[PROGRESS 19:05:58] Execution time of 'stewbeet.plugins.finalyze.dependencies': 0.875ms (874900ns)
[PROGRESS 19:05:58] Execution time of 'stewbeet.plugins.finalyze.last_final': 0.154ms (154500ns)
Generating lang file: 100%|████████████████████████████████████████████████| 21/21 [4481.78it/s, 00:00<00:00]
[PROGRESS 19:05:58] Execution time of 'stewbeet.plugins.auto.lang_file': 73.613ms (73613100ns)
[PROGRESS 19:05:58] Execution time of 'stewbeet.plugins.auto.headers': 0.561ms (561000ns)
[PROGRESS 19:05:58] Execution time of 'stewbeet.plugins.check_unused_textures': 0.125ms (124800ns)
[PROGRESS 19:05:58] Execution time of 'stewbeet.plugins.archive': 23.592ms (23592200ns)
[WARNING 19:05:58] No datapacks or libs to merge for build\AwesomeOres_datapack_with_libs.zip. Skipping weld.
[WARNING 19:05:58] No resource packs or libs to merge for build\AwesomeOres_resource_pack_with_libs.zip. Skipping weld.
[PROGRESS 19:05:58] Execution time of 'stewbeet.plugins.merge_smithed_weld': 0.593ms (593100ns)
[PROGRESS 19:05:58] Execution time of 'stewbeet.plugins.copy_to_destination': 0.007ms (7300ns)
[PROGRESS 19:05:58] Execution time of 'stewbeet.plugins.compute_sha1': 25.546ms (25546400ns)
[DEBUG 19:05:58] Total execution time: 0.56934s
Done!Load it in Minecraft
The fastest loop is to let every build copy the packs into your game. Add this to beet.yml, with your own paths:
From now on, uv run stewbeet copies both packs after each build.
To copy them by hand instead:
- Copy
build/AwesomeOres_datapack.zipinto the world's datapacks folder:- Windows:
%appdata%\.minecraft\saves\[WorldName]\datapacks\ - macOS:
~/Library/Application Support/minecraft/saves/[WorldName]/datapacks/
- Windows:
- Copy
build/AwesomeOres_resource_pack.zipinto the resource packs folder:- Windows:
%appdata%\.minecraft\resourcepacks\ - macOS:
~/Library/Application Support/minecraft/resourcepacks/
- Windows:
Then, in game:
- Run
/reload. - Enable the resource pack in Options, Resource Packs.
- If you kept the example function in
src/data/awesome_ores/function/, run it with/function awesome_ores:path/to/a/random/function/i/guess.
meta:
stewbeet:
build_copy_destinations:
datapack: ["C:/Users/YourName/AppData/Roaming/.minecraft/saves/YourWorldName/datapacks"]
resource_pack: ["C:/Users/YourName/AppData/Roaming/.minecraft/resourcepacks"]Add a custom item
- Create
assets/textures/and put a 16x16 PNG in it, for exampleruby.png, so the file isassets/textures/ruby.png. - Open
src/definitions/additions.pyand declare the item. Theidmatches the texture name, which is how StewBeet finds it:
- Run
uv run stewbeet. The first build that renders item models takes a little longer. - In game, run
/reload, then/loot give @s loot awesome_ores:i/rubyor/function awesome_ores:_give_all.
From that one declaration, StewBeet wrote the item model and its reference, added the texture to the resource pack, built the item components, and added a manual page.
# Imports
from stewbeet import *
# Main entry point
def main():
# Add items to the definitions
Mem.definitions["ruby"] = Item(
id="ruby",
components={
"lore": [{"text":"A precious red gemstone","color":"gray","italic":False}]
}
)
# See extensive_template/src/definitions/additions.py for examples
passAdd a whole ore tier
Put these textures in assets/textures/:
| File | Used for |
|---|---|
ruby_ore.png | The ore block |
ruby_sword.png | The sword |
ruby_chestplate.png | The chestplate item |
ruby_layer_1.png | Worn armour, top layer (how Minecraft draws custom armour) |
ruby_layer_2.png | Worn armour, bottom layer |
Open src/definitions/ores.py and describe the material. Everything StewBeet finds in the textures folder under the ruby prefix is registered from this entry:
Build, /reload, then run /loot give @s loot awesome_ores:i/ruby_ore and place the block. It is a working custom block: StewBeet wrote its model, its placement and breaking logic, its drops and mining requirements, its Fortune and Silk Touch behaviour, and wired it to the Smithed Custom Blocks library.
# Imports
from stewbeet import *
# Main entry point
def main():
# Configuration to generate everything about a material
ORES_CONFIGS: dict[str, EquipmentsConfig|None] = {
"ruby": EquipmentsConfig(
# This ruby is equivalent to diamond,
equivalent_to = DefaultOre.DIAMOND,
# But, has more durability (1.2 times more)
pickaxe_durability = 1.2 * VanillaEquipments.PICKAXE.value[DefaultOre.DIAMOND]["durability"],
# And, does 1 more damage per hit (mainhand), and has 0.5 more armor, and mines 20% faster (pickaxe)
attributes = {"attack_damage": 1, "armor": 0.5, "mining_efficiency": 0.2}
),
}
# Generate ores in definitions (add every stuff (found in the textures folder) related to the given materials, to the definitions)
generate_everything_about_these_materials(ORES_CONFIGS)
returnOpen the in-game manual
The manual uses Minecraft's dialog system, which only picks up new dialogs on a server restart, so leave and rejoin the world first. Then press G (the quick action keybind), or run /loot give @s loot awesome_ores:i/manual if you started from the Extensive template.
The manual lists your items with their recipes, drawn from the definitions you just wrote.
What is in beet.yml
You have now used the whole loop. Two more parts of beet.yml are worth knowing before you go further.
The folders StewBeet reads from, and where it copies the result:
meta:
stewbeet:
# Directory containing all project textures
textures_folder: "assets/textures"
# Directory containing all custom sounds
sounds_folder: "assets/sounds"
# Directory containing all jukebox records
records_folder: "assets/records"
# Directory containing libraries that will be copied to the build destination, and merged using Smithed Weld if enabled.
libs_folder: "libs"
# Optional: glob patterns (relative to libs_folder) of library archives to leave out of the build
libs_exclude_patterns: []
# Optional list of destination paths where generated files will be copied
build_copy_destinations:
datapack: ["C:/Users/YourName/AppData/Roaming/.minecraft/saves/YourWorldName/datapacks"]
resource_pack: ["C:/Users/YourName/AppData/Roaming/.minecraft/resourcepacks"]The pipeline, which lists every step of the build in order. Remove a line to turn a feature off:
# Plugins to run first
require:
- "stewbeet" # Equivalent to "stewbeet.plugins.initialize"
- "bolt" # Initialize bolt
# A list of strings representing "plugins".
# - These plugins will execute after the pack is loaded (all src/data and src/assets contents are loaded first)
pipeline:
- "src.setup_definitions" # Your User code for defining items/blocks
- "stewbeet.plugins.resource_pack.sounds" # Generate sound files
- "stewbeet.plugins.resource_pack.item_models" # Generate item models
- "stewbeet.plugins.resource_pack.check_power_of_2" # Verify texture dimensions
- "stewbeet.plugins.custom_recipes" # Generate custom recipes
- "stewbeet.plugins.custom_paintings" # Generate custom paintings
- "stewbeet.plugins.ingame_manual" # Generate in-game manual
- "stewbeet.plugins.datapack.loading" # Set up load/tick functions
- "stewbeet.plugins.datapack.custom_blocks" # Set up block mechanics
- "stewbeet.plugins.datapack.loot_tables" # Generate loot tables
- "stewbeet.plugins.datapack.sorters" # Set up item sorters
- "stewbeet.plugins.compatibilities.simpledrawer" # SimpleDrawer compatibility
- "stewbeet.plugins.compatibilities.neo_enchant" # NeoEnchant compatibility
- "src.link" # User code for linking features
- "mecha" # Bolt/Mecha compilation
- "stewbeet.plugins.finalyze.custom_blocks_ticking" # Finalize block ticking
- "stewbeet.plugins.finalyze.basic_datapack_structure" # Structure finalization
- "stewbeet.plugins.finalyze.dependencies" # Dependency checks
- "stewbeet.plugins.finalyze.last_final" # Final cleanup
- "stewbeet.plugins.auto.lang_file" # Generate language files
- "stewbeet.plugins.auto.headers" # Generate function headers
- "stewbeet.plugins.check_unused_textures" # Find unused textures
- "stewbeet.plugins.archive" # Create zip files
- "stewbeet.plugins.merge_smithed_weld" # Merge with Smithed Weld
- "stewbeet.plugins.copy_to_destination" # Copy to configured paths
- "stewbeet.plugins.compute_sha1" # Compute file hashesEvery option is described in Configuring the build.
Next steps
- Defining items and blocks: every field an
Itemor aBlockaccepts, recipes included. - Writing functions and files: add your own commands to the pack.
- Using datapack libraries: Smithed, Bookshelf and the version checks StewBeet writes for you.
- The Extensive template is a complete project to read.
Stuck? Ask on Discord or open a GitHub issue.