@nodecraft/rendermite 0.0.1 → 1.0.1

package/LICENSE

@@ -0,0 +1,25 @@
+MIT License
+
+Copyright (c) 2026 Nodecraft, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+The vendored resource packs under assets/ originate from
+https://github.com/aternosorg/renderchest and are Copyright (c) Aternos GmbH,
+also under the MIT License.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,92 @@
+# rendermite
+
+Minecraft item icon renderer for Node.js. Point it at a game version or a pile of mod jars and it produces inventory-identical 3D item icons as optimized PNG and lossless WebP (plus optional GIF and AVIF), a ready-to-use CSS spritesheet, and a JSON item library.
+
+> [!NOTE]
+> **Heads-up:** this project was primarily AI-authored. The renderer, tests, tooling, and this README were written by Claude (Anthropic) in interactive sessions, with a human operator directing the work, reviewing output, and validating renders against real game assets. Read the code before trusting it in production.
+
+## What it does
+
+- **Renders items the way the inventory does**: orthographic block projection, per-face gui lighting, display transforms, tints, enchant glint layers, and animated textures (as animated WebP/GIF).
+- **One codebase, every version**: 1.2.5 through the latest snapshots. Old versions are handled with era detection, donor geometry, and legacy spritesheet slicing; new ones with item definitions, atlases (including `paletted_permutations` armor trims), and dynamic items (trims, decorated pots, charged crossbows).
+- **Serious mod support**: Forge/NeoForge/Fabric loader models (composite, separate transforms, fluid containers, split multiblocks), OBJ+MTL geometry, GeckoLib Bedrock `.geo.json`, cross-jar dependencies, Gson-tolerant junk JSON, case-insensitive 1.7.10-era assets, and synthesized models for texture-only jars.
+- **Honest fallbacks, never black squares**: items the game draws in code fall through a chain of same-name block models, Bedrock geometry, builtin chest/head/banner/shulker geometry with the mod's own textures, dyed-variant tinting, and flat sprites. Every fallback is reported, and anything unrenderable fails loudly into a per-item failure sidecar instead of shipping a blank icon.
+- **Optimized output**: PNGs use palette encoding only when provably lossless, WebP is lossless, and the generated CSS is minified with [lightningcss](https://lightningcss.dev). Output is smaller than the PHP renderer's on identical inputs.
+
+## Install
+
+```sh
+npm install @nodecraft/rendermite
+```
+
+Requires Node.js 24+.
+
+## Usage
+
+Render a vanilla version (the client jar is downloaded and cached automatically):
+
+```sh
+rendermite --version 1.21.8 --output ./icons
+```
+
+Render a mod's items on top of a vanilla version:
+
+```sh
+rendermite --version 1.20.4 \
+  --mod ./create-1.20.1.jar \
+  --namespace create \
+  --output ./icons/create --item-list
+```
+
+Or use an extracted asset tree directly:
+
+```sh
+rendermite --assets ./my-resource-pack --output ./icons
+```
+
+Useful flags: `--size <px>` (default 64), `--format webp|avif`, `--gif` for legacy-browser animation, `--lighting-profile modern|legacy`, `--concurrency <n>`. Run `rendermite` with no arguments for the full list.
+
+### Output layout
+
+```
+icons/
+  items/<namespace>/<item>.png     # always written
+  items/<namespace>/<item>.webp    # lossless, animated where the item animates
+  rc-enchantment.<format>          # each lossless glint format referenced by the CSS
+  rc-<namespace>-64.css            # spritesheet CSS (class per item, enchant glint, tint layers)
+  rc-<namespace>.json              # rendered item id list
+  rc-<namespace>-failures.json     # per-item failures with reasons, never silent
+```
+
+### As a library
+
+Everything the CLI does is exported, from the high-level `run()` down to individual pieces (`ModelLoader`, `TextureLoader`, `renderModel`, `prepareVersionResources`, `prepareModResources`, `generateStylesheet`).
+
+```ts
+import { run, prepareModResources, builtinPackPath } from '@nodecraft/rendermite';
+```
+
+## Performance
+
+Benchmarked against PHP renderchest v5.1.0 on the same machine, rendering the same extracted 1.21.8 assets at 64px (PNG + WebP):
+
+| | wall time | items written | silent drops | throughput |
+| --- | --- | --- | --- | --- |
+| renderchest (docker, 8 workers) | 210s | 1,573 | 33 | ~449/min |
+| rendermite (one Node process, pool 8) | 22.9s | 2,065 | 0 | ~5,410/min |
+
+## Testing
+
+```sh
+npm test
+```
+
+The suite is fully self-contained: vanilla jars download from Mojang at test time (cached under `.work/fixtures/`), synthetic mod jars are built from committed declarations, and real mods download from Modrinth. Set `RENDERMITE_SKIP_ONLINE=1` to skip the Modrinth suite offline, and point `RENDERMITE_MODJARS` at a local directory of jars to run the optional real-mod suite (third-party jars are license-restricted and never committed).
+
+## Attribution
+
+rendermite is a from-scratch Node.js renderer, but it owes its existence to [aternos/renderchest](https://github.com/aternosorg/renderchest) (MIT, © Aternos GmbH): the projection, rasterization, and lighting behavior were reverse-engineered from it for visual parity, and the hand-modeled builtin resource packs under [`assets/`](assets/README.md) (chests, banners, shulker boxes, mob heads, and friends) are vendored from it under the same MIT license.
+
+## License
+
+[MIT](LICENSE) © Nodecraft, Inc. Vendored `assets/` packs © Aternos GmbH, MIT.

package/assets/README.md

@@ -0,0 +1,17 @@
+# Vendored builtin resource packs
+
+These packs originate from [aternos/renderchest](https://github.com/aternosorg/renderchest)
+(MIT license, © Aternos GmbH) and provide the hand-modeled replacements for items the game
+draws in code rather than through JSON models (chests, banners, shulker boxes, mob heads,
+conduit, shield, decorated pots, and the internal `rc_*` layer sources used by the CSS
+generators).
+
+- `builtin/` — from renderchest master (v5.2.0-beta line), used for 1.21.4+ asset trees.
+- `builtin-legacy/` — from renderchest v2.5.2, used below 1.21.4: it still carries beds and
+  parents era-appropriate template models that modern jars renamed or removed.
+- `builtin-bed-compat/` — just the bed geometry from v2.5.2, layered over 1.21.4–26.1 jars
+  whose bed item models chain to `builtin/entity` (vanilla only shipped real bed block models
+  in 26.2). Without it that whole era renders beds as fully transparent icons.
+
+Layout is `<namespace>/<models|textures|items|atlases>/…` (no `assets/` nesting) — mount with
+`FolderResourceManager` above the version's own assets.

package/assets/builtin/minecraft/atlases/misc.json

@@ -0,0 +1,24 @@
+{
+  "sources": [
+    {
+      "type": "directory",
+      "source": "misc",
+      "prefix": "misc/"
+    },
+    {
+      "type": "directory",
+      "source": "entity",
+      "prefix": "entity/"
+    },
+    {
+      "type": "directory",
+      "source": "colormap",
+      "prefix": "colormap/"
+    },
+    {
+      "type": "single",
+      "resource": "minecraft:item/unknown",
+      "sprite": "missingno"
+    }
+  ]
+}

package/assets/builtin/minecraft/items/black_banner.json

@@ -0,0 +1,12 @@
+{
+    "model": {
+        "type": "minecraft:model",
+        "model": "renderchest:item/banner",
+        "tints": [
+            {
+                "type": "minecraft:constant",
+                "value": 4280098081
+            }
+        ]
+    }
+}

package/assets/builtin/minecraft/items/black_shulker_box.json

@@ -0,0 +1,6 @@
+{
+    "model": {
+        "type": "minecraft:model",
+        "model": "renderchest:item/shulker_box/black_shulker_box"
+    }
+}

package/assets/builtin/minecraft/items/blue_banner.json

@@ -0,0 +1,12 @@
+{
+    "model": {
+        "type": "minecraft:model",
+        "model": "renderchest:item/banner",
+        "tints": [
+            {
+                "type": "minecraft:constant",
+                "value": 4282074024
+            }
+        ]
+    }
+}

package/assets/builtin/minecraft/items/blue_shulker_box.json

@@ -0,0 +1,6 @@
+{
+    "model": {
+        "type": "minecraft:model",
+        "model": "renderchest:item/shulker_box/blue_shulker_box"
+    }
+}

package/assets/builtin/minecraft/items/brown_banner.json

@@ -0,0 +1,12 @@
+{
+    "model": {
+        "type": "minecraft:model",
+        "model": "renderchest:item/banner",
+        "tints": [
+            {
+                "type": "minecraft:constant",
+                "value": 4286665521
+            }
+        ]
+    }
+}

package/assets/builtin/minecraft/items/brown_shulker_box.json

@@ -0,0 +1,6 @@
+{
+    "model": {
+        "type": "minecraft:model",
+        "model": "renderchest:item/shulker_box/brown_shulker_box"
+    }
+}

package/assets/builtin/minecraft/items/chest.json

@@ -0,0 +1,6 @@
+{
+    "model": {
+        "type": "minecraft:model",
+        "model": "renderchest:item/chest/chest"
+    }
+}

package/assets/builtin/minecraft/items/conduit.json

@@ -0,0 +1,6 @@
+{
+    "model": {
+        "type": "minecraft:model",
+        "model": "renderchest:item/conduit"
+    }
+}

package/assets/builtin/minecraft/items/copper_chest.json

@@ -0,0 +1,6 @@
+{
+    "model": {
+        "type": "minecraft:model",
+        "model": "renderchest:item/chest/copper_chest"
+    }
+}

package/assets/builtin/minecraft/items/copper_golem_statue.json

@@ -0,0 +1,6 @@
+{
+  "model": {
+    "type": "minecraft:model",
+    "model": "renderchest:item/copper_golem_statue/copper_golem_statue"
+  }
+}

package/assets/builtin/minecraft/items/creeper_head.json

@@ -0,0 +1,6 @@
+{
+  "model": {
+    "type": "minecraft:model",
+    "model": "mobheads:item/creeper"
+  }
+}

package/assets/builtin/minecraft/items/cyan_banner.json

@@ -0,0 +1,12 @@
+{
+    "model": {
+        "type": "minecraft:model",
+        "model": "renderchest:item/banner",
+        "tints": [
+            {
+                "type": "minecraft:constant",
+                "value": 4279671450
+            }
+        ]
+    }
+}

package/assets/builtin/minecraft/items/cyan_shulker_box.json

@@ -0,0 +1,6 @@
+{
+    "model": {
+        "type": "minecraft:model",
+        "model": "renderchest:item/shulker_box/cyan_shulker_box"
+    }
+}

package/assets/builtin/minecraft/items/decorated_pot.json

@@ -0,0 +1,6 @@
+{
+    "model": {
+        "type": "minecraft:model",
+        "model": "_decorated_pot:pot_b_brick"
+    }
+}

package/assets/builtin/minecraft/items/dragon_head.json

@@ -0,0 +1,6 @@
+{
+  "model": {
+    "type": "minecraft:model",
+    "model": "mobheads:item/ender_dragon"
+  }
+}

package/assets/builtin/minecraft/items/ender_chest.json

@@ -0,0 +1,6 @@
+{
+    "model": {
+        "type": "minecraft:model",
+        "model": "renderchest:item/chest/ender_chest"
+    }
+}

package/assets/builtin/minecraft/items/exposed_copper_chest.json

@@ -0,0 +1,6 @@
+{
+    "model": {
+        "type": "minecraft:model",
+        "model": "renderchest:item/chest/exposed_copper_chest"
+    }
+}

package/assets/builtin/minecraft/items/exposed_copper_golem_statue.json

@@ -0,0 +1,6 @@
+{
+  "model": {
+    "type": "minecraft:model",
+    "model": "renderchest:item/copper_golem_statue/exposed_copper_golem_statue"
+  }
+}

package/assets/builtin/minecraft/items/gray_banner.json

@@ -0,0 +1,12 @@
+{
+    "model": {
+        "type": "minecraft:model",
+        "model": "renderchest:item/banner",
+        "tints": [
+            {
+                "type": "minecraft:constant",
+                "value": 4282797649
+            }
+        ]
+    }
+}

package/assets/builtin/minecraft/items/gray_shulker_box.json

@@ -0,0 +1,6 @@
+{
+    "model": {
+        "type": "minecraft:model",
+        "model": "renderchest:item/shulker_box/gray_shulker_box"
+    }
+}

package/assets/builtin/minecraft/items/green_banner.json

@@ -0,0 +1,12 @@
+{
+    "model": {
+        "type": "minecraft:model",
+        "model": "renderchest:item/banner",
+        "tints": [
+            {
+                "type": "minecraft:constant",
+                "value": 4284316438
+            }
+        ]
+    }
+}

package/assets/builtin/minecraft/items/green_shulker_box.json

@@ -0,0 +1,6 @@
+{
+    "model": {
+        "type": "minecraft:model",
+        "model": "renderchest:item/shulker_box/green_shulker_box"
+    }
+}

package/assets/builtin/minecraft/items/light_blue_banner.json

@@ -0,0 +1,12 @@
+{
+    "model": {
+        "type": "minecraft:model",
+        "model": "renderchest:item/banner",
+        "tints": [
+            {
+                "type": "minecraft:constant",
+                "value": 4281971159
+            }
+        ]
+    }
+}

package/assets/builtin/minecraft/items/light_blue_shulker_box.json

@@ -0,0 +1,6 @@
+{
+    "model": {
+        "type": "minecraft:model",
+        "model": "renderchest:item/shulker_box/light_blue_shulker_box"
+    }
+}

package/assets/builtin/minecraft/items/light_gray_banner.json

@@ -0,0 +1,12 @@
+{
+    "model": {
+        "type": "minecraft:model",
+        "model": "renderchest:item/banner",
+        "tints": [
+            {
+                "type": "minecraft:constant",
+                "value": 4288387989
+            }
+        ]
+    }
+}

package/assets/builtin/minecraft/items/light_gray_shulker_box.json

@@ -0,0 +1,6 @@
+{
+    "model": {
+        "type": "minecraft:model",
+        "model": "renderchest:item/shulker_box/light_gray_shulker_box"
+    }
+}

package/assets/builtin/minecraft/items/lime_banner.json

@@ -0,0 +1,12 @@
+{
+    "model": {
+        "type": "minecraft:model",
+        "model": "renderchest:item/banner",
+        "tints": [
+            {
+                "type": "minecraft:constant",
+                "value": 4286498079
+            }
+        ]
+    }
+}

package/assets/builtin/minecraft/items/lime_shulker_box.json

@@ -0,0 +1,6 @@
+{
+    "model": {
+        "type": "minecraft:model",
+        "model": "renderchest:item/shulker_box/lime_shulker_box"
+    }
+}

package/assets/builtin/minecraft/items/magenta_banner.json

@@ -0,0 +1,12 @@
+{
+    "model": {
+        "type": "minecraft:model",
+        "model": "renderchest:item/banner",
+        "tints": [
+            {
+                "type": "minecraft:constant",
+                "value": 4291120571
+            }
+        ]
+    }
+}

package/assets/builtin/minecraft/items/magenta_shulker_box.json

@@ -0,0 +1,6 @@
+{
+    "model": {
+        "type": "minecraft:model",
+        "model": "renderchest:item/shulker_box/magenta_shulker_box"
+    }
+}

package/assets/builtin/minecraft/items/orange_banner.json

@@ -0,0 +1,12 @@
+{
+    "model": {
+        "type": "minecraft:model",
+        "model": "renderchest:item/banner",
+        "tints": [
+            {
+                "type": "minecraft:constant",
+                "value": 4294344221
+            }
+        ]
+    }
+}

package/assets/builtin/minecraft/items/orange_shulker_box.json

@@ -0,0 +1,6 @@
+{
+    "model": {
+        "type": "minecraft:model",
+        "model": "renderchest:item/shulker_box/orange_shulker_box"
+    }
+}

package/assets/builtin/minecraft/items/oxidized_copper_chest.json

@@ -0,0 +1,6 @@
+{
+    "model": {
+        "type": "minecraft:model",
+        "model": "renderchest:item/chest/oxidized_copper_chest"
+    }
+}

package/assets/builtin/minecraft/items/oxidized_copper_golem_statue.json

@@ -0,0 +1,6 @@
+{
+  "model": {
+    "type": "minecraft:model",
+    "model": "renderchest:item/copper_golem_statue/oxidized_copper_golem_statue"
+  }
+}

package/assets/builtin/minecraft/items/piglin_head.json

@@ -0,0 +1,6 @@
+{
+  "model": {
+    "type": "minecraft:model",
+    "model": "mobheads:item/piglin"
+  }
+}

package/assets/builtin/minecraft/items/pink_banner.json

@@ -0,0 +1,12 @@
+{
+    "model": {
+        "type": "minecraft:model",
+        "model": "renderchest:item/banner",
+        "tints": [
+            {
+                "type": "minecraft:constant",
+                "value": 4293953960
+            }
+        ]
+    }
+}

package/assets/builtin/minecraft/items/pink_shulker_box.json

@@ -0,0 +1,6 @@
+{
+    "model": {
+        "type": "minecraft:model",
+        "model": "renderchest:item/shulker_box/pink_shulker_box"
+    }
+}

package/assets/builtin/minecraft/items/player_head.json

@@ -0,0 +1,6 @@
+{
+  "model": {
+    "type": "minecraft:model",
+    "model": "mobheads:item/player"
+  }
+}

package/assets/builtin/minecraft/items/purple_banner.json

@@ -0,0 +1,12 @@
+{
+    "model": {
+        "type": "minecraft:model",
+        "model": "renderchest:item/banner",
+        "tints": [
+            {
+                "type": "minecraft:constant",
+                "value": 4287050166
+            }
+        ]
+    }
+}

package/assets/builtin/minecraft/items/purple_shulker_box.json

@@ -0,0 +1,6 @@
+{
+    "model": {
+        "type": "minecraft:model",
+        "model": "renderchest:item/shulker_box/purple_shulker_box"
+    }
+}

package/assets/builtin/minecraft/items/rc_filled_map_base.json

@@ -0,0 +1,6 @@
+{
+  "model": {
+    "type": "minecraft:model",
+    "model": "renderchest:item/filled_map/base"
+  }
+}

package/assets/builtin/minecraft/items/rc_filled_map_overlay.json

@@ -0,0 +1,7 @@
+{
+  "model": {
+    "type": "minecraft:model",
+    "model": "renderchest:item/filled_map/overlay"
+  }
+}
+

package/assets/builtin/minecraft/items/rc_firework_star_base.json

@@ -0,0 +1,6 @@
+{
+  "model": {
+    "type": "minecraft:model",
+    "model": "renderchest:item/firework_star/base"
+  }
+}

package/assets/builtin/minecraft/items/rc_firework_star_overlay.json

@@ -0,0 +1,6 @@
+{
+  "model": {
+    "type": "minecraft:model",
+    "model": "renderchest:item/firework_star/overlay"
+  }
+}

package/assets/builtin/minecraft/items/rc_potion_bottle.json

@@ -0,0 +1,6 @@
+{
+  "model": {
+    "type": "minecraft:model",
+    "model": "renderchest:item/potion/bottle"
+  }
+}

package/assets/builtin/minecraft/items/rc_potion_bottle_lingering.json

@@ -0,0 +1,6 @@
+{
+  "model": {
+    "type": "minecraft:model",
+    "model": "renderchest:item/potion/bottle_lingering"
+  }
+}

package/assets/builtin/minecraft/items/rc_potion_bottle_splash.json

@@ -0,0 +1,6 @@
+{
+  "model": {
+    "type": "minecraft:model",
+    "model": "renderchest:item/potion/bottle_splash"
+  }
+}

package/assets/builtin/minecraft/items/rc_potion_content.json

@@ -0,0 +1,6 @@
+{
+  "model": {
+    "type": "minecraft:model",
+    "model": "renderchest:item/potion/content"
+  }
+}

package/assets/builtin/minecraft/items/rc_tipped_arrow_base.json

@@ -0,0 +1,6 @@
+{
+  "model": {
+    "type": "minecraft:model",
+    "model": "renderchest:item/potion/arrow_base"
+  }
+}

package/assets/builtin/minecraft/items/rc_tipped_arrow_head.json

@@ -0,0 +1,6 @@
+{
+  "model": {
+    "type": "minecraft:model",
+    "model": "renderchest:item/potion/arrow_head"
+  }
+}