@nodecraft/rendermite 1.0.7 → 1.1.1

package/dist/{loader-B8NJO7pR.js → loader-DwkA9LR5.js}

@@ -2,12 +2,18 @@ import { n as ResourceLocator } from "./locator-ycZzh_6z.js";
 import { t as LruCache } from "./cache-Cr2ON3RQ.js";
 //#region src/models/loader.ts
 var ModelResolutionError = class extends Error {};
+/** Override redirects to follow before giving up; cycles are the reason. */
+const MAX_OVERRIDE_REDIRECTS = 4;
 const MAX_PARENT_DEPTH = 64;
 const MAX_TEXTURE_REF_DEPTH = 16;
 /** Forge's generated-item aliases are injected by the loader, not shipped as resources. */
 const MODEL_PARENT_ALIASES = {
 	"forge:item/default": "minecraft:item/generated",
-	"forge:item/default-tool": "minecraft:item/handheld"
+	"forge:item/default-tool": "minecraft:item/handheld",
+	"forge:block/default": "minecraft:block/block",
+	"neoforge:block/default": "minecraft:block/block",
+	"neoforge:item/default": "minecraft:item/generated",
+	"neoforge:item/default-tool": "minecraft:item/handheld"
 };
 /**
 * Per-mod synthesizers for loaders whose geometry lives entirely in Java but
@@ -19,6 +25,15 @@ const MODEL_PARENT_ALIASES = {
 */
 const MOD_LOADER_HANDLERS = {
 	"immersiveengineering:conf_sides": flattenConfSides,
+	"mekanism:energy_cube": flattenEnergyCube,
+	"mekanism:transmitter": restrictTransmitterToUnconnected,
+	"botania:floating_flower": composeFloatingFlower,
+	"tconstruct:tool": layerToolParts,
+	"modern_industrialization:machine": composeMachine,
+	"modern_industrialization:use_block_model": imitateBlockModel,
+	"sophisticatedstorage:barrel": flattenStorageBarrel,
+	"sophisticatedstorage:limited_barrel": flattenStorageBarrel,
+	"sophisticatedstorage:simple_composite": mergeCompositeParts,
 	"immersiveengineering:models/conveyor": flattenConveyor
 };
 /**
@@ -34,25 +49,26 @@ const MOD_LOADER_HANDLERS = {
 function flattenLoaderModel(json, depth = 0) {
 	const loader = extractLoaderType(json);
 	if (!loader || depth > 8) return json;
-	if (/obj$/i.test(loader)) {
-		const extended = json;
-		if (typeof extended.model === "string") {
-			const marked = withoutLoader(json);
-			marked.objModel = {
-				model: extended.model,
-				flipV: extended.flip_v ?? extended.flip_V ?? false
-			};
-			delete marked.model;
-			return marked;
-		}
-		return json;
+	const objCandidate = json;
+	const objReference = typeof objCandidate.model === "string" && (/obj$/i.test(loader) || /\.obj(?:$|\.)/i.test(objCandidate.model)) ? objCandidate.model : null;
+	if (objReference !== null) {
+		const marked = withoutLoader(json);
+		marked.objModel = {
+			model: objReference,
+			flipV: objCandidate.flip_v ?? objCandidate.flip_V ?? false
+		};
+		delete marked.model;
+		const objHandler = MOD_LOADER_HANDLERS[loader];
+		return objHandler ? objHandler(marked) : marked;
 	}
+	if (/obj$/i.test(loader)) return json;
 	const handler = MOD_LOADER_HANDLERS[loader];
 	if (handler) return handler(json);
 	const extended = json;
 	if (extended.perspectives?.gui && typeof extended.perspectives.gui === "object") return flattenLoaderModel(extended.perspectives.gui, depth + 1);
 	if (extended.base && typeof extended.base === "object") return flattenLoaderModel(extended.base, depth + 1);
 	if (typeof extended.childModel === "string") return { parent: extended.childModel };
+	if (typeof extended.delegate === "string") return { parent: extended.delegate };
 	if (extended.children && typeof extended.children === "object") {
 		const children = Object.values(extended.children);
 		const inline = children.filter((child) => typeof child === "object" && child !== null);
@@ -67,13 +83,27 @@ function flattenLoaderModel(json, depth = 0) {
 		if (first && typeof first === "object") return flattenLoaderModel(first, depth + 1);
 	}
 	if (extended.inner_model && typeof extended.inner_model === "object") return flattenLoaderModel(extended.inner_model, depth + 1);
+	for (const value of Object.values(json)) {
+		const nested = value;
+		if (typeof nested !== "object" || nested === null || Array.isArray(nested)) continue;
+		if (nested.parent !== void 0 || Array.isArray(nested.elements)) return flattenLoaderModel(nested, depth + 1);
+	}
 	if (/fluid_container|bucket/i.test(loader)) {
 		const fluid = json.fluid;
 		const bucket = { parent: "minecraft:item/bucket" };
 		if (typeof fluid === "string" && fluid.length > 0 && !fluid.endsWith(":empty")) bucket.fluidContained = fluid;
 		return bucket;
 	}
-	return withoutLoader(json);
+	const stripped = withoutLoader(json);
+	const sprite = stripped.textures?.texture;
+	if (typeof sprite === "string" && stripped.textures?.layer0 === void 0) return {
+		...stripped,
+		textures: {
+			...stripped.textures,
+			layer0: sprite
+		}
+	};
+	return stripped;
 }
 /** IE conveyor types whose belt texture is not simply `block/conveyor/<type>`. */
 const CONVEYOR_BELTS = {
@@ -197,6 +227,186 @@ function flattenConfSides(json) {
 		}
 	};
 }
