Skip to content

Core concepts ​

MineRender's APIs use different units for scene geometry, world blocks, GUI layers, and frame timing. Rendering also depends on initialization, dirty notifications, and resource ownership.

Units and coordinates ​

Use the units expected by the API you call:

ContextUnits and direction
Scene geometry and positionsOne Minecraft block spans 16 scene units.
World block positionsInteger block coordinates, including negative coordinates. A cubic chunk contains 16 × 16 × 16 blocks.
GUI layer positionsPixels measured from the top-left. One GUI pixel is one scene unit; positive GUI y becomes negative scene y.
three.js rotations and part posesRadians. Source model formats may use different units before MineRender converts them.
Renderer.onFrametime and delta are seconds. time is the animation-loop timestamp, not time since subscription.

MineRenderWorld provides worldToScenePosition and sceneToWorldPosition. The latter divides by 16 without rounding; world block lookups and setters still require integer coordinates.

For GUI camera fitting, use GuiObject's bounds. It includes item-model overhang as well as layer rectangles, in GUI coordinates.

render.pixelRatio sets drawing-buffer pixels per CSS pixel, with a default of 1. It changes image-export resolution; layout and inspector picking use CSS pixels.

Await initialization ​

The addModel, addBlock, addSkin, addEntity, and addGui methods on MineRenderScene return promises. Await them before changing the returned object's parts or capturing an image. These methods wait for object initialization, including the required asset work.

Texture changes can also be asynchronous. Await SkinObject.setSkinTexture before relying on skin dimensions or model detection, and await setCapeTexture before capturing the cape.

World edits such as setBlockAt, placeMultiBlock, and clear also return promises. Await them before reading the resulting rendered state. Bulk placement resolves each distinct block state once, yields to the event loop every few milliseconds, and refreshes neighbor culling once at the end; pass a BatchedExecutor to keep per-position batches instead. A failed bulk placement can leave successfully placed blocks in the world; it is not a transaction that rolls back earlier placements.

With sectionMeshing: true, changed sections rebuild after the placement promise resolves. The browser build prepares section geometry in a Web Worker when the bundle keeps section.worker beside the module; otherwise it builds synchronously. See Browser and Node.js.

Versioned registry data ​

AssetLoader.setVersion(version) selects both vanilla assets and the registry data used for item defaults, potion colors, block properties, preview tints, face culling rules, fluids, dyes, legacy numeric mappings, and renamed IDs. These datasets load from assets.mcasset.cloud/<version>/minerender-data/ when needed.

When the exact dataset version is missing, MineRender selects the nearest published patch in the same release line, preferring the older patch on a tie. Otherwise it uses the latest earlier published release. Releases older than the published data use the oldest available release; an unpublished snapshot rejects. Models and textures retain the requested asset version. A missing dataset or failed request rejects rather than returning an empty registry.

BlockStates.get, item keys in Models.getMerged, and saved world entities replace older IDs through the optional renames dataset. An ID the selected version still registers keeps its meaning, and stored world data keeps the input's ID. Published data without this dataset applies no renames and does not reject. Renames.resolve(kind, id, dataVersion?, root?) returns the replacement directly and accepts the input's DataVersion when the caller knows it.

Inspect the selected registry version with resolve:

ts
AssetLoader.setVersion("1.21.6");
const data = await MineRenderData.resolve();
console.log(data.requestedVersion, data.version);
const defaults = await ItemDefaults.get("minecraft:diamond_sword");

Pass an explicit asset root as the second argument to MineRenderData.get(dataset, root) or ItemDefaults.get(itemId, root) when loading another version or a mirror. SchematicParser, AnvilParser, and AnvilWorldSource accept root in their options to select the target registry for numeric block mappings; the file's DataVersion does not choose or migrate that target.

The former synchronous data lookups now return promises: ItemDefaults.get, ItemTints.getPotionList, getBlockFluidState, getFluidKind, and resolveLegacyBlock. For repeated synchronous calculations, load fluids or legacyBlocks once with MineRenderData.get and pass the table to resolveBlockFluidState or resolveLegacyBlockState. Rendering and parser entry points await their data automatically. BannerPatterns.getColors(root?) provides versioned texture dyes; DYE_COLORS and BannerPatterns.getColor retain the fixed 1.21.11 palette for compatibility and are deprecated.

Entity and block-entity geometry from entity-models/ uses the same version selection when the exact dataset version is missing. This also applies to entity lists, animations, and the block-entity index. An unpublished snapshot keeps its own version and draws block entities with their block models. Textures keep the requested asset version.

