📖 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,
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.
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>,
Bases:
objectTyped mirror of the
manualstewbeet 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'
- 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.
- button_layout: ButtonLayout[source]#
- property left_padding: int[source]#
Category grid left padding: higher items-per-row -> lower padding.
- classmethod from_meta(
- ctx: Context,
Build a
ManualConfigfrom 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:
objectBuilds one dialog per manual page plus the open-manual plumbing.
eq=Falsekeeps identity semantics (theManualreference would make field-based equality both meaningless and expensive).- render_icon(
- item: str,
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_renderspass, so the dialogs still show their icons when that plugin is not in the pipeline.- Parameters:
item – Item id, or the reserved
ICONstanding 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,
A sprite icon component for
sprite(atlas-aware for pack format >= 93).
- add_icon(
- title: TextComponent,
- icon: JsonDict,
Wrap a title between two copies of an icon component.
- add_sprite(
- title: TextComponent,
- sprite: str,
Wrap a title between two sprite icons (atlas-aware for pack format >= 93).
- get_atlas_title(
- item: str,
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.
- write_page_dialog(
- page_index: int,
- page: list[TextComponent],
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,
A page’s dialog title: the item sprite for an item page, else its title text, empty for neither.
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.
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,
Bases:
objectA piece of text to draw directly onto a
TexturePagebackground.>>> bt = BakedText(text="Step 1", xy=(10, 20)) >>> bt.xy (10, 20)
- 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>,
Bases:
objectBuilds 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,
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,
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,
Load the case template, widened by one pixel column in high-res mode.
- image_count(
- count: int | str,
Generate a 32x32 image showing an item count (Minecraft inventory style).
- high_res_icon(
- item: str,
- item_image: Image,
- count: int | str | JsonDict = 1,
Generate a 256px item glyph (with optional count) and return its font string.
- load_square_texture(
- path_id: str,
Load an item texture by
ns/itempath id, resized to SQUARE_SIZE (placeholder if missing).
- load_result_texture(
- name: str,
- craft: JsonDict,
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 = '',
Generate the single-item box image (item with no recipe). Per-recipe-type images are produced by each renderer’s
build_imageunderrecipes.types.
- wiki_result_icon(
- name: str,
- craft: JsonDict,
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_pxpixels (”” if <= 0).The square
nonetexture rendered at heightHadvancesH + 1pixels, so one provider (ascent 0, heightwidth_px - 1) is registered per distinct width, then reused. Used byTexturePageleft/right paddings.
- bake_text_onto(
- background: Image,
- baked_texts: list[BakedText],
Draw a list of
BakedTextonto a copy ofbackgroundand return it.
- register_full_page_glyph(
- image: Image,
- name: str,
- ascent: int = 1,
- height: int = 131,
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:
EnumPoints in the build pipeline at which developer hooks run.
- class Manual(
- config: ManualConfig,
Bases:
objectOrchestrates manual generation and exposes the public extension API.
Construct with
Manual(config); every other field is derived.eq=Falsekeeps 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.
- hooks: dict[Phase, list[Callable[[Manual], None]]][source]#
Per-
Phasedeveloper hooks (seeon()/register()).
- item_page_hooks: list[Callable[[ItemPage, Manual], None]][source]#
Hooks run on every
ItemPageduring preparation.
- discovered: bool = False[source]#
True once
discover()built the default pages.
- pending_ops: list[Callable[[], None]][source]#
Page operations deferred until after
discover().
- pages_content: list[list[TextComponent]][source]#
Rendered dialog bodies, one list of components per page.
- 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()).
- object_for(
- item_id: str | None,
Return the cached
Itemfor an internal id, or None.
- load_item_texture(item: str) Image[source]#
Open an item’s cached iso-render texture (placeholder if missing).
- insert_page(
- page: Page,
- *,
- before: str | None = None,
- after: str | None = None,
- index: int | None = None,
Insert a page before/after an anchor, or at an explicit index.
- move_page(
- anchor: str,
- *,
- before: str | None = None,
- after: str | None = None,
- index: int | None = None,
Move an existing page to a new position.
- apply_add(
- page: Page,
Immediate (non-deferred) implementation of
add_page().
- apply_insert(
- page: Page,
- before: str | None,
- after: str | None,
- index: int | None,
Immediate (non-deferred) implementation of
insert_page().
- apply_replace(
- anchor: str,
- page: Page,
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,
Immediate (non-deferred) implementation of
move_page().
- get_page_for_item(
- item_id: str,
Return the
ItemPagefor 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( ) Callable[[Manual], None][source]#
Register
fnto run afterphase. Returnsfn(usable as a decorator).
- on(
- phase: Phase,
Decorator form of
register().
- on_item_page( ) Callable[[ItemPage, Manual], None][source]#
Register
fn(page, manual)to run on every item page during preparation.
- page_index_of(
- ref: PageRef,
Resolve a
PageRefto a 1-based page index (-1 if unknown).
- 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_pageitems for a category holding more.
- item_pages() list[ItemPage][source]#
A page per item with a category, in the order of the categories.
- 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 beetBoxobjects 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_pageclick event into ashow_dialogto the target page.A
PageRefis 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 inclick_event, so we never descend intohover_eventsubtrees (which hold deep item-component data).
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,
Open a per-page override texture.
A string resolves as a project path first, then against the templates dir, so a
manual_overridesfilename works. The source is marked used because it gets re-encoded under a new name.
Register dedicated glyphs for every page overriding
book_texture/home_texture.Each glyph replaces
BOOK_FONT/HOME_FONTin 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>:manualfont of the resource pack.
- copy_generated_textures(manual: Manual) None[source]#
Copy every generated font PNG into the resource pack.
optimizer#
Text-component optimization (merge adjacent compounds, strip nested events).
- optimize_element(
- content: TextComponent,
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,
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,
Whether two compounds are the same apart from their text, two dicts being compared without it.
- remove_events(
- compound: TextComponent,
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.
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,
Bases:
objectA 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), thenanchor(link to a page by its stable anchor), thenpage(a literal 1-based page index).>>> PageRef(item="wrench").item 'wrench' >>> PageRef(anchor="category:Materials").anchor 'category:Materials' >>> PageRef(page=3).page 3
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_imagedraws 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_countitems.>>> 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,
Generate showcase image(s) per mode (1=manual, 2=all, 3=both).
When
all_itemsis given it overrides the default “all items” set (every definition) used forall_items.png: e.g. to skip items that have no iso render. Defaults tolist(Mem.definitions.keys())whenNone.
- start_showcase_image(
- items: list[str],
- filename: str,
- simple_case: Image,
- renders_path: str,
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,
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,
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 = '',
Build one composite showcase grid image and save it to
output_dir.With
record_path, the image saved is recorded there as drawn fromsignature, seeis_showcase_up_to_date.
special#
Special, non-item pages built on the public API.
register_heavy_workbenchregisters a temporaryheavy_workbenchBlock(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 viaManual.move_page(no page bumping).build_stardust_forge_pagereturns the ported Awakened Forge page content, inserted as aRawPageviaManual.insert_page.