items#

block#

class Block(
*,
id: str,
base_item: str = 'minecraft:furnace',
manual_category: str | None = None,
recipes: list[RecipeBase] = <factory>,
override_model: JsonDict | None = None,
hand_model: JsonDict | None = None,
override_model_contexts: list[str] | None = None,
wiki_buttons: list[WikiButton] | TextComponent | None = None,
components: JsonDict = <factory>,
skip_gives: bool = False,
remainder: str | None = None,
ranged_weapon: RangedWeapon | None = None,
vanilla_block: VanillaBlock | None = None,
no_silk_touch_drop: NoSilkTouchDrop | LootTable | str | None = None,
on_place: str | None = None,
mining: Mining | None = None,
growing_seed: GrowingSeed | None = None,
)[source]#

Bases: Item

Represents a block item with vanilla block properties.

## Simple example

>>> from stewbeet import Mem
>>> block = Block(id="machine_block", vanilla_block=VanillaBlock(id="minecraft:stone"))
>>> block.id
'machine_block'
>>> block.vanilla_block.id
'minecraft:stone'
>>> block.id in Mem.definitions
True
>>> block is Block.from_id("machine_block")
True

## Big example with all fields

>>> from stewbeet import CraftingShapelessRecipe, WikiButton, NoSilkTouchDrop, GrowingSeed, GrowingSeedLoot, Ingr
>>> obj = BlockAlternative(
...     id="stardust_seed",
...     manual_category="miscellaneous",
...     recipes=[
...         CraftingShapelessRecipe(ingredients=8*[Ingr("stardust_fragment")] + [Ingr("minecraft:wheat_seeds")])
...     ],
...     override_model={"parent":"item/generated","textures":{"layer0":"stardust:item/stardust_seed"}},
...     wiki_buttons=[WikiButton({"text":"A magical seed that grows stardust.","color":"aqua"})],
...     components={
...         "item_name": {"text":"Stardust Seed","color":"aqua"},
...         "max_stack_size": 64,
...     },
...     vanilla_block=VanillaBlock(id="minecraft:wheat"),
...     no_silk_touch_drop=NoSilkTouchDrop(id="stardust_fragment", count=1),
...     growing_seed=GrowingSeed(
...         texture_basename="stardust",
...         seconds=480,
...         planted_on="diamond_block",
...         loots=[GrowingSeedLoot(id="stardust_fragment", rolls=3)]
...     ),
... )
>>> also_obj = Block.from_id("stardust_seed")
>>> obj is also_obj
True

## Resource locations

>>> block.functions.place_main
'your_namespace:custom_blocks/machine_block/place_main'
>>> block.functions.place_secondary
'your_namespace:custom_blocks/machine_block/place_secondary'
>>> block.functions.destroy
'your_namespace:custom_blocks/machine_block/destroy'
>>> block.functions["any_custom_function"]
'your_namespace:custom_blocks/machine_block/any_custom_function'
>>> block.functions.folder
'your_namespace:custom_blocks/machine_block'
>>> block.loot_table
'your_namespace:i/machine_block'
>>> block.no_silk_touch_loot_table
'your_namespace:custom_blocks/no_silk_touch_drop/machine_block'

Growing seed stages use the seed texture basename, not the block ID:

>>> obj.seed_stage_item_model(2)
'your_namespace:seeds/stardust_stage_2'
>>> obj.seed_stage_model(2)
'your_namespace:item/seeds/stardust_stage_2'
>>> obj.seed_loot_table
'your_namespace:seeds/stardust_seed'

Regular custom blocks are detected by the smithed custom_block library, so they have no placement advancement of their own:

>>> block.advancement
Traceback (most recent call last):
...
ValueError: Block 'machine_block' uses base_item 'minecraft:furnace' and has no placement advancement (...)
vanilla_block: VanillaBlock | None[source]#

(Optional) If the block is based on a vanilla block, this defines which one and whether to apply facing.

no_silk_touch_drop: NoSilkTouchDrop | LootTable | str | None[source]#

(Optional) What drops without silk touch. Deterministic with NoSilkTouchDrop(id="raw_simplunium") or the item id “raw_simplunium”, dynamic with a beet LootTable.

on_place: str | None[source]#

Deprecated since v3.5.0.

mining: Mining | None[source]#

(Optional) The tool needed to get the item when breaking it. A real host left unset becomes the first of Mining.hosts, an interaction host checks the breaker’s tool itself.

