📖 ingame_manual#

ingame_manual: modern, extensible, dialog-first in-game manual generator.

Opt in by replacing stewbeet.plugins.ingame_manual with stewbeet.plugins.ingame_manual in your beet pipeline. See api (get_manual, Page subclasses, Phase, ButtonLayout, BakedText) for the customization API.

copy_templates(
config: ManualConfig,
) → None[source]#

Copy bundled assets (and optional manual_overrides) into the temporary templates dir.

beet_default(ctx: Context) → None[source]#

Entry point: build the manual (reusing any Manual registered during setup).

api#

Public API surface for ingame_manual (re-exported from the top-level stewbeet).

Developers use get_manual() in their setup to grab the live Manual and register pages/hooks before the plugin builds it.

get_manual() → Manual[source]#

Return the current Manual, creating it from the beet meta if needed.

Call this in setup_definitions (after items are defined) to register custom pages, hooks (manual.on(...) / manual.on_item_page(...)) and button layouts. The ingame_manual plugin reuses the same handle when it runs.

button_layout#

Wiki-button placement configuration.

A ButtonLayout decides where and which wiki buttons (small clickable recipe-result / info icons) appear on a page, and how overflow is handled. It can be set as the manual-wide default (ManualConfig.button_layout) or overridden per page (Page.button_layout).

Lives at the package root (not under pages/) so config can import it without triggering the pages package: which would create an import cycle.

class ButtonLayout(*, columns: int = 5, max_buttons: int = 20, position: str | ~collections.abc.Callable[[...], ~typing.Any] = 'after_recipe', order: ~collections.abc.Callable[[~stewbeet.plugins.ingame_manual.recipes.buttons.WikiButtonRender], ~typing.Any] | None = None, include: ~collections.abc.Callable[[~stewbeet.plugins.ingame_manual.recipes.buttons.WikiButtonRender], bool] | None = None, extra_buttons: list[~stewbeet.plugins.ingame_manual.recipes.buttons.WikiButtonRender] = <factory>)[source]#

Bases: object

Controls wiki-button rendering for a page.

>>> layout = ButtonLayout(columns=6, position="bottom")
>>> layout.columns
6
columns: int[source]#

Number of buttons per row.

max_buttons: int[source]#

Hard cap on how many buttons are shown (overflow dropped by priority).

position: str | Callable[[...], Any][source]#

Where the button grid is spliced into the page content: “after_recipe” inserts it right after the main craft content (before anything appended later, e.g. special notes), “top” places it just under the title (before the recipe), “bottom” appends it at the very end of the page, and a callable (content, buttons, manual) -> content takes full control (it receives the un-rendered WikiButtonRender list and must return the final content).

order: Callable[[WikiButtonRender], Any] | None[source]#

Sort key applied to buttons before layout (e.g. lambda b: -b.priority).

include: Callable[[WikiButtonRender], bool] | None[source]#

Predicate (button) -> bool filtering which buttons to keep.

extra_buttons: list[WikiButtonRender][source]#

Additional developer-supplied buttons appended before layout.

clone() → ButtonLayout[source]#

Return a shallow copy (so per-page overrides don’t mutate the shared default).

>>> layout = ButtonLayout(columns=4)
>>> copy = layout.clone()
>>> copy == layout, copy is layout
(True, False)

config#

Typed configuration for the manual, read from ctx.meta["stewbeet"]["manual"].

Replaces the scattered manual_config.get(...) calls and the config-ish fields of the old SharedMemory. v2 is dialog-first: use_dialog is validated to be 1 or 2 (0 is coerced to 1 with a warning). The old caching keys (cache_pages) are intentionally not read; json_dump_path survives only as an optional debug dump.

class ManualConfig(
*,
project_id: str,
project_name: str,
project_author: str,
iso_renders_path: str = '',
font_cache_path: str = '',
manual_overrides: str = '',
json_dump_path: str = '',
high_resolution: bool = True,
use_dialog: int = 1,
debug_mode: bool = False,
cache_assets: bool = True,
max_items_per_row: int = 5,
max_rows_per_page: int = 5,
showcase_image: int = 3,
name: str = '',
first_page_text: TextComponent = '',
components_to_include: list[str] = <factory>,
button_layout: ButtonLayout = <factory>,
)[source]#

