🚀 initialize#

First plugin of a build: resets the build state, fills configuration defaults and sets up both pack.mcmeta files.

TEXTURE_SUFFIX_RENAMES: dict[str, str] = {'_down': '_bottom', '_east': '_right', '_north': '_front', '_off': '', '_south': '_back', '_up': '_top', '_west': '_left'}[source]#

Texture name parts renamed to the side names the generated models look for.

PACK_KEYS_ORDER: tuple[str, ...] = ('pack_format', 'description', 'supported_formats', 'min_format', 'max_format')[source]#

The keys of pack.mcmeta’s pack that come first, in this order.

reset_build_state(
ctx: Context,
) → None[source]#

Start the build from empty memory, so consecutive builds in one process (stewbeet watch) behave like fresh runs.

ctx.meta becomes a default Box, which every later plugin reads through.

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

Fill in the project description, the source lore and the manual name when the project leaves them out or sets “auto”.

warn_older_mecha_tree(
ctx: Context,
) → None[source]#

Warn when meta.mecha.version is older than the project’s Minecraft version, whose commands mecha would reject.

register_pack_formats(
ctx: Context,
) → None[source]#

Teach beet the pack formats and data versions it does not know yet, and set both packs’ format from the Minecraft version.

rename_textures(textures_folder: str) → None[source]#

Lowercase the textures at the top of the folder, with the side names of TEXTURE_SUFFIX_RENAMES, never overwriting.

setup_pack_mcmeta(
ctx: Context,
pack: Pack[Any],
pack_format: FormatSpecifier | None,
) → None[source]#

Write a pack’s pack.mcmeta over the one it has: its format, the range mc_supports gives, the description and the id.

The format defaults to the Minecraft version’s, else the latest known one’s.

supported_formats(
ctx: Context,
pack: Pack[Any],
int_pack_format: int,
) → JsonDict[source]#

The formats a pack supports, from the first and last versions of mc_supports, empty when the project gives none.

The first is capped at the project’s Minecraft version, and “infinite” stands for it first and for the latest known one last.

beet_patches#

Monkey patches applied to beet at the very start of every build.

These live here instead of in a beet fork so upstream stays pullable. Each patch keeps the exact behaviour of what it replaces and is applied once per process, never re-wrapping on the second build of a stewbeet watch session.

patches_applied: bool = False[source]#

Whether apply_beet_patches already ran in this process.

fast_list_files(
directory: FileSystemPath,
) → Iterator[Path][source]#

Drop-in replacement for beet.library.utils.list_files, yielding every file below a directory relative to it.

Upstream builds a Path out of every walked file and then re-parses it through relative_to(directory), which is about five times slower than slicing the prefix off the string os.walk already hands over. Files come in sorted order, so a pack loads the same way on every file system.

>>> import tempfile
>>> with tempfile.TemporaryDirectory() as tmp:
...     Path(tmp, "sub").mkdir()
...     _ = Path(tmp, "sub", "a.txt").write_text("a")
...     sorted(path.as_posix() for path in fast_list_files(tmp))
['sub/a.txt']
same_pixels(
left: Image,
right: Image,
) → bool[source]#

Tell whether two images hold exactly the same pixels, mode and palette included.

>>> red = Image.new("RGBA", (2, 2), "red")
>>> same_pixels(red, Image.new("RGBA", (2, 2), "red"))
True
>>> same_pixels(red, Image.new("RGBA", (2, 2), "blue"))
False
>>> same_pixels(red, Image.new("RGB", (2, 2), "red"))
False
reuse_unchanged_pngs(
pack: Pack[Any],
directory: FileSystemPath,
) → None[source]#

Give the in-memory images of a pack the bytes saved in directory by the previous build, when their pixels are unchanged.

>>> import tempfile
>>> from beet import ResourcePack, Texture
>>> with tempfile.TemporaryDirectory() as tmp:
...     saved = Texture(Image.new("RGBA", (4, 4), "red")).ensure_serialized() + b"previous encoding"
...     Path(tmp, "assets/demo/textures").mkdir(parents=True)
...     _ = Path(tmp, "assets/demo/textures/red.png").write_bytes(saved)
...     pack = ResourcePack()
...     pack.textures["demo:red"] = Texture(Image.new("RGBA", (4, 4), "red"))
...     reuse_unchanged_pngs(pack, tmp)
...     pack.textures["demo:red"].ensure_serialized() == saved
True
reuse_unchanged_png_bytes(
pack: Pack[Any],
read_previous: Callable[[str], bytes | None],
) → None[source]#

Give the in-memory images of a pack the bytes the previous build wrote, when their pixels are unchanged.