growing_seed: GrowingSeed | None[source]#

(Optional) Defines a seed that grows over time (Stardust Seed from Stardust Fragment).

property functions: BlockFunctions[source]#

The mcfunctions of this custom block, ex: block.functions.place_secondary.

property no_silk_touch_loot_table: Resource[LootTable][source]#

The loot table used when this block is broken without silk touch.

property seed_loot_table: Resource[LootTable][source]#

The loot table dropped when this growing seed is fully grown and harvested.

property alternative_advancement: Resource[Advancement][source]#

The advancement detecting the placement of an item frame based custom block.

property head_advancement: Resource[Advancement][source]#

The advancement detecting the placement of a player head based custom block.

property advancement: Resource[Advancement][source]#

The advancement detecting the placement of this custom block.

Returns:

The placement advancement

Return type:

Resource[Advancement]

Raises:

ValueError – If the block is a regular custom block, since those are handled by the smithed custom_block library instead of a per-block advancement.

The function searching the placed player head of this custom block.

seed_stage_name(stage: str | int) → str[source]#

Get the shared base name of a growth stage of this growing seed.

Parameters:

stage – The growth stage, ex: 0, 1, 2, …

Returns:

The stage name, ex: “stardust_stage_2”

Return type:

str

seed_stage_item_model(
stage: str | int,
) → Resource[ItemModel][source]#

Get the item model of a growth stage of this growing seed.

Parameters:

stage – The growth stage, ex: 0, 1, 2, …

Returns:

The item model, ex: “your_namespace:seeds/stardust_stage_2”

Return type:

Resource[ItemModel]

seed_stage_model(
stage: str | int,
) → Resource[Model][source]#

Get the model of a growth stage of this growing seed.

Parameters:

stage – The growth stage, ex: 0, 1, 2, …

Returns:

The model, ex: “your_namespace:item/seeds/stardust_stage_2”

Return type:

Resource[Model]

seed_stage_texture(
stage: str | int,
) → Resource[Texture][source]#

Get the texture of a growth stage of this growing seed.

Parameters:

stage – The growth stage, ex: 0, 1, 2, …

Returns:

The texture, ex: “your_namespace:item/seeds/stardust_stage_2”

Return type:

Resource[Texture]

class BlockAlternative(
*,
id: str,
base_item: str = 'minecraft:furnace',
manual_category: str | None = None,
recipes: list[RecipeBase] = <factory>,
override_model: JsonDict | None = None,
hand_model: JsonDict | None = None,
override_model_contexts: list[str] | None = None,
wiki_buttons: list[WikiButton] | TextComponent | None = None,
components: JsonDict = <factory>,
skip_gives: bool = False,
remainder: str | None = None,
ranged_weapon: RangedWeapon | None = None,
vanilla_block: VanillaBlock | None = None,
no_silk_touch_drop: NoSilkTouchDrop | LootTable | str | None = None,
on_place: str | None = None,
mining: Mining | None = None,
growing_seed: GrowingSeed | None = None,
)[source]#

Bases: Block

Represents a block that uses an item frame for placement (e.g., servo inserter/extractor).

>>> ba = BlockAlternative(id="servo_inserter", vanilla_block=VanillaBlock(contents=True))
>>> ba.base_item
'minecraft:item_frame'
>>> ba.advancement
'your_namespace:custom_block_alternative/servo_inserter'
>>> ba.functions.search
'your_namespace:custom_blocks/servo_inserter/search'
class BlockHead(
*,
id: str,
base_item: str = 'minecraft:furnace',
manual_category: str | None = None,
recipes: list[RecipeBase] = <factory>,
override_model: JsonDict | None = None,
hand_model: JsonDict | None = None,
override_model_contexts: list[str] | None = None,
wiki_buttons: list[WikiButton] | TextComponent | None = None,
components: JsonDict = <factory>,
skip_gives: bool = False,
remainder: str | None = None,
ranged_weapon: RangedWeapon | None = None,
vanilla_block: VanillaBlock | None = None,
no_silk_touch_drop: NoSilkTouchDrop | LootTable | str | None = None,
on_place: str | None = None,
mining: Mining | None = None,
growing_seed: GrowingSeed | None = None,
)[source]#

Bases: Block

Represents a block that uses a player head for placement.

