Définir items et blocs
Les définitions d'items sont au cœur du framework StewBeet. Elles définissent les custom items, blocks, équipements et recipes, ainsi que leurs propriétés en utilisant des classes Python modernes. La configuration des définitions crée une base de données complète de tout le custom content que les plugins suivants utilisent pour générer les datapacks et resource packs.
C'est typiquement le premier plugin créé par l'utilisateur dans le pipeline (après stewbeet.plugins.initialize).
Démonstration de quelques fonctionnalités
Définitions d'items du Template Extensive :
Fichier d'exemple : extensive/src/setup_definitions.py
Exemple réel : SimplEnergy/src/definitions/setup_main.py
Requis : Framework StewBeet (from stewbeet import *)
Requis : Contexte Beet (from beet import Context)
Position : Doit être appelé tôt dans le pipeline avant les autres plugins qui dépendent des définitions
Intégration : Fonctionne avec tous les plugins StewBeet qui traitent les définitions d'items
- Définir des custom items, blocks et équipements en utilisant des classes Python
- Configurer la génération automatique de matériaux (minerais, lingots, outils, armures)
- Configurer les recipes de craft avec des classes typées
- Établir les relations entre les items et leurs utilisations
- Configurer les noms, lores et catégories des items
- Lier les items à leurs textures et models
Configuration
Structure de base
Cette structure définit le cycle de vie de votre plugin de définitions : génération, normalisation des métadonnées, post-traitements requis et export de debug optionnel.
from beet import Context
from stewbeet import *
# Importer vos modules de définitions
from .definitions.additions import main as main_additions
from .definitions.ores import main as main_ores
def beet_default(ctx: Context):
# 1. Générer les matériaux et équipements
main_ores()
# 2. Générer les custom records
generate_custom_records("auto")
# 3. Ajouter les custom items, blocks et paintings
main_additions()
# 4. Définir les catégories manquantes
for item in Mem.definitions.keys():
obj = Item.from_id(item)
if not obj.manual_category:
obj.manual_category = "miscellaneous"
# 5. Ajustements finaux (REQUIS !)
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. Export de débogage (optionnel)
export_all_definitions_to_json(f"{Mem.ctx.directory}/definitions_debug.json")Concepts de base
La base de données Mem.definitions
Toutes les définitions d'items sont stockées dans Mem.definitions, un dictionnaire global qui se remplit lorsque vous créez des instances Item, Block ou Painting :
# Créer un item l'enregistre automatiquement
item = Item(id="my_item", base_item="minecraft:iron_ingot")
# Y accéder de n'importe où
same_item = Item.from_id("my_item")
assert item is same_item # C'est le même objet !
# Vérifier le dictionnaire sous-jacent
assert "my_item" in Mem.definitionsClasse Item
Définition des propriétés de la classe Item :
Propriétés Item
| Propriété | Type | Description |
|---|---|---|
id | str | Requis : Identifiant unique (ex., "magic_sword") |
base_item | str | Item Minecraft de base (défaut : CUSTOM_ITEM_VANILLA) |
manual_category | str | None | Catégorie pour l'organisation du manuel en jeu |
recipes | list[RecipeBase] | Liste d'objets recipe qui créent cet item |
override_model | JsonDict | None | Override de l'item model auto-généré |
hand_model | JsonDict | None | Model utilisé à la place du model normal dans la plupart des contextes d'affichage (main, gui, sol, ...) |
override_model_contexts | list[str] | None | Contextes d'affichage gardant le model normal quand hand_model est défini (défaut : ["none", "fixed"], c.-à-d. entités item display et cadres) |
wiki_buttons | list[WikiButton] | TextComponent | None | Documentation du manuel |
remainder | str | None | Id de l'item laissé une fois celui-ci mangé ou bu (ex. "beer_mug"), rendu avec le nom, le model et les custom data du récipient, et lié depuis la page de l'item dans le manuel |
ranged_weapon | RangedWeapon | None | Temps de charge, dégâts des flèches et munition d'un arc ou d'une arbalète (voir plus bas) |
components | JsonDict | Components d'items Minecraft (sans préfixe minecraft:) |
Exemple d'utilisation de la classe Item :
from stewbeet import Item, Ingr, CraftingShapedRecipe, WikiButton
item = Item(
id="magic_sword", # Requis : identifiant unique
base_item="minecraft:iron_sword", # Item Minecraft de base (défaut : CUSTOM_ITEM_VANILLA)
manual_category="equipment", # Catégorie pour le manuel
recipes=[ # Liste d'objets Recipe
CraftingShapedRecipe(
category="equipment",
shape=["X", "X", "Y"],
ingredients={"X": Ingr("minecraft:amethyst_shard"), "Y": Ingr("minecraft:stick")}
)
],
override_model=None, # Override du model auto-généré
hand_model=None, # Model spécial tenu en main
override_model_contexts=None, # Contextes gardant le model normal quand hand_model est défini
wiki_buttons=[ # Boutons de documentation du manuel
WikiButton({"text": "Une épée puissante", "color": "gold"})
],
components={ # Components d'items Minecraft
"item_name": {"text": "Épée Magique", "color": "gold"},
"lore": [{"text": "Inflige des dégâts supplémentaires", "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"
}
]
}
)Classe Block
Les custom blocks étendent la classe Item avec des propriétés spécifiques aux blocs :
from stewbeet import Block, VanillaBlock, CraftingShapedRecipe, SmeltingRecipe, Ingr
block = Block(
id="super_stone",
vanilla_block=VanillaBlock(id="minecraft:cobblestone"),
manual_category="building",
recipes=[
# Aurait pu être shapeless, mais juste pour l'exemple :
CraftingShapedRecipe(
category="building",
shape=["XXX", "XXX", "XXX"],
ingredients={"X": Ingr("minecraft:stone")}
),
# Plusieurs types de recipes supportés
SmeltingRecipe(
experience=0.1,
cookingtime=200,
category="building",
ingredient=Ingr("super_stone"),
result=Ingr("minecraft:diamond")
)
],
components={
# Le nom d'item, lore et container seront auto-générés si manquants
}
)Configuration VanillaBlock
VanillaBlock définit l'état de bloc vanilla utilisé par StewBeet comme point d'ancrage d'exécution pour le comportement de votre custom block.
@dataclass
class VanillaBlock:
id: str # Bloc vanilla de base (ex., "minecraft:cobblestone")
contents: bool = False # Pour les blocs utilisant des item frames sans bloc vanilla
block_facing: Literal[False, "player"] = False # Rotation du bloc placé selon le joueur
visual_facing: Literal["none", "player", "item_frame"] = "none" # Source d'orientation visuelle
half: Literal["click"] | None = None # Dalle, escalier ou trappe sur la moitié cliquée par le joueur
interaction: Interaction | None = None # Entité interaction pour un hôte invisible (barrier, structure void, light)
uvlock: bool = False # Avec visual_facing="player", copies tournées du model gardant les textures alignées sur le monde
margin: float = 1.002 # Échelle du model affiché autour du centre du bloc, 1.0 garde sa taille
machine_speed: float | None = None # Four, fumoir, haut fourneau ou alambic qui travaille ce nombre de fois plus viteAvec block_facing="player", l'hôte est tourné comme vanilla le tourne : vers le joueur pour un four, dans le sens du regard pour les escaliers et les portillons.
L'entité display est mise à l'échelle de margin autour du centre du bloc, pour que ses faces passent devant celles de l'hôte. Prenez une marge plus grande si les faces scintillent encore de loin (1.008 vaut 1/16 de pixel sur un bloc plein). margin=1.0 garde la taille.
half="click" place le type (dalle) ou la half (escalier, trappe) de l'hôte selon l'endroit cliqué, trouvé au placement en avançant le long du regard du joueur ({ns}:custom_blocks/_aim/main). En plus de #upper, il laisse #floor {ns}.data à 1 quand le joueur a cliqué le dessus du bloc du dessous.
Un hôte escalier prend un shape d'angle selon ses voisins, et son display le suit chaque seconde avec une copie du model découpée dans ses éléments, dessinés orientés vers le sud : un angle intérieur ajoute l'escalier tourné d'un quart, un angle extérieur garde ce que les deux ont en commun. Un hôte four, fumoir ou haut fourneau ayant un model _on l'affiche tant qu'il brûle. Les deux passent par la chaîne custom_model_data du display, et seulement pour un model que StewBeet dessine.
Hôtes invisibles : Interaction
Un hôte sans collision ou qu'on ne peut pas miner (minecraft:barrier, minecraft:structure_void, minecraft:light[level=N]) reçoit une entité interaction qui casse le bloc quand on la frappe :
Block(
id="oak_chair",
vanilla_block=VanillaBlock(id="minecraft:barrier", visual_facing="player", interaction=Interaction(
width=1.01, height=1.01, # Depuis le bas du bloc
seat=0.5, # L'utiliser assoit le joueur à cette hauteur, None pour aucun siège
hits=3, hit_timeout=20, # 3 coups à moins de 20 ticks d'écart le cassent
sound="minecraft:block.wood", # Joue <sound>.hit et <sound>.break avec des particules de l'item
)),
)L'item tombe sauf si le joueur qui casse est en créatif, et aussi quand aucun joueur ne le casse (une quarry qui appelle #common_signals:calls/destroyed_block le récupère). Un id d'item en no_silk_touch_drop fait tomber cet item à la place. Pour un bloc lumineux sans collision, utilisez minecraft:light[level=15] comme hôte. Pour lancer des commandes quand un joueur utilise une interaction, ajoutez-les à {ns}:custom_blocks/_interaction/use, exécutée en tant que l'interaction avec le joueur tagué {ns}.user.
Niveau de minage : Mining
Block(id="steel_block", mining=Mining(tool="pickaxe", level="iron"))Un outil trop faible casse le bloc sans faire tomber son item. Sans hôte, le bloc prend le premier hôte de Mining.hosts pour son niveau (minecraft:diamond_block pour le fer), dont les règles de drop vanilla décident alors, vitesse et animation de minage comprises ; un hôte donné doit en faire partie. Un hôte interaction vérifie la main principale du joueur avec l'item tag Mining.item_tag (tout type d'outil y fonctionne). Un minerai sur VANILLA_BLOCK_FOR_ORES vérifie l'outil du joueur en survie le plus proche à 8 blocs.
Configuration NoSilkTouchDrop
Définit les custom drops quand le bloc est cassé sans toucher de soie :
@dataclass
class NoSilkTouchDrop:
id: str = "" # ID de l'item à drop (ex., "raw_simplunium")
loot_table: LootTable | str | None = None # Ou une loot table tirée avec l'outil du joueur, à la place de id et count
count: dict | int = 1 # Nombre de drops : int ou {"min": 1, "max": 3}
experience: dict | float = 0.0 # Points d'expérience : 2.5 (50 % de chance d'un troisième point) ou {"min": 3, "max": 7}Le manuel affiche l'expérience dans le survol de la recette de minage.
# Exemple d'utilisation
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})
)
# Ou raccourci
block = Block(
id="simplunium_ore",
vanilla_block=VanillaBlockForOres,
no_silk_touch_drop="raw_simplunium" # Par défaut count=1
)
# Ou drops dynamiques avec une LootTable beet directe
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}
]
}]
})
)
# Ou une loot table avec de l'expérience
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})
)Configuration RangedWeapon
Item(
id="crossbow", base_item="minecraft:crossbow",
ranged_weapon=RangedWeapon(
charge_time=2.5, # Secondes pour charger une arbalète, 1.25 en vanilla
damage_multiplier=1.5, # Dégâts des flèches tirées
ammunition="bolt", # Le seul item des définitions qu'elle charge, tout autre est rendu
name="Heavy Draw", # Nom dans l'infobulle de l'enchantement caché qui l'applique
),
)L'item reçoit un enchantement (Item.ranged_weapon_enchantment) tagué comme malédiction pour qu'une meule le garde, et pas de reflet d'enchantement. Une arbalète avec des textures _pulling_<n>, _arrow et _firework reçoit l'item model vanilla de l'arbalète : tendue selon sa charge, et montrant ce qu'elle tient une fois chargée.
Configuration GrowingSeed
Pour les graines qui poussent avec le temps (comme Stardust Seed de Stardust Fragment) :
@dataclass
class GrowingSeedLoot:
id: str # ID de l'item à drop
rolls: JsonDict | int = 1 # Définition de roll ou nombre
fortune: JsonDict | None = None # Modificateur de fortune
@dataclass
class GrowingSeed:
texture_basename: str # Nom de base de la texture (ex., "stardust")
seconds: int # Temps de croissance en secondes
planted_on: str # Bloc sur lequel planter (ex., "diamond_block")
loots: list[GrowingSeedLoot] | str # Liste de loots ou chemin de loot table# Exemple d'utilisation
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 et BlockHead
Types de blocs alternatifs pour des méthodes de placement spéciales :
from stewbeet import BlockAlternative, BlockHead
# Utilisant des item frames (ex., pour des machines sans bloc vanilla)
servo = BlockAlternative(
id="servo_inserter",
vanilla_block=VanillaBlock(contents=True), # Pas de bloc vanilla, juste item frame
manual_category="machines"
)
# Utilisant des têtes de joueur (pour des custom heads)
custom_head = BlockHead(
id="stoupy_head",
vanilla_block=VanillaBlock(id="minecraft:player_head[profile={name:\"Stoupy51\"}]"),
manual_category="decorations"
)Classe Painting
Custom paintings pour la décoration :
from stewbeet import Painting, PaintingData
painting = Painting(
id="stewbeet_painting",
manual_category="decorations",
painting_data=PaintingData(
texture="stewbeet_painting_2x2", # Nom du fichier texture (sans .png)
author={"text": "Stoupy", "color": "yellow"}, # Par défaut ctx.project_author
title={"text": "L'Icône", "color": "gray"}, # Par défaut nom de l'item
width=2, # Largeur en blocs
height=2 # Hauteur en blocs
)
)Système de recipes
Classes de recipes
StewBeet fournit des classes de recipes typées pour tous les types de recipes Minecraft :
Crafting Shaped Recipe
Utilisez une recipe shaped quand la position des ingrédients est importante ; la shape associe des symboles aux ingrédients et impose la disposition.
from stewbeet import CraftingShapedRecipe, Ingr
recipe = CraftingShapedRecipe(
result_count=1, # Nombre d'items produits
group="tools", # Groupement du recipe book
category="equipment", # Catégorie du recipe book
shape=["X X", " Y ", "X X"], # Motif 3x3
ingredients={
"X": Ingr("minecraft:iron_ingot"),
"Y": Ingr("minecraft:stick")
}
)Crafting Shapeless Recipe
Utilisez une recipe shapeless quand seule la présence des ingrédients compte, sans tenir compte de leur position dans la grille.
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")]
# Peut aussi utiliser : ingredients=(2*[Ingr("minecraft:oak_wood")] + 2*[Ingr("minecraft:oak_log"])
)Smelting Recipe
Les recipes de smelting modélisent les transformations de type four avec un temps de cuisson, une récompense XP et une conversion entrée-sortie.
recipe = SmeltingRecipe(
result_count=1,
cookingtime=200, # Ticks (200 = 10 secondes)
experience=0.7,
category="misc",
ingredient=Ingr("ruby_ore"),
result=Ingr("ruby")
)Autres types de recipes
StewBeet fournit des wrappers typés pour les mécaniques de recipe vanilla spécialisées afin de configurer chaque comportement explicitement.
# Haut fourneau (cuisson plus rapide)
# cookingtime est la durée dans le bloc lui-même, StewBeet écrit la valeur attendue par chaque version de Minecraft
BlastingRecipe(cookingtime=100, experience=0.7, ...)
# Fumoir (pour la nourriture)
SmokingRecipe(cookingtime=100, experience=0.35, ...)
# Feu de camp
CampfireCookingRecipe(cookingtime=600, experience=0.35, ...)
# Taille de pierre
StonecuttingRecipe(result_count=1, ingredient=Ingr(...), result=Ingr(...))
# Forge transformation
SmithingTransformRecipe(template=Ingr(...), base=Ingr(...), addition=Ingr(...), result=Ingr(...))
# Forge parure
SmithingTrimRecipe(template=Ingr(...), base=Ingr(...), addition=Ingr(...))Helper Ingredient
La fonction Ingr crée des spécifications d'ingrédients :
from stewbeet import Ingr
# Item du namespace local
Ingr("steel_ingot")
# Résultat : {"custom_data": {"your_namespace": {"steel_ingot": True}}}
# Item Minecraft
Ingr("minecraft:iron_ingot")
# Résultat : {"id": "minecraft:iron_ingot"}
# Item de datapack externe
Ingr("tin_ingot", ns="mechanization")
# Résultat : {"custom_data": {"mechanization": {"tin_ingot": True}}}
# Utilisation dans les recipes
recipe = CraftingShapedRecipe(
shape=["XXX", "XYX", "XXX"],
ingredients={
"X": Ingr("steel_ingot"),
"Y": Ingr("minecraft:diamond")
}
)Génération de matériaux
Génération automatique d'équipements
Générez des sets de matériaux complets automatiquement :
# Dans src/definitions/ores.py
from stewbeet import *
def main():
ORES_CONFIGS: dict[str, EquipmentsConfig | None] = {
"steel_ingot": EquipmentsConfig(
equivalent_to=DefaultOre.IRON, # Stats du matériau de base
pickaxe_durability=3 * VanillaEquipments.PICKAXE.value[DefaultOre.IRON]["durability"],
attributes={
"attack_damage": 1, # +1 dégâts pour les armes
"armor": 0.5, # +0.5 armure pour les pièces d'armure
"mining_efficiency": 2 # +20% vitesse de minage pour les outils
}
),
"minecraft:stone": None, # Auto-détection depuis les textures (ex., stone_stick, stone_rod, etc.)
}
# Génère : 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)
# Configurer les custom blocks après génération
# ⚠️ Nous utilisons Block.from_id() pour accéder aux définitions existantes et les modifier
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")Configuration d'équipement
EquipmentsConfig contrôle l'héritage des statistiques de base des familles de matériaux générées et l'application des custom modifiers sur les outils et armures.
class EquipmentsConfig:
equivalent_to: DefaultOre # Matériau de base (WOOD, STONE, GOLD, IRON, DIAMOND, NETHERITE, COPPER, CHAINMAIL, LEATHER)
pickaxe_durability: float | int = 0 # Custom durability (0 = utiliser équivalent vanilla)
attributes: dict[str, float] | None = None # Modificateurs de stats à AJOUTER (pas remplacer)
ignore_recipes: bool = False # Ignorer la génération automatique de recipesModificateurs d'attributs courants :
"attack_damage": 1.0-> +1 dégât d'attaque pour les armes (ex., pioche diamant : 5 -> 6)"armor": 0.5-> +0.5 armure pour chaque pièce d'armure"armor_toughness": 1.0-> +1 robustesse d'armure pour les pièces d'armure"mining_efficiency": 2-> +20% vitesse de minage pour les outils"knockback_resistance": 0.1-> +0.1 résistance au recul (appliqué à l'armure uniquement)
Intégration de la documentation
Boutons Wiki
Ajoutez de la documentation interactive pour le manuel en jeu :
from stewbeet import Item, WikiButton
item = Item.from_id("steel_ingot") # Récupérer un item existant
item.wiki_buttons = [
WikiButton([
{"text": "L'acier est une variante plus solide du fer.\n"},
{"text": "Il offre une meilleure durabilité.", "color": "yellow"}
]),
WikiButton({"text": "Ceci est un autre bouton.", "color": "aqua"})
]Item du manuel
Créez une recipe pour le manuel en jeu :
Item(
id="manual",
manual_category="miscellaneous",
recipes=[
# Craft avec livre + lingot d'acier
CraftingShapelessRecipe(
category="misc",
ingredients=[Ingr("minecraft:book"), Ingr("steel_ingot")]
),
# Mettre à jour le manuel en le craftant à nouveau
CraftingShapelessRecipe(
category="misc",
ingredients=[Ingr("manual")]
)
],
components={
"item_name": Mem.ctx.meta.get("stewbeet", {}).get("manual", {}).get("name") or "Manuel"
}
)Contenu audio
Custom music discs
La génération de records mappe les assets .ogg vers les définitions afin de garder sons, items et références synchronisés automatiquement.
# Auto-génération depuis les fichiers assets/records/*.ogg
generate_custom_records("auto")
# Ou spécifier manuellement
generate_custom_records({
"my_disc": "Ma Musique Custom.ogg",
"battle_theme": "Musique de Combat Épique.ogg"
})
# Réduire la portée d'écoute par rapport aux 16 blocs vanilla
generate_custom_records("auto", attenuation_distance=5)Fonctions utilitaires
Fonctions helper essentielles
Ces helpers finalisent les définitions pour garantir une sortie cohérente, correctement namespacée, et prête pour les plugins suivants.
# Générer les item models pour tous les items définis
add_item_model_component(black_list=["excluded_items"])
# Ajouter les noms et lores par défaut là où manquants
add_item_name_and_lore_if_missing()
# Ajouter les données de détection de namespace (REQUIS !)
add_private_custom_data_for_namespace()
# Ajouter les données de convention Smithed
add_smithed_ignore_vanilla_behaviours_convention()
# Configurer les components de survol du manuel
set_manual_components(white_list=["item_name", "lore", "custom_name", "damage", "max_damage"])
# Exporter les définitions pour le débogage
export_all_definitions_to_json(f"{Mem.ctx.directory}/definitions_debug.json")Catégories d'items
Catégories courantes pour l'organisation du manuel (mais c'est toujours à vous de décider !) :
| Catégorie | Description |
|---|---|
"materials" | Matériaux bruts, lingots, gemmes |
"equipment" | Outils, armes, armures |
"building" | Blocs de construction, blocs décoratifs |
"miscellaneous" | Autres items, items spéciaux |
"food" | Items consommables |
"decorations" | Paintings, items décoratifs |
Fonctionnalités avancées
Intégration de textures
Les items détectent automatiquement les textures par nom depuis assets/textures/ :
steel_ingot.png-> itemsteel_ingotsteel_pickaxe.png-> outilsteel_pickaxesteel_block.png-> custom blocksteel_block
Accéder aux items existants
Item.from_id permet de récupérer et modifier des définitions déjà déclarées, ce qui facilite une configuration par étapes sans recréer les items.
# Récupérer un item existant
item = Item.from_id("my_item")
# Le modifier
item.manual_category = "materials"
item.wiki_buttons = [WikiButton({"text": "Nouvelle info !"})]
# Ajouter une recipe
item.recipes.append(CraftingShapelessRecipe(
category="misc",
ingredients=[Ingr("something")]
))Emplacements de ressources
Ne codez plus jamais en dur un emplacement comme f"{ns}:custom_blocks/{item}/place_secondary". Chaque emplacement que StewBeet dérive d'un ID d'item est exposé sous forme de propriété renvoyant un objet Resource.
Un Resource est un str contenant l'emplacement complet namespace:path, il fonctionne donc partout où un chemin est attendu: dans une f-string, comme argument de write_function, comme clé de dictionnaire, ou comparé à un littéral. En plus de ça, il donne accès au fichier beet sous-jacent.
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]
# Utilisation directe dans une commande
write_function(f"{ns}:give_steel", f"loot give @s loot {item.loot_table}")NOTE
item_model suit le component item_model lorsque vous le surchargez, tandis que generated_item_model pointe toujours vers le fichier réellement écrit par StewBeet. Ils ne diffèrent que si vous définissez le component vous-même.
Fonctions de bloc
Block.functions regroupe toutes les mcfunctions d'un 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"] # n'importe quelle autre fonction de ce dossier
block.functions.folder # "ns:custom_blocks/steel_block"
# Également disponibles : 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 # advancement de placement (BlockAlternative / BlockHead uniquement)
# L'exemple de ticking du template devient donc :
write_function(block.functions.tick, "particle heart ~ ~1 ~ 0.5 0.5 0.5 0.01 1")Block.functions renvoie un objet BlockFunctions, que vous pouvez aussi construire directement depuis un ID de bloc si vous trouvez ça plus lisible: pas besoin de passer par Block.from_id, ça fonctionne donc même pour des IDs sans définition :
from stewbeet import BlockFunctions
funcs = BlockFunctions("steel_block")
funcs.tick # "ns:custom_blocks/steel_block/tick"
BlockFunctions("steel_block").destroy # mêmes chemins que Block.from_id("steel_block").functions.destroy
BlockFunctions("gauge", namespace="other") # cibler un autre namespaceLes deux formes produisent exactement les mêmes objets Resource[Function]: utilisez celle que vous préférez.
Lire et écrire le fichier
res = item.loot_table
res.exists() # le fichier est-il déjà dans le pack ?
res.get() # la LootTable beet, ou None
res.obj # la LootTable beet, lève KeyError si absente
res.obj = LootTable({...}) # l'écrire
res.write(LootTable({...})) # pareil, et renvoie le fichier
res.delete() # la supprimer si présente
res.namespace # "ns"
res.relative_path # "i/steel_ingot"
res.file_type # beet.LootTablePour les mcfunctions, .obj est un objet Function beet, vous pouvez donc ajouter des commandes à une fonction existante directement: même résultat qu'un appel à write_function(res, ...) :
# Exécuter des commandes en tant qu'entité display du bloc quand il est placé
# (depuis un plugin exécuté APRÈS datapack.custom_blocks, pour que la fonction existe) :
Block.from_id("super_stone").functions.place_secondary.obj.append("""
say Quelqu'un a placé la super stone !
particle minecraft:explosion ~ ~ ~
""")TIP
Lire .obj avant que le plugin qui le génère n'ait été exécuté lève une KeyError. Utilisez .get() ou .exists() lorsque le fichier peut ne pas encore exister ou faites votre code après exécution des plugins cibles.
Pour l'exemple d'append ci-dessus, c'est en réalité un avantage : ajouter trop tôt échoue bruyamment au lieu de placer silencieusement vos commandes avant le setup du bloc.
Exemples de models complexes
Motifs de textures reconnus
StewBeet reconnaît automatiquement les motifs de textures et génère les models appropriés :
Motifs de blocs :
cube_all: Texture unique (ex.,my_block.png)cake: bottom, side, top, inner (ex.,my_cake_bottom.png,my_cake_side.png,my_cake_top.png,my_cake_inner.png)orientable_with_bottom: front, bottom, side, top (ex.,furnace_front.png,furnace_bottom.png,furnace_side.png,furnace_top.png)cube_bottom_top: bottom, side, top (ex.,barrel_bottom.png,barrel_side.png,barrel_top.png)orientable: front, side, top (ex.,dropper_front.png,dropper_side.png,dropper_top.png)cube_column: end, side (ex.,pillar_end.png,pillar_side.png)
Motifs d'items :
leather_armor: Les items commençant parleather_utilisent automatiquement layer1 pour la coloration en overlayoverlay: Items avec texture_overlay(ex.,my_item.png+my_item_overlay.png-> layer0 + layer1)bow_pulling: Items d'arc avec_pulling_0,_pulling_1,_pulling_2, etc. (triés numériquement)spear_in_hand: Lances se terminant par_spear+ variante de texture_in_hand(utilise le changement de contexte d'affichage)
États alimentés :
- N'importe quel bloc/item peut avoir des variantes
_on(ex.,furnace_front.png+furnace_front_on.png) - StewBeet génère automatiquement les deux états si des textures
_onsont détectées, un hôte four, fumoir ou haut fourneau affichant l'état_ontant qu'il brûle
États multiples (On/Off, Facing)
Exemple du four électrique de SimplEnergy avec états on/off et orientation directionnelle :
from stewbeet import Block, VanillaBlock, CraftingShapedRecipe, Ingr
# Créer le bloc de four électrique
electric_furnace = Block(
id="electric_furnace",
vanilla_block=VanillaBlock(
id="minecraft:furnace",
block_facing="player" # Active les variantes directionnelles (nord, est, sud, ouest)
),
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": "Four Électrique", "color": "aqua"},
"custom_data": {"energy": {"usage": 20, "max_storage": 1600}}
}
)
# StewBeet détecte automatiquement les motifs de block models depuis les noms de textures :
# Textures requises : electric_furnace_front.png, electric_furnace_side.png, electric_furnace_top.png, electric_furnace_bottom.png
# Optionnel pour l'état on : electric_furnace_front_on.png (les autres côtés peuvent aussi avoir des variantes _on)
# Motif reconnu : "orientable_with_bottom" (front, side, top, bottom)
# Autres motifs supportés : "orientable" (front, side, top), "cube_bottom_top" (bottom, side, top), "cube_column" (end, side)Item models animés (Tir à l'arc)
Exemple avec animations de tir à l'arc :
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 Arc", "color": "gold"},
"max_damage": 500
}
)
# StewBeet auto-génère les models d'animation de tir et les fichiers JSON item_model :
# Textures requises dans assets/textures/item/ :
# - super_bow.png (texture d'arc de base)
# - super_bow_pulling_0.png (légèrement tiré)
# - super_bow_pulling_1.png (à moitié tiré)
# - super_bow_pulling_2.png (complètement tiré)
# # Fichiers générés :
# - assets/models/item/super_bow_pulling_0.json, super_bow_pulling_1.json, super_bow_pulling_2.json
# - assets/items/super_bow.json (avec condition et range_dispatch pour les états de tir)Bonnes pratiques
À faire
- Utilisez les classes
Item,Block,Paintingpour des définitions propres et typées - Utilisez
Ingr()pour toutes les références d'ingrédients - Appelez les fonctions d'ajustement final à la fin de
beet_default() - Organisez les définitions dans des modules séparés (comme
ores.py,additions.py) - Utilisez des catégories significatives pour l'organisation du manuel
- Définissez
vanilla_blockpour les custom blocks après génération
À ne pas faire
- Ne modifiez pas
Mem.definitionsdirectement (utilisez les classes) - N'utilisez pas de dictionnaires bruts pour les ingrédients (utilisez
Ingr()) - N'oubliez pas d'appeler les fonctions d'ajustement final
- Ne sautez pas la configuration de
vanilla_blockpour les custom blocks
Exemple complet
# 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. Générer les matériaux
main_ores()
# 2. Générer les records
generate_custom_records("auto")
# 3. Ajouter les custom items
main_additions()
# 4. Définir les catégories manquantes
for item_id in Mem.definitions.keys():
obj = Item.from_id(item_id)
if not obj.manual_category:
obj.manual_category = "miscellaneous"
# 5. Ajustements finaux (REQUIS !)
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. Export de débogage
export_all_definitions_to_json(f"{Mem.ctx.directory}/definitions_debug.json")🎉 Cette approche moderne crée des définitions d'items propres et type-safe qui s'intègrent parfaitement avec tous les plugins StewBeet !
Consultez les exemples réels en haut de cette page pour voir comment ça fonctionne en pratique ! 🚀
Glossaire
| Terme | Signification |
|---|---|
| Configuration des définitions | Plugin utilisateur qui crée et enrichit Mem.definitions. |
| Définition | Entrée d'objet typée (Item, Block, Painting, etc.) utilisée par les plugins StewBeet suivants. |
| Mem.definitions | Registre global où toutes les définitions sont stockées et partagées dans le pipeline. |
Prochaines étapes
- Écrire fonctions et fichiers: transformer vos définitions en fichiers.
- Recipes: comment une recipe atteint chaque système de craft.
- Manuel en jeu: le livre généré depuis vos définitions.