Bases: object

Typed mirror of the manual stewbeet config block.

Build one with from_meta(). All fields are public.

>>> config = ManualConfig(project_id="mypack", project_name="My Pack", project_author="me", max_items_per_row=9)
>>> config.max_items_per_row  # clamped like v1 (max 6 per row)
6
>>> config.font
'mypack:manual'
>>> config.name  # defaults to "<project_name> Manual"
'My Pack Manual'
project_id: str[source]#
project_name: str[source]#
project_author: str[source]#
iso_renders_path: str[source]#

Folder holding the per-item PNG renders, shared with auto.text_renders. Resolved lazily when empty.

font_cache_path: str[source]#

Throwaway folder for the generated glyph PNGs, inside beet’s own cache. Resolved lazily when empty.

manual_overrides: str[source]#
json_dump_path: str[source]#
high_resolution: bool[source]#
use_dialog: int[source]#
debug_mode: bool[source]#
cache_assets: bool[source]#
max_items_per_row: int[source]#
max_rows_per_page: int[source]#
showcase_image: int[source]#
name: str[source]#
first_page_text: TextComponent[source]#
components_to_include: list[str][source]#
button_layout: ButtonLayout[source]#
property max_items_per_page: int[source]#

Item capacity of a category page (rows x columns).

property left_padding: int[source]#

Category grid left padding: higher items-per-row -> lower padding.

property font: str[source]#

Fully-qualified font id, e.g. mynamespace:manual.

classmethod from_meta(
ctx: Context,
) → ManualConfig[source]#

Build a ManualConfig from the beet context meta.

dialog#

Dialog generation, the manual’s only output.

Each page already produces its own dialog body (see base), so the DialogEmitter only wraps that body with the title (item sprite or text, taken from the page) and the prev/home/next navigation row. The page->item mapping comes from Manual pages. The manual is reachable through the vanilla quick_actions dialog tag.

DIALOG_ICON_HEIGHT: int = 12[source]#

On-screen height of the item icon framing a dialog title.

An atlas sprite rendered at 8 pixels; the glyph is a little taller so the icon carries next to the title text without towering over it.

class DialogEmitter(manual: Manual)[source]#

Bases: object

Builds one dialog per manual page plus the open-manual plumbing.

eq=False keeps identity semantics (the Manual reference would make field-based equality both meaningless and expensive).

manual: Manual[source]#

The manual whose rendered pages are emitted as dialogs.

render_icon(
item: str,
) → JsonDict | None[source]#

The glyph component showing item, or None when no image could be resolved for it.

Resolved here rather than left to the later auto.text_renders pass, so the dialogs still show their icons when that plugin is not in the pipeline.

Parameters:

item – Item id, or the reserved ICON standing for the project logo.

Returns:

A glyph text component, or None to fall back to a sprite.

Return type:

JsonDict | None

sprite_icon(
sprite: str,
) → JsonDict[source]#

A sprite icon component for sprite (atlas-aware for pack format >= 93).

add_icon(
title: TextComponent,
icon: JsonDict,
) → TextComponent[source]#

Wrap a title between two copies of an icon component.

add_sprite(
title: TextComponent,
sprite: str,
) → TextComponent[source]#

Wrap a title between two sprite icons (atlas-aware for pack format >= 93).

get_atlas_title(
item: str,
) → TextComponent[source]#

Build a dialog title with the item’s icon if one is available, else its name.

A render glyph is preferred: it keeps the full resolution of the iso render instead of the 16x16 the sprite atlas forces. An animated texture still goes through a sprite, since a baked glyph would freeze it on its first frame.

emit() → None[source]#

Generate per-page dialogs, the open-manual advancement, and the quick action.

write_page_dialog(
page_index: int,
page: list[TextComponent],
) → str[source]#

Write the dialog of one page: its title, the navigation row, then its body padded to 22 lines.

Returns:

The dialog’s path, without namespace.

page_title(
page_obj: Page | None,
) → TextComponent[source]#

A page’s dialog title: the item sprite for an item page, else its title text, empty for neither.