>>> bh = BlockHead(id="custom_head", vanilla_block=VanillaBlock(id="minecraft:player_head"))
>>> bh.base_item
'minecraft:player_head'
>>> bh.advancement
'your_namespace:custom_block_head/custom_head'
>>> bh.head_search
'your_namespace:custom_blocks/_player_head/search_custom_head'

external_item#

class ExternalItem(
id: str,
custom_data_predicate: JsonDict | str,
components: JsonDict = <factory>,
loot_table: str | Resource[LootTable] | None = None,
base_item: str = 'minecraft:recovery_compass',
)[source]#

Bases: StMapping

Represents an item from an external datapack.

>>> obj = ExternalItem(
...     id="mechanization:raw_tin",
...     base_item="minecraft:structure_block",
...     custom_data_predicate={"smithed": {"dict": {"raw": {"tin": True}}}, "mechanization": {"id": "raw_tin"}},
...     components={
...         "item_name": {"text": "Raw Tin"},
...         "lore": [{"text": "A chunk of unrefined tin."}],
...     },
...     loot_table="mechanization:base/tin_raw",
... )
>>> obj.loot_table
'mechanization:base/tin_raw'
>>> obj = ExternalItem("simplenergy:machine_block", custom_data_predicate={"simplenergy": {"machine_block": True}})
>>> obj.id
'simplenergy:machine_block'
id: str[source]#

Unique identifier for the item, e.g. ‘mechanization:raw_tin’, ‘simplenergy:machine_block’.

custom_data_predicate: JsonDict | str[source]#

Predicate to use for matching custom data when used in recipes, e.g. {“smithed”: {“dict”: {“raw”: {“tin”: True}}}}.

components: JsonDict[source]#

Additional components for the item, e.g. {“item_name”: {“text”: “Raw Tin”}, “lore”: [{“text”: “Some lore”}]}.

loot_table: str | Resource[LootTable] | None[source]#

(Optional) Loot table path to use to get the item, e.g. “mechanization:base/tin_raw”.

Beware: unlike Item.loot_table (which is generated by StewBeet at “{ns}:i/{id}”), this points into the OTHER datapack and is supplied by the user, hence being optional.

base_item: str[source]#

(Optional) Base item identifier, e.g. “minecraft:poisonous_potato”.

recipe_loot_table_for(
result_count: int | JsonDict,
) → Resource[LootTable][source]#

Get the loot table THIS project generates to give this external item as a recipe result.

Parameters:

result_count – The amount to give, ex: 1, 5, {“min”:4,”max”:6}

Returns:

The loot table, ex: “your_namespace:recipes/mechanization/raw_tin”

Return type:

Resource[LootTable]

>>> obj = ExternalItem("mechanization:raw_tin", custom_data_predicate={}, loot_table="mechanization:base/tin_raw")
>>> obj.recipe_loot_table_for(1)
'your_namespace:recipes/mechanization/raw_tin'
>>> obj.recipe_loot_table_for(5)
'your_namespace:recipes/mechanization/raw_tin_x5'
static json_dump(obj: Any) → Any[source]#

Custom JSON dump function to prevent escaping of certain fields.

features#

What a custom block is made of: its vanilla host, its drops and growth, how it is mined, and the projectile tuning of a weapon.

MODEL_MARGIN: float = 1.002[source]#

The default VanillaBlock.margin: about 1/60 of a pixel on each side of a full block.

MINING_LEVELS: tuple[str, ...] = ('wood', 'stone', 'iron', 'diamond', 'netherite')[source]#

Mining levels from the weakest, each tool of a level also mining every level below it.

TOOL_MATERIALS: tuple[tuple[str, ...], ...] = (('wooden', 'golden'), ('stone', 'copper'), ('iron',), ('diamond',), ('netherite',))[source]#

The vanilla tool materials of each of MINING_LEVELS.

MINING_HOSTS: dict[str, tuple[str, ...]] = {'diamond': ('minecraft:obsidian', 'minecraft:netherite_block', 'minecraft:crying_obsidian'), 'iron': ('minecraft:diamond_block', 'minecraft:gold_block', 'minecraft:emerald_block', 'minecraft:raw_gold_block'), 'stone': ('minecraft:iron_block', 'minecraft:raw_iron_block', 'minecraft:lapis_block', 'minecraft:waxed_copper_block'), 'wood': ('minecraft:cobblestone', 'minecraft:stone_bricks', 'minecraft:polished_deepslate', 'minecraft:coal_block')}[source]#

Vanilla blocks dropping themselves only when mined with a pickaxe of the level, the first being the default host.