+/**
+* Mekanism's energy_cube loader keeps the body under `frame` and each side's
+* connector and indicator under `<side>Port`/`<side>LEDs`, picking which sides
+* show at runtime from the stack's stored side config. Every group is emitted:
+* a cube with all its ports is what a configured cube looks like, and dropping
+* them would leave the six faces blank.
+*/
+function flattenEnergyCube(json) {
+	const elements = Object.entries(json).filter(([name, value]) => (name === "frame" || /(?:Port|LEDs)$/.test(name)) && Array.isArray(value)).flatMap(([, value]) => value);
+	if (elements.length === 0) return withoutLoader(json);
+	return {
+		...withoutLoader(json),
+		elements
+	};
+}
+/**
+* Mekanism's transmitter loader wraps one OBJ holding every connection state of
+* a cable — each direction appears as `<direction>NONE`, `NORMAL`, `PUSH` and
+* `PULL` objects, and the loader picks one per side from the neighbouring
+* blocks. An item has no neighbours, so every side is NONE; drawing the lot
+* gives a spiked ball of overlapping states.
+*/
+function restrictTransmitterToUnconnected(json) {
+	const marked = json;
+	if (marked.objModel) marked.objModel.objects = [
+		"down",
+		"up",
+		"north",
+		"south",
+		"east",
+		"west"
+	].map((side) => `${side}NONE`);
+	return marked;
+}
+/**
+* Botania's floating flowers are a mystical island with a flower planted on it:
+* the loader draws `botania:block/islands/island_<type>` under the model named
+* by the `flower` key. The island type is stored per block and defaults to
+* GRASS, which is what a freshly crafted one — and so the item — shows.
+*/
+function composeFloatingFlower(json) {
+	const flower = json.flower;
+	const merges = ["botania:block/islands/island_grass"];
+	if (typeof flower?.parent === "string") merges.push(flower.parent);
+	const composed = {
+		...withoutLoader(json),
+		mergeModels: merges
+	};
+	delete composed.flower;
+	return composed;
+}
+/**
+* Tinkers' tool loader stacks one sprite per tool part — head, handle, binding
+* and so on — tinting each by the material it was built from. The parts are
+* declared in draw order, so laying them out as layer0..layerN reproduces the
+* uncoloured tool. `large_*` duplicates are the broad-tool variants the item
+* icon never uses, and `modifier_roots` are overlays for applied modifiers.
+*/
+function layerToolParts(json) {
+	const stripped = withoutLoader(json);
+	const parts = Object.entries(stripped.textures ?? {}).filter(([name]) => !name.startsWith("large_") && name !== "particle" && !/^layer\d+$/.test(name));
+	if (parts.length === 0) return stripped;
+	const layers = Object.fromEntries(parts.map(([, value], index) => [`layer${index}`, value]));
+	return {
+		...stripped,
+		parent: "minecraft:item/generated",
+		textures: {
+			...stripped.textures,
+			...layers
+		}
+	};
+}
+/**
+* A casing that borrows another block's look states only the block id. Its
+* model is that block's, under the conventional block/<path> name — which is
+* where every casing MI does this for actually keeps it.
+*/
+function imitateBlockModel(json) {
+	const block = json.block;
+	if (typeof block !== "string") return withoutLoader(json);
+	const locator = ResourceLocator.tryParse(block);
+	return locator === null ? withoutLoader(json) : { parent: `${locator.namespace}:block/${locator.path}` };
+}
+/**
+* Which face each of MI's machine overlays belongs on. The rest of the
+* vocabulary — `*_active`, `output`, `item_auto`, `fluid_auto` — is runtime
+* state (running, or a configured auto-IO side) that a freshly crafted machine
+* does not show, so the icon leaves them off.
+*/
+const MACHINE_OVERLAY_FACES = {
+	front: ["north"],
+	top: ["up"],
+	bottom: ["down"],
+	side: [
+		"east",
+		"west",
+		"south"
+	]
+};
+/**
+* MI machines are a casing block wearing per-face overlays. The casing is named
+* rather than inlined (`"casing": "lv"` ↔ machine_casing/lv), and the overlays
+* are full texture ids, so the model becomes the casing merged in underneath a
+* hair-inflated cube carrying the overlay faces.
+*/
+function composeMachine(json) {
+	const extended = json;
+	const casing = typeof extended.casing === "string" ? extended.casing : null;
+	const overlays = extended.default_overlays ?? {};
+	const textures = {};
+	const faces = {};
+	for (const [name, directions] of Object.entries(MACHINE_OVERLAY_FACES)) {
+		const texture = overlays[name];
+		if (typeof texture !== "string") continue;
+		textures[name] = texture;
+		for (const direction of directions) faces[direction] = { texture: `#${name}` };
+	}
+	return {
+		parent: "minecraft:block/block",
+		textures,
+		elements: Object.keys(faces).length > 0 ? [{
+			from: [
+				-.01,
+				-.01,
+				-.01
+			],
+			to: [
+				16.01,
+				16.01,
+				16.01
+			],
+			faces
+		}] : [],
+		...casing !== null && { mergeModels: [`modern_industrialization:machine_casing/${casing}`] }
+	};
+}
+/**
+* Sophisticated Storage composes its barrels from part models with two levels of
+* texture indirection, but the tier part states the three textures a barrel
+* actually wears under vanilla's own `top`/`side`/`bottom` names. Those names
+* belong to `cube_bottom_top`, which is the shape a barrel is — the parts the
+* loader adds on top are trim and the tintable core.
+*/
+function flattenStorageBarrel(json) {
+	const extended = json;
+	const groups = [extended.partitioned_model_parts, extended.model_parts];
+	const textures = {};
+	const merges = [];
+	for (const group of groups) for (const part of Object.values(group ?? {})) {
+		Object.assign(textures, part.textures);
+		if (typeof part.model === "string") merges.push(part.model);
+	}
+	const flattened = withoutLoader(json);
+	delete flattened.model_parts;
+	delete flattened.partitioned_model_parts;
+	delete flattened.dynamic_part_models;
+	delete flattened.wood_overrides;
+	return {
+		...flattened,
+		parent: flattened.parent ?? "minecraft:block/block",
+		textures: {
+			...flattened.textures,
+			...textures
+		},
+		...merges.length > 0 && { mergeModels: merges }
+	};
+}
+/**
+* A composite whose parts are named parent references rather than inline
+* geometry — every part is drawn, so they all merge in.
+*/
+function mergeCompositeParts(json) {
+	const parts = json.parts ?? {};
+	const merges = Object.values(parts).map((part) => part.parent).filter((parent) => typeof parent === "string");
+	return merges.length === 0 ? withoutLoader(json) : {
+		...withoutLoader(json),
+		parts: void 0,
+		mergeModels: merges
+	};
+}
 function extractLoaderType(json) {
 	const record = json;
 	if (typeof record.loader === "string") return record.loader;
@@ -286,7 +496,7 @@ var ModelLoader = class {
 		}
 		return flattenLoaderModel(json);
 	}
