📄 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,
)[source]#

Bases: object

Base 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.

title: str[source]#

Human-readable page title.

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_overrides files 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.

transformers: list[Transformer][source]#

Developer hooks applied to the rendered content, in order.

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,
)[source]#

Bases: Page

The “Category browser” page: one clickable cell per category page.

build(
manual: Manual,
) → list[TextComponent][source]#

Draw the case-grid background glyph and overlay one clickable cell per category page, showing its first item.

button_layout#

Backward-compatible re-export of ButtonLayout (now defined at the package root to avoid an import cycle between config and the pages package).

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>,
)[source]#

Bases: Page

A page showing every item of one category as a clickable grid.

items: list[str][source]#
build(manual: Manual) → list[TextComponent][source]#

Draw the case-grid background glyph and overlay one clickable component per item.

grid_page(
manual: Manual,
file_name: str,
items: list[str],
decorate: Callable[[int, JsonDict], None] | None = None,
) → list[TextComponent][source]#

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.

grid_row(
line: list[TextComponent],
left_padding: int,
) → list[TextComponent][source]#

One row of the grid, written twice: once with the item glyphs, then again with each clickable cell blank, laid over them.

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>,
)[source]#

Bases: Page

A page with a developer-supplied component body and optional extra glyphs.

declared_glyphs lets a page ship its own bitmap providers (each a dict with char/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'}]
body: list[TextComponent][source]#

The page content, as a list of Minecraft text components.

declared_glyphs: list[JsonDict][source]#

Optional glyphs to register at build time.

build(manual: Manual) → list[TextComponent][source]#

Register the declared glyphs, then return the body under a neutral (no-font) base.

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,
)[source]#

Bases: Page

The first page: manual name, logo glyph, then the project’s intro text.

build(manual: Manual) → list[TextComponent][source]#

Logo glyph on top, then the configured first_page_text in the default font.

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>,
)[source]#

Bases: Page

A page describing a single item: its main recipe, then a grid of wiki buttons.

After prepare(), crafts and buttons are populated and can be inspected or mutated by on_item_page hooks before build() runs.

crafts: list[JsonDict][source]#

Every craft related to the item, gathered by prepare().

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 via manual.recipes.link_button(...).

classmethod for_item(
item_id: str,
**kwargs: Any,
) → ItemPage[source]#

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,
) → list[TextComponent][source]#

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(
manual: Manual,
name: str,
obj: Item | None,
) → 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,
) → list[WikiButtonRender][source]#

Build info buttons from the item’s WIKI_COMPONENT (WikiButton list or raw text).

static consume_effects_button(
obj: Item | None,
) → WikiButtonRender | None[source]#

An info button listing the effects the consumable component 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,
) → JsonDict | None[source]#

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,
) → list[WikiButtonRender][source]#

Apply the layout’s include, extra buttons and order, then trim to its maximum.

static trimmed(
buttons: list[WikiButtonRender],
limit: int,
) → list[WikiButtonRender][source]#

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,
) → JsonDict[source]#

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,
) → list[TextComponent][source]#

Splice the button grid into content where layout.position asks for.

recipe_end is the index right after the main craft content. At this point content still holds the in-body title at index 1 (dropped later by build()), 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,
) → None[source]#

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>,
)[source]#

Bases: Page

A page that simply yields its pre-built content.

>>> RawPage(anchor="forge", content=["hello"]).build(None)
['hello']
content: list[TextComponent][source]#

The ready-made dialog body, deep-copied at build time.

build(manual: Manual) → list[TextComponent][source]#

Return a deep copy of content (so later passes cannot mutate the original).

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,
)[source]#

Bases: Page

A full-texture page with optional baked-in text and trailing MC components.

background: str | Image.Image[source]#

Background image path, or a ready PIL image.

baked_texts: list[BakedText][source]#

Texts drawn onto the background with PIL.

body: list[TextComponent][source]#

Optional MC text shown under the texture.

glyph_ascent: int[source]#

Y offset of the page texture bitmap.

glyph_height: int[source]#

Size of the page texture bitmap.

left_padding: int[source]#

Invisible pixels emitted before the texture glyph, shifting it right by half the padding since the dialog centers the line.

right_padding: int[source]#

Invisible pixels emitted after the texture glyph, shifting it left by half the padding since the dialog centers the line.

build(manual: Manual) → list[TextComponent][source]#

Composite the background + baked texts, register it as one glyph, append the body.