MACHINE_HOSTS: tuple[str, ...] = ('minecraft:furnace', 'minecraft:smoker', 'minecraft:blast_furnace', 'minecraft:brewing_stand')[source]#

Hosts whose work VanillaBlock.machine_speed speeds up.

LIT_HOSTS: tuple[str, ...] = ('minecraft:furnace', 'minecraft:smoker', 'minecraft:blast_furnace')[source]#

Hosts whose display shows the block’s _on model while they burn.

STAIRS_SHAPES: tuple[str, ...] = ('straight', 'inner_left', 'inner_right', 'outer_left', 'outer_right')[source]#

The shape a stairs host takes from its neighbours, its display showing the model’s corner copy for each but the first.

class Interaction(
*,
width: float = 1.01,
height: float = 1.01,
seat: float | None = None,
hits: int = 1,
hit_timeout: int = 20,
sound: str = 'minecraft:block.stone',
)[source]#

Bases: object

An interaction entity standing in the block, for a host that cannot be mined or targeted: barrier, structure void, light.

Hitting it breaks the block, dropping its item unless the breaker is in creative.

>>> Interaction(seat=0.5, hits=3)
Interaction(width=1.01, height=1.01, seat=0.5, hits=3, hit_timeout=20, sound='minecraft:block.stone')
width: float[source]#
height: float[source]#

From the bottom of the block, a little more than a block so it is targeted before the host.

seat: float | None[source]#

Height above the bottom of the block a player sits at when using it, None when it is not a seat.

hits: int[source]#

Hits needed to break it, each counting only when it comes less than hit_timeout ticks after the previous one.

hit_timeout: int[source]#
sound: str[source]#

Sound group played on each hit and on the break, as <sound>.hit and <sound>.break.

class Mining(
*,
tool: Literal['pickaxe', 'axe', 'shovel', 'hoe'] = 'pickaxe',
level: Literal['wood', 'stone', 'iron', 'diamond', 'netherite'] = 'wood',
)[source]#

Bases: object

The tool needed to get the block’s item when breaking it, the block dropping nothing with a weaker one.

>>> mining = Mining(tool="pickaxe", level="iron")
>>> mining.tools
['minecraft:iron_pickaxe', 'minecraft:diamond_pickaxe', 'minecraft:netherite_pickaxe']
>>> mining.item_tag, mining.hosts[0]
('your_namespace:mining/pickaxe_iron', 'minecraft:diamond_block')
tool: Literal['pickaxe', 'axe', 'shovel', 'hoe'][source]#
level: Literal['wood', 'stone', 'iron', 'diamond', 'netherite'][source]#
property tools: list[str][source]#

The vanilla tools of this level or a stronger one.

property item_tag: Resource[ItemTag][source]#

The item tag listing tools.

property hosts: tuple[str, ...][source]#

The vanilla hosts making vanilla itself require this tool, empty when none does.

class RangedWeapon(
*,
charge_time: float | None = None,
damage_multiplier: float = 1.0,
ammunition: str | None = None,
name: str = 'Heavy Draw',
)[source]#

Bases: object

How a bow or a crossbow shoots, through a hidden enchantment the item carries.

>>> RangedWeapon(charge_time=2.5, damage_multiplier=1.5, ammunition="bolt").name
'Heavy Draw'
charge_time: float | None[source]#

Seconds a crossbow takes to load, vanilla’s being 1.25.

damage_multiplier: float[source]#

Applied to the damage of the arrows it shoots.

ammunition: str | None[source]#

The only item of the definitions a crossbow loads, anything else being given back.

name: str[source]#

What the tooltip calls its enchantment, red as a curse so a grindstone keeps it.

class VanillaBlock(
*,
id: str | None = '',
contents: bool = False,
block_facing: Literal[False, 'player'] = False,
visual_facing: Literal['none', 'player', 'item_frame'] = 'none',
apply_facing: Literal[False, True, 'entity', None] = None,
half: Literal['click'] | None = None,
interaction: Interaction | None = None,
uvlock: bool = False,
margin: float = 1.002,
machine_speed: float | None = None,
)[source]#

Bases: StMapping

Represents a vanilla block with explicit facing semantics.

This class separates block orientation into two independent axes: - block_facing: controls the orientation of the placed vanilla block itself - visual_facing: controls the orientation of the visual entity/display

