Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
// Collaborative voxel building for Coin Communities — the Minecraft layer.
//
// Every /play world is a shared, persistent place; this module lets the people
// in it BUILD that place. Players place and break 1.5m blocks on a grid; the
// server (WalkRoom) is authoritative and persists the result per coin, so a
// community's creation is there when they come back and there for everyone who
// drops in. Two coins never share a build — it rides on the same per-mint room
// isolation the avatars and chat already use.
//
// This file owns three things, kept deliberately separate from the scene:
// 1. The block palette (BLOCK_TYPES) + grid maths, shared with the server's
// validation (the caps here MUST mirror WalkRoom's).
// 2. VoxelWorld — instanced rendering of the whole build (one InstancedMesh
// per block type so a few thousand blocks stay a handful of draw calls),
// plus raycasting (what cell is the player aiming at?) and a ghost cursor.
// 3. createBuildHud — the self-contained build HUD (hotbar, mode toggle), so
// the build UI never has to thread through the rest of the chrome.
import {
Object3D, Vector3, Color, BoxGeometry, EdgesGeometry,
InstancedMesh, LineSegments, LineBasicMaterial, Mesh,
MeshStandardMaterial, MeshBasicMaterial, DynamicDrawUsage, Group,
} from 'three';
// Metres per grid cell. Sized so a stack of three reads as "wall height" next to
// a ~1.7m avatar — substantial to build with, without thousands of tiny cubes.
export const BLOCK = 1.5;
// Build bounds — a circular area on the plaza and a height ceiling, in cells.
// These mirror WalkRoom's MAX_GRID_XZ / MAX_GRID_Y exactly; the server rejects
// anything outside them, so keeping them in sync keeps the client honest.
export const MAX_GRID_XZ = 30;
export const MAX_GRID_Y = 24;
export const MAX_BLOCKS = 6000;
// The palette. Index === the wire type the server validates against, so order is
// load-bearing — never reorder, only append (and bump BLOCK_TYPE_COUNT server
// side). `swatch` is the hotbar colour; `emissive`/`opacity`/`metalness` tune the
// in-world material so gold glints, neon glows, and glass reads as glass.
export const BLOCK_TYPES = [
{ name: 'Stone', color: 0x9aa0a8, swatch: '#9aa0a8', roughness: 0.95 },
{ name: 'Grass', color: 0x5cb24f, swatch: '#5cb24f', roughness: 1 },
{ name: 'Dirt', color: 0x8a5a36, swatch: '#8a5a36', roughness: 1 },
{ name: 'Wood', color: 0xb07f43, swatch: '#b07f43', roughness: 0.85 },
{ name: 'Brick', color: 0xb5483a, swatch: '#b5483a', roughness: 0.9 },
{ name: 'Snow', color: 0xeef3f8, swatch: '#eef3f8', roughness: 0.8 },
{ name: 'Glass', color: 0xbfe6ff, swatch: '#bfe6ff', roughness: 0.1, opacity: 0.4, metalness: 0.1 },
{ name: 'Obsidian', color: 0x15171d, swatch: '#15171d', roughness: 0.4, metalness: 0.3 },
{ name: 'Gold', color: 0xffce5c, swatch: '#ffce5c', roughness: 0.3, metalness: 0.7, emissive: 0x3a2e00, emissiveIntensity: 0.35 },
{ name: 'Neon', color: 0x2af0e0, swatch: '#2af0e0', roughness: 0.3, emissive: 0x2af0e0, emissiveIntensity: 0.85 },
];
export const BLOCK_TYPE_COUNT = BLOCK_TYPES.length;
// Composite pieces — ready-made structures placed as a single unit so a builder
// can stamp a wall or a flight of stairs in one click instead of stacking dozens
// of blocks by hand. Each piece is a list of cells in its own LOCAL frame (before
// rotation): `dx`/`dz` are the horizontal footprint (rotated in 90° steps about
// the anchor), `dy` is height (rotation-invariant), and an optional `t` pins a
// block type — omit it and the cell inherits the player's selected palette block.
// The anchor cell (where the ghost is aimed) is the piece's near-bottom corner,
// so a piece grows up-and-forward from the cursor. The whole stamp goes through
// the SAME server-authoritative block channel as single placements (a batch of
// validated cells), so there's no second build path to keep honest.
export const COMPOSITE_PIECES = [
{
id: 'wall', name: 'Wall', icon: '▯',
// 4 wide × 3 tall slab, one cell deep.
cells() {
const out = [];
for (let dx = 0; dx < 4; dx++) for (let dy = 0; dy < 3; dy++) out.push({ dx, dy, dz: 0 });
return out;
},
},
{
id: 'floor', name: 'Floor', icon: '▦',
// 4 × 4 flat slab — a platform or roof tile.
cells() {
const out = [];
for (let dx = 0; dx < 4; dx++) for (let dz = 0; dz < 4; dz++) out.push({ dx, dy: 0, dz });
return out;
},
},
{
id: 'ramp', name: 'Stairs', icon: '◢',
// A 4-step staircase climbing along +dx, 2 cells wide, solid underneath so
// it's walkable both as a ramp and as a viewing stand.
cells() {
const out = [];
for (let step = 0; step < 4; step++) {
for (let dy = 0; dy <= step; dy++) for (let dz = 0; dz < 2; dz++) out.push({ dx: step, dy, dz });
}
return out;
},
},
{
id: 'door', name: 'Doorway', icon: '🚪',
// A 3 × 3 wall with a 1-wide, 2-tall opening punched in the middle.
cells() {
const out = [];
for (let dx = 0; dx < 3; dx++) for (let dy = 0; dy < 3; dy++) {
if (dx === 1 && dy < 2) continue; // the doorway
out.push({ dx, dy, dz: 0 });
}
return out;
},
},
];
// The largest stamp any piece produces — the server caps a batch at this so a
// crafted client can't smuggle a giant write through the composite channel, and
// the footprint-ghost instance pool is sized to it.
export const MAX_COMPOSITE_CELLS = COMPOSITE_PIECES.reduce((m, p) => Math.max(m, p.cells().length), 0);
const _dummy = new Object3D();
export function keyOf(gx, gy, gz) { return `${gx},${gy},${gz}`; }
export function parseKey(key) { const p = key.split(','); return [+p[0], +p[1], +p[2]]; }
// Rotate a horizontal footprint offset by a quarter-turn step (0–3 = 0/90/180/270°)
// about the anchor. Integer-only so a rotated piece stays perfectly grid-aligned.
export function rotateXZ(dx, dz, rot) {
// `|| 0` folds negative zero (e.g. -dx when dx===0) back to +0 so rotated
// offsets compare cleanly and never key a cell as "-0".
switch (((rot % 4) + 4) % 4) {
case 1: return [dz || 0, -dx || 0];
case 2: return [-dx || 0, -dz || 0];
case 3: return [-dz || 0, dx || 0];
default: return [dx || 0, dz || 0];
}
}
// Resolve a composite piece to absolute world cells for a given anchor, rotation,
// and selected block type. Each cell is `{ x, y, z, t }` ready for the place/batch
// channel. Returns [] for an unknown piece id so callers can treat it as a no-op.
export function compositeCells(pieceId, anchor, rot, type) {
const piece = COMPOSITE_PIECES.find((p) => p.id === pieceId);
if (!piece || !anchor) return [];
return piece.cells().map(({ dx, dy, dz, t }) => {
const [rx, rz] = rotateXZ(dx, dz, rot);
return { x: anchor[0] + rx, y: anchor[1] + dy, z: anchor[2] + rz, t: t == null ? type : t };
});
}
// Centre of a grid cell in world space. y is offset by half a block so gy=0 sits
// flush on the ground plane (its base at y=0, top at y=BLOCK).
export function cellToWorld(gx, gy, gz, target = new Vector3()) {
return target.set(gx * BLOCK, gy * BLOCK + BLOCK / 2, gz * BLOCK);
}
// Is a cell inside the legal build volume? Mirrors the server's _cellKey checks.
export function cellInBounds(gx, gy, gz) {
if (!Number.isInteger(gx) || !Number.isInteger(gy) || !Number.isInteger(gz)) return false;
if (gy < 0 || gy >= MAX_GRID_Y) return false;
return Math.hypot(gx, gz) <= MAX_GRID_XZ;
}
function makeMaterial(def) {
const opts = {
color: def.color,
roughness: def.roughness ?? 0.9,
metalness: def.metalness ?? 0,
};
if (def.emissive !== undefined) { opts.emissive = def.emissive; opts.emissiveIntensity = def.emissiveIntensity ?? 0.4; }
if (def.opacity !== undefined) { opts.transparent = true; opts.opacity = def.opacity; }
return new MeshStandardMaterial(opts);
}
// One InstancedMesh per block type, grown in powers of two as the build expands.
// Instance index ↔ key is kept in `keys[]`; removal swap-pops the last instance
// into the freed slot and reports the moved key so the owner can fix its index.
class TypeBatch {
constructor(scene, geometry, material, type) {
this.scene = scene;
this.geometry = geometry;
this.material = material;
this.type = type;
this.keys = [];
this.capacity = 0;
this.mesh = null;
}
_alloc(cap) {
const m = new InstancedMesh(this.geometry, this.material, cap);
m.castShadow = true;
m.receiveShadow = true;
m.frustumCulled = false; // a build can sprawl past the avatar-fit bounds
m.instanceMatrix.setUsage(DynamicDrawUsage);
m.userData.voxelType = this.type; // raycast hit → which palette batch
m.count = this.keys.length;
return m;
}
_ensure(n) {
if (this.mesh && n <= this.capacity) return;
const cap = Math.max(64, 1 << Math.ceil(Math.log2(Math.max(1, n))));
const next = this._alloc(cap);
this.capacity = cap;
if (this.mesh) { this.scene.remove(this.mesh); this.mesh.dispose(); }
this.mesh = next;
this.scene.add(this.mesh);
this._writeAll();
}
_writeOne(i) {
const [gx, gy, gz] = parseKey(this.keys[i]);
cellToWorld(gx, gy, gz, _dummy.position);
_dummy.rotation.set(0, 0, 0);
_dummy.scale.setScalar(1);
_dummy.updateMatrix();
this.mesh.setMatrixAt(i, _dummy.matrix);
}
_writeAll() {
for (let i = 0; i < this.keys.length; i++) this._writeOne(i);
this.mesh.count = this.keys.length;
this.mesh.instanceMatrix.needsUpdate = true;
}
add(key) {
const i = this.keys.length;
this.keys.push(key);
this._ensure(this.keys.length); // may rewrite all; cheap at human pace
this._writeOne(i);
this.mesh.count = this.keys.length;
this.mesh.instanceMatrix.needsUpdate = true;
return i;
}
// Remove instance i. Returns the key swapped into slot i (or null if i was
// last), so the VoxelWorld index can be repaired in O(1).
removeAt(i) {
const last = this.keys.length - 1;
let moved = null;
if (i !== last) {
this.keys[i] = this.keys[last];
this._writeOne(i);
moved = this.keys[i];
}
this.keys.pop();
this.mesh.count = this.keys.length;
this.mesh.instanceMatrix.needsUpdate = true;
return moved;
}
dispose() {
if (this.mesh) { this.scene.remove(this.mesh); this.mesh.dispose(); this.mesh = null; }
this.material.dispose();
}
}
export class VoxelWorld {
constructor(scene) {
this.scene = scene;
this.geometry = new BoxGeometry(BLOCK, BLOCK, BLOCK);
this.batches = BLOCK_TYPES.map((def, i) => new TypeBatch(scene, this.geometry, makeMaterial(def), i));
this.index = new Map(); // key → { type, i }
this._meshes = []; // refreshed lazily for raycasting
this._buildGhost();
this._buildFootprintGhost();
}
get count() { return this.index.size; }
hasBlock(key) { return this.index.has(key); }
// Palette type at a cell, or -1 if empty. Lets a break record what it removed
// so undo can restore the exact block.
typeAt(gx, gy, gz) { const e = this.index.get(keyOf(gx, gy, gz)); return e ? e.type : -1; }
// Add or repaint a block. Idempotent for an unchanged (key,type).
setBlock(gx, gy, gz, type) {
if (type < 0 || type >= this.batches.length) return;
const key = keyOf(gx, gy, gz);
const cur = this.index.get(key);
if (cur) {
if (cur.type === type) return;
this._removeKey(key); // repaint = remove from old batch, add to new
}
const i = this.batches[type].add(key);
this.index.set(key, { type, i });
}
removeBlock(gx, gy, gz) { this._removeKey(keyOf(gx, gy, gz)); }
_removeKey(key) {
const entry = this.index.get(key);
if (!entry) return;
const moved = this.batches[entry.type].removeAt(entry.i);
this.index.delete(key);
// The swap-popped block now lives at the freed slot — fix its stored index.
if (moved) {
const m = this.index.get(moved);
if (m) m.i = entry.i;
}
}
clear() {
for (const b of this.batches) { while (b.keys.length) b.removeAt(b.keys.length - 1); }
this.index.clear();
}
// What cell is the camera ray aiming at? Returns the hit block's cell (for
// breaking), the adjacent empty cell along the hit face (for placing), and
// whether that placement cell is in bounds. Falls back to the ground plane so
// the very first block has somewhere to land.
raycast(raycaster) {
this._meshes.length = 0;
for (const b of this.batches) if (b.mesh && b.mesh.count > 0) this._meshes.push(b.mesh);
const hits = raycaster.intersectObjects(this._meshes, false);
const blockHit = hits.find((h) => h.instanceId != null);
// Ground-plane (y=0) intersection, computed analytically so we don't need a
// raycastable floor object competing with the real plaza mesh.
const ground = this._groundCell(raycaster);
if (blockHit && (!ground || blockHit.distance <= ground.distance)) {
const batch = this.batches[blockHit.object.userData.voxelType];
const key = batch?.keys[blockHit.instanceId];
if (key) {
const [gx, gy, gz] = parseKey(key);
const n = blockHit.face?.normal || { x: 0, y: 1, z: 0 };
const place = [gx + Math.round(n.x), gy + Math.round(n.y), gz + Math.round(n.z)];
return {
hit: 'block',
cell: [gx, gy, gz],
placeCell: place,
placeValid: cellInBounds(place[0], place[1], place[2]) && !this.index.has(keyOf(...place)),
};
}
}
if (ground) {
return {
hit: 'ground',
cell: null,
placeCell: ground.cell,
placeValid: cellInBounds(...ground.cell) && !this.index.has(keyOf(...ground.cell)),
};
}
return null;
}
_groundCell(raycaster) {
const { origin, direction } = raycaster.ray;
if (direction.y >= -1e-4) return null; // looking up / parallel — no floor hit
const t = -origin.y / direction.y;
if (t <= 0) return null;
const px = origin.x + direction.x * t;
const pz = origin.z + direction.z * t;
const gx = Math.round(px / BLOCK);
const gz = Math.round(pz / BLOCK);
return { cell: [gx, 0, gz], distance: t * direction.length() };
}
// --- Ghost cursor ------------------------------------------------------
_buildGhost() {
const g = new Group();
g.visible = false;
// Slightly inflated so the wireframe rides just outside whatever it marks.
const box = new BoxGeometry(BLOCK * 1.02, BLOCK * 1.02, BLOCK * 1.02);
this._ghostFill = new Mesh(box, new MeshBasicMaterial({ transparent: true, opacity: 0.16, depthWrite: false }));
this._ghostEdges = new LineSegments(new EdgesGeometry(box), new LineBasicMaterial({ transparent: true, opacity: 0.9 }));
g.add(this._ghostFill, this._ghostEdges);
this.scene.add(g);
this._ghost = g;
this._ghostColor = new Color();
}
// Show the cursor at a cell, tinted by intent: green = will place, red = will
// break, amber = blocked (out of bounds / occupied).
showGhost(cell, kind) {
if (!cell) { this.hideGhost(); return; }
cellToWorld(cell[0], cell[1], cell[2], this._ghost.position);
const hex = kind === 'remove' ? 0xff5a5a : kind === 'blocked' ? 0xffb648 : 0x66ff8c;
this._ghostColor.setHex(hex);
this._ghostFill.material.color.copy(this._ghostColor);
this._ghostEdges.material.color.copy(this._ghostColor);
this._ghost.visible = true;
}
hideGhost() { if (this._ghost) this._ghost.visible = false; }
// --- Composite footprint ghost ----------------------------------------
// A single InstancedMesh previewing every cell a composite piece would place,
// so a wall or staircase shows its full shape (and rotation) before you commit.
// One draw call regardless of piece size — it never competes with the build's
// own instanced batches for performance.
_buildFootprintGhost() {
const box = new BoxGeometry(BLOCK * 1.02, BLOCK * 1.02, BLOCK * 1.02);
this._fpGeom = box;
this._fpMat = new MeshBasicMaterial({ transparent: true, opacity: 0.22, depthWrite: false });
const m = new InstancedMesh(box, this._fpMat, MAX_COMPOSITE_CELLS);
m.frustumCulled = false;
m.count = 0;
m.visible = false;
this.scene.add(m);
this._fpGhost = m;
this._fpColor = new Color();
}
// Preview a composite piece's cells, tinted by whether the whole stamp can
// land (green) or is blocked (amber). Hides the single-cell ghost so the two
// cursors never overlap.
showFootprint(cells, valid) {
this.hideGhost();
if (!cells || cells.length === 0) { this.hideFootprint(); return; }
const n = Math.min(cells.length, MAX_COMPOSITE_CELLS);
for (let i = 0; i < n; i++) {
cellToWorld(cells[i].x, cells[i].y, cells[i].z, _dummy.position);
_dummy.rotation.set(0, 0, 0);
_dummy.scale.setScalar(1);
_dummy.updateMatrix();
this._fpGhost.setMatrixAt(i, _dummy.matrix);
}
this._fpGhost.count = n;
this._fpGhost.instanceMatrix.needsUpdate = true;
this._fpColor.setHex(valid ? 0x66ff8c : 0xffb648);
this._fpMat.color.copy(this._fpColor);
this._fpGhost.visible = true;
}
hideFootprint() { if (this._fpGhost) { this._fpGhost.visible = false; this._fpGhost.count = 0; } }
// True only when every cell of a proposed stamp is in bounds, empty, and the
// build has room for all of them under the block budget. Used to tint the
// footprint ghost and to gate a composite placement client-side.
canPlaceAll(cells, maxBlocks = Infinity) {
if (!cells || cells.length === 0) return false;
let fresh = 0;
const seen = new Set();
for (const c of cells) {
if (!cellInBounds(c.x, c.y, c.z)) return false;
const key = keyOf(c.x, c.y, c.z);
if (seen.has(key)) continue; // a piece never repeats a cell, but be safe
seen.add(key);
if (!this.index.has(key)) fresh++;
}
return this.count + fresh <= maxBlocks;
}
dispose() {
this.hideGhost();
this.hideFootprint();
this.scene.remove(this._ghost);
this._ghostFill.geometry.dispose(); this._ghostFill.material.dispose();
this._ghostEdges.geometry.dispose(); this._ghostEdges.material.dispose();
this.scene.remove(this._fpGhost);
this._fpGeom.dispose(); this._fpMat.dispose();
for (const b of this.batches) b.dispose();
this.geometry.dispose();
this.index.clear();
}
}
// --- Build HUD -------------------------------------------------------------
// A self-contained DOM control: a hotbar of the palette (1–0 / click to pick), a
// place/break mode toggle, and an enable toggle. Returned controller lets the
// scene drive selection from keys and reflect connection state. Kept here so the
// build feature owns its own chrome end-to-end.
export function createBuildHud({ onToggle, onPick, onModeChange, onClearArea }) {
const el = (tag, props = {}, kids = []) => {
const n = document.createElement(tag);
for (const [k, v] of Object.entries(props)) {
if (k === 'class') n.className = v;
else if (k === 'text') n.textContent = v;
else if (k.startsWith('on') && typeof v === 'function') n.addEventListener(k.slice(2), v);
else if (v != null && v !== false) n.setAttribute(k, v === true ? '' : v);
}
for (const kid of [].concat(kids)) if (kid != null) n.appendChild(typeof kid === 'string' ? document.createTextNode(kid) : kid);
return n;
};
let active = false;
let mode = 'place';
const toggleBtn = el('button', {
class: 'cc-build-toggle', type: 'button', title: 'Build mode (B)', 'aria-pressed': 'false',
onclick: () => setActive(!active),
}, [el('span', { class: 'cc-build-toggle-ico', text: '⛏' }), el('span', { class: 'cc-build-toggle-text', text: 'Build' })]);
const slots = BLOCK_TYPES.map((def, i) => {
const slot = el('button', {
class: 'cc-build-slot' + (i === 0 ? ' cc-on' : ''), type: 'button',
title: `${def.name} (${(i + 1) % 10})`, 'aria-label': def.name,
onclick: () => pick(i),
}, [
el('span', { class: 'cc-build-swatch', style: `background:${def.swatch}` }),
el('span', { class: 'cc-build-key', text: String((i + 1) % 10) }),
]);
return slot;
});
const hotbar = el('div', { class: 'cc-build-hotbar', role: 'toolbar', 'aria-label': 'Block palette' }, slots);
const modeBtn = el('button', {
class: 'cc-build-mode', type: 'button', title: 'Toggle place / break (right-click also breaks)',
onclick: () => setMode(mode === 'place' ? 'remove' : 'place'),
}, [el('span', { class: 'cc-build-mode-ico', text: '▦' }), el('span', { class: 'cc-build-mode-text', text: 'Place' })]);
// Touch has no right-click; long-press breaks, and the mode toggle is the
// explicit path. Tailor the hint so phone players aren't told to "right-click".
const touch = typeof matchMedia === 'function' && matchMedia('(hover: none), (pointer: coarse)').matches;
const hint = el('div', {
class: 'cc-build-hint',
text: touch
? 'Tap to place · long-press to break · pick a block above'
: 'Click to place · right-click to break · 1–0 pick block',
});
// Live block-budget meter. The build is hard-capped per world (MAX_BLOCKS);
// without this the cap is a silent wall — a builder hits 6000 and blocks just
// stop appearing. The fill bar warms to amber, then red, as the world fills.
const budgetFill = el('span', { class: 'cc-build-budget-fill' });
const budgetText = el('span', { class: 'cc-build-budget-text', text: `0 / ${MAX_BLOCKS}` });
const budget = el('div', {
class: 'cc-build-budget', role: 'status', 'aria-label': 'Blocks used',
title: `Blocks placed in this world (max ${MAX_BLOCKS})`,
}, [el('span', { class: 'cc-build-budget-bar' }, [budgetFill]), budgetText]);
// Durability badge: tells builders, honestly, whether this world's creation is
// saved for keeps (Redis) or only for the life of the server process.
const durBadge = el('div', { class: 'cc-build-durability', role: 'status', hidden: true });
// Per-player allowance (R19): how many blocks YOU own here vs your personal cap,
// separate from the world budget above. Hidden until the server reports a cap, so
// a solo (offline) build — which has no per-player limit — never shows it.
const mineFill = el('span', { class: 'cc-build-mine-fill' });
const mineText = el('span', { class: 'cc-build-mine-text', text: '' });
const mine = el('div', {
class: 'cc-build-mine', role: 'status', 'aria-label': 'Your blocks', hidden: true,
title: 'Blocks you have placed in this world (your personal cap)',
}, [el('span', { class: 'cc-build-mine-bar' }, [mineFill]), mineText]);
// Creator moderation (R19): the coin's creator can wipe griefed builds. Hidden for
// everyone else; the server is the real authority, so revealing it is purely a UI
// affordance — a non-creator's request is refused server-side regardless.
const clearAreaBtn = el('button', {
class: 'cc-build-mod-btn', type: 'button',
title: 'Clear the blocks around where you stand',
onclick: () => onClearArea?.('area'),
}, ['Clear nearby']);
const clearAllBtn = el('button', {
class: 'cc-build-mod-btn cc-danger', type: 'button',
title: 'Clear every block in this world',
onclick: () => onClearArea?.('all'),
}, ['Clear all']);
const modRow = el('div', { class: 'cc-build-mod', hidden: true }, [
el('span', { class: 'cc-build-mod-tag', text: '★ Creator' }),
clearAreaBtn, clearAllBtn,
]);
const panel = el('div', { class: 'cc-build-panel', hidden: true }, [modeBtn, hotbar, budget, mine, durBadge, modRow, hint]);
const root = el('div', { id: 'cc-build', class: 'cc-build' }, [toggleBtn, panel]);
document.body.appendChild(root);
function pick(i) {
for (let k = 0; k < slots.length; k++) slots[k].classList.toggle('cc-on', k === i);
onPick?.(i);
}
function setMode(m) {
mode = m;
modeBtn.classList.toggle('cc-removing', m === 'remove');
modeBtn.querySelector('.cc-build-mode-text').textContent = m === 'remove' ? 'Break' : 'Place';
modeBtn.querySelector('.cc-build-mode-ico').textContent = m === 'remove' ? '✖' : '▦';
onModeChange?.(m);
}
function setActive(v) {
active = v;
root.classList.toggle('cc-build-on', v);
toggleBtn.classList.toggle('cc-on', v);
toggleBtn.setAttribute('aria-pressed', String(v));
panel.hidden = !v;
onToggle?.(v);
}
return {
root,
get active() { return active; },
get mode() { return mode; },
setActive,
setMode,
select: pick,
// Disable the whole control when there's no live connection to build into.
setEnabled(enabled, reason) {
toggleBtn.disabled = !enabled;
toggleBtn.title = enabled ? 'Build mode (B)' : (reason || 'Building needs a live connection');
if (!enabled && active) setActive(false);
},
// Reflect how full the world's block budget is. Warms the bar (amber ≥80%,
// red when full) and flags the panel so place actions can read "full".
setBudget(used, max = MAX_BLOCKS) {
const u = Math.max(0, Math.min(used | 0, max));
const pct = max > 0 ? u / max : 0;
budgetFill.style.transform = `scaleX(${pct})`;
budgetText.textContent = `${u.toLocaleString()} / ${max.toLocaleString()}`;
const full = u >= max;
budget.classList.toggle('cc-warn', pct >= 0.8 && !full);
budget.classList.toggle('cc-full', full);
root.classList.toggle('cc-build-full', full);
},
// Show whether this world's build survives a server restart. Online only —
// solo single-player builds aren't persisted at all (passing null hides it).
setPersistent(durable) {
if (durable == null) { durBadge.hidden = true; return; }
durBadge.hidden = false;
durBadge.classList.toggle('cc-durable', !!durable);
durBadge.textContent = durable ? '✓ Saved for everyone' : '⚠ This session only';
durBadge.title = durable
? 'This world is saved to durable storage — your build is here when you return.'
: 'Durable storage is unavailable — this build lives only until the server restarts.';
},
// Per-player allowance meter. used/cap come from the server's build-perms
// snapshot; passing a falsy cap (solo build) hides the meter entirely.
setUsage(used, cap) {
if (!cap || cap <= 0) { mine.hidden = true; return; }
const u = Math.max(0, Math.min(used | 0, cap));
const pct = u / cap;
mineFill.style.transform = `scaleX(${pct})`;
mineText.textContent = `You: ${u.toLocaleString()} / ${cap.toLocaleString()}`;
mine.hidden = false;
mine.classList.toggle('cc-warn', pct >= 0.8 && u < cap);
mine.classList.toggle('cc-full', u >= cap);
},
// Reveal the creator-only moderation controls. Server-enforced — this only
// surfaces the affordance to the coin's creator.
setCreator(isCreator) { modRow.hidden = !isCreator; },
dispose() { root.remove(); },
};
}