navigation_row(
page_index: int,
page_obj: Page | None,
) → list[TextComponent][source]#

The top of a page: the book background, then previous (left), home (middle, to the first page) and next (right).

The home glyph shares NONE_FONT’s advance to keep the layout, and a spacer on the second row extends its hit area.

write_dialog_list(
dialog_ids: list[str],
) → None[source]#

The dialog listing every page, titled with the pack icon, as a render glyph when possible.

count_breaklines(
element: TextComponent,
) → int[source]#

The line breaks a text component holds, nested components included.

>>> count_breaklines(["a\n", {"text": "b\n\n"}, [{"text": "c"}]])
3

glyphs#

Glyph code points reserved by the manual.

The allocator itself lives in stewbeet.core.utils.fonts.allocator and is shared with every other font generator; this module only owns the manual’s own reserved characters and sizes.

Every visual element of the manual (item icon, recipe template, page background, invisible spacer) is a PNG mapped to a private-use unicode character inside a Minecraft bitmap font. The reserved glyph code points below are alignment-critical and are kept byte-identical to the v1 plugin so existing template PNGs keep rendering correctly.

HOME_FONT: str = '4'[source]#

Dialog “go to first page” arrow.

WIKI_GROWING_SEED_FONT: str = 'T'[source]#

Growing seed wiki button icon.

INVISIBLE_ITEM_FONT: str = 'U'[source]#

Invisible item to place.

images#

All PIL image generation for the manual, encapsulated in GlyphImageBuilder.

Ports the v1 image_utils + page_font modules into instance methods that read from an injected ManualConfig and write glyph providers through an injected GlyphAllocator (no more global SharedMemory). Also adds the new texture-page helpers (bake_text_onto(), register_full_page_glyph()).

WIKI_ICON_TEMPLATES: dict[str, str] = {'mining': 'wiki_mining_template.png', 'source_link': 'wiki_source_link_template.png'}[source]#

Wiki icon background per craft type, the green ingredient-of-craft template being the default.

class BakedText(
*,
text: str,
xy: tuple[int, int],
color: tuple[int, int, int, int] = (0, 0, 0, 255),
font_size: int = 16,
font_path: str | None = None,
align: str = 'left',
shadow: tuple[int, int, int, int] | None = None,
)[source]#

Bases: object

A piece of text to draw directly onto a TexturePage background.

>>> bt = BakedText(text="Step 1", xy=(10, 20))
>>> bt.xy
(10, 20)
text: str[source]#
xy: tuple[int, int][source]#
color: tuple[int, int, int, int][source]#
font_size: int[source]#
font_path: str | None[source]#
align: str[source]#
shadow: tuple[int, int, int, int] | None[source]#
class GlyphImageBuilder(
config: ManualConfig,
glyphs: GlyphAllocator,
_border_color: tuple[int,
int,
int,
int] | None=None,
_wiki_icons_generated: set[str] = <factory>,
_spacer_chars: dict[int,
str]=<factory>,
)[source]#

Bases: object

Builds every manual texture and registers its glyph provider.

Holds a reference to the config and the glyph allocator; all paths/flags come from those instead of globals.

>>> config = ManualConfig(project_id="demo", project_name="Demo", project_author="me")
>>> builder = GlyphImageBuilder(config, GlyphAllocator(project_id="demo"))
>>> builder.image_count(5).size  # Minecraft-style count overlay, always 32x32
(32, 32)
static careful_resize(
image: Image,
max_result_size: int,
resampling: Resampling = Resampling.NEAREST,
) → Image[source]#

Resize an image while keeping the aspect ratio.

>>> careful_resize(Image.new("RGBA", (64, 32)), 32).size
(32, 16)
>>> careful_resize(Image.new("RGBA", (16, 64)), 32).size
(8, 32)
static add_border(
image: Image,
border_color: tuple[int, int, int, int],
border_size: int,
) → Image[source]#

Add a colored border around the opaque region of an image (alpha dilation).

config: ManualConfig[source]#

The manual configuration (paths, resolution flags…).

glyphs: GlyphAllocator[source]#

Where generated textures register their font providers.

get_border_color() → tuple[int, int, int, int][source]#