Legacy apply_facing field is still accepted for backward compatibility: - apply_facing=True -> block_facing="player", visual_facing="player" - apply_facing="entity" -> visual_facing="player" - apply_facing=False -> no change (defaults)

Default behavior (no facing):

>>> vb = VanillaBlock(id="minecraft:stone")
>>> vb.id
'minecraft:stone'
>>> vb.block_facing
False
>>> vb.visual_facing
'none'

Legacy apply_facing=True (block + visual rotation):

>>> vb = VanillaBlock(id="minecraft:furnace", apply_facing=True)
>>> vb.block_facing
'player'
>>> vb.visual_facing
'player'

Legacy apply_facing="entity" (visual only):

>>> vb = VanillaBlock(id="minecraft:stone", apply_facing="entity")
>>> vb.block_facing
False
>>> vb.visual_facing
'player'

Item frame custom block (no rotation):

>>> vb = VanillaBlock(contents=True)
>>> vb.contents
True
>>> vb.id is None
True
>>> vb.visual_facing
'none'

Item frame rotated like player (4 horizontal directions):

>>> vb = VanillaBlock(contents=True, visual_facing="player")
>>> vb.visual_facing
'player'

Item frame using its own facing (6 directions):

>>> vb = VanillaBlock(contents=True, visual_facing="item_frame")
>>> vb.visual_facing
'item_frame'

Invalid: block_facing with contents=True:

>>> VanillaBlock(contents=True, block_facing="player")
Traceback (most recent call last):
...
ValueError: contents=True cannot use block_facing="player"; use visual_facing instead.

New fields directly:

>>> vb = VanillaBlock(id="minecraft:barrel", block_facing="player")
>>> vb.block_facing
'player'
>>> vb.visual_facing
'player'

A slab taking its half from where the player clicks:

>>> VanillaBlock(id="oak_slab", half="click").half_property
'type'
>>> VanillaBlock(id="oak_stairs", half="click").half_property
'half'
id: str | None[source]#

The vanilla block ID, e.g. ‘minecraft:stone’, “minecraft:conduit[waterlogged=false]”.

contents: bool[source]#

For blocks using item frames and no vanilla block, e.g. servo inserter/extractor from SimplEnergy.

block_facing: Literal[False, 'player'][source]#

Whether to rotate the placed vanilla block based on player orientation ([facing=…] blockstate).

visual_facing: Literal['none', 'player', 'item_frame'][source]#

Source of the visual orientation. “none” is no rotation, “player” gives 4 horizontal directions, “item_frame” gives 6 from the item frame’s Facing.

apply_facing: Literal[False, True, 'entity', None][source]#

Legacy field for backward compatibility. Prefer block_facing and visual_facing.

half: Literal['click'] | None[source]#

“click” takes the top or bottom state of a slab, stairs or trapdoor host from the half of the block the player clicked.

interaction: Interaction | None[source]#

An interaction entity breaking the block when hit, for an invisible host such as “minecraft:barrier”.

uvlock: bool[source]#

With visual_facing=”player”, show a copy of the model turned for each direction instead of turning the display. Its textures then keep the world grid, as uvlock does.

margin: float[source]#

Scale of each element of the displayed model about its own center, so none of its faces lies on one of the host. 1.0: none.

machine_speed: float | None[source]#

How many times faster a host of MACHINE_HOSTS cooks or brews.

property base_id: str[source]#

The id without its states or data, empty for an item frame block.

property half_property: str[source]#

The state holding the half: type for a slab, half for stairs and trapdoors.

property host_states: dict[str, str][source]#

The host states that change after placement, each with the suffix of the model copy the display shows in it.

>>> VanillaBlock(id="oak_stairs").host_states["shape=outer_left"], VanillaBlock(id="furnace").host_states
('_outer_left', {'lit=false': '', 'lit=true': '_on'})
class NoSilkTouchDrop(
*,
id: str = '',
loot_table: LootTable | str | None = None,
count: dict[str, int] | int = 1,
experience: dict[str, int] | float = 0.0,
)[source]#

Bases: StMapping

Defines deterministic drops when the block is broken without silk touch.

>>> nsd = NoSilkTouchDrop(id="raw_iron")
>>> nsd.id
'raw_iron'
>>> nsd.count, nsd.experience
(1, 0.0)
>>> NoSilkTouchDrop(loot_table="my_ns:blocks/ruby_ore", experience=2.5).loot_table
'my_ns:blocks/ruby_ore'
id: str[source]#

