Lodestone

A TypeScript library for rendering Minecraft structures in the browser or headless environments.

Why Lodestone?

Build interactive Minecraft structure viewers, schematic editors, world previews, or any web-based Minecraft visualization tool. Lodestone handles the complexity of parsing Minecraft's block models, assembling meshes, and rendering them efficiently with Three.js—so you can focus on your application.

Features

• Litematic file support — Load and render .litematic schematic files (Litematica mod format)
• Flexible rendering — ThreeStructureRenderer provides full-featured Three.js rendering
• Resource pack system — Works with the built-in default pack or your own custom resource packs
• Advanced rendering — Chunked meshing with occlusion culling, transparency sorting, and emissive block support
• Universal runtime — Runs in browsers and headless environments with WebGL
• Full type safety — Written in TypeScript with complete type definitions
• Code Agent Friendly - See MinecraftLM

Installation

npm install @mattzh72/lodestone

Three.js is a peer dependency. Most package managers (npm v7+) install it automatically:

npm install three

Quick Start

import { Structure, ThreeStructureRenderer, loadDefaultPackResources } from '@mattzh72/lodestone'
import { mat4 } from 'gl-matrix'

const { resources } = await loadDefaultPackResources()

const structure = new Structure([4, 3, 4])
structure.addBlock([0, 0, 3], 'minecraft:stone')
structure.addBlock([0, 1, 3], 'minecraft:cactus', { age: '1' })

const renderer = new ThreeStructureRenderer(canvas, structure, resources)
renderer.setViewport(0, 0, canvas.width, canvas.height)

const view = mat4.create()
mat4.translate(view, view, [0, 0, -5])
renderer.drawStructure(view)

For a complete example with item rendering and controls, see demo/main.ts.

Usage

Loading Litematic Files

Lodestone can load .litematic files (the schematic format used by Litematica mod):

import { LitematicLoader, ThreeStructureRenderer, loadDefaultPackResources } from '@mattzh72/lodestone'

// Load litematic file
const response = await fetch('path/to/build.litematic')
const buffer = await response.arrayBuffer()
const structure = LitematicLoader.load(new Uint8Array(buffer))

// Get metadata
const metadata = LitematicLoader.getMetadata(new Uint8Array(buffer))
console.log(metadata.name, metadata.author, metadata.totalBlocks)

// Render it
const { resources } = await loadDefaultPackResources()
const renderer = new ThreeStructureRenderer(canvas, structure, resources)

The loader handles gzip-compressed NBT parsing, variable-width bit-packed block state arrays, block palettes and properties, and multiple regions (loads first region by default).

CDN Usage (UMD)

Load Three.js first, then Lodestone. The UMD bundle exposes window.Lodestone.

Pinned version (recommended for reproducible builds):

<script src="https://unpkg.com/three@0.164.1/build/three.min.js"></script>
<script src="https://unpkg.com/@mattzh72/lodestone@0.4.0/dist/lodestone.umd.cjs"></script>
<script>
  // Load the built-in default pack from unpkg
  (async () => {
    const baseUrl = 'https://unpkg.com/@mattzh72/lodestone@0.4.0/assets/default-pack/'
    const { resources } = await Lodestone.loadDefaultPackResources({ baseUrl })
    // ...use resources with ThreeStructureRenderer
  })()
</script>

Latest version (convenient but may change):

<script src="https://unpkg.com/three@0.164.1/build/three.min.js"></script>
<script src="https://unpkg.com/@mattzh72/lodestone@0.4.0/dist/lodestone.umd.cjs"></script>
<script>
  const { Structure, ThreeStructureRenderer } = window.Lodestone
</script>

Custom Resource Packs

To use your own resource pack instead of the built-in default, provide a Resources object with:

• Block definitions (blockstates/*.json)
• Block models (models/*.json)
• Texture atlas (ImageData) and UV lookup
• Block flags (opaque, transparent, emissive)

See the demo/ folder for a concrete implementation example.

Development

Run the local demo:

npm install
npm run demo

Contributing

Issues and pull requests are welcome! Visit the issue tracker to report bugs or suggest features.

License

MIT. Lodestone includes upstream MIT-licensed code from Misode.

Acknowledgments

Special thanks to deepslate—Lodestone is an optimized, Three.js-native version of their work.