Border color from the top-right pixel of the case template, lightened (cached).

load_simple_case_no_border(
high_res: bool,
) → Image[source]#

Load the case template, widened by one pixel column in high-res mode.

image_count(
count: int | str,
) → Image[source]#

Generate a 32x32 image showing an item count (Minecraft inventory style).

high_res_icon(
item: str,
item_image: Image,
count: int | str | JsonDict = 1,
) → str[source]#

Generate a 256px item glyph (with optional count) and return its font string.

load_square_texture(
path_id: str,
) → Image[source]#

Load an item texture by ns/item path id, resized to SQUARE_SIZE (placeholder if missing).

load_result_texture(
name: str,
craft: JsonDict,
) → tuple[Image, Image][source]#

Load + resize a craft’s result texture (or the item’s own), return (texture, alpha mask).

recipe_image(
name: str,
page_font: str,
output_name: str = '',
) → None[source]#

Generate the single-item box image (item with no recipe). Per-recipe-type images are produced by each renderer’s build_image under recipes.types.

wiki_result_icon(
name: str,
craft: JsonDict,
) → str[source]#

Generate a small recipe-result wiki icon and return its font (or default font).

invisible_spacer(width_px: int) → str[source]#

Return an invisible glyph advancing exactly width_px pixels (”” if <= 0).

The square none texture rendered at height H advances H + 1 pixels, so one provider (ascent 0, height width_px - 1) is registered per distinct width, then reused. Used by TexturePage left/right paddings.

bake_text_onto(
background: Image,
baked_texts: list[BakedText],
) → Image[source]#

Draw a list of BakedText onto a copy of background and return it.

register_full_page_glyph(
image: Image,
name: str,
ascent: int = 1,
height: int = 131,
) → str[source]#

Save a full-page image under font/page/ and register it as a single glyph.

Returns the glyph character. Used by TexturePage.

manual#

The Manual orchestrator.

Owns the ordered list of pages, the glyph allocator, the image builder and the recipe renderer, plus the developer hook registry. build() runs the pipeline:

discover -> prepare -> order -> render -> resolve -> optimize -> emit

firing the matching Phase hooks after each step. Cross-page links are emitted as PageRef during render and substituted once in resolve (after the order is final), so inserting/reordering pages never needs page-number bookkeeping.

class Phase(*values)[source]#

Bases: Enum

Points in the build pipeline at which developer hooks run.

DISCOVERED = 'discovered'[source]#
PREPARED = 'prepared'[source]#
ORDERED = 'ordered'[source]#
RENDERED = 'rendered'[source]#
RESOLVED = 'resolved'[source]#
BEFORE_EMIT = 'before_emit'[source]#
class Manual(
config: ManualConfig,
)[source]#

Bases: object

Orchestrates manual generation and exposes the public extension API.

Construct with Manual(config); every other field is derived. eq=False keeps identity semantics: the manual and its collaborators (RecipeRenderer) reference each other, so field-based equality would recurse.

>>> manual = Manual(ManualConfig(project_id="demo", project_name="Demo", project_author="me"))
>>> manual.recipes.manual is manual
True
>>> _ = manual.add_page(Page(anchor="later"))
>>> len(manual.pages), len(manual.pending_ops)  # deferred until discover() builds the defaults
(0, 1)
config: ManualConfig[source]#

The typed manual configuration (the only constructor argument).

glyphs: GlyphAllocator[source]#

Dynamic glyph counter + bitmap font-provider registry.

images: GlyphImageBuilder[source]#

Builder for every manual texture (icons, templates, page backgrounds).

recipes: RecipeRenderer[source]#

Dispatcher rendering each recipe through its registered CraftRenderer.

pages: list[Page][source]#

The ordered pages; 1-based page numbers follow this order.

by_anchor: dict[str, Page][source]#

Anchor -> page lookup (rebuilt by order()).

hooks: dict[Phase, list[Callable[[Manual], None]]][source]#

Per-Phase developer hooks (see on() / register()).

item_page_hooks: list[Callable[[ItemPage, Manual], None]][source]#

Hooks run on every ItemPage during preparation.

discovered: bool = False[source]#

True once discover() built the default pages.