The item ID to drop when the block is broken without silk touch, e.g. ‘raw_simplunium’. Empty when loot_table drops instead.

loot_table: LootTable | str | None[source]#

(Optional) A loot table, or its path, dropping instead of id and count, rolled with the breaker’s tool.

count: dict[str, int] | int[source]#

(Optional) The count of items to drop. Can be an integer or a dict with ‘min’ and ‘max’ keys. Default is 1.

experience: dict[str, int] | float[source]#

(Optional) Experience points dropped with it, like vanilla ores do, as a dict with ‘min’ and ‘max’ keys or a number. The fractional part of a number is the chance of one more point: 0.5 gives 1 point half of the time.

class GrowingSeedLoot(
*,
id: str,
rolls: JsonDict | int = 1,
fortune: JsonDict | None = None,
)[source]#

Bases: StMapping

Defines a single loot entry for a growing seed.

>>> gsl = GrowingSeedLoot(id="stardust_fragment", rolls=3)
>>> gsl.id
'stardust_fragment'
>>> gsl.rolls
3
id: str[source]#

The item ID to drop, e.g. “stardust_fragment”, “minecraft:stone”.

rolls: JsonDict | int[source]#

(Optional) The roll definition for the loot, e.g. {“type”:”minecraft:uniform”,”min”:3,”max”:9}.

fortune: JsonDict | None[source]#

(Optional) The fortune modifier for the loot, e.g. {“extra”:0,”probability”:0.5}.

class GrowingSeed(
*,
texture_basename: str,
seconds: int,
planted_on: str,
loots: list[GrowingSeedLoot] | str,
)[source]#

Bases: StMapping

Defines a seed that grows over time (Stardust Seed from Stardust Fragment).

>>> gs = GrowingSeed(
...     texture_basename="stardust", seconds=480, planted_on="diamond_block", loots=[GrowingSeedLoot(id="stardust_fragment")]
... )
>>> gs.texture_basename
'stardust'
>>> gs.seconds
480
texture_basename: str[source]#

The base name of the texture for the growing seed, e.g. ‘stardust’.

seconds: int[source]#

The time in seconds it takes for the seed to grow, e.g. 480.

planted_on: str[source]#

The block ID on which the seed can be planted, e.g. ‘diamond_block’.

loots: list[GrowingSeedLoot] | str[source]#

The list of loot definitions for the seed when it is harvested, or a loot path path.

item#

class Item(
*,
id: str,
base_item: str = 'minecraft:recovery_compass',
manual_category: str | None = None,
recipes: list[RecipeBase] = <factory>,
override_model: JsonDict | None = None,
hand_model: JsonDict | None = None,
override_model_contexts: list[str] | None = None,
wiki_buttons: list[WikiButton] | TextComponent | None = None,
components: JsonDict = <factory>,
skip_gives: bool = False,
remainder: str | None = None,
ranged_weapon: RangedWeapon | None = None,
)[source]#

Bases: StMapping

Represents an item with a unique identifier.

## Simple example

>>> from stewbeet import Mem
>>> item = Item(id="multimeter", base_item="minecraft:warped_fungus_on_a_stick")
>>> item.id
'multimeter'
>>> item.base_item
'minecraft:warped_fungus_on_a_stick'
>>> item.id in Mem.definitions
True
>>> item is Item.from_id("multimeter")
True

## Instance without registration in Mem.definitions

>>> nonreg_item = Item(id="")   # Item with empty ID won't be registered
>>> nonreg_item.id = "temporary_item"
>>> "temporary_item" in Mem.definitions
False
>>> nonreg_item is Item.from_id("temporary_item", strict=False)
False

## Big example with all fields

>>> from stewbeet import CraftingShapedRecipe, WikiButton, Ingr
>>> obj = Item(
...     id="stardust_ingot",
...     base_item="minecraft:raw_iron",
...     manual_category="materials",
...     recipes=[
...         CraftingShapedRecipe(
...             shape=["###","#F#","###"], ingredients={"#":Ingr("stardust_fragment"),"F":Ingr("minecraft:iron_ingot")}
...         )
...     ],
...     override_model={"parent":"item/generated","textures":{"layer0":"stardust:item/stardust_ingot"}},
...     wiki_buttons=[WikiButton({"text":"This is a stardust ingot.","color":"aqua"})],
...     components={
...         "item_name": {"text":"Stardust Ingot","color":"aqua"},
...         "max_stack_size": 99,
...     }
... )
>>> also_obj = Item.from_id("stardust_ingot")
>>> obj is also_obj
True

