BITMAPWIN SDK

Render any Land Forge payload (BWVX1 or BWVX2) in your own Three.js viewer as a single InstancedMesh. Need Blender or Unreal? Use DOWNLOAD .GLB in Land Forge.

// BWVXLoader.js — renders any BITMAP Land Forge payload (BWVX1 or BWVX2) in ONE draw call.
// Input: the base64 payload from an inscription (data-bwvx / metadata). MIT, no dependencies beyond three.
import * as THREE from "three";

export const BWVX_PALETTE = ["#5fa83a","#7a5634","#e3cf8f","#8a8a8a","#6d6d6d","#b8874a","#c79a5b","#a5462f","#f3c43b","#bfe8f5","#ffd27a"];

export function bwvxBoxes(b64) {
  let raw;
  try { raw = atob(b64); } catch { throw new Error("BWVX: payload is not valid base64"); }
  const b = Uint8Array.from(raw, (c) => c.charCodeAt(0));
  const v2 = b[0] === 66 && b[1] === 87 && b[2] === 50 && b[3] === 0;   // "BW2\0": greedy boxes, 7 bytes each; else BWVX1, 4 bytes per voxel
  const body = v2 ? b.length - 4 : b.length, stride = v2 ? 7 : 4;
  if (body <= 0 || body % stride !== 0) throw new Error("BWVX: truncated payload");
  const out = [];
  for (let i = v2 ? 4 : 0; i < b.length; i += stride) {
    const box = v2 ? [b[i], b[i+1], b[i+2], b[i+3], b[i+4], b[i+5], b[i+6]] : [b[i], b[i+1], b[i+2], b[i], b[i+1], b[i+2], b[i+3]];
    if (box[3] < box[0] || box[4] < box[1] || box[5] < box[2]) throw new Error("BWVX: reversed box bounds at byte " + i);
    if (box[6] >= BWVX_PALETTE.length) throw new Error("BWVX: invalid palette index " + box[6] + " at byte " + i);
    out.push(box);
  }
  return out; // [x0, y0, z0, x1, y1, z1, kindIndex] inclusive, y is up
}

export function loadBWVX(b64, { blockSize = 1 } = {}) {
  const boxes = bwvxBoxes(b64);
  const mesh = new THREE.InstancedMesh(
    new THREE.BoxGeometry(1, 1, 1),
    new THREE.MeshStandardMaterial({ roughness: 0.75 }),
    boxes.length,
  );
  const m = new THREE.Matrix4(), p = new THREE.Vector3(), q = new THREE.Quaternion(), s = new THREE.Vector3();
  const colors = BWVX_PALETTE.map((h) => new THREE.Color(h));
  boxes.forEach(([x0, y0, z0, x1, y1, z1, k], i) => {
    const sx = x1 - x0 + 1, sy = y1 - y0 + 1, sz = z1 - z0 + 1;
    p.set((x0 + sx / 2) * blockSize, (y0 + sy / 2) * blockSize, (z0 + sz / 2) * blockSize);
    s.set(sx * blockSize, sy * blockSize, sz * blockSize);
    mesh.setMatrixAt(i, m.compose(p, q, s));
    mesh.setColorAt(i, colors[k]);
  });
  mesh.instanceMatrix.needsUpdate = true;
  if (mesh.instanceColor) mesh.instanceColor.needsUpdate = true;
  mesh.computeBoundingSphere();
  return mesh; // add to your scene: scene.add(loadBWVX(payload))
}

// Safe viewer swap: always removes the previous build first, so a bad payload never leaves stale geometry.
export function showBWVX(scene, b64, prev, opts) {
  if (prev) { scene.remove(prev); prev.geometry.dispose(); prev.material.dispose(); }
  try { const mesh = loadBWVX(b64, opts); scene.add(mesh); return { mesh, error: null }; }
  catch (e) { return { mesh: null, error: String((e && e.message) || e) }; }
}

INTEROPERABILITY — USING EXPORTS ELSEWHERE

Land Forge and the Colony build proposals export the same build three ways. Each export stays one mesh, so it draws in one draw call.

.BWVX · COORDINATES

Raw BWVX2 bytes: a "BW2\0" header, then 7-byte boxes (x0 y0 z0 x1 y1 z1 kind), with inclusive bounds and y pointing up. One unit is one block on the 64-block canvas. Exported files keep their canvas positions. When a file is imported into Land Forge, it is shifted so its lowest corner sits at 0,0,0; the shape is unchanged and you choose where to place it. Base64 text of the same bytes is also accepted.

.GLB · COLOURS

glTF 2.0 binary file: one node, one mesh and one primitive with POSITION, NORMAL and COLOR_0. The colours are vertex colours in linear RGB, taken from each block's top colour in the Forge palette. There are no textures or UVs, and the material is standard with roughness 0.75. One unit is one block.

THREE.JS LOADER · DEPENDENCIES

Needs only three as an ES module (tested with r185) and the browser's atob. It returns one InstancedMesh with one instance per box. "Copy Three.js loader" in Colony adds a ready-made PAYLOAD export: scene.add(loadBWVX(PAYLOAD)). Use showBWVX to swap builds safely.

OTHER ENGINES

Blender: File → Import → glTF 2.0. To see the colours, set the material's Base Color to a Color Attribute node. Unreal: import the .glb with the Interchange importer, then multiply Vertex Color into Base Color. Godot: drag the .glb into the project and turn on Vertex Color → Use as Albedo. Unity: use glTFast, with a shader that reads vertex colour. Babylon.js / web: load the .glb with any glTF loader. Bitcoin: inscribe .bwvx data as the build payload. Land Forge and the Oasis read it directly.

LAND PERMISSIONS

Every extender declares what it needs on a tile. An owner grants rights explicitly; a deployment is refused when the live chain says the caller has none.

• VIEW
• ENTER
• BUILD
• EDIT
• DEPLOY
• MANAGE
• LEASE
• MONETIZE