pending_ops: list[Callable[[], None]][source]#

Page operations deferred until after discover().

definitions_as_objects: dict[str, Item][source]#

Item id -> Item cache built at discover time.

categories: dict[str, list[str]][source]#

Category name -> item ids (insertion order preserved).

has_forge_3x3: bool = False[source]#

Whether any recipe needs the 3x3 awakened forge assets.

has_forge_3x4: bool = False[source]#

Whether any recipe needs the 3x4 awakened forge assets.

pages_content: list[list[TextComponent]][source]#

Rendered dialog bodies, one list of components per page.

item_index: dict[str, int][source]#

Item id -> 1-based page index (computed by order()).

anchor_index: dict[str, int][source]#

Anchor -> 1-based page index (computed by order()).

cached_simple_case: Image | None = None[source]#

Cache for simple_case.

texture_cache: dict[str, Image][source]#

Item id -> loaded texture cache (see load_item_texture()).

property simple_case: Image[source]#

The case background image (cached), widened in high-res mode.

object_for(
item_id: str | None,
) → Item | None[source]#

Return the cached Item for an internal id, or None.

load_item_texture(item: str) → Image[source]#

Open an item’s cached iso-render texture (placeholder if missing).

add_page(
page: Page,
) → Page[source]#

Append a page to the end of the manual.

insert_page(
page: Page,
*,
before: str | None = None,
after: str | None = None,
index: int | None = None,
) → Page[source]#

Insert a page before/after an anchor, or at an explicit index.

replace_page(
anchor: str,
page: Page,
) → Page[source]#

Replace the page at anchor with page.

remove_page(anchor: str) → None[source]#

Remove the page identified by anchor.

move_page(
anchor: str,
*,
before: str | None = None,
after: str | None = None,
index: int | None = None,
) → None[source]#

Move an existing page to a new position.

apply_add(
page: Page,
) → None[source]#

Immediate (non-deferred) implementation of add_page().

apply_insert(
page: Page,
before: str | None,
after: str | None,
index: int | None,
) → None[source]#

Immediate (non-deferred) implementation of insert_page().

apply_replace(
anchor: str,
page: Page,
) → None[source]#

Immediate (non-deferred) implementation of replace_page().

apply_remove(anchor: str) → None[source]#

Immediate (non-deferred) implementation of remove_page().

apply_move(
anchor: str,
before: str | None,
after: str | None,
index: int | None,
) → None[source]#

Immediate (non-deferred) implementation of move_page().

get_page(
anchor: str,
) → Page[source]#

Return the page registered under anchor.

get_page_for_item(
item_id: str,
) → ItemPage | None[source]#

Return the ItemPage for an item id, if present.

index_of_anchor(anchor: str) → int[source]#

Return the 0-based list index of the page with anchor (KeyError if absent).

register(
phase: Phase,
fn: Callable[[Manual], None],
) → Callable[[Manual], None][source]#

Register fn to run after phase. Returns fn (usable as a decorator).

on(
phase: Phase,
) → Callable[[Callable[[Manual], None]], Callable[[Manual], None]][source]#

Decorator form of register().

on_item_page(
fn: Callable[[ItemPage, Manual], None],
) → Callable[[ItemPage, Manual], None][source]#

Register fn(page, manual) to run on every item page during preparation.

run_hooks(
phase: Phase,
) → None[source]#

Fire all hooks registered for phase.

page_index_of(
ref: PageRef,
) → int[source]#

Resolve a PageRef to a 1-based page index (-1 if unknown).

build() → None[source]#

Run the full generation pipeline, firing hooks between steps.

discover() → None[source]#

Create the default page set (intro, browser, categories, items, special).

detect_forge_sizes() → None[source]#

Note which awakened forge grids the recipes use, 3x3 for up to 9 ingredients and 3x4 above.

category_pages() → list[CategoryPage][source]#

A page per category, numbered pages of max_items_per_page items for a category holding more.

item_pages() → list[ItemPage][source]#

A page per item with a category, in the order of the categories.

prepare() → None[source]#

Run per-page preparation and the on_item_page hooks.

order() → None[source]#

Finalize the order and compute the anchor/item -> index maps (1-based).