-	async resolve(locator) {
+	async resolve(locator, overrideDepth = 0) {
 		const chain = [];
 		const seen = /* @__PURE__ */ new Set();
 		let current = locator;
@@ -338,6 +548,22 @@ var ModelLoader = class {
 				break;
 			}
 		}
+		for (const entry of chain) {
+			const merges = entry.json.mergeModels;
+			if (!merges) continue;
+			for (const reference of merges) {
+				const merged = await this.load(reference).catch(() => null);
+				if (!merged) continue;
+				elements = [...elements, ...merged.elements.map((element) => bindElementTextures(element, merged, textures))];
+			}
+			break;
+		}
+		if (obj === void 0 && elements.length === 0 && Object.keys(textures).length === 0) {
+			const overridden = chain.find((entry) => entry.json.overrides?.length)?.json.overrides;
+			const chosen = overridden && (overridden.findLast((entry) => Object.values(entry.predicate).every((value) => value <= 0)) ?? overridden[0]);
+			const target = chosen ? ResourceLocator.tryParse(chosen.model) : null;
+			if (target && overrideDepth < MAX_OVERRIDE_REDIRECTS && target.toString() !== locator.toString()) return this.resolve(target, overrideDepth + 1);
+		}
 		const defaultLight = builtinParent === "builtin/generated" ? "front" : "side";
 		return {
 			obj,
@@ -365,6 +591,32 @@ var ModelLoader = class {
 	}
 };
 /**
+* Rewrite an element's face textures from the owning model's variables to
+* concrete locators, so the element survives being merged into another model.
+*/
+function bindElementTextures(element, model, owner) {
+	const rebound = {
+		...model,
+		textures: {
+			...model.textures,
+			...owner
+		}
+	};
+	const faces = {};
+	for (const [direction, face] of Object.entries(element.faces)) {
+		if (!face) continue;
+		const bound = resolveTexture(rebound, face.texture) ?? resolveTexture(model, face.texture);
+		faces[direction] = bound ? {
+			...face,
+			texture: bound.toString()
+		} : face;
+	}
+	return {
+		...element,
+		faces
+	};
+}
+/**
 * Resolve a texture variable (`#layer0`) through the merged texture map to a locator.
 * Returns null for unresolved variables — the caller decides whether that fails the
 * item or just the face.

package/dist/{loader-CfXMxcEV.js → loader-Lb0ZeILz.js}

@@ -1,3 +1,4 @@
+import { n as ResourceLocator } from "./locator-ycZzh_6z.js";
 import { t as LruCache } from "./cache-Cr2ON3RQ.js";
 import sharp from "sharp";
 //#region src/textures/loader.ts
@@ -21,15 +22,20 @@ var AnimatedTexture = class {
 	constructor(full, meta) {
 		this.full = full;
 		this.meta = meta;
-		const metaWidth = meta?.animation?.width ?? 16;
-		const metaHeight = meta?.animation?.height ?? 16;
+		if (!meta?.animation) {
+			const stacked = full.height > full.width && full.height % full.width === 0;
+			this.columns = 1;
+			this.frameWidth = full.width;
+			this.frameHeight = stacked ? full.width : full.height;
+			this.frameCount = 1;
+			return;
+		}
+		const metaWidth = meta.animation.width ?? 16;
+		const metaHeight = meta.animation.height ?? 16;
 		this.columns = Math.max(1, Math.trunc(16 / metaWidth));
 		this.frameWidth = Math.round(full.width * (metaWidth / 16));
 		this.frameHeight = Math.round(this.frameWidth * (metaHeight / 16));
-		const frames = meta?.animation?.frames;
-		if (!meta?.animation) this.frameCount = 1;
-		else if (frames?.length) this.frameCount = frames.length;
-		else this.frameCount = Math.max(1, Math.round(full.height / this.frameHeight * this.columns));
+		this.frameCount = meta.animation.frames?.length || Math.max(1, Math.round(full.height / this.frameHeight * this.columns));
 	}
 	get interpolated() {
 		return this.meta?.animation?.interpolate ?? false;
@@ -146,6 +152,7 @@ var TextureLoader = class {
 			if (sprite?.kind === "pixels") return sprite.texture;
 			if (sprite?.kind === "file") raw = await this.resources.getResource("texture", sprite.locator);
 		}
+		if (raw === null) raw = await this.resources.getResource("raw", new ResourceLocator(locator.namespace, `${locator.path}.png`));
 		if (raw === null) return null;
 		let image;
 		try {
@@ -190,7 +197,12 @@ var TextureLoader = class {
 		const raw = await this.resources.getResource("texture", locator);
 		let full = null;
 		if (raw !== null) {
-			const image = await sharp(raw).ensureAlpha().raw().toBuffer({ resolveWithObject: true });
+			let image;
+			try {
+				image = await sharp(raw).ensureAlpha().raw().toBuffer({ resolveWithObject: true });
+			} catch (err) {
+				throw new TextureResolutionError(`Failed to decode texture ${locator}: ${err.message}`);
+			}
 			full = {
 				width: image.info.width,
 				height: image.info.height,

package/dist/models/loader.d.ts

@@ -1,2 +1,2 @@
-import { a as resolveTexture, i as flattenLoaderModel, n as ModelResolutionError, o as salvageJson, r as ResolvedModel, t as ModelLoader } from "../loader-D22zZME7.js";
+import { a as resolveTexture, i as flattenLoaderModel, n as ModelResolutionError, o as salvageJson, r as ResolvedModel, t as ModelLoader } from "../loader-DD83d80u.js";
 export { ModelLoader, ModelResolutionError, ResolvedModel, flattenLoaderModel, resolveTexture, salvageJson };

package/dist/models/loader.js

@@ -1,2 +1,2 @@
-import { a as salvageJson, i as resolveTexture, n as ModelResolutionError, r as flattenLoaderModel, t as ModelLoader } from "../loader-B8NJO7pR.js";
+import { a as salvageJson, i as resolveTexture, n as ModelResolutionError, r as flattenLoaderModel, t as ModelLoader } from "../loader-DwkA9LR5.js";
 export { ModelLoader, ModelResolutionError, flattenLoaderModel, resolveTexture, salvageJson };

package/dist/models/types.d.ts

@@ -1,2 +1,2 @@
-import { a as FaceDirectionName, c as ModelJson, i as FaceDirection, l as Vec3, n as DisplayTransformJson, o as ModelElementJson, r as ElementRotationJson, s as ModelFaceJson, t as DisplayPosition, u as Vec4 } from "../types-COGbtA1t.js";
+import { a as FaceDirectionName, c as ModelJson, i as FaceDirection, l as Vec3, n as DisplayTransformJson, o as ModelElementJson, r as ElementRotationJson, s as ModelFaceJson, t as DisplayPosition, u as Vec4 } from "../types-DpRSF9Vj.js";
 export { DisplayPosition, DisplayTransformJson, ElementRotationJson, FaceDirection, FaceDirectionName, ModelElementJson, ModelFaceJson, ModelJson, Vec3, Vec4 };

package/dist/models-BKxGkPS7.js

@@ -0,0 +1,18 @@
+import { r as modModelPackPath } from "./builtin-WkWjATeh.js";
+import { t as FolderResourceManager } from "./manager-CkletR5K.js";
+//#region src/mods/models.ts
+/**
+* Geometry for mod items the game draws in code. A `builtin/entity` item model
+* carries display transforms and nothing else — the boxes live in a Java class,
+* so no fallback in the chain can find them and the item fails outright.
+*
+* `assets/mod-models/` ports that geometry to ordinary element models, keyed by
+* the model path the mod's own item already resolves to. Hand-authored per item
+* and layered ABOVE the mod jars, so it shadows the `builtin/entity` stub in
+* every era (see assets/mod-models/README.md for per-item provenance).
+*/
+function curatedModelOverrides() {
+	return new FolderResourceManager(modModelPackPath());
+}
+//#endregion
+export { curatedModelOverrides as t };

package/dist/mods/models.d.ts

@@ -0,0 +1,5 @@
+import { a as ResourceManager } from "../manager-Cv1NeFyF.js";
+//#region src/mods/models.d.ts
+declare function curatedModelOverrides(): ResourceManager;
+//#endregion
+export { curatedModelOverrides };

package/dist/mods/models.js

@@ -0,0 +1,2 @@
+import { t as curatedModelOverrides } from "../models-BKxGkPS7.js";
+export { curatedModelOverrides };

package/dist/mods/prepare.d.ts

@@ -1,2 +1,2 @@
-import { i as prepareModResources, n as ModPreparation, r as PrepareModsOptions, t as LOADER_NAMESPACES } from "../prepare-CPxO0kKz.js";
+import { i as prepareModResources, n as ModPreparation, r as PrepareModsOptions, t as LOADER_NAMESPACES } from "../prepare-Dce7-HAe.js";
 export { LOADER_NAMESPACES, ModPreparation, PrepareModsOptions, prepareModResources };

package/dist/mods/prepare.js

@@ -1,2 +1,2 @@
-import { n as prepareModResources, t as LOADER_NAMESPACES } from "../prepare-BESRrh6K.js";
+import { n as prepareModResources, t as LOADER_NAMESPACES } from "../prepare-D56Z-9cg.js";
 export { LOADER_NAMESPACES, prepareModResources };

package/dist/mods/tints.js

@@ -1,2 +1,2 @@
-import { n as harvestTintOverrides, t as curatedTintOverrides } from "../tints-B8UJmZMu.js";
+import { n as harvestTintOverrides, t as curatedTintOverrides } from "../tints-CebmvjmP.js";
 export { curatedTintOverrides, harvestTintOverrides };

package/dist/output/encode.d.ts

@@ -1,2 +1,2 @@
-import { a as RasterAssetFormat, c as encodeRasterAsset, i as EncodedIcon, n as EncodeOptions, o as encodeAnimatedIcon, r as EncodedAnimatedIcon, s as encodeIcon, t as AnimatedEncodeOptions } from "../encode-CaSK8-mi.js";
+import { a as RasterAssetFormat, c as encodeRasterAsset, i as EncodedIcon, n as EncodeOptions, o as encodeAnimatedIcon, r as EncodedAnimatedIcon, s as encodeIcon, t as AnimatedEncodeOptions } from "../encode-DNcXXvYe.js";
 export { AnimatedEncodeOptions, EncodeOptions, EncodedAnimatedIcon, EncodedIcon, RasterAssetFormat, encodeAnimatedIcon, encodeIcon, encodeRasterAsset };

package/dist/output/encode.js

@@ -1,2 +1,2 @@
-import { n as encodeIcon, r as encodeRasterAsset, t as encodeAnimatedIcon } from "../encode-Df_tWzkl.js";
+import { n as encodeIcon, r as encodeRasterAsset, t as encodeAnimatedIcon } from "../encode-LR9wxigC.js";
 export { encodeAnimatedIcon, encodeIcon, encodeRasterAsset };

package/dist/{pipeline-HiA3DC71.d.ts → pipeline-Bp6amYz_.d.ts}

@@ -1,7 +1,7 @@
 import { a as ResourceManager } from "./manager-Cv1NeFyF.js";
-import { t as FloatTexture } from "./blend-CEHoJ7tM.js";
+import { n as FloatTexture } from "./blend-8lnfxtLe.js";
 import { a as LightingProfileName } from "./lighting-3FGRC3Af.js";
-import { n as AnimationLimits } from "./renderer-B20ssjRm.js";
+import { n as AnimationLimits } from "./renderer-C79EQDSn.js";
 //#region src/render/pipeline.d.ts
 interface PipelineSettings {
   builtin?: string;
@@ -40,13 +40,25 @@ declare class ItemPipeline {
    * pipeline's black-icon audit checked exactly this). A real sprite beats
    * no icon; the fallback is recorded so it is never a silent substitution.
    */
+  /** Whether the game draws this item from an entity model rather than a sprite. */
+  private isEntityDrawn;
   private spriteFallback;
+  /**
+   * A blockstate-named block model, drawn the way a block-entity item renderer
+   * draws it. The renderer runs inside the *item's* display transform, which the
+   * block model does not carry — a block model that never chains to
+   * `minecraft:block/block` has no gui transform at all and would otherwise fill
+   * the frame flat-on (mekanism:block/fluid_tank).
+   */
+  private renderStatedBlock;
   /** Render an item's frames from its own model, without any fallback. */
   renderFrames(id: string): Promise<RenderedFrames>;
   /**
-   * Frames for an item, falling back through the same-name block model,
-   * GeckoLib geometry, builtin entity geometry, dyed variants, and finally the
-   * flat sprite. Rethrows the item's own error when nothing draws it.
+   * Frames for an item that its own model cannot draw. The first step is not a
+   * guess: a BlockItem's blockstate names the model the game's own block-entity
+   * item renderers draw, so that is consulted before the same-name heuristic.
+   * After it come GeckoLib geometry, builtin entity geometry, dyed variants and
+   * finally the flat sprite. Rethrows the item's own error when nothing draws it.
    */
   renderFramesWithFallback(id: string): Promise<RenderedFrames & {
     usedFallback: boolean;