📄 pages#
Page classes for the in-game manual.
base#
The Page base class and lifecycle.
A page is a self-contained unit that knows how to render itself directly to a dialog body:
a list of Minecraft text components where element 0 is the parent whose style (notably its font) cascades to the siblings.
Subclasses implement build(); the base render() wraps it and applies developer transformers last,
so per-item/page overrides compose cleanly.
- class Page(
- *,
- anchor: str,
- title: str = '',
- item_id: str | None = None,
- button_layout: ButtonLayout | None = None,
- book_texture: str | Image.Image | None = None,
- home_texture: str | Image.Image | None = None,
- home_button: bool = True,
- transformers: list[Transformer] = <factory>,
- optimize: bool = True,
Bases:
objectBase class for every manual page.
>>> page = Page(anchor="demo", transformers=[lambda content, manual: [*content, "!"]]) >>> page.render(None) # the default build() yields [], then transformers run in order ['!']
- anchor: str[source]#
Stable identity used for ordering and deferred links (e.g. “intro”, “category:Materials”, “item:wrench”). Must be unique within a manual.
- item_id: str | None[source]#
If this page represents an item, its id (drives
PageRef(item=...)resolution and dialog atlas sprites).
- button_layout: ButtonLayout | None[source]#
Per-page override of the manual-wide button layout.
- book_texture: str | Image.Image | None[source]#
Per-page override of the book background (“book.png”). A path (project path, or a filename resolved against the templates dir so
manual_overridesfiles work) or a ready PIL image. None = shared book.
- book_font: str[source]#
Glyph char registered for
book_texture(set during emit, “” = shared BOOK_FONT).
- home_texture: str | Image.Image | None[source]#
Per-page override of the home button (“home.png”), same accepted values as
book_texture. Keep the default’s 16x16 proportions so the navigation row stays aligned. None = shared home.
- home_font: str[source]#
Glyph char registered for
home_texture(set during emit, “” = shared HOME_FONT).
- home_button: bool[source]#
Whether this page shows the home button in its navigation row (an invisible spacer keeps the prev/next layout when hidden). The first page never shows it regardless of this flag.
- optimize: bool[source]#
Whether the optimizer may merge this page’s components. Set False for pre-built content whose element positions are significant (e.g. a RawPage relying on absolute indices).
- prepare(manual: Manual) None[source]#
Heavy, order-independent setup (collect data, allocate glyphs). Default: no-op.
- build(manual: Manual) list[TextComponent][source]#
Produce the raw page content. Subclasses override this.
- render(manual: Manual) list[TextComponent][source]#
Build the page then apply
transformers(last), returning final content.
- resolve_button_layout(manual: Manual) ButtonLayout[source]#
Return this page’s effective button layout (own override or manual default).
browser_page#
Category browser page: a clickable grid linking to each category page.
- class CategoryBrowserPage(
- *,
- anchor: str,
- title: str = '',
- item_id: str | None = None,
- button_layout: ButtonLayout | None = None,
- book_texture: str | Image.Image | None = None,
- home_texture: str | Image.Image | None = None,
- home_button: bool = True,
- transformers: list[Transformer] = <factory>,
- optimize: bool = True,
Bases:
PageThe “Category browser” page: one clickable cell per category page.
category_page#
Category page: a clickable grid of the items in one category.
The grid background (item “cases”) is drawn as a single 131px-tall bitmap glyph;
clickable per-item glyphs are overlaid on top, each linking to its item page via a deferred PageRef.
- class CategoryPage(
- *,
- anchor: str,
- title: str = '',
- item_id: str | None = None,
- button_layout: ButtonLayout | None = None,
- book_texture: str | Image.Image | None = None,
- home_texture: str | Image.Image | None = None,
- home_button: bool = True,
- transformers: list[Transformer] = <factory>,
- optimize: bool = True,
- items: list[str] = <factory>,
Bases:
PageA page showing every item of one category as a clickable grid.
- grid_page(
- manual: Manual,
- file_name: str,
- items: list[str],
- decorate: Callable[[int, JsonDict], None] | None = None,
A page of item cases over the glyph
font/category/<file_name>.png, each case overlaid with its item’s component.- Parameters:
decorate – Called with each item’s index and component before the component is laid out, to change what it shows or does.
custom_page#
A free-form page: arbitrary Minecraft text components, unrelated to any item.
- class CustomPage(
- *,
- anchor: str,
- title: str = '',
- item_id: str | None = None,
- button_layout: ButtonLayout | None = None,
- book_texture: str | Image.Image | None = None,
- home_texture: str | Image.Image | None = None,
- home_button: bool = True,
- transformers: list[Transformer] = <factory>,
- optimize: bool = True,
- body: list[TextComponent] = <factory>,
- declared_glyphs: list[JsonDict] = <factory>,
Bases:
PageA page with a developer-supplied component body and optional extra glyphs.
declared_glyphslets a page ship its own bitmap providers (each a dict withchar/file/ascent/height); they are registered at build time.>>> page = CustomPage(anchor="welcome", title="Welcome", body=[{"text": "Hi"}]) >>> page.build(None) # neutral base first, then the developer body untouched [{'text': '', 'shadow_color': [0, 0, 0, 0]}, {'text': 'Hi'}]
intro_page#
Introduction page: manual title, project logo, and the configurable first-page text.
- class IntroPage(
- *,
- anchor: str,
- title: str = '',
- item_id: str | None = None,
- button_layout: ButtonLayout | None = None,
- book_texture: str | Image.Image | None = None,
- home_texture: str | Image.Image | None = None,
- home_button: bool = True,
- transformers: list[Transformer] = <factory>,
- optimize: bool = True,
Bases:
PageThe first page: manual name, logo glyph, then the project’s intro text.
item_page#
Per-item page.
Encapsulates the v1 encode_page item branch (main content selection + wiki buttons),
re-expressed on top of RecipeRenderer and WikiButtonRender,
with button placement driven by ButtonLayout and cross-page links
emitted as deferred PageRef.
- class ItemPage(
- *,
- anchor: str,
- title: str = '',
- item_id: str | None = None,
- button_layout: ButtonLayout | None = None,
- book_texture: str | Image.Image | None = None,
- home_texture: str | Image.Image | None = None,
- home_button: bool = True,
- transformers: list[Transformer] = <factory>,
- optimize: bool = True,
- crafts: list[JsonDict] = <factory>,
- main_craft: JsonDict | None = None,
- buttons: list[WikiButtonRender] = <factory>,
- extra_buttons: list[WikiButtonRender] = <factory>,
Bases:
PageA page describing a single item: its main recipe, then a grid of wiki buttons.
After
prepare(),craftsandbuttonsare populated and can be inspected or mutated byon_item_pagehooks beforebuild()runs.- main_craft: JsonDict | None[source]#
A craft shown as the main recipe instead of the automatic choice, e.g. one of
crafts.
- buttons: list[WikiButtonRender][source]#
The wiki buttons rendered on the page (populated during
build()).
- extra_buttons: list[WikiButtonRender][source]#
Developer-added buttons appended after the automatic ones, e.g. another item’s recipe via
manual.recipes.button_for_item(...)or a page link viamanual.recipes.link_button(...).
- classmethod for_item(
- item_id: str,
- **kwargs: Any,
Convenience constructor producing a page anchored at
item:<id>.
- prepare(manual: Manual) None[source]#
Collect this item’s crafts (own recipes, otherside crafts, mining drops).
- build(manual: Manual) list[TextComponent][source]#
Render the main recipe (or single-item box) followed by the wiki-button grid.
- main_content(
- manual: Manual,
- name: str,
The page’s main craft: how the item is mined, else the craft using most of it, else the item alone in a box.
- craft_buttons( ) list[WikiButtonRender][source]#
The item’s info buttons, its growing seed, consume effects and remainder buttons, then a button per craft, skipping a repeat of the previous result.
- wiki_info_buttons(
- obj: Item | None,
Build info buttons from the item’s WIKI_COMPONENT (WikiButton list or raw text).
- static consume_effects_button(
- obj: Item | None,
An info button listing the effects the
consumablecomponent applies, None when it applies none.>>> item = Item(id="manual_beer", components={"consumable": {"on_consume_effects": [ ... {"type": "minecraft:apply_effects", "effects": [{"id": "minecraft:nausea", "duration": 600}]}, ... ]}}) >>> ItemPage.consume_effects_button(item).hover[1] {'text': '\n- Nausea (0:30)', 'color': 'gray'}
- static click_event_of(
- component: TextComponent,
The click event of a text component, or of the first part of one that has one.
- apply_layout_filters(
- buttons: list[WikiButtonRender],
- layout: ButtonLayout,
Apply the layout’s include, extra buttons and order, then trim to its maximum.
- static trimmed(
- buttons: list[WikiButtonRender],
- limit: int,
Buttons cut down to
limit: the blue crafts but the last one go first, info buttons kept, then the lowest priorities.
- button_to_component(
- button: WikiButtonRender,
Convert a button to its visible text component (icon + hover + optional click).
- place_button_grid(
- content: list[TextComponent],
- buttons: list[WikiButtonRender],
- layout: ButtonLayout,
- manual: Manual,
- recipe_end: int,
Splice the button grid into
contentwherelayout.positionasks for.recipe_endis the index right after the main craft content. At this pointcontentstill holds the in-body title at index 1 (dropped later bybuild()), so “top” inserts at index 2.>>> layout = ButtonLayout(position=lambda content, buttons, manual: [*content, "grid"]) >>> ItemPage(anchor="item:demo").place_button_grid(["base"], [], layout, None, 1) ['base', 'grid']
- render_button_grid(
- content: list[TextComponent],
- buttons: list[WikiButtonRender],
- layout: ButtonLayout,
Lay buttons into a grid, duplicating each line for the 2-row hover trick (ported).
raw_page#
A pre-built page: passes a ready list of text components straight through.
Used for special pages whose content is produced elsewhere (e.g. the ported
stardust_forge page in special).
- class RawPage(
- *,
- anchor: str,
- title: str = '',
- item_id: str | None = None,
- button_layout: ButtonLayout | None = None,
- book_texture: str | Image.Image | None = None,
- home_texture: str | Image.Image | None = None,
- home_button: bool = True,
- transformers: list[Transformer] = <factory>,
- optimize: bool = True,
- content: list[TextComponent] = <factory>,
Bases:
PageA page that simply yields its pre-built
content.>>> RawPage(anchor="forge", content=["hello"]).build(None) ['hello']
texture_page#
A page whose body is a custom background texture, optionally with text baked into it.
This is the feature that lets developers ship “different textures for different pages and the text/descriptions on the texture itself”:
supply a background image (path or PIL image) and a list of BakedText drawn onto it via PIL.
The composited image is registered as a single full-page glyph; optional Minecraft body components can be added underneath (e.g.
clickable links).
- class TexturePage(
- *,
- anchor: str,
- title: str = '',
- item_id: str | None = None,
- button_layout: ButtonLayout | None = None,
- book_texture: str | Image.Image | None = None,
- home_texture: str | Image.Image | None = None,
- home_button: bool = True,
- transformers: list[Transformer] = <factory>,
- optimize: bool = True,
- background: str | Image.Image = '',
- baked_texts: list[BakedText] = <factory>,
- body: list[TextComponent] = <factory>,
- glyph_ascent: int = 1,
- glyph_height: int = 131,
- left_padding: int = 0,
- right_padding: int = 0,
Bases:
PageA full-texture page with optional baked-in text and trailing MC components.
- left_padding: int[source]#
Invisible pixels emitted before the texture glyph, shifting it right by half the padding since the dialog centers the line.