block-model-renderer

Minecraft block and item model rendering for Node.js and the browser. Render any block, item, or custom model JSON, with full support for vanilla resource pack features. On Node renders go to image files or buffers; in the browser they go straight to canvases, with live animation players.

Live Examples

Features

• Renders blocks, items, and custom models from a resource pack
• Runs on Node.js and in the browser from the same package
• Full vanilla model, blockstate, item-definition, and texture atlas support, with accurate lighting and tints
• Bundled overrides for block entities that Minecraft renders dynamically (banners, chests, heads, etc)
• Stack resource pack folders, zips, and virtual handlers, with higher packs overriding lower ones just like in Minecraft
• Animated textures: WebP and GIF output on Node, live self-updating canvases in the browser
• Game-accurate world lighting: torches glow and light up spaces, with working day/night cycles
• Scene optimization: near game-accurate hidden-face culling from neighboring blocks, and the whole scene merged into a handful of draw calls, with far fewer polygons
• Extensible model loaders: write your own to support modded formats (OBJ models, connected textures, etc)
• PNG, JPEG, WebP, GIF, and AVIF output on Node

Install

For Node.js, or the browser through a bundler:

npm install block-model-renderer

Or in the browser, import it straight from a CDN:

import { renderBlock } from "https://cdn.jsdelivr.net/npm/block-model-renderer@2/dist/block-model-renderer.min.js"

Pinning to the major version like that is the recommended way to load it. The library ships the bundled packs that make block entities render, and those are updated for new Minecraft versions as they land, so a major-pinned URL picks the new assets up on its own while staying on an API you've built against. Pinning an exact version freezes the assets where that release left them.

In the browser you also provide three.js yourself; see Providing three.js.

Quick Start

import { renderBlock, renderItem, renderModel } from "block-model-renderer"

const assets = "C:/Users/ewanh/AppData/Roaming/.minecraft/resourcepacks/vanilla"

// Render a block by id
await renderBlock({
  id: "oak_log",
  assets,
  path: "oak_log.png"
})

// Render an item by id
await renderItem({
  id: "diamond_sword",
  assets,
  path: "diamond_sword.png"
})

// Render a custom model JSON
await renderModel({
  assets,
  model: {
    textures: { main: "block/stone" },
    elements: [{
      from: [0, 0, 0],
      to: [16, 16, 16],
      faces: {
        up:    { texture: "#main" },
        down:  { texture: "#main" },
        north: { texture: "#main" },
        south: { texture: "#main" },
        east:  { texture: "#main" },
        west:  { texture: "#main" }
      }
    }]
  },
  path: "custom.png"
})

And in the browser, where renders go into canvases:

import { renderBlock, prepareAssets } from "block-model-renderer"

// a resource pack zip from a file input, fetch, anywhere
const assets = await prepareAssets([zipFileOrBuffer])

// returns a canvas you can append
const canvas = await renderBlock({ id: "oak_log", assets, width: 128, height: 128 })
document.body.append(canvas)

// animated renders return a live, self-updating player
const player = await renderBlock({ id: "magma_block", assets, animated: true })
document.body.append(player.canvas)

Options

A quick preview of the most-used renderBlock options (full lists, and renderItem/renderModel, in the Standard API):

| Option | Default | Description | |---|---|---| | id | required | The block id (e.g. "oak_log", "stone") | | assets | required | The assets source: pack folders, zips, virtual handlers, or a layered stack of them. Vanilla assets aren't bundled, so provide a base pack. See Assets | | blockstates | {} | Blockstate property values (e.g. { axis: "y", half: "top" }) | | width, height | 256 | Output size in pixels | | path | | Node: save the output to this file path | | canvas | | Browser: a canvas (or several) to draw into | | background | transparent | Background color | | display | the gui view | Display transform: a model display context ("gui", "fixed", etc) or custom rotation/translation/scale. See Display transforms | | animated | false | Animated WebP/GIF on Node, a live player in the browser |

Documentation

The full documentation lives in docs/:

| Doc | Covers | |---|---| | API reference | Every export in one place, grouped and linked to its full docs | | Standard API | The render functions on both platforms: all options, file and buffer output, animated WebP/GIF, canvases, animation players, providing three.js | | Advanced API | Upgradable renders, batch rendering from worker pools, syncing the animation clock, the frame cache, texture players | | Rendering | How a render looks: backgrounds, lighting modes, computeSceneLight volumes, the sky | | Models | Model-level behavior: display transforms, model-inspection helpers, the tint tables | | Assets | Asset sources, pack layering, virtual handlers, prepareAssets and caching, the bundled packs, file access | | Fluids | Water and lava surface shaping, fluidTypeOf, fluidHeights | | Building scenes | The low-level API: createScene, blockstate and item definition parsing, loadModel, dynamic models, map art | | Culling | Hidden-face culling, getCullFaces, fullyOccludes, persisting the occlusion cache | | Scene optimization | optimizeScene, translucent sorting, packed scenes and shared atlases for worker builds | | Extending | Non-vanilla model and blockstate fields, default blockstates, custom model loaders | | Legacy Minecraft versions | The version option and the era-specific behavior it enables |

Examples

Everything on the live pages runs in your browser, on the latest vanilla Minecraft assets:

• Live Examples: the main demo page, every feature rendered live
• Model Viewer: inspect any block or item up close: blockstates, display transforms, lighting modes, culling, wireframe
• Render Gallery: batch-render blocks straight to canvases, with live animation players
• Rotating Grid: an endless scrolling wall of spinning blocks and items
• Scenes: voxel dioramas with neighbor-aware culling, fluid surface shaping, and world lighting
• Structure Viewer: a full website built on the library: browse every vanilla structure, open your own .nbt files, and walk around inside builds
• Node examples: simple renders, batch-rendering every block and item in a pack, animated output, the bundled overrides, and two worked custom model loaders

License

MPL-2.0 © Ewan Howell