## Resource locations (namespace falls back to “your_namespace” outside a build)

>>> obj.loot_table
'your_namespace:i/stardust_ingot'
>>> obj.loot_table_for(5)
'your_namespace:i/stardust_ingot_x5'
>>> obj.loot_table_for({"min": 4, "max": 6})
'your_namespace:i/stardust_ingot_x4to6'
>>> obj.item_model
'your_namespace:stardust_ingot'
>>> obj.model
'your_namespace:item/stardust_ingot'
>>> obj.texture
'your_namespace:item/stardust_ingot'
>>> obj.recipe(), obj.recipe(2)
('your_namespace:stardust_ingot', 'your_namespace:stardust_ingot_2')

A user-defined “item_model” component wins, but the generated file location doesn’t move:

>>> obj.components["item_model"] = "minecraft:air"
>>> obj.item_model
'minecraft:air'
>>> obj.generated_item_model
'your_namespace:stardust_ingot'
>>> del obj.components["item_model"]
id: str[source]#

Unique identifier for the item, e.g. ‘multimeter’, ‘simplunium_block’.

base_item: str[source]#

Represents an item with a unique identifier, e.g ‘minecraft:recovery_compass’.

manual_category: str | None[source]#

(Optional) manual category for organizing items in the ingame-manual.

recipes: list[RecipeBase][source]#

(Optional) List of recipes associated with this item.

override_model: JsonDict | None[source]#

(Optional) Merge with/Override auto-generated item model (based on the textures folder).

DEFAULT_OVERRIDE_MODEL_CONTEXTS: ClassVar[list[str]] = ['none', 'fixed'][source]#

Display contexts that keep the regular model when a hand_model is defined: item display entities and item frames.

hand_model: JsonDict | None[source]#

(Optional) Model used instead of the regular one in most display contexts (hand, gui, ground, …). See override_model_contexts. If None, the item uses the same model everywhere.

override_model_contexts: list[str] | None[source]#

(Optional) When hand_model is set, display contexts in which the regular model is still used. Defaults to DEFAULT_OVERRIDE_MODEL_CONTEXTS, i.e. item display entities and item frames.

wiki_buttons: list[WikiButton] | TextComponent | None[source]#

(Optional) Additional informations to be displayed in the ingame manual.

components: JsonDict[source]#

(Optional) Additional custom components for this item, e.g. “item_name”: {…}, etc.

skip_gives: bool[source]#

(Optional) If True, loot tables and give_all chests won’t give this item. Useful for items that are never meant to be obtained by players.

remainder: str | None[source]#

(Optional) Id in the definitions of the item left once this one is eaten or drunk, ex: “beer_mug”. It becomes the use_remainder component, carrying the container’s item_name, item_model and custom_data.

ranged_weapon: RangedWeapon | None[source]#

(Optional) Charge time, damage and ammunition of a bow or a crossbow.

origin: SourceOrigin | None[source]#

Where this definition was declared, captured by the source_maps plugin so content a plugin generates from it maps back to the declaration instead of to the plugin. None unless that plugin is active.

loot_table_for(
result_count: int | JsonDict,
) → Resource[LootTable][source]#

Get the loot table giving this item in the requested amount.

Parameters:

result_count – The amount to give, ex: 1, 5, {“min”:4,”max”:6}

Returns:

The loot table, ex: “your_namespace:i/stardust_ingot_x5”

Return type:

Resource[LootTable]

property loot_table: Resource[LootTable][source]#

The loot table giving one of this item, ex: “your_namespace:i/stardust_ingot”.

property ranged_weapon_enchantment: Resource[Enchantment][source]#

The hidden enchantment applying ranged_weapon, ex: “your_namespace:ranged_weapon/crossbow”.

property item_model: Resource[ItemModel][source]#

The item model this item renders as, honoring the “item_model” component when set.

Beware: this is what the item points to, which the user can override to anything. Use generated_item_model for the location StewBeet actually writes the file at.

property generated_item_model: Resource[ItemModel][source]#

The item model location StewBeet generates for this item, ex: “your_namespace:stardust_ingot”.

property model: Resource[Model][source]#

The model generated for this item, ex: “your_namespace:item/stardust_ingot”.

property texture: Resource[Texture][source]#

The main texture of this item, ex: “your_namespace:item/stardust_ingot”.