render() → None[source]#

Render every page to text components (links left as PageRef).

normalize() → None[source]#

Convert the rendered tree to plain dict/list/str (preserving PageRef).

Item components copied from definitions (and meta-derived components like first_page_text) are beet Box objects with default-box behavior: accessing a missing key auto-creates an empty {} entry, which corrupts the output (Minecraft: “Not a string: {}”). Flattening to plain Python types up front makes every later pass (resolve/optimize/dialog) safe.

resolve() → None[source]#

Turn every change_page click event into a show_dialog to the target page.

A PageRef is resolved to its 1-based index first; a literal int page is used as-is (covers author-provided WikiButton links). Unresolvable links are dropped. Iterative (no recursion limit) and bounded: such links only live in click_event, so we never descend into hover_event subtrees (which hold deep item-component data).

resolve_click_event(
node: dict[str, Any],
) → None[source]#

Turn a node’s change_page click event into a show_dialog, or drop it when its page does not exist.

optimize() → None[source]#

Merge adjacent compounds per page (skipping pages that opt out).

emit() → None[source]#

Write fonts/textures, dialogs, the manual item, showcase, and clean up.

manual_emit#

Emit helpers for Manual (static assets, font/texture output, manual item).

Extracted from manual.py to keep the orchestrator focused on the pipeline. Each function takes the Manual instance.

register_static_assets(manual: Manual) → None[source]#

Copy reserved template textures to the RP and register their providers.

register_static_providers(manual: Manual) → None[source]#

Register the font providers of the reserved template textures, whose ascents and heights align the manual’s layout.

load_page_texture(
texture: str | Image,
) → Image[source]#

Open a per-page override texture.

A string resolves as a project path first, then against the templates dir, so a manual_overrides filename works. The source is marked used because it gets re-encoded under a new name.

register_nav_overrides(manual: Manual) → None[source]#

Register dedicated glyphs for every page overriding book_texture / home_texture.

Each glyph replaces BOOK_FONT / HOME_FONT in that page’s dialog navigation row, with the same ascent/height as the shared provider so the layout stays put (a home texture should keep the default’s 16x16 proportions, since the glyph advance follows the image content).

write_font(manual: Manual) → None[source]#

Register every collected provider in the <ns>:manual font of the resource pack.

copy_generated_textures(manual: Manual) → None[source]#

Copy every generated font PNG into the resource pack.

validate_providers(manual: Manual) → None[source]#

Error out if any font provider references a missing texture or has no chars.

create_manual_item(manual: Manual) → None[source]#

Create/merge the manual item (dialog-first: no written_book NBT).

optimizer#

Text-component optimization (merge adjacent compounds, strip nested events).

optimize_element(
content: TextComponent,
) → TextComponent[source]#

Optimize the page content by merging compounds when possible.

>>> optimize_element(["","",{"text": "A", "color": "red", "bold": True, "shadow_color": [0,0,0,0]}])
['', {'text': 'A', 'color': 'red', 'bold': True, 'shadow_color': [0, 0, 0, 0]}]
merge_into(
new_content: list[TextComponent],
compound: TextComponent,
) → None[source]#

Append a compound, merged into the last one when both differ only by their text, or when it is only line breaks.

A string merges into a string. A compound merging into one that is neither a string nor a dict is dropped.

same_style(
compound: TextComponent,
previous: TextComponent,
) → bool[source]#

Whether two compounds are the same apart from their text, two dicts being compared without it.

remove_events(
compound: TextComponent,
) → None[source]#

Remove hover/click events from a compound recursively (in place).

>>> component = {"text": "a", "click_event": {"action": "open_url"}, "extra": [{"text": "b", "hover_event": {}}]}
>>> remove_events(component)
>>> component
{'text': 'a', 'extra': [{'text': 'b'}]}

paths#

Filesystem paths for the manual’s bundled assets/templates.

MANUAL_ASSETS_PATH: str = '/home/runner/work/StewBeet/StewBeet/python_package/stewbeet/plugins/ingame_manual'[source]#

Root of this plugin package.

TEMPLATES_PATH: str = '/tmp/stewbeet_manual_v2_templates_zeve5x08'[source]#