Redrawing after changes ​

Renderer draws only when the scene is dirty, render.renderAlways is enabled, an onFrame subscription is active, or a video is recording. Calling start() runs this loop; it does not force an unchanged scene to redraw continuously.

MineRender setters such as setPosition notify the scene. When you change a three.js property directly, such as a named part's rotation or visible, call the owning SceneObject's notifyDirty() or set renderer.scene.dirty = true. The loop draws the change on its next eligible frame.

Built-in controls created with controls.enabled handle redraw notifications. controls.mode selects orbit (OrbitControls, the default) or fly, creative-style flight with WASD, space/shift, R to sprint, mouse look through pointer lock or dragging, the wheel to change speed, and a touch joystick on the left half of the canvas. renderer.orbitControls and renderer.flyControls return the active one, and renderer.setControlsMode(...) switches at runtime while keeping the camera in place; the switch creates a new controls object, so add listeners and settings again. renderer.controls is typed as either class; read OrbitControls members such as target from renderer.orbitControls. Register controls you create yourself with renderer.registerEventDispatcher(...) so their change events mark the renderer dirty.

For continuous animation, use renderer.onFrame(...). Its synchronous callback runs before each draw and keeps rendering active. render.fpsLimit caps these draws; its default is 60, and a nonpositive value disables the cap. The first callback after subscribing or restarting receives delta: 0. Call the returned unsubscribe function when the animation ends.

renderer.toImage() renders a fresh frame even while stopped. It does not call onFrame callbacks, so update the pose first when exporting a specific animation frame.

Video export ​

Call renderer.toVideo({ duration: 5, fps: 30 }) to record five seconds of the current scene, including running animations and camera movements. It returns a silent video Blob. The browser selects a supported WebM or MP4 encoder; use blob.type to choose the file extension. Set mimeType to request a specific supported format, or videoBitsPerSecond to request an encoding bitrate.

Recording runs in real time. Keep the tab visible; browser scheduling and render.fpsLimit can reduce the frame rate or affect duration. The video keeps the canvas's initial drawing-buffer dimensions, scales later resizes to fit, and fills transparent pixels with black. It does not trim frames or rewind animations.

Only one video can record per renderer. A stopped renderer starts for the recording and stops again afterward. Pass an AbortSignal as signal to cancel. Calling stop() or disposing the renderer also cancels the recording and rejects its promise. Calling start() while the renderer is running leaves the recording active.

Entity animation blending ​

Entities.getAnimations(modelKey) loads native and sampled vanilla clips. entity.playAnimation(clip, options) plays one clip; entity.playAnimations(clips, options) plays several with a shared clock. Call entity.advanceAnimation(delta) from renderer.onFrame, or set an explicit time with entity.setAnimationTime(seconds) before a capture.

Pass weights in clip order to combine animations on the same geometry layer. Each weight must be finite and nonnegative, and the array must have one entry per clip. Omitted weights default to 1; without playback, setAnimationWeights does nothing. Given walking and head-look clips, apply both and adjust the look strength without restarting playback:

ts
entity.playAnimations([walk, look], { weights: [1, 0.5] });
const unsubscribe = renderer.onFrame(({ delta }) => entity.advanceAnimation(delta));
entity.setAnimationWeights([1, 0.25]);

Each update adds the weighted position, Euler-angle, and scale offsets to the baked part pose. Weights are not normalized: [1, 1] adds both clips at full strength, while [0.25, 0.75] blends between their offsets. A zero weight contributes no offset. activeAnimations and animationWeights retain the input clip order. Without a loop override, each clip uses its own loop flag; speed and time are shared.

A clip targets its layer, which defaults to main, including repeated draws of that geometry. The main-layer blend also poses selected layers without clips of their own. An explicit layer clip takes precedence, including when its weight is zero. Call unsubscribe() when playback ends; entity.stopAnimation() restores the caller's pose from before playback. Automatic gameplay-state selection, part visibility changes, and animated renderer transforms remain unsupported.

Scene documents store a blend in an entity's animation.clips list. For example, a camel's animation settings can combine walking and idle offsets:

json
{
  "clips": [{ "name": "walk", "weight": 0.5 }, { "name": "idle" }],
  "loop": true
}

name plays one clip. Supply either name or a nonempty clips list. Every named clip must exist and target a selected entity layer, or document loading rejects before the document attaches to the scene.

Item state ​