recipe(
index: int = 1,
) → Resource[Recipe][source]#

Get the vanilla recipe file of this item.

Parameters:

index – The recipe number when the item has multiple vanilla recipes (1-based)

Returns:

The recipe, ex: “your_namespace:stardust_ingot” or “your_namespace:stardust_ingot_2”

Return type:

Resource[Recipe]

painting#

class PaintingData(
*,
texture: str | None = None,
author: TextComponent | None = None,
title: TextComponent | None = None,
width: int,
height: int,
)[source]#

Bases: StMapping

Data class for painting-specific data.

>>> pd = PaintingData(
...     texture="stewbeet_painting_2x2",            # Defaults to the item id, here "assets/textures/stewbeet_painting_2x2.png"
...     author={"text":"Stoupy","color":"yellow"},  # Author defaults to ctx.project_author if not given
...     title={"text":"Da' Icon","color":"gray"},   # Title defaults to item name if not given
...     width=4,
...     height=3
... )
texture: str | None[source]#

Texture identifier for the painting. Defaults to item id if not provided.

author: TextComponent | None[source]#

Author of the painting. Defaults to ctx.project_author if not provided.

title: TextComponent | None[source]#

Title of the painting. Defaults to item name if not provided.

width: int[source]#

Width of the painting in blocks.

height: int[source]#

Height of the painting in blocks.

class Painting(
*,
id: str,
base_item: str = 'minecraft:painting',
manual_category: str | None = None,
recipes: list[RecipeBase] = <factory>,
override_model: JsonDict | None = None,
hand_model: JsonDict | None = None,
override_model_contexts: list[str] | None = None,
wiki_buttons: list[WikiButton] | TextComponent | None = None,
components: JsonDict = <factory>,
skip_gives: bool = False,
remainder: str | None = None,
ranged_weapon: RangedWeapon | None = None,
painting_data: PaintingData,
)[source]#

Bases: Item

Represents a custom painting item.

### Texture will default to “stewbeet_painting_2x2”, author and title will default accordingly

>>> my_painting = Painting(
...     id="stewbeet_painting_2x2",
...     painting_data=PaintingData(
...         author={"text":"An Artist I would say","color":"yellow"},
...         width=2,
...         height=2
...     ),
...     recipes=[],
...     components={
...         "max_stack_size": 16
...     }
... )
>>> my_painting
Painting(id='stewbeet_painting_2x2', base_item='minecraft:painting', manual_category=None, recipes=[], override_model=None, hand_model=None, override_model_contexts=None, wiki_buttons=None, components={'max_stack_size': 16, 'painting/variant': 'your_namespace:stewbeet_painting_2x2'}, skip_gives=False, remainder=None, ranged_weapon=None, painting_data=PaintingData(texture='stewbeet_painting_2x2', author={'text': 'An Artist I would say', 'color': 'yellow'}, title={'text': 'Stewbeet Painting 2X2'}, width=2, height=2))

### Resource locations

>>> my_painting.variant
'your_namespace:stewbeet_painting_2x2'
>>> my_painting.painting_texture
'your_namespace:painting/stewbeet_painting_2x2'
>>> my_painting.asset_id
'your_namespace:stewbeet_painting_2x2'
painting_data: PaintingData[source]#
property variant: Resource[PaintingVariant][source]#

The painting variant of this painting, honoring the “painting/variant” component when set.

property painting_texture: Resource[Texture][source]#

The texture of this painting, ex: “your_namespace:painting/stewbeet_painting_2x2”.

property asset_id: str[source]#

The asset_id referenced by the painting variant, ex: “your_namespace:stewbeet_painting_2x2”.

Beware: this is NOT the texture resource location. Minecraft resolves a painting asset_id of “ns:name” to “assets/ns/textures/painting/name.png”, so the two strings differ.

wiki_button#

class WikiButton(content: TextComponent)[source]#

Bases: object

Represents a button in the ingame manual that provides additional information about an item.

>>> content = [{"text": "Hello", "color": "yellow"}]
>>> button = WikiButton(content)
>>> button.content
[{'text': 'Hello', 'color': 'yellow'}]
>>> button.content[0]
{'text': 'Hello', 'color': 'yellow'}
>>> WikiButton(button.content[0]).content["text"]
'Hello'
content[source]#
to_dict() → str | list[Any] | dict[str, Any][source]#

Convert to JSON-serializable format (returns the underlying TextComponent).