Track V1 feature parity and the remaining V2 work here. Commands and architecture are in AGENTS.md.
Library paths below are relative to packages/minerender/.
| Source | Destination | Revision |
|---|---|---|
| InventivetalentDev/MineRenderWeb | apps/web/ |
01ff6efdb2d83549b4ac93f05ae9acc68ac96fee |
| MineRender/example-vite | examples/vite/ |
1c2fc275d8b3dc9f6c8beb0bcf7d5538975b577d |
| MineRender/example-bundle | examples/script-tag/ |
411044c1edf241bff8b919296a72183e53fcf709 |
V1 master, tags, bundles, and website URLs must remain available. V2 targets main.
Details and remaining work for each row are in the continuation plan.
| Feature | V1 | V2 | Status | Priority |
|---|---|---|---|---|
| Build & dev environment | webpack 4 per-feature IIFE bundles | Yarn 4 and tsup | complete | — |
| Packaging / npm hygiene | script-tag CDN | Browser/Node conditional exports, declarations, files whitelist | complete | — |
| Clean import (no side effects) | window globals, telemetry beacon | Lazy platform setup and Ticker; idle Node processes exit | complete | — |
| Browser/Node dual-target | browser-only | Per-platform entries; Node canvas optional for browsers | complete | — |
| Renderer core | continuous loop, SSAA, fps limit, dispose() | Dirty-flag loop, frame limit, disposal, sRGB output | complete | — |
| Camera controls | OrbitControls via options.controls |
Opt-in OrbitControls or FlyControls (controls.mode) |
complete | — |
| Skins — classic 64×64 | named toggleable parts | Vanilla dimensions, UVs, pivots, overlays, named parts | complete | — |
| Skins — slim + legacy 64×32 | auto-detected | Slim/legacy UVs and detection; legacy skins normalized | complete | — |
| Capes (vanilla/OptiFine/LabyMod) | 3 layouts, capes.dev | All three static layouts and capes.dev lookup | partial | medium |
| Armor | none | Worn and standalone 1.21.4+ armor: dye, trims, glint | partial | medium |
| Block/item model rendering | tints, display transforms | Tints, display poses, composite and special items, glint | partial | high |
| Blockstate resolution | variants, weighted, multipart | Variants, weighted alternatives, multipart AND/OR | complete | — |
| Animated textures | frametime | Frame grids, sequences, durations, interpolation | complete | — |
| Entity rendering | 76 hosted models, mirror | Versioned dataset, passes, render modes, transforms | partial | high |
| Entity keyframe animations | none | Native and sampled clips, layer playback, weights | partial | high |
| GUI / inventory / recipes | GuiRender, Positions, recipe() | Layers, containers, recipes, bitmap/Unihex text, layouts | partial | medium |
| Structure (.nbt) loading | via ModelConverter | Bounded placement, block entities, opt-in saved mobs | partial | high |
| Legacy .schematic | incl. AddBlocks nibbles | IDs, metadata, AddBlocks, custom mappings, lenient mode | complete | — |
| Combined multi-renderer scene | CombinedRender wrapper | Superseded: one scene hosts all types | complete | — |
| Screenshots, video & 3D export | toImage, toObj/toGLTF/toPLY | Trimmed captures, browser video, OBJ/PLY, textured glTF | complete | — |
| Asset loading & resource packs | swappable assetRoot | Ordered sources, ZIP overlays, version selection | partial | high |
| Per-frame animation API | <type>Render CustomEvents |
onFrame with time/delta, FPS limit, pause |
complete | — |
| Scene documents & editor | n/a | Versioned scene JSON and a browser editor | complete | — |
| Embeds & website | minerender.org, iframe embeds | V2 site, playgrounds, editor, API reference, embeds | complete | — |
| Large-scale worlds (V2 goal) | n/a | Paletted chunks, section meshes, streaming, light, AO | partial | high |
| Anvil .mca / world formats (V2 goal) | n/a | Anvil regions, Sponge, Litematica, entity regions; ID renames only | partial | high |
| Node headless rendering (V2 goal) | MineRenderServer | NodeRenderer, PNG buffers, scene-document HTTP API |
complete | — |
| Bedrock geometry (V2 ambition) | n/a | Type declarations only | not started | low |
| Instancing architecture | merged Geometry, instancing fork | Reusable slots, growing buffers, per-placement refs | partial | high |
Done:
- Build tooling, package exports, import-time initialization, and browser/Node providers.
- Update cache and queue dependencies so idle imports let Node exit.
- Build the browser ESM output per module, and load optional object types, exporters, and storage on first use.
Done:
- Fix start/stop, disposal, resize invalidation, and scene listeners.
- Integrate opt-in OrbitControls.
- Implement frame limiting.
- Align Three types and color spaces; fix direct/composer brightness.
- Compile the shaded model material for both instanced and non-instanced meshes.
Done:
- Resolve sources in priority order and return the first defined asset.
- Initialize node-persist before use.
- Decode fetched image bytes without refetching them; reject invalid images and allow retry.
- Skip nullish persistent writes and evict missing or rejected async cache loads.
- Bound request concurrency, retries, cancellation, timeouts, and shutdown.
- Propagate hosted/archive and model initialization errors with source context.
- Default to 1.21.11 with static item definitions, animal texture paths, structure directory aliases, and versioned cache keys.
- Add an asset-version selection API.
- Load versioned registry and rendering data from
minerender-data, replacing bundled runtime datasets. The nearest published release is used when the exact registry version is unavailable. - Replace renamed block, item, and saved-entity IDs through the optional versioned
renamesdataset. - Read ZIP pack metadata, select version-applicable overlays, and filter lower-priority resources.
- Fix
WrappedImageframe math.
Done (item rendering):
- Chest, bed, mob-head, and shulker-box items, including shulker textures, openness, and six orientations.
- Banner and shield items with supplied base colors and ordered banner patterns.
- Held and throwing trident poses, static conduits, and decorated pots with four supplied sherd sides.
- Player-head items from supplied profiles: skin lookup, texture properties, resource-pack texture overrides, and default skins.
- Copper-golem statue variants and poses from supplied block-state components.
- Nested composite items with each child's textures, display pose, lighting, and tints.
- Item properties from supplied data components, stack counts, display contexts, and overrides. Shared playground controls include bundle, bow, crossbow, and indexed custom-model-data presets.
- Static and default item tint sources.
- Supplied dye, map, firework, potion custom-color, and indexed custom-model-data tints, including GUI item contexts.
- Potion and tipped-arrow colors from supplied potion IDs and visible custom effects, with a playground potion selector.
- Animated enchantment glint on ordinary and composite items, shields, and held or throwing tridents, with explicit overrides.
- Vanilla glint defaults by item ID, retaining explicit overrides and resource-pack model replacements.
- Projected glint on compasses, recovery compasses, and clocks; normal-compass glint from supplied lodestone tracking.
- Vanilla durability and stack-size defaults in model selectors and GUI bars, with editable playground overrides.
Composite items and items with glint do not use instancing.
Remaining:
- Glint on other special renderers.
- Other special renderers.
- Team colors (only declared defaults are used).
- Other item registry defaults.
- Automatic calculation of world and player state.
- ZIP resource packs outside the browser (archive sources are browser-only).
Done (small, high-impact fixes):
Axis.X = "X"→ lowercase (x-rotations silently no-op).- Await
BlockStates.getDefaultState. - Fix the texPosition-undefined crash.
ModelMerger: childelementsoverride the parent's instead of concatenating.- Remove the 150ms rotation workaround and preserve multipart rotations during placement.
- Multipart AND/OR,
applyarrays, and weighted variants. AssetKey.parseextension fallback and the brokenisAssetKey.
Done (follow-ups):
tintindexwith explicit colors.- Automatic block preview colors.
uvlock.- Display transforms.
- Honor element
shade: falsein block models and world sections; item previews keep directional shading.
Done:
- Correct slim arm/sleeve UVs; preserve named parts, poses, visibility, and shared resources when switching classic/slim.
- Add the 64×32 legacy layout and slim/legacy auto-detection.
- Match vanilla base opacity, overlay blending, dimensions, UVs, and joint pivots.
- Add vanilla cape meshes wired to the existing
Skins.tsresolvers. - Add OptiFine/LabyMod layouts and capes.dev lookup.
- Add worn and standalone 1.21.4+ armor with dye, trims, glint, and skin scene-document support.
- Add opt-in deadmau5 ears and Dinnerbone/Grumm upside-down players.
Remaining:
- Animated capes.
- Consider sharing geometry construction with
EntityObject.
Done:
- Recurse
ModelPart.children. - Implement
mirror. - Verify the face UVs and pivot translation.
- Compose selected entity layers with separate textures and named groups (e.g. sheep body and wool).
- Support dataset render passes, emissive and scrolling materials, tint overrides, and renderer-specific root transforms.
- Render supported block entities during block placement.
- Play native and sampled procedural clips with synchronized, layer-specific playback.
- Blend clips within a layer with explicit weights, and update weights without restarting playback.
- Store clip blends in scene documents and edit them in the scene editor.
- Publish the
1.21.11entity dataset with the procedural clips from minecraft-entity-models #7. - Load entity geometry, lists, animations, and the block-entity index from the nearest published dataset version. Textures keep the requested version.
Default textures and root transforms come from the versioned entity dataset. Callers can override textures and select conditional passes.
flip: false explicitly keeps raw model space rather than applying the dataset transform.
Remaining:
- Runtime gameplay state selection, visibility changes, and animated renderer transforms.
- Upside-down mobs named Dinnerbone or Grumm. Vanilla raises them by their bounding-box height, which no published dataset provides yet.
Done:
- Limit
InstancedMesh.countto allocated slots. - Add a free-list so removal reclaims slots.
- Grow capacity on demand instead of silent out-of-bounds writes.
- Provide per-placement transforms through
InstanceReferences. - Replace the
children[0]-is-the-InstancedMesh assumption with a stored reference.
Remaining:
- Shared-owner transforms still affect all live instances; changing that API is separate work.
- Extend deduplication beyond
assetType === "models"to blockstate level.
Done (immediate fixes):
- Fix
getChunkAtto useMap.get(key). - Remove the 4×4×4 bound and negative-coordinate rejection.
- Remove hardcoded debug wireframes.
- Fix
BatchedExecutor's missing setInterval delay and addstop(). - Place structures and chunks in bounded batches with one final neighbor-culling pass.
Done (redesign):
- Palette and typed-array section storage.
- Opt-in merged meshes and bounded atlas pages per chunk section, for models of any shape and for fluid surfaces. This covers cutout, translucent, multipart, and animated models; block entities keep per-block objects.
- Neighbor face culling via model
cullfaceagainst opaque full cubes. Vanilla's same-block and connected-block rules from theblockCullingdataset also hide shared faces. - Explicit chunk load/unload.
await world.unloadChunkColumns(positions)removes columns together and refreshes surviving neighbors once. The streamer requires this method, whichMineRenderWorldprovides, for eviction and disposal.- Per-block visibility without deleting block data.
- Camera-driven streaming.
- Opt-in baked per-vertex ambient occlusion on axis-aligned boundary faces, with runtime toggling. It honors model opt-outs and refreshes edited or streamed neighbors.
- Seed weighted blockstate alternatives by world position, so unloading and reloading a chunk preserves its appearance.
Individual blocks and section meshes share vanilla-identical selection from absolute block coordinates.
Standalone previews remain random unless given
variantPosition. - Pick individual world blocks through
world.raycast, including merged terrain. The world demo inspects their coordinates, properties, and saved biome. - Pick rendered mobs through
world.raycastEntities; the world demo inspects their type and saved position. - Resolve each block state once per placement group and yield to the event loop instead of a timer-driven batch queue.
- Build section geometry in a browser worker.
- Group ready streamed columns with a four-column read window and refresh shared borders once per placement group.
- Sort transparent model and fluid quads back to front within each atlas page.
Done (biomes and light):
- Preserve modern Anvil biome palettes during import and placement, including air-only sections, with world-coordinate lookup.
- Apply biome colors to grass, foliage, dry foliage, and water in both rendering modes. This includes merged fluid sections, resource-pack colormaps, and dark forest/swamp grass modifiers.
- Opt-in biome color blending in section meshes, with a runtime radius, cached color averaging, and border refreshes after biome edits or streaming.
- Import saved sky/block light and apply opt-in flat lighting to blocks and fluids in section meshes.
Done (fluids):
- Render sloped water/lava surfaces with still/flow textures and waterlogged blocks.
- Cover intrinsic water in kelp, seagrass, and bubble columns.
Remaining:
- Exact partial-shape ambient occlusion.
- Light propagation. The published
blockLightingdataset is not read yet. - Intersecting surfaces and quad ordering across pages or sections remain approximate.
- Per-position flower offsets. The published
blockAppearanceoffsets are not read yet. - Draw glass and panes on the translucent page, as vanilla's render layers do (
blockAppearancerender layers); they currently use the solid/cutout page. - Chunk-level visibility management and LOD. Section meshes already have bounds for Three.js frustum culling.
- Older numeric biome arrays (the published
legacyBiomesdataset is not read yet) and world-seed-based biome sampling. - Region decoding still runs on the main thread. Wasm or worker-side chunk parsing remains a scale option once placement stops dominating.
- Measure real-world decoding, placement, frame stalls, and retained memory before choosing further worker or LOD work. Use the world-streaming benchmark: it records fixed local-save routes with cold and warm asset passes, operation timings, frame-callback gaps, and JavaScript heap samples.
- Fluid parity: read the published
fluidStatesdataset (fluid definitions, face-occlusion shapes, solidity and flow-blocking flags) and add water overlays against glass/leaves.
Keep 1 block = 16 units.
Done:
- Make
Rendererconstructible without DOM through an injected canvas and WebGL 2 context. - Add
renderOnce()and Node-onlyNodeRenderer.renderToBuffer()for fresh frames and PNG buffers without the animation loop. - Add a V2 HTTP rendering service.
NodeRenderer.create({ width, height, ...options }) owns a native context from optional gl@9.0.0-rc.10 (experimental WebGL 2).
The Node entry uses canvas 3 for texture preparation. Injected contexts remain caller-owned.
See platform setup and usage.
apps/api accepts versioned scene documents at POST /v1/renders and serves render metadata and PNG images:
- Rendering uses a pool of isolated processes with reusable asset caches, bounded concurrency, deadlines, and an expiring PNG cache.
- V2 deliberately replaces the V1
GET /render/skin/:texture,GET /render/model/:type/:model, andminerender-optionscontract. - Returned PNG URLs can be embedded while cached; GET requests do not create renders.
Remaining:
- Hosting and persistent render storage.
Done:
- Add a world-format layer feeding chunk storage:
.mcasector tables, section palettes, and DataVersion. Preserve NBT type/compression metadata, implement legacy.schematicID/metadata and AddBlocks conversion, and retain structure entities and DataVersion. - Support custom legacy schematic mappings and opt-in lenient parsing.
- Decode Anvil LZ4 block streams with checksum validation.
- Read external
.mccpayloads through caller-supplied readers and local world-folder imports. - Decode pre-1.13 numeric Anvil chunks with shared schematic mappings, custom overrides, and opt-in lenient parsing.
- Load Sponge v2/v3
.schemfiles with local palettes, block states, offsets, block/entity NBT, and DataVersion; add playground and editor imports. - Load Litematica v5–7
.litematicfiles with named regions, signed dimensions, relative placement, and preserved block/entity NBT; add playground and editor imports. - Add opt-in rendering of supported saved mobs at their positions and yaw, with cleanup on column replacement, unloading, and world clearing.
- Load modern worlds' separate
entities/*.mcafiles alongside terrain with shared cache limits and cancellation, including entity-only columns and world-folder imports. - Read structure palettes saved with either
Name/Propertiesor the Minecraft 26.xid/propertiesfields.
Remaining:
- Sponge biome and metadata import.
- DataVersion-based block-state and NBT migration. Renamed IDs are already replaced (section 6).
Done:
- Implement
GuiObject: layered textured planes with UV crop, pixel positioning, and ordered layers. - Wire
scene.addGui(...),inventorySlot, and a chest demo with camera fitting. - Add item models in the GUI display pose.
- Draw stack counts and supplied-component durability bars, preserve recipe output counts, and add an inventory-slot playground preview.
- Add shaped/shapeless recipe layouts and update crafting for the newer recipe format.
- Add modern GUI sprite scaling (stretch, tile, nine-slice).
- Render styled bitmap text and tooltips from supplied lines.
- Update V1's boss bar and book layouts for the newer texture paths, expose chest/crafting presets, and add playground controls.
- Load vanilla and resource-pack Unihex providers with size overrides, shared atlas pages, and matching text metrics.
Remaining:
- TrueType providers.
- Translated text.
- Right-to-left shaping.
Done:
- Port toObj/toGLTF and toImage trim/mime.
- Add a per-frame callback integrated with the dirty flag (replaces V1's CustomEvent contract).
- Fix
SceneInspectorraycast normalization and select individual instances. - Fix
SceneStatsDisplay's leaked interval. - Fix animated-texture timing, frame grids/sequences, and stationary-camera redraw for all scenes sharing an atlas, respecting
fpsLimit. Stop unused atlas tickers. - Add texture interpolation.
- Build the V2 website with live examples.
- Rework the demos into configurable playgrounds.
- Add portable scene documents and a browser scene editor.
- Add TypeDoc/VitePress reference tooling and library API JSDoc.
- Host the playgrounds and editor on Cloudflare.
- Add browser video export with recording controls.
- Add scene-driven iframe embeds with shorthand URLs, portable scene links, and editor copy support.
- Remove unused V1 website files from the V2 tree while preserving V1 delivery URLs.
- Deploy the embed Worker at
beta.minerender.org/embed/. - Route library logging through leveled per-component loggers; only warnings and errors print by default.
Remaining:
- Extend existing regression coverage as remaining model and blockstate features land.
- Keep the consumer API contract in AGENTS.md as the beta compatibility baseline.