Models.getMerged(key, context) evaluates an item definition with the supplied ItemModelContext: data components, item-model properties, a stack count, a displayContext, and itemReferences for nodes such as minecraft:bundle/selected_item. The same state selects models, special renderers, and automatic tints.

ts
const key = new AssetKey("minecraft", "leather_chestplate", "models", "item");
const model = await Models.getMerged(key, { components: { "minecraft:dyed_color": 0x3f76e4 } });
await scene.addGui([{ item: "minecraft:item/shield", context: { components: {
    "minecraft:base_color": "blue",
    "minecraft:banner_patterns": [{ pattern: "minecraft:stripe_center", color: "white" }]
} } }]);

The selected version's stack-size, durability, and glint defaults from ItemDefaults apply unless overridden by supplied components. Supply any other components a selector reads. GUI item layers and scene-document item definitions take the same context; documents name item references by item ID. Explicit tints still override automatic colors. See the AGENTS.md item notes for the supported components and renderers.

GUI text ​

GUI text accepts literal Unicode strings or styled text runs. Fonts loads bitmap, Unihex, space, and reference providers from the selected assets and resource packs. Unihex ZIPs use vanilla glyph metrics and size overrides, with shared atlas pages allocated as glyphs are drawn. A Unihex file downloads only when text needs a character that earlier providers lack, so plain ASCII text in the default font never loads unifont.zip. TrueType fonts, translation keys, and right-to-left shaping remain unsupported.

Objects and instance references ​

With model instancing enabled, scene methods can return an InstanceReference instead of a separate model object. Use the reference's transform methods to change that placement. Changing the underlying shared object's transform can affect its other instances.

Calling removeFromScene() or dispose() on an instance reference releases its slot. A released reference rejects transform access; create another placement to obtain a usable reference.

Block model elements with shade: false skip directional face shading in separate, merged, and instanced models, including world section meshes. Tints, saved world light, and ambient occlusion still apply. Item previews keep directional shading because vanilla's item renderer ignores the flag. Omitted or true values retain directional shading; GUI items with gui_light: "front" disable it for the whole model.

World placement selects weighted block models from absolute block coordinates, so unloading and reloading preserves their appearance in both rendering modes. Standalone scene.addBlock previews remain random unless you supply variantPosition: [x, y, z] in block units. The position is copied at construction; moving the object does not change its selection. The pick is vanilla-identical for the same coordinates and ordered weights. Position-based selection rejects total weights above 2,147,483,647.

World section meshes ​

With sectionMeshing: true, MineRenderWorld merges the block models in each 16 × 16 × 16 section into a few meshes. This includes cutout, translucent, multipart, and animated models, plus fluid surfaces. Solid, translucent, and fluid geometry use separate atlas pages of at most maxAtlasSize pixels per side, 2048 by default, with one mesh per page; animated textures get their own pages. Block entities keep individual objects.

A merged block has no individual BlockInfo.object. Edit it through the world or chunk setters so geometry and neighbor culling update together.

Translucent blocks and water in a section mesh draw back to front. Perspective views sort them by distance from the camera and re-sort when the camera enters another block; orthographic views sort by view depth. Separate section meshes rely on Three.js sorting the meshes as whole objects, and intersecting surfaces can still blend incorrectly.

In both rendering modes, a face whose model cullface touches an opaque full cube is hidden. The selected version's blockCulling dataset adds vanilla's other rules: glass, ice, slime, and similar blocks hide faces toward the same block, mangrove roots toward the same block above or below, and connected panes or bars toward each other. Leaves keep their faces.

await world.setBlockVisibleAt(position, false) hides a block without deleting its data and reveals its neighbors' faces. Replacing or removing the block resets its visibility.

Inspecting world blocks ​

Pass a three.js Raycaster to world.raycast to find the nearest visible block in that world. It works with individual instances and merged sections, including fluid surfaces and block entities. It does not load chunks or select unrelated objects in the same scene.

ts
import { Raycaster, Vector2 } from "three";

const rect = renderer.renderer.domElement.getBoundingClientRect();
const pointer = new Vector2(
    (event.clientX - rect.left) / rect.width * 2 - 1,
    1 - (event.clientY - rect.top) / rect.height * 2
);
renderer.camera.updateWorldMatrix(true, false);
const raycaster = new Raycaster();
raycaster.setFromCamera(pointer, renderer.camera);
const hit = world.raycast(raycaster);
if (hit) console.log(hit.position, hit.block.type, hit.block.properties);