Runtime templates folder, filled with the assets at build time and overlaid with the project’s manual_overrides.

It is a per-process temporary directory, so concurrent builds never share it, removed on interpreter exit.

template_path(filename: str) → str[source]#

Path to a template file: the runtime templates dir once copy_templates() populated it (so manual_overrides win), else the bundled asset (lets code run before the beet entrypoint, e.g. in doctests).

refs#

Deferred page links.

A PageRef represents “a link to some page” without committing to a concrete page number. Links are emitted during rendering and substituted in a single pass by Manual.resolve() after the page order is final. So inserting/reordering/replacing pages never requires the manual +1 page-number bumping the v1 plugin needed.

class PageRef(
item: str | None = None,
anchor: str | None = None,
page: int | None = None,
)[source]#

Bases: object

A deferred reference to a manual page.

Exactly one of the targeting fields is meaningful, checked in order: item (link to the page generated for an item id), then anchor (link to a page by its stable anchor), then page (a literal 1-based page index).

>>> PageRef(item="wrench").item
'wrench'
>>> PageRef(anchor="category:Materials").anchor
'category:Materials'
>>> PageRef(page=3).page
3
item: str | None[source]#
anchor: str | None[source]#
page: int | None[source]#

showcase#

Showcase image generation (promotional grids of items).

Ported from v1 showcase_image with renders_path passed in rather than read from a global.

SHOWCASE_FORMAT: str = '1'[source]#

Part of every showcase signature: bump it when create_showcase_image draws differently, so existing images are redrawn.

CACHE_NAME: str = 'stewbeet_showcase'[source]#

Beet cache slot recording what each showcase image on disk was drawn from.

calculate_optimal_grid(item_count: int) → tuple[int, int][source]#

Grid dimensions closest to a 16:9 aspect ratio for item_count items.

>>> calculate_optimal_grid(0)
(0, 0)
>>> calculate_optimal_grid(12)
(3, 4)
generate_showcase_images(
showcase_mode: int,
categories: dict[str, list[str]],
simple_case: Image,
renders_path: str,
all_items: list[str] | None = None,
) → None[source]#

Generate showcase image(s) per mode (1=manual, 2=all, 3=both).

When all_items is given it overrides the default “all items” set (every definition) used for all_items.png: e.g. to skip items that have no iso render. Defaults to list(Mem.definitions.keys()) when None.

start_showcase_image(
items: list[str],
filename: str,
simple_case: Image,
renders_path: str,
) → None[source]#

Draw one showcase image in a background process, unless the one on disk was drawn from the same inputs.

Drawing and encoding a grid of every item takes seconds, and the build waits for that process before exiting.

showcase_signature(
items: list[str],
filename: str,
simple_case: Image,
project_id: str,
renders_path: str,
) → str[source]#

Fingerprint of everything a showcase image is drawn from: the items, their renders on disk and the case template.

is_showcase_up_to_date(
image_path: str,
record_path: str,
signature: str,
) → bool[source]#

Whether the image on disk is the one recorded as drawn from signature, untouched since.

create_showcase_image(
items: list[str],
filename: str,
simple_case: Image,
output_dir: str,
project_id: str,
renders_path: str,
record_path: str = '',
signature: str = '',
) → None[source]#

Build one composite showcase grid image and save it to output_dir.

With record_path, the image saved is recorded there as drawn from signature, see is_showcase_up_to_date.

special#

Special, non-item pages built on the public API.

  • register_heavy_workbench registers a temporary heavy_workbench Block (when the smithed.crafter lib is used) so it flows through the normal item-page pipeline; the manual then moves its page to position 2 via Manual.move_page (no page bumping).

  • build_stardust_forge_page returns the ported Awakened Forge page content, inserted as a RawPage via Manual.insert_page.

register_heavy_workbench() → None[source]#

Register the temporary heavy_workbench block/model if smithed.crafter is used.

build_stardust_forge_page() → list[TextComponent][source]#

Awakened Forge dialog body (the “Awakened Forge” title is the RawPage’s title).

The first element is the parent: its open_url click + hover cascade to the whole page, and shadow_color disables text shadows (dialog look).