Générer le manuel en jeu

ingame_manual génère un manuel en jeu à partir de vos items Mem.definitions : une page d'introduction, un navigateur de catégories, une page par catégorie, et une page par item avec ses recipes et boutons wiki, dont les effets qu'il donne une fois consommé et un lien vers le récipient qu'il laisse (remainder) et vers les graines qui le font pousser. Il est orienté dialogue (l'ancien mode livre écrit NBT est supprimé) et entièrement extensible: vous pouvez modifier la page de n'importe quel item, insérer des pages arbitraires (même sans rapport avec un item), contrôler le placement des boutons, et rendre des pages basées sur votre propre texture. Chaque classe publique de l'API (sous-classes de Page, ButtonLayout, BakedText, PageRef, CraftRenderer, Manual lui-même...) est une dataclass Python.

Activez-le en remplaçant stewbeet.plugins.ingame_manual par stewbeet.plugins.ingame_manual dans votre pipeline.

Fichier d'exemple : extensive/src/definitions/manual_customization.py

Code source : stewbeet/plugins/ingame_manual/

Requis : Framework StewBeet (from stewbeet import *)
Position : L'étape stewbeet.plugins.ingame_manual de votre pipeline beet.yml, après custom_recipes et avant les plugins de datapack
Personnalisation : Appelez get_manual() dans votre setup_definitions (après la définition des items) pour enregistrer pages et hooks
Sortie : Orienté dialogue: génère un dialogue Minecraft par page, accessible via le menu quick actions natif (et l'item manual en mode 1)

  • Générer automatiquement les pages de recipes de chaque item (craft, cuisson, forge, découpe, minage, et custom recipe types)
  • Insérer/remplacer/réordonner des pages arbitraires via une API Python claire
  • Enregistrer des fonctions exécutées pendant la création du manuel (hooks Phase)
  • Fournir des pages basées sur une custom texture, avec le texte intégré dans l'image elle-même
  • Remplacer la texture de fond du livre ou du bouton home sur une page spécifique (book_texture, home_texture)
  • Lier des pages entre elles : afficher le bouton de recipe d'un autre item, ou un bouton de lien vers sa page (extra_buttons)
  • Décider où apparaissent les boutons wiki et comment gérer le dépassement (ButtonLayout)
  • Les liens différés PageRef gardent la navigation correcte après toute insertion/réorganisation

Présentation des fonctionnalités

Configuration

À définir dans beet.yml sous meta.stewbeet.manual :

CléTypeDéfautDescription
cache_pathstr-Déprécié. Remplacé par iso_renders_path au niveau racine ; les fonts et textures générées vivent maintenant dans .beet_cache
use_dialogint11 = dialogue + item manual qui l'ouvre · 2 = dialogue seul (sans item)
high_resolutionbooltrueIcônes d'items haute résolution (256px) dans les recipes
cache_assetsbooltrueÉvite de re-rendre/re-télécharger les textures d'items déjà présentes
max_items_per_rowint5Largeur de la grille de catégorie (max 6)
max_rows_per_pageint5Hauteur de la grille de catégorie (max 7)
namestr"{projet} Manual"Titre du manuel (max 32 caractères)
first_page_textTextComponent""Texte de la page d'introduction
manual_overridesstr""Dossier de textures remplaçant les défauts fournis
showcase_imageint30 off · 1 items du manuel · 2 tous les items · 3 les deux
json_dump_pathstr""Export de debug optionnel des pages rendues

Note : use_dialog: 0 et cache_pages de la v1 sont supprimés. Le manuel est toujours basé sur les dialogues.


API d'extension

Récupérez le manuel actif après la définition de vos items :

python
from stewbeet import get_manual, Phase, CustomPage, TexturePage, BakedText, ButtonLayout

manual = get_manual()

Hooks & Phases

Enregistrez des fonctions exécutées pendant la création du manuel. C'est le mécanisme d'extension principal, car les pages par défaut n'existent que pendant la génération.

python
@manual.on(Phase.PREPARED)
def tweak(m):
    page = m.get_page_for_item("steel_ingot")
    if page is not None:
        page.transformers.append(lambda content, _m: [*content, {"text": "\nQuel métal !", "color": "dark_gray"}])
PhaseSe déclenche aprèsUsage typique
DISCOVEREDpages par défaut crééesinsérer/réordonner des pages
PREPAREDdonnées par page collectéeséditer les pages d'items, définir les layouts de boutons
ORDEREDordre final calculéréorganisation de dernière minute
RENDEREDpages renduesajouter des transformers
RESOLVEDliens résolusinspecter les liens finaux
BEFORE_EMITjuste avant la sortieajustements finaux

manual.on_item_page(fn) exécute fn(page, manual) sur chaque page d'item pendant la préparation.

Custom pages & texture

insert_page accepte before=/after= (un anchor) ou index=. Les anchors par défaut incluent "intro", "category_browser", "category:<Titre>" et "item:<id>".

python
# Une page libre (n'importe quels components de texte)
manual.insert_page(CustomPage(
    anchor="welcome", title="Bienvenue",
    body=[{"text": "Bonjour depuis une custom page !", "color": "black"}],
), after="intro")

# Une page dont le corps est une texture, avec le texte intégré dans l'image elle-même
from PIL import Image
manual.insert_page(TexturePage(
    anchor="credits", title="Crédits",
    background=Image.new("RGBA", (256, 128), (30, 30, 46, 255)),  # ou un chemin PNG
    baked_texts=[BakedText(text="Fait avec StewBeet", xy=(128, 40), align="center", color=(255, 255, 255, 255))],
    body=[{"text": "\n[le texte ci-dessus fait partie de l'image]", "color": "black"}],
    glyph_height=64,
    left_padding=10,  # décale la texture vers la droite (voir ci-dessous)
), after="welcome")

Attributs de placement de TexturePage :

AttributDescription
glyph_ascent / glyph_heightPlacement bitmap de la texture de page : taille et décalage Y
left_padding / right_paddingPixels invisibles émis avant/après le glyphe de la texture (décalage X)

Le dialogue centre la ligne : left_padding décale donc la texture vers la droite et right_padding vers la gauche, chacun de la moitié du padding. Gardez largeur de texture + paddings dans le corps du dialogue (140px), sinon la ligne passe à la ligne.

Fond de livre & bouton home par page

Chaque page (toute sous-classe de Page) accepte book_texture pour remplacer le fond de livre (book.png) et home_texture pour remplacer le bouton home (home.png) sur cette page uniquement: ex. un livre fermé sur la première page. Les deux prennent une image PIL prête, ou un chemin résolu d'abord comme chemin du projet, puis dans le dossier des templates (un nom de fichier de votre dossier manual_overrides fonctionne donc). template_path(filename) retourne le chemin effectif d'un asset de template fourni/surchargé.

python
from stewbeet import CustomPage, Mem, Phase, get_manual

manual = get_manual()

# Tiré du template extensive : une page d'accueil avec son propre fond de livre et sa propre flèche home
textures_folder: str = Mem.ctx.meta["stewbeet"]["textures_folder"]
manual.insert_page(
    CustomPage(
        anchor="welcome", title="Bienvenue",
        body=[{"text": "Bienvenue dans le Template Extensive !", "color": "black", "bold": True}],
        book_texture=f"{textures_folder}/manual/a_custom_book_page.png",
        home_texture=f"{textures_folder}/manual/home_for_welcome_page.png",
    ),
    after="intro",
)

# Les pages existantes fonctionnent aussi, ex. un livre fermé depuis votre dossier manual_overrides sur la page d'intro
@manual.on(Phase.DISCOVERED)
def closed_book_intro(m):
    m.get_page("intro").book_texture = "closed_book.png"  # résolu depuis manual_overrides

Notes : gardez une home_texture proche des proportions 16x16 par défaut, car l'avance du glyphe dépend du contenu de l'image (une flèche plus large décale les boutons précédent/suivant sur cette page). La première page n'affiche jamais le bouton home: elle est la page d'accueil (un espaceur invisible conserve la mise en page des boutons précédent/suivant), et toute autre page peut aussi le masquer avec home_button=False.

Placement des boutons

Contrôlez où les boutons wiki sont rendus, par page ou comme défaut global du manuel (ManualConfig.button_layout) :

python
manual.on_item_page(lambda page, _m: setattr(
    page, "button_layout", ButtonLayout(columns=6, max_buttons=42, position="after_recipe")
))
ChampDescription
columnsBoutons par ligne
max_buttonsPlafond strict (dépassement supprimé par priorité)
position"after_recipe" · "top" · "bottom" · ou un callable
orderClé de tri, ex. lambda b: -b.priority
includePrédicat (button) -> bool pour filtrer
extra_buttonsWikiButtonRender supplémentaires à ajouter

Gestion des pages

MéthodeDescription
manual.add_page(page)Ajoute une page à la fin
manual.insert_page(page, *, before/after/index)Insère à une position
manual.replace_page(anchor, page)Remplace une page
manual.move_page(anchor, *, before/after/index)Déplace une page
manual.remove_page(anchor)Supprime une page
manual.get_page(anchor) / get_page_for_item(id)Récupère une page

Les opérations de page appelées depuis le setup sont différées et rejouées une fois les pages par défaut créées, vous pouvez donc référencer directement des anchors par défaut comme "intro".


Plus d'exemples

Insérer une page de lore entre deux catégories

python
manual.insert_page(CustomPage(
    anchor="lore", title="Lore",
    body=[{"text": "Il y a longtemps, le monde fonctionnait à l'acier...", "color": "black"}],
), after="category:Materials")

Remplacer entièrement la page d'un item

python
@manual.on(Phase.DISCOVERED)
def custom_wrench_page(m):
    m.replace_page("item:wrench", CustomPage(
        anchor="item:wrench", item_id="wrench", title="Clé",
        body=[{"text": "Une page écrite à la main pour la clé.", "color": "black"}],
    ))

Ajouter un pied de page à chaque page

python
@manual.on(Phase.RENDERED)
def add_footer(m):
    for page in m.pages:
        page.transformers.append(lambda content, _m: [*content, {"text": "\n- MonPack", "color": "dark_gray"}])

Réordonner les pages (déplacer une catégorie juste après le navigateur)

python
@manual.on(Phase.DISCOVERED)
def reorder(m):
    m.move_page("category:Energy", after="category_browser")

Filtrer & trier les boutons wiki d'un item

python
@manual.on(Phase.PREPARED)
def tidy_buttons(m):
    page = m.get_page_for_item("simplunium_ingot")
    if page is not None:
        page.button_layout = ButtonLayout(
            columns=5,
            include=lambda b: not b.blue_craft,   # garder uniquement les recipes qui produisent un résultat
            order=lambda b: -b.priority,          # priorité la plus haute en premier
        )

Choisir la recipe principale d'une page d'item

Par défaut, la recipe principale est la façon de miner l'item quand il tombe d'un minerai. Définissez ItemPage.main_craft pour afficher un autre craft à la place ; les autres restent disponibles en boutons.

python
@manual.on(Phase.PREPARED)
def craft_first(m):
    page = m.get_page_for_item("stardust_fragment")
    if page is not None:
        page.main_craft = next(c for c in page.crafts if c["type"].startswith("crafting"))

Lier deux pages d'items entre elles (boutons de recipe inter-pages)

ItemPage.extra_buttons contient les boutons wiki ajoutés par le développeur, placés après les boutons automatiques. Construisez-les avec :

  • manual.recipes.button_for_item(item_id, index=0): le bouton de recipe d'un autre item : le survol montre sa recipe, le clic ouvre sa page (index choisit lequel de ses crafts ; retourne None avec un avertissement si le craft n'existe pas) ;
  • manual.recipes.link_button(item_id, hover=None): un simple lien de page : l'icône de l'item dans une case wiki, le clic ouvre sa page (hover vaut par défaut le nom de l'item plus une indication de clic).
python
# Exemple tiré de Stardust Fragment : le Starlight Infuser invoque le boss Stardust Pillar,
# donc chaque page pointe vers l'autre.
@manual.on(Phase.PREPARED)
def link_pillar_and_infuser(m):
    pillar = m.get_page_for_item("stardust_pillar")
    infuser = m.get_page_for_item("starlight_infuser")
    if pillar is not None and infuser is not None:
        # Afficher la recipe du Starlight Infuser sur la page du Stardust Pillar (clic -> sa page)
        button = m.recipes.button_for_item("starlight_infuser")
        if button is not None:
            pillar.extra_buttons.append(button)
        # Et le lien retour : un bouton sur la page du Starlight Infuser ouvrant la page du Stardust Pillar
        infuser.extra_buttons.append(m.recipes.link_button("stardust_pillar"))

Insérer une page texture depuis un fichier PNG (au lieu d'une image générée)

python
manual.insert_page(TexturePage(
    anchor="tutorial", title="Tutoriel",
    background="assets/manual/tutorial_bg.png",   # votre propre texture
    baked_texts=[BakedText(text="Étape 1 : miner le minerai", xy=(20, 40))],
), before="category:Materials")

Ajouter une page seulement si une condition est remplie

python
@manual.on(Phase.DISCOVERED)
def maybe_changelog(m):
    if m.get_page_for_item("prototype") is not None:
        m.insert_page(CustomPage(anchor="changelog", title="Changelog",
            body=[{"text": "Le prototype est activé dans ce build.", "color": "red"}]), index=1)

Custom recipe types

Chaque type de recipe est rendu par un CraftRenderer enregistré dans un registre global : ajouter un type = une classe + un appel à register_craft_renderer(...). Les types intégrés vivent un par fichier sous recipes/types/ (shaped, furnace, smithing, linear, awakened_forge). Comme toutes les classes de l'API du manuel, les renderers sont des dataclasses: décorez votre sous-classe avec @dataclass pour suivre le style des types intégrés.

python
from dataclasses import dataclass
from typing import ClassVar

from stewbeet import CraftRenderer, register_craft_renderer

@dataclass
class MyMachineRenderer(CraftRenderer):
    types: ClassVar[tuple[str, ...]] = ("myplugin_machining",)  # le(s) "type" de craft géré(s)
    name: ClassVar[str] = "Mon Usinage"                         # titre du survol ("" = pas de titre, comme le craft vanilla)

    def render_body(self, r, craft, name, content, result_component, page_font, use_dialog, add_change_page_to_ingr):
        # Ajoutez votre mise en page à `content`. Construisez les cases avec r.item_component(...)
        # et r.append_or_invisible(content, component, ligne). `result_component` est déjà prêt.
        ...

    def append_hover(self, r, craft, hover):   # lignes de survol du bouton wiki (défaut : un seul "- x1 <ingrédient>")
        ...

register_craft_renderer(MyMachineRenderer())

Seuls types et render_body sont obligatoires ; static_glyph (glyphe de template haute résolution), append_hover et build_image (PNG basse résolution) ont tous des valeurs par défaut. r est le RecipeRenderer, exposant r.config, r.glyphs, r.images, r.item_component(...) et r.append_or_invisible(...). Appelez register_craft_renderer(...) une fois (ex. dans votre setup) ; un craft dont le type n'a pas de renderer enregistré est ignoré.


Migration depuis la v1

  • Changez l'entrée du pipeline en stewbeet.plugins.ingame_manual.
  • WikiButton et set_manual_components(...) continuent de fonctionner sans changement.
  • Retirez la clé cache_pages et utilisez use_dialog: 1 ou 2 (le mode 0 n'existe plus).
  • Le storage universal_manual n'est plus enregistré ; le manuel s'ouvre depuis le menu quick actions natif.

Glossaire

TermeSignification
ManualL'objet orchestrateur qui possède la liste ordonnée des pages, le registre de glyphes/fonts, le constructeur d'images, le rendu des recipes et les hooks développeur. Récupéré avec get_manual().
PageUne unité autonome rendue en components de texte Minecraft. Sous-classes : IntroPage, CategoryBrowserPage, CategoryPage, ItemPage, ainsi que CustomPage, TexturePage et RawPage destinées aux développeurs.
PageRefUn lien différé vers une page (par item, anchor ou page littéral). Les liens sont résolus en numéros de page concrets après l'ordonnancement, donc insérer/réordonner des pages ne casse jamais les liens inter-pages.
Phase hookUne fonction que vous enregistrez pour s'exécuter pendant la création du manuel (manual.on(Phase.X)), à une étape précise du pipeline de génération.
ButtonLayoutContrôle où et quels boutons wiki apparaissent sur une page (colonnes, maximum, tri, filtrage, position).
BakedTextUn texte dessiné directement sur l'image de fond d'une TexturePage avec PIL.
WikiButtonTexte d'information par item affiché comme un bouton dans le manuel (inchangé depuis v1, défini via Item(wiki_buttons=...)).

Prochaines étapes