hit.position contains integer block coordinates, and hit.block is a detached data snapshot. hit.point and hit.distance use scene units; hit.normal is the triangle's unit normal in world space. The raycaster's distance range and layers apply. Picking tests geometry, including transparent texture pixels, and returns undefined when no block is hit. Await world edits before picking their resulting geometry.

Saved entities ​

Enable renderEntities to render supported mobs from parsed structures or Anvil entity records:

ts
const world = new MineRenderWorld(renderer.scene, { renderEntities: true });
await world.placeMultiBlock(structure);

The option defaults to false. With renderEntities, supported mobs render at their saved position and yaw; sheep wool colour and shearing and fox, axolotl and parrot variants apply; other appearance state is ignored. Unsupported entities retain their NBT without creating a render object.

The world owns these entity objects. Replacing or unloading a chunk column disposes its entities, including structure entities positioned within that column. await world.clear() removes all of them.

Use world.raycastEntities(raycaster) to inspect the nearest visible rendered mob. The hit includes its canonical type (such as minecraft:pig), a copy of its saved fractional position in block units, and its live object. The point, normal, and distance fields use the same units as block hits. Hidden or detached entities and objects owned by another world are excluded. Picking respects the raycaster's layers and distance range and tests geometry, including transparent texture pixels.

Compare the block and entity hit distances to select whichever is in front:

ts
const block = world.raycast(raycaster);
const entity = world.raycastEntities(raycaster);
const hit = entity && (!block || entity.distance < block.distance) ? entity : block;

Without renderEntities, or when no rendered mob is hit, raycastEntities returns undefined.

Streaming a Java world ​

Use a dedicated MineRenderWorld with sectionMeshing: true and a WorldStreamer to render nearby chunk columns. This example reads one dimension's terrain and entity regions at region coordinates:

ts
const readRegion = (directory: "region" | "entities") => async (x: number, z: number, signal?: AbortSignal) => {
    const response = await fetch(`/world/${directory}/r.${x}.${z}.mca`, { signal });
    if (response.status === 404) return undefined;
    if (!response.ok) throw new Error(`Region request failed: ${response.status}`);
    return response.arrayBuffer();
};
const source = new AnvilWorldSource(readRegion("region"), {
    readEntityRegion: readRegion("entities"),
    readExternalChunk: async (x, z, signal) => {
        const response = await fetch(`/world/region/c.${x}.${z}.mcc`, { signal });
        if (response.status === 404) return undefined;
        if (!response.ok) throw new Error(`External chunk request failed: ${response.status}`);
        return response.arrayBuffer();
    }
});
const world = new MineRenderWorld(renderer.scene, { sectionMeshing: true, renderEntities: true });
const stream = new WorldStreamer(world, source, { loadRadius: 1, unloadRadius: 2 });
await stream.updatePosition(renderer.camera.position);

readEntityRegion is optional. Terrain and entity regions share the configured cache limits. A stored entity chunk replaces embedded entity records, including when its list is empty; a missing entity chunk preserves them. Entity-only columns have an empty sections array. The resulting chunk keeps the entity file's DataVersion in entityDataVersion, separate from terrain dataVersion.

For direct decoding, call AnvilParser.parseEntityChunk(bytes, localX, localZ). It returns absolute chunk coordinates, dataVersion, and typed entity NBT, or undefined when the region has no entry there.

Call updatePosition after the camera or view center moves. It accepts scene units; update(x, z) accepts absolute chunk coordinates.

With MineRenderWorld, the streamer reads ahead by at most four columns, counting both pending reads and decoded results. It places the nearest ready columns together and refreshes their shared borders once. An unfinished later read does not delay the ready prefix. Custom world adapters can provide placeChunks to use this path; adapters with only placeChunk retain one-at-a-time reads and placement.

The streamer aborts obsolete reads and active reads during disposal. Source callbacks must forward the optional signal to cancellable I/O to stop that work. Reads that ignore cancellation occupy their window slots until they settle. dispose() waits for them; a placement failure rejects without waiting for them.

readExternalChunk handles oversized chunks stored beside their region file. Its coordinates are absolute chunk coordinates, and it reads from the same dimension as the region reader. The source caches region files within its configured limits; external payloads are read on demand without retaining them. A missing external file is a chunk error and can be retried.

Source errors appear in failedChunks while other columns continue loading. Call await stream.retryFailedChunks() to retry them. Placement or unloading failures reject the update.

A failed placement group can have changed any of its columns. The streamer cleans the whole group before loading it again, and retains ownership if cleanup fails. An active placement finishes before eviction or disposal.