Parameters:
  • pack – The pack whose images to check.

  • read_previous – The bytes the previous build wrote at a path of the pack, None when it wrote nothing there.

stable_png_save(
save: Callable[[...], Path],
) → Callable[[...], Path][source]#

Wrap Pack.save so a pack saved as a folder over a previous build keeps the bytes of its unchanged images.

stable_png_incremental_save(
save: Callable[[...], None],
) → Callable[[...], None][source]#

Wrap beet’s incremental_save, which writes an output folder without going through Pack.save, like stable_png_save.

console_safe_emit(
emit: Callable[[Any, LogRecord], None],
) → Callable[[Any, LogRecord], None][source]#

Wrap beet’s LogHandler.emit, which draws through prompt_toolkit, to print the plain message where that raises.

prompt_toolkit needs a real Windows console. In Git Bash or a redirected output it raises, and a caller swallowing the error (such as a weld run under Muffle) then fails without a word.

apply_beet_patches() → None[source]#

Install every beet monkey patch, once per process.

project_images#

find_project_png(
filename: str,
root: str | None = None,
) → str | None[source]#

Find a project image in <root>/src/, then <root>/assets/, then any <root>/*<filename>.

Parameters:
  • filename – Name of the image to look for, e.g. "pack.png".

  • root – Base directory to search in, defaults to the beet project directory.

Returns:

Path to the image, or None when it was not found.

Return type:

str | None

find_pack_png(root: str | None = None) → str | None[source]#

Find the project pack.png (the logo), or None when the project has none.

find_tooltip_png(root: str | None = None) → str | None[source]#

Find a project tooltip.png replacing the packaged atlas, or None to use the packaged one.

silent#

source_lore_colors#

source_lore_color resolution.

The color analysis itself lives in stewbeet.core.utils.fonts.colors; this module only reads the configuration and hands it over. The analysis helpers are re-exported because they are part of this module’s documented surface.

resolve_source_lore_color(
logo_path: str | None = None,
) → tuple[int, int, int] | None[source]#

Resolve the source_lore_color configuration into the color the atlas should use.

Accepted values are "auto" (derive it from the logo), any color Pillow understands ("#55FFFF", "gold", [85, 255, 255]), or a falsy value / "none" to keep the packaged atlas colors untouched.

Parameters:

logo_path – Path to the logo used by the "auto" mode.

Returns:

Target color, or None when no recolor should happen.

Return type:

tuple[int, int, int] | None

source_lore_font#

TOOLTIP_FONT: str = 'tooltip'[source]#

Font generated in the project namespace: <project_id>:tooltip.

ICON_CHAR: str = 'ꀁ'[source]#

Glyph showing the project logo (only provided when a pack.png was found)

SPACER_CHAR: str = '뀁'[source]#

2px spacer glyph coming from the font “space” provider.

ATLAS_TEXTURE: str = 'font/tooltip'[source]#

Character atlas, relative to textures/.

ICON_TEXTURE: str = 'tooltip/tooltip'[source]#

Logo glyph, relative to textures/.

is_icon_placeholder(
component: TextComponent,
) → bool[source]#

Whether a text component is the {"text": "ICON"} placeholder standing for the logo glyph.

>>> is_icon_placeholder({"text": "ICON"}), is_icon_placeholder({"text": "nope"}), is_icon_placeholder("ICON")
(True, False, False)
warn_foreign_tooltip_font(
source_lore: TextComponent,
) → None[source]#

Warn when the source lore asks for a tooltip font belonging to another namespace.

StewBeet only ever generates <project_id>:tooltip, and only when something actually asks for it. A source lore naming someone_else:tooltip therefore gets no font at all and silently falls back to the default one in game. The templates ship _your_namespace:tooltip, so this is what a project that renamed its id and not its source lore runs into.

Parameters:

source_lore – Source lore to inspect.

prepare_source_lore_font(
source_lore: list[TextComponent],
) → str[source]#

Replace every ICON placeholder of the source lore with the logo glyph of the tooltip font.

Parameters:

source_lore – Source lore to patch in place.

Returns:

Path to the pack.png backing the glyph, or “” when there is no placeholder or no logo.

Return type:

str

create_source_lore_font(pack_icon: str = '') → None[source]#

Create the <project_id>:tooltip font used by the source lore.

The character atlas comes from a project-supplied tooltip.png when there is one (used as-is), otherwise from the packaged one, recolored according to source_lore_color.

Parameters:

pack_icon – Path to the project pack.png. When empty, the logo glyph provider is skipped so the font never points at a missing texture.

delete_source_lore_font() → None[source]#

Delete the source lore font and its textures if they exist.