Defining items and blocks
Item definitions are the heart of the StewBeet framework. They define custom items, blocks, equipment, recipes, and their properties using modern Python classes. The definitions setup creates a database of all custom content that subsequent plugins use to generate datapacks and resource packs.
This is typically the first user-created plugin in the pipeline (after stewbeet.plugins.initialize).
Required: StewBeet framework (from stewbeet import *)
Required: Beet context (from beet import Context)
Position: Must be called early in the pipeline before other plugins that depend on definitions
Integration: Works with all StewBeet plugins that process item definitions
Some Features Showcase
Item definitions from the Extensive Template:
Example File: extensive/src/setup_definitions.py
Real-world Example: SimplEnergy/src/definitions/setup_main.py
- Define custom items, blocks, and equipment using Python classes
- Configure automatic material generation (ores, ingots, tools, armor)
- Set up crafting recipes with typed classes
- Establish relationships between items and their uses
- Configure item names, lore, and categories
- Link items to their texture and model assets
Configuration
Basic Setup Structure
This structure defines the lifecycle of your definitions plugin: generate content, normalize metadata, run required post-processing, and optionally export debug data.
from beet import Context
from stewbeet import *
# Import your definition modules
from .definitions.additions import main as main_additions
from .definitions.ores import main as main_ores
def beet_default(ctx: Context):
# 1. Generate materials and equipment
main_ores()
# 2. Generate custom records
generate_custom_records("auto")
# 3. Add custom items, blocks, paintings
main_additions()
# 4. Set missing categories
for item in Mem.definitions.keys():
obj = Item.from_id(item)
if not obj.manual_category:
obj.manual_category = "miscellaneous"
# 5. Final adjustments (REQUIRED!)
add_item_model_component(black_list=["excluded_items"])
add_item_name_and_lore_if_missing()
add_private_custom_data_for_namespace()
add_smithed_ignore_vanilla_behaviours_convention()
set_manual_components(white_list=["item_name", "lore", "custom_name", "damage", "max_damage"])
# 6. Debug export (optional)
export_all_definitions_to_json(f"{Mem.ctx.directory}/definitions_debug.json")Core Concepts
The Mem.definitions Database
All item definitions are stored in Mem.definitions, a global dictionary that gets populated when you create Item, Block, or Painting instances:
# Creating an item automatically registers it
item = Item(id="my_item", base_item="minecraft:iron_ingot")
# Access it from anywhere
same_item = Item.from_id("my_item")
assert item is same_item # They're the same object!
# Check the underlying dictionary
assert "my_item" in Mem.definitionsItem Class
Definition of the Item class properties:
Item Properties
| Property | Type | Description |
|---|---|---|
id | str | Required: Unique identifier (e.g., "magic_sword") |
base_item | str | Base Minecraft item (default: CUSTOM_ITEM_VANILLA) |
manual_category | str | None | Category for in-game manual organization |
recipes | list[RecipeBase] | List of recipe objects that create this item |
override_model | JsonDict | None | Override auto-generated item model |
hand_model | JsonDict | None | Model used instead of the regular one in most display contexts (hand, gui, ground, ...) |
override_model_contexts | list[str] | None | Display contexts keeping the regular model when hand_model is set (default: ["none", "fixed"], i.e. item display entities and item frames) |
wiki_buttons | list[WikiButton] | TextComponent | None | Manual documentation |
remainder | str | None | Id of the item left once this one is eaten or drunk (e.g. "beer_mug"), given back with the container's name, model and custom data, and linked from the item's manual page |
ranged_weapon | RangedWeapon | None | Charge time, arrow damage and ammunition of a bow or crossbow (see below) |
components | JsonDict | Minecraft item components (without minecraft: prefix) |
Example using the Item class:
from stewbeet import Item, Ingr, CraftingShapedRecipe, WikiButton
item = Item(
id="magic_sword", # Required: unique identifier
base_item="minecraft:iron_sword", # Base Minecraft item (default: CUSTOM_ITEM_VANILLA)
manual_category="equipment", # Category for the manual
recipes=[ # List of Recipe objects
CraftingShapedRecipe(
category="equipment",
shape=["X", "X", "Y"],
ingredients={"X": Ingr("minecraft:amethyst_shard"), "Y": Ingr("minecraft:stick")}
)
],
override_model=None, # Override auto-generated model
hand_model=None, # Special hand-held model
override_model_contexts=None, # Contexts keeping the regular model when hand_model is set
wiki_buttons=[ # Manual documentation buttons
WikiButton({"text": "A powerful sword", "color": "gold"})
],
components={ # Minecraft item components
"item_name": {"text": "Magic Sword", "color": "gold"},
"lore": [{"text": "Deals extra damage", "color": "gray"}],
"max_damage": 500,
"enchantments": {"minecraft:sharpness": 5},
"attribute_modifiers": [
{
"type": "minecraft:attack_damage",
"amount": 8,
"operation": "add_value",
"slot": "mainhand",
"id": "minecraft:base_attack_damage"
}
]
}
)Block Class
Custom blocks extend the Item class with block-specific properties:
from stewbeet import Block, VanillaBlock, CraftingShapedRecipe, SmeltingRecipe, Ingr
block = Block(
id="super_stone",
vanilla_block=VanillaBlock(id="minecraft:cobblestone"),
manual_category="building",
recipes=[
# Could have been shapeless, but just for example:
CraftingShapedRecipe(
category="building",
shape=["XXX", "XXX", "XXX"],
ingredients={"X": Ingr("minecraft:stone")}
),
# Multiple recipe types supported
SmeltingRecipe(
experience=0.1,
cookingtime=200,
category="building",
ingredient=Ingr("super_stone"),
result=Ingr("minecraft:diamond")
)
],
components={
# Item name, lore, and container will be auto-generated if missing
}
)VanillaBlock Configuration
VanillaBlock defines the vanilla block state StewBeet uses as the runtime anchor for your custom block behavior.
@dataclass
class VanillaBlock:
id: str # Base vanilla block (e.g., "minecraft:cobblestone")
contents: bool = False # For blocks using item frames without vanilla block
block_facing: Literal[False, "player"] = False # Rotate placed block based on player facing
visual_facing: Literal["none", "player", "item_frame"] = "none" # Visual entity orientation source
half: Literal["click"] | None = None # Slab, stairs or trapdoor host on the half the player clicked
interaction: Interaction | None = None # Interaction entity for an invisible host (barrier, structure void, light)
uvlock: bool = False # With visual_facing="player", turned model copies keeping textures on the world grid
margin: float = 1.002 # Scale of the displayed model about the block's center, 1.0 leaves its size
machine_speed: float | None = None # Furnace, smoker, blast furnace or brewing stand working this many times fasterWith block_facing="player", the host faces the way vanilla turns it: towards the player for a furnace, the way the player looks for stairs and fence gates.
The display entity is scaled by margin about the block's center, so its faces are drawn in front of the host's. Use a larger margin when faces still flicker from far away (1.008 is 1/16 of a pixel on a full block). margin=1.0 leaves the size.
half="click" places the host's type (slab) or half (stairs, trapdoor) from where the player clicked, found at placement by stepping along the player's look ({ns}:custom_blocks/_aim/main). Besides #upper, it leaves #floor {ns}.data at 1 when the player clicked the top of the block below.
A stairs host takes a corner shape from its neighbours, and its display follows it every second with a copy of the model cut from its elements, drawn facing south: an inner corner adds the stairs turned a quarter, an outer corner keeps what both share. A furnace, smoker or blast furnace host with an _on model shows it while it burns. Both switch through the display's custom_model_data string, and only for a model StewBeet draws.
Invisible hosts: Interaction
A host without collision or that cannot be mined (minecraft:barrier, minecraft:structure_void, minecraft:light[level=N]) gets an interaction entity breaking the block when hit:
Block(
id="oak_chair",
vanilla_block=VanillaBlock(id="minecraft:barrier", visual_facing="player", interaction=Interaction(
width=1.01, height=1.01, # From the bottom of the block
seat=0.5, # Using it seats the player this high, None for no seat
hits=3, hit_timeout=20, # 3 hits less than 20 ticks apart break it
sound="minecraft:block.wood", # Plays <sound>.hit and <sound>.break with particles of the item
)),
)The item drops unless the breaker is in creative, and also when no player breaks it (a quarry calling #common_signals:calls/destroyed_block gets it). An item id as no_silk_touch_drop drops that item instead. For an emissive block without collision, use minecraft:light[level=15] as the host. Run commands when a player uses an interaction by appending to {ns}:custom_blocks/_interaction/use, run as the interaction with the player tagged {ns}.user.
Mining level: Mining
Block(id="steel_block", mining=Mining(tool="pickaxe", level="iron"))A weaker tool breaks the block without dropping its item. Without a host, the block takes the first host of Mining.hosts for its level (minecraft:diamond_block for iron), whose vanilla drop rules then decide, mining speed and animation included; a host given must be one of them. An interaction host checks the breaker's main hand against the item tag Mining.item_tag (any tool kind works there). An ore on VANILLA_BLOCK_FOR_ORES checks the tool of the nearest survival player within 8 blocks.
NoSilkTouchDrop Configuration
Defines custom drops when the block is broken without silk touch:
@dataclass
class NoSilkTouchDrop:
id: str = "" # Item ID to drop (e.g., "raw_simplunium")
loot_table: LootTable | str | None = None # Or a loot table rolled with the breaker's tool, instead of id and count
count: dict | int = 1 # Drop count: int or {"min": 1, "max": 3}
experience: dict | float = 0.0 # Experience points: 2.5 (a 50% chance of a third point) or {"min": 3, "max": 7}The manual shows the experience in the hover of the mining recipe.
# Example usage
block = Block(
id="simplunium_ore",
vanilla_block=VanillaBlockForOres,
no_silk_touch_drop=NoSilkTouchDrop(id="raw_simplunium", count={"min": 2, "max": 4}, experience={"min": 1, "max": 3})
)
# Or shorthand
block = Block(
id="simplunium_ore",
vanilla_block=VanillaBlockForOres,
no_silk_touch_drop="raw_simplunium" # Defaults to count=1
)
# Or dynamic drops with a direct beet LootTable
block = Block(
id="simplunium_ore",
vanilla_block=VanillaBlockForOres,
no_silk_touch_drop=LootTable({
"pools": [{
"rolls": 1,
"entries": [
{"type": "minecraft:item", "name": "minecraft:raw_iron", "weight": 3},
{"type": "minecraft:item", "name": "minecraft:iron_nugget", "weight": 7}
]
}]
})
)
# Or a loot table with experience
block = Block(
id="simplunium_ore",
vanilla_block=VanillaBlockForOres,
no_silk_touch_drop=NoSilkTouchDrop(loot_table="my_ns:blocks/simplunium_ore", experience={"min": 2, "max": 5})
)RangedWeapon Configuration
Item(
id="crossbow", base_item="minecraft:crossbow",
ranged_weapon=RangedWeapon(
charge_time=2.5, # Seconds to load a crossbow, 1.25 in vanilla
damage_multiplier=1.5, # Damage of the arrows it shoots
ammunition="bolt", # The only item of the definitions it loads, anything else is given back
name="Heavy Draw", # Tooltip name of the hidden enchantment applying it
),
)The item gets an enchantment (Item.ranged_weapon_enchantment) tagged as a curse so a grindstone keeps it, and no enchantment glint. A crossbow with _pulling_<n>, _arrow and _firework textures gets the vanilla crossbow item model: drawn by its charge, and showing what it holds once loaded.
GrowingSeed Configuration
For seeds that grow over time (like Stardust Seed from Stardust Fragment):
@dataclass
class GrowingSeedLoot:
id: str # Item ID to drop
rolls: JsonDict | int = 1 # Roll definition or count
fortune: JsonDict | None = None # Fortune modifier
@dataclass
class GrowingSeed:
texture_basename: str # Base texture name (e.g., "stardust")
seconds: int # Growth time in seconds
planted_on: str # Block to plant on (e.g., "diamond_block")
loots: list[GrowingSeedLoot] | str # Loot list or loot table path# Example usage
seed = Block(
id="stardust_seed",
vanilla_block=VanillaBlock(id="minecraft:wheat"),
no_silk_touch_drop=NoSilkTouchDrop(id="stardust_fragment", count=1),
growing_seed=GrowingSeed(
texture_basename="stardust",
seconds=480, # 8 minutes
planted_on="diamond_block",
loots=[
GrowingSeedLoot(
id="stardust_fragment",
rolls={"type": "minecraft:uniform", "min": 3, "max": 9},
fortune={"extra": 0, "probability": 0.5}
)
]
)
)BlockAlternative and BlockHead
Alternative block types for special placement methods:
from stewbeet import BlockAlternative, BlockHead
# Using item frames (e.g., for machinery with no vanilla block)
servo = BlockAlternative(
id="servo_inserter",
vanilla_block=VanillaBlock(contents=True), # No vanilla block, just item frame
manual_category="machines"
)
# Using player heads (for custom heads)
custom_head = BlockHead(
id="stoupy_head",
vanilla_block=VanillaBlock(id="minecraft:player_head[profile={name:\"Stoupy51\"}]"),
manual_category="decorations"
)Painting Class
Custom paintings for decoration:
from stewbeet import Painting, PaintingData
painting = Painting(
id="stewbeet_painting",
manual_category="decorations",
painting_data=PaintingData(
texture="stewbeet_painting_2x2", # Texture file name (without .png)
author={"text": "Stoupy", "color": "yellow"}, # Defaults to ctx.project_author
title={"text": "Da' Icon", "color": "gray"}, # Defaults to item name
width=2, # Width in blocks
height=2 # Height in blocks
)
)Recipe System
Recipe Classes
StewBeet provides typed recipe classes for all Minecraft recipe types:
Crafting Shaped Recipe
Use a shaped recipe when slot position matters; the shape maps symbols to ingredients and controls exact crafting layout.
from stewbeet import CraftingShapedRecipe, Ingr
recipe = CraftingShapedRecipe(
result_count=1, # Number of items produced
group="tools", # Recipe book grouping
category="equipment", # Recipe book category
shape=["X X", " Y ", "X X"], # 3x3 pattern
ingredients={
"X": Ingr("minecraft:iron_ingot"),
"Y": Ingr("minecraft:stick")
}
)Crafting Shapeless Recipe
Use a shapeless recipe when only ingredient presence matters, regardless of placement order in the crafting grid.
recipe = CraftingShapelessRecipe(
result_count=4,
category="building_blocks",
ingredients=[Ingr("minecraft:oak_wood"), Ingr("minecraft:oak_log"),
Ingr("minecraft:oak_log"), Ingr("minecraft:oak_wood")]
# Can also use: ingredients=(2*[Ingr("minecraft:oak_wood")] + 2*[Ingr("minecraft:oak_log"])
)Smelting Recipe
Smelting recipes model furnace-like transformations with controlled time, XP reward, and one input-to-output conversion.
recipe = SmeltingRecipe(
result_count=1,
cookingtime=200, # Ticks (200 = 10 seconds)
experience=0.7,
category="misc",
ingredient=Ingr("ruby_ore"),
result=Ingr("ruby")
)Other Recipe Types
StewBeet exposes typed wrappers for specialized vanilla recipe systems so each mechanic can be configured explicitly.
# Blasting Furnace (faster smelting)
# cookingtime is the duration inside the block itself, StewBeet writes the value each Minecraft version expects
BlastingRecipe(cookingtime=100, experience=0.7, ...)
# Smoking (for food)
SmokingRecipe(cookingtime=100, experience=0.35, ...)
# Campfire
CampfireCookingRecipe(cookingtime=600, experience=0.35, ...)
# Stonecutting
StonecuttingRecipe(result_count=1, ingredient=Ingr(...), result=Ingr(...))
# Smithing Transform
SmithingTransformRecipe(template=Ingr(...), base=Ingr(...), addition=Ingr(...), result=Ingr(...))
# Smithing Trim
SmithingTrimRecipe(template=Ingr(...), base=Ingr(...), addition=Ingr(...))Ingredient Helper
The Ingr function creates ingredient specifications:
from stewbeet import Ingr
# Local namespace item
Ingr("steel_ingot")
# Result: {"custom_data": {"your_namespace": {"steel_ingot": True}}}
# Minecraft item
Ingr("minecraft:iron_ingot")
# Result: {"id": "minecraft:iron_ingot"}
# External datapack item
Ingr("tin_ingot", ns="mechanization")
# Result: {"custom_data": {"mechanization": {"tin_ingot": True}}}
# Use in recipes
recipe = CraftingShapedRecipe(
shape=["XXX", "XYX", "XXX"],
ingredients={
"X": Ingr("steel_ingot"),
"Y": Ingr("minecraft:diamond")
}
)Material Generation
Automatic Equipment Generation
Generate complete material sets automatically:
# In src/definitions/ores.py
from stewbeet import *
def main():
ORES_CONFIGS: dict[str, EquipmentsConfig | None] = {
"steel_ingot": EquipmentsConfig(
equivalent_to=DefaultOre.IRON, # Base material stats
pickaxe_durability=3 * VanillaEquipments.PICKAXE.value[DefaultOre.IRON]["durability"],
attributes={
"attack_damage": 1, # +1 damage for weapons
"armor": 0.5, # +0.5 armor for armor pieces
"mining_efficiency": 2 # +20% mining speed for tools
}
),
"minecraft:stone": None, # Auto-detect from textures (e.g., stone_stick, stone_rod, etc.)
}
# Generates: steel_ingot, steel_pickaxe, steel_axe, steel_shovel,
# steel_sword, steel_hoe, steel_helmet, steel_chestplate,
# steel_leggings, steel_boots, steel_block, raw_steel, raw_steel_block, etc.
generate_everything_about_these_materials(ORES_CONFIGS)
# Configure custom blocks after generation
# ⚠️ We use Block.from_id() to access existing definitions and modify them
Block.from_id("steel_block").vanilla_block = VanillaBlock(id="minecraft:iron_block")
Block.from_id("raw_steel_block").vanilla_block = VanillaBlock(id="minecraft:raw_iron_block")Equipment Configuration
EquipmentsConfig controls how generated material families inherit base stats and how custom modifiers are applied across tools and armor.
class EquipmentsConfig:
equivalent_to: DefaultOre # Base material (WOOD, STONE, GOLD, IRON, DIAMOND, NETHERITE, COPPER, CHAINMAIL, LEATHER)
pickaxe_durability: float | int = 0 # Custom durability (0 = use vanilla equivalent)
attributes: dict[str, float] | None = None # Stat modifiers to ADD (not override)
ignore_recipes: bool = False # Skip automatic recipe generationCommon attribute modifiers:
"attack_damage": 1.0-> +1 attack damage for weapons (e.g., diamond pickaxe: 5 -> 6)"armor": 0.5-> +0.5 armor for each armor piece"armor_toughness": 1.0-> +1 armor toughness for armor pieces"mining_efficiency": 2-> +20% mining speed for tools"knockback_resistance": 0.1-> +0.1 knockback resistance (applied to armor only)
Documentation Integration
Wiki Buttons
Add interactive documentation for the in-game manual:
from stewbeet import Item, WikiButton
item = Item.from_id("steel_ingot") # Get existing item
item.wiki_buttons = [
WikiButton([
{"text": "Steel is a stronger variant of iron.\n"},
{"text": "It provides better durability.", "color": "yellow"}
]),
WikiButton({"text": "This is another button.", "color": "aqua"})
]Manual Item
Create a recipe for the in-game manual:
Item(
id="manual",
manual_category="miscellaneous",
recipes=[
# Craft with book + steel ingot
CraftingShapelessRecipe(
category="misc",
ingredients=[Ingr("minecraft:book"), Ingr("steel_ingot")]
),
# Update manual by crafting it again
CraftingShapelessRecipe(
category="misc",
ingredients=[Ingr("manual")]
)
],
components={
"item_name": Mem.ctx.meta.get("stewbeet", {}).get("manual", {}).get("name") or "Manual"
}
)Audio Content
Custom Music Discs
Music disc generation maps .ogg assets to definitions so sounds, items, and references stay synchronized automatically.
# Auto-generate from assets/records/*.ogg files
generate_custom_records("auto")
# Or specify manually
generate_custom_records({
"my_disc": "My Custom Music.ogg",
"battle_theme": "Epic Battle Music.ogg"
})
# Cut the hearing range down from the vanilla 16 blocks
generate_custom_records("auto", attenuation_distance=5)Utility Functions
Essential Helper Functions
These helpers finalize definitions so generated output remains consistent, namespaced correctly, and ready for downstream plugins.
# Generate item models for all defined items
add_item_model_component(black_list=["excluded_items"])
# Add default names and lore where missing
add_item_name_and_lore_if_missing()
# Add namespace detection data (REQUIRED!)
add_private_custom_data_for_namespace()
# Add Smithed convention data
add_smithed_ignore_vanilla_behaviours_convention()
# Configure manual hover components
set_manual_components(white_list=["item_name", "lore", "custom_name", "damage", "max_damage"])
# Export definitions for debugging
export_all_definitions_to_json(f"{Mem.ctx.directory}/definitions_debug.json")Item Categories
Common categories for manual organization (but it's always up to you!):
| Category | Description |
|---|---|
"materials" | Raw materials, ingots, gems |
"equipment" | Tools, weapons, armor |
"building" | Building blocks, decorative blocks |
"miscellaneous" | Other items, special items |
"food" | Consumable items |
"decorations" | Paintings, decorative items |
Advanced Features
Texture Integration
Items automatically detect textures by name from assets/textures/:
steel_ingot.png->steel_ingotitemsteel_pickaxe.png->steel_pickaxetoolsteel_block.png->steel_blockcustom block
Accessing Existing Items
Item.from_id lets you fetch and mutate previously declared definitions, enabling staged configuration without re-creating objects.
# Get an existing item
item = Item.from_id("my_item")
# Modify it
item.manual_category = "materials"
item.wiki_buttons = [WikiButton({"text": "New info!"})]
# Add a recipe
item.recipes.append(CraftingShapelessRecipe(
category="misc",
ingredients=[Ingr("something")]
))Resource Locations
Never hardcode a resource location like f"{ns}:custom_blocks/{item}/place_secondary" again. Every location StewBeet derives from an item ID is exposed as a property returning a Resource.
A Resource is a string holding the full namespace:path location, so it works everywhere a path is expected: inside f-strings, as a write_function argument, as a dict key, compared against a literal. On top of that it gives you the underlying beet file.
item = Item.from_id("steel_ingot")
item.loot_table # "ns:i/steel_ingot" -> Resource[LootTable]
item.loot_table_for(4) # "ns:i/steel_ingot_x4"
item.item_model # "ns:steel_ingot" -> Resource[ItemModel]
item.model # "ns:item/steel_ingot" -> Resource[Model]
item.texture # "ns:item/steel_ingot" -> Resource[Texture]
item.recipe() # "ns:steel_ingot" -> Resource[Recipe]
# Use it directly in a command
write_function(f"{ns}:give_steel", f"loot give @s loot {item.loot_table}")NOTE
item_model follows the item_model component when you override it, while generated_item_model always points at the file StewBeet writes. They only differ if you set the component yourself.
Block Functions
Block.functions groups every mcfunction of a custom block:
block = Block.from_id("steel_block")
block.functions.place_main # "ns:custom_blocks/steel_block/place_main"
block.functions.place_secondary # "ns:custom_blocks/steel_block/place_secondary"
block.functions.destroy # "ns:custom_blocks/steel_block/destroy"
block.functions.tick # "ns:custom_blocks/steel_block/tick"
block.functions.second # "ns:custom_blocks/steel_block/second"
block.functions["my_own_call"] # any other function in that folder
block.functions.folder # "ns:custom_blocks/steel_block"
# Also available: place_check, search, get_facing, replace_item,
# update_seed_model, is_fully_grown, tick_2, second_5, minute
block.no_silk_touch_loot_table # "ns:custom_blocks/no_silk_touch_drop/steel_block"
block.seed_loot_table # "ns:seeds/steel_block"
block.advancement # placement advancement (BlockAlternative / BlockHead only)
# So the ticking example from the template becomes:
write_function(block.functions.tick, "particle heart ~ ~1 ~ 0.5 0.5 0.5 0.01 1")Block.functions returns a BlockFunctions object, which you can also build directly from a block ID if that reads better to you: no Block.from_id lookup needed, so it even works for IDs that have no definition:
from stewbeet import BlockFunctions
funcs = BlockFunctions("steel_block")
funcs.tick # "ns:custom_blocks/steel_block/tick"
BlockFunctions("steel_block").destroy # same paths as Block.from_id("steel_block").functions.destroy
BlockFunctions("gauge", namespace="other") # target another namespaceBoth forms produce the exact same Resource[Function] objects: use whichever you prefer.
Reading and Writing the File
res = item.loot_table
res.exists() # is the file in the pack yet?
res.get() # the beet LootTable, or None
res.obj # the beet LootTable, raises KeyError if missing
res.obj = LootTable({...}) # write it
res.write(LootTable({...})) # same, and returns the file
res.delete() # remove it if present
res.namespace # "ns"
res.relative_path # "i/steel_ingot"
res.file_type # beet.LootTableFor mcfunctions, .obj is a beet Function object, so you can append commands to an existing function directly: same result as calling write_function(res, ...):
# Run commands as the block display entity when it is placed
# (from a plugin running AFTER datapack.custom_blocks, so the function exists):
Block.from_id("super_stone").functions.place_secondary.obj.append("""
say Someone placed the super stone!
particle minecraft:explosion ~ ~ ~
""")TIP
Reading .obj before the plugin that generates it has run raises KeyError. Use .get() or .exists() when the file may not exist yet or do your code after plugin execution.
For the append example above, that's actually a feature: appending too early fails loudly instead of silently landing your commands before the block setup.
Complex Model Examples
Recognized Texture Patterns
StewBeet automatically recognizes texture patterns and generates appropriate models:
Block Patterns:
cube_all: Single texture (e.g.,my_block.png)cake: bottom, side, top, inner (e.g.,my_cake_bottom.png,my_cake_side.png,my_cake_top.png,my_cake_inner.png)orientable_with_bottom: front, bottom, side, top (e.g.,furnace_front.png,furnace_bottom.png,furnace_side.png,furnace_top.png)cube_bottom_top: bottom, side, top (e.g.,barrel_bottom.png,barrel_side.png,barrel_top.png)orientable: front, side, top (e.g.,dropper_front.png,dropper_side.png,dropper_top.png)cube_column: end, side (e.g.,pillar_end.png,pillar_side.png)
Item Patterns:
leather_armor: Items starting withleather_automatically use layer1 for overlay coloringoverlay: Items with_overlaytexture (e.g.,my_item.png+my_item_overlay.png-> layer0 + layer1)bow_pulling: Bow items with_pulling_0,_pulling_1,_pulling_2, etc. (sorted numerically)spear_in_hand: Spears ending with_spear+_in_handtexture variant (uses display context switching)
Powered States:
- Any block/item can have
_onvariants (e.g.,furnace_front.png+furnace_front_on.png) - StewBeet automatically generates both states if
_ontextures are detected, a furnace, smoker or blast furnace host showing the_onone while it burns
Multiple States (On/Off, Facing)
Example from SimplEnergy's Electric Furnace with on/off states and directional facing:
from stewbeet import Block, VanillaBlock, CraftingShapedRecipe, Ingr
# Create the electric furnace block
electric_furnace = Block(
id="electric_furnace",
vanilla_block=VanillaBlock(
id="minecraft:furnace",
block_facing="player" # Enables directional variants (north, east, south, west)
),
manual_category="energy",
recipes=[
CraftingShapedRecipe(
category="misc",
shape=["LLL", "LML", "III"],
ingredients={
"L": Ingr("minecraft:lapis_lazuli"),
"M": Ingr("machine_block"),
"I": Ingr("minecraft:iron_block")
}
)
],
components={
"item_name": {"text": "Electric Furnace", "color": "aqua"},
"custom_data": {"energy": {"usage": 20, "max_storage": 1600}}
}
)
# StewBeet automatically detects block model patterns from texture names:
# Required textures: electric_furnace_front.png, electric_furnace_side.png, electric_furnace_top.png, electric_furnace_bottom.png
# Optional for on state: electric_furnace_front_on.png (other sides can also have _on variants)
# Pattern recognized: "orientable_with_bottom" (front, side, top, bottom)
# Other supported patterns: "orientable" (front, side, top), "cube_bottom_top" (bottom, side, top), "cube_column" (end, side)Animated Item Models (Bow Pulling)
Example with bow pulling animations:
from stewbeet import Item, Ingr, CraftingShapedRecipe
custom_bow = Item(
id="super_bow",
base_item="minecraft:bow",
manual_category="equipment",
recipes=[
CraftingShapedRecipe(
category="equipment",
shape=[" XY", "X Y", " XY"],
ingredients={"X": Ingr("minecraft:stick"), "Y": Ingr("minecraft:string")}
)
],
components={
"item_name": {"text": "Super Bow", "color": "gold"},
"max_damage": 500
}
)
# StewBeet auto-generates pulling animation models and item_model JSON files:
# Required textures in assets/textures/item/:
# - super_bow.png (base bow texture)
# - super_bow_pulling_0.png (slightly pulled)
# - super_bow_pulling_1.png (half pulled)
# - super_bow_pulling_2.png (fully pulled)
#
# Generated files:
# - assets/models/item/super_bow_pulling_0.json, super_bow_pulling_1.json, super_bow_pulling_2.json
# - assets/items/super_bow.json (with condition and range_dispatch for pull states)Best Practices
Do's
- Use
Item,Block,Paintingclasses for clean, typed definitions - Use
Ingr()for all ingredient references - Call final adjustment functions at the end of
beet_default() - Organize definitions into separate modules (like
ores.py,additions.py) - Use meaningful categories for manual organization
- Set
vanilla_blockfor custom blocks after generation
Don'ts
- Don't modify
Mem.definitionsdirectly (use classes instead) - Don't use raw dictionaries for ingredients (use
Ingr()) - Don't forget to call final adjustment functions
- Don't skip
vanilla_blockconfiguration for custom blocks
Complete Example
# src/setup_definitions.py
from beet import Context
from stewbeet import *
from .definitions.additions import main as main_additions
from .definitions.ores import main as main_ores
def beet_default(ctx: Context):
# 1. Generate materials
main_ores()
# 2. Generate records
generate_custom_records("auto")
# 3. Add custom items
main_additions()
# 4. Set missing categories
for item_id in Mem.definitions.keys():
obj = Item.from_id(item_id)
if not obj.manual_category:
obj.manual_category = "miscellaneous"
# 5. Final adjustments (REQUIRED!)
add_item_model_component()
add_item_name_and_lore_if_missing()
add_private_custom_data_for_namespace()
add_smithed_ignore_vanilla_behaviours_convention()
set_manual_components(white_list=["item_name", "lore", "custom_name", "damage", "max_damage"])
# 6. Debug export
export_all_definitions_to_json(f"{Mem.ctx.directory}/definitions_debug.json")🎉 This modern approach creates clean, type-safe item definitions that work with every StewBeet plugin!
Check the real-world examples at the top of this page to see how it works in practice! 🚀
Glossary
| Term | Meaning |
|---|---|
| Definitions Setup | The user plugin responsible for creating and enriching Mem.definitions. |
| Definition | A typed object entry (Item, Block, Painting, etc.) used by downstream StewBeet plugins. |
| Mem.definitions | Global registry where all definitions are stored and shared through the pipeline. |
Next steps
- Writing to files: turn definitions into functions and files.
- Recipes: how a declared recipe reaches every crafting system.
- In-game manual: the book your definitions generate.