Call await world.placeChunks(columns) to replace already decoded columns together. The method validates and copies all column and section coordinates before mutation, preserves input order, and refreshes queued biomes, faces, fluids, saved lighting, and ambient occlusion after the group. If a column fails, later columns are skipped and applied changes refresh before the promise rejects. The first placement error takes precedence over a refresh error. The input's section data remains caller-owned; keep it unchanged until placement finishes.

Use await world.unloadChunkColumns([{ x: -1, z: 0 }, { x: 0, z: 0 }]) to remove several columns and refresh surviving faces, fluids, saved lighting, ambient occlusion, and biome colors together. Coordinates are absolute chunk columns. The method validates and copies the whole input before removal, ignores duplicates and missing columns, and refreshes surviving neighbors once.

The streamer groups obsolete columns and disposal cleanup through this method. Its world must provide unloadChunkColumns; MineRenderWorld provides it. A rejected bulk unload keeps its column ownership for retry and invalidates the group's loaded entries, because some columns may already have been removed. The next update finishes that cleanup before loading the latest requested area.

Await stream.dispose() before editing or clearing the world; it unloads its columns and leaves the world and source caller-owned.

Numeric and paletted Java chunks support gzip, zlib, LZ4, and uncompressed payloads, including external .mcc files. Pre-1.13 numeric chunks use the same block mappings as legacy schematics. Pass legacyMappings: { "id:metadata": "namespace:block[property=value]" } to AnvilParser.parse, AnvilParser.parseChunk, or AnvilWorldSource to override those mappings. Set lenient: true to try metadata 0 for unmapped numeric states and skip unknown IDs; malformed arrays still fail validation.

Numeric mappings do not reconstruct states that depend on neighbors or block-entity NBT, such as paired doors or bed colors. DataVersion migration remains unsupported.

Biomes, light, and ambient occlusion ​

Modern Anvil sections retain their biome palettes as 64 IDs in section.biomes, ordered by x + z * 4 + y * 16. Each sample covers 4×4×4 blocks. placeChunk copies these samples, including in air-only sections. Call world.getBiomeAt(x, y, z) with integer world block coordinates to read the saved ID, or undefined when biome data is absent. Block edits preserve samples; replacing or unloading the column removes its previous biome data.

World blocks use these samples for grass, foliage, dry foliage, and water colors in both rendering modes, including multiple water colors within a merged section. Biome definitions come from the selected version's data/<namespace>/worldgen/biome/ directory, with colors sampled from resource-pack colormaps or explicit biome effects. Grass colors include dark forest and swamp modifiers; swamp colors use world block coordinates. Waterlogged blocks keep separate model and water colors. Missing biome data or definitions retain preview colors; source errors reject placement. Older numeric Biomes arrays and world-seed-based biome sampling remain unsupported.

Await chunk.setBiomes(samples) to replace a section's samples and refresh its placed blocks, including tall-plant halves in the section above. Hidden blocks remain hidden. For standalone previews, pass biome and optional biomePosition: [x, y, z] to scene.addBlock; explicit tints still take precedence.

Set biomeBlendRadius together with sectionMeshing to an integer from 0 to 7 to smooth grass, foliage, dry-foliage, and water colors across biome borders. The radius is in blocks; 0 disables blending and is the default. Read it through world.biomeBlendRadius, or update loaded terrain without reloading the source:

ts
const world = new MineRenderWorld(renderer.scene, { sectionMeshing: true, biomeBlendRadius: 3 });
await world.placeChunk(chunk);
await world.setBiomeBlendRadius(0);

Blending averages colors over a horizontal square at the sampled block's height. It applies to section meshes; blocks that keep individual objects, such as block entities, keep unblended colors. It leaves getBiomeAt unchanged, honors explicit tints, and works with saved lighting and ambient occlusion. Missing neighbors, and neighbors whose biome fails to load, are excluded; a missing center biome or definition retains preview colors. Biome edits and column loading or unloading refresh only the neighboring cells whose color changes. Colors are cached and updated with terrain, with no per-frame averaging. Larger radii add update work.

Enable savedLighting together with sectionMeshing to shade blocks and fluids from imported light data:

ts
const world = new MineRenderWorld(renderer.scene, { sectionMeshing: true, savedLighting: true });
await world.placeChunk(chunk);
const light = world.getLightAt(x, y, z); // { block, sky }, each from 0 to 15, or undefined

