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/dist/block-model-renderer.min.js"

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
Rendering	How a render looks: backgrounds and lighting modes
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: blockstate and item definition parsing, loadModel, hidden-face culling, scene optimization
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

MIT © Ewan Howell