
# 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`).**

### <u>Démonstration de quelques fonctionnalités</u>

**Définitions d'items du Template Extensive :**<br>
<img src="./additions.jpg">

**Fichier d'exemple** : [extensive/src/setup_definitions.py](https://github.com/Stoupy51/StewBeet/blob/main/templates/extensive/src/setup_definitions.py) <br>  
**Exemple réel** : [SimplEnergy/src/definitions/setup_main.py](https://github.com/Stoupy51/SimplEnergy/blob/main/src/definitions/setup_main.py) <br>  
**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.

```python
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` :

```python
# 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.definitions
```

### Classe 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` :

```python
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 :

```python
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.

```python
@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 vite
```

Avec `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 :

```python
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**

```python
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 :

```python
@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.
```python
# 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**

```python
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](https://github.com/Stoupy51/StardustFragment)) :

```python
@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
```
```python
# 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 :

```python
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 :

```python
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.

```python
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.

```python
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.

```python
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.

```python
# 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 :

```python
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 :

```python
# 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.

```python
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 recipes
```

**Modificateurs 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 :

```python
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 :

```python
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.

```python
# 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.

```python
# 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` -> item `steel_ingot`
- `steel_pickaxe.png` -> outil `steel_pickaxe`
- `steel_block.png` -> custom block `steel_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.

```python
# 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.

```python
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 :

```python
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 :

```python
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 namespace
```

Les deux formes produisent exactement les mêmes objets `Resource[Function]`: utilisez celle que vous préférez.

#### **Lire et écrire le fichier**

```python
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.LootTable
```

Pour 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, ...)` :

```python
# 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 par `leather_` utilisent automatiquement layer1 pour la coloration en overlay
- **`overlay`** : 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 `_on` sont détectées, un hôte four, fumoir ou haut fourneau affichant l'état `_on` tant qu'il brûle

#### **États multiples (On/Off, Facing)**

Exemple du four électrique de SimplEnergy avec états on/off et orientation directionnelle :

```python
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 :

```python
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`, `Painting` pour 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_block` pour les custom blocks après génération

### À ne pas faire
- Ne modifiez pas `Mem.definitions` directement (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_block` pour les custom blocks

## Exemple complet

```python
# 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 !**<br>
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](../2_writing_to_files/fr.md): transformer vos définitions en fichiers.
- [Recipes](../plugins/custom_recipes.md): comment une recipe atteint chaque système de craft.
- [Manuel en jeu](../7_ingame_manual/fr.md): le livre généré depuis vos définitions.