Anvil sections retain packed BlockLight and SkyLight arrays in section.light, including light-only sections. Each channel has 2,048 bytes: the cell index is x + 16*z + 256*y, with the even cell in the low nibble. An omitted channel in a saved section is zero, and an absent section has unknown light. Above a column's highest saved sky-light array, sky light is 15, as in vanilla; a column without any sky-light array has none. placeChunk copies the arrays, and column replacement, unloading, or clearing removes them. getLightAt returns stored values even when the save marks them invalid. savedLighting without sectionMeshing throws.

Rendering uses the brighter of sky and block light with a neutral daylight brightness curve, multiplied by the existing face shading and biome colors. ambientLight, from 0 to 1 and 0 by default, sets a minimum brightness the way a dimension type's ambient_light does. Vanilla uses 0.1 for the Nether and 0.25 for the End. Boundary faces sample the adjacent cell; inset faces sample their own cell. Water and lava use the brighter of their cell and the cell above, or below for bottom faces. Loading or unloading adjacent columns refreshes these samples.

savedLighting defaults to false. When enabled, missing sections and lighting marked invalid by the save retain preview brightness. Modern saves without a lighting-validity flag count as invalid. Block edits and visibility changes preserve the saved samples without recalculating light. Light propagation, entity and block-entity lighting, and dimension-, weather-, or time-dependent lightmap colors are not applied.

Enable ambientOcclusion to darken block corners near opaque full-cube neighbors. It requires sectionMeshing and works with or without saved lighting:

ts
const world = new MineRenderWorld(renderer.scene, { sectionMeshing: true, ambientOcclusion: true });
await world.placeChunk(chunk);
await world.setAmbientOcclusion(false); // Rebuilds loaded terrain without reloading the source.

Ambient occlusion defaults to false; world.ambientOcclusion reports the setting. It shades axis-aligned faces on block boundaries and honors a model's ambientocclusion: false. Inset and non-axis-aligned faces keep their existing shading. Partial boundary faces interpolate full-face corners; this does not reproduce exact vanilla shading for partial shapes. Light-emitting blocks are not automatically exempt. Block edits, visibility changes, and chunk loading or unloading refresh affected corners, including across section boundaries. Fluids, entities, and block entities are unchanged.

Enabling ambient occlusion adds work during placement and geometry updates, with no extra per-frame rendering pass. Keep it disabled when load or edit performance matters more than corner shading.

Logging ​

MineRender prints warnings and errors to the console and hides debug and info messages. Each message starts with a tag that names the component that logged it, such as UVMapper or HostedAssetSource.

To change what is printed, set a default level and per-component overrides:

ts
import { Logging } from "minerender";

Logging.configure({
    level: "error",
    namespaces: { HostedAssetSource: "debug" },
});

Levels from most to least verbose are debug, info, warn, and error; silent prints nothing. configure changes only the settings you pass, and namespaces replaces earlier overrides. Chrome shows debug messages only when the console's Verbose level is enabled.

To change logging on a deployed page without changing its code, save a setting in the browser console and reload the page:

js
localStorage.setItem("minerender:log", "warn,HostedAssetSource=debug");

In Node, set the MINERENDER_LOG environment variable to the same text. The setting is a comma-separated list: a level on its own sets the default, and Name=level sets one component. MineRender reads it once, at its first log message, and it takes precedence over Logging.configure. Remove it with localStorage.removeItem("minerender:log") and reload. Pages in iframes with sandbox="allow-scripts" cannot read localStorage; open the embed URL in its own tab instead.

To send messages to your own logger, set a handler. It receives each message that passes the levels, without the tag. Call setHandler() without an argument to restore console output.

ts
Logging.setHandler((level, namespace, args) => {
    appLogger.log({ level, source: `minerender:${namespace}`, args });
});

Ownership and cleanup ​

Choose cleanup according to the resource you own:

ResourceCleanup behavior
Rendererstop() pauses rendering and frame callbacks. dispose() permanently releases renderer-owned resources, clears subscriptions, and detaches scene objects.
Scene objects and worldsDispose objects you own when finished. Use await world.clear() to release a world's block handles, section meshes, and owned entities. Renderer disposal does not replace this cleanup.
ControlsRenderer-created controls are disposed with the renderer. Dispose caller-created controls yourself.
SceneStatsDisplayCall dispose() separately to remove its timer and DOM elements.
Shared library servicesCall shutdown only when all MineRender work is finished. It stops shared queues and timers and clears in-memory caches; request shutdown is permanent.

Cached materials, textures, and geometry can be shared by several objects. Do not manually dispose a shared resource while another object still uses it.