Skip to content

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.

9.7 KB
Raw Blame
// Build (voxel) feature — grid math, VoxelWorld instanced-batch integrity, and
// client↔server constant parity. These are the load-bearing invariants behind
// /play's collaborative building: the swap-pop index repair must never desync a
// rendered instance from its grid key, and the client's bounds/budget caps must
// mirror the server's exactly (drift = blocks the client lets you place that the
// server silently rejects).

import { describe, it, expect } from 'vitest';
import { readFileSync } from 'node:fs';
import { fileURLToPath } from 'node:url';
import { dirname, resolve } from 'node:path';

// three's instanced meshes touch a couple of browser globals on import in some
// builds; mirror the polyfill the other three-using tests use.
globalThis.self = globalThis;

import {
	VoxelWorld, keyOf, parseKey, cellToWorld, cellInBounds,
	BLOCK, MAX_GRID_XZ, MAX_GRID_Y, MAX_BLOCKS, BLOCK_TYPE_COUNT, BLOCK_TYPES,
	COMPOSITE_PIECES, MAX_COMPOSITE_CELLS, rotateXZ, compositeCells,
} from '../src/game/build-voxels.js';

const __dirname = dirname(fileURLToPath(import.meta.url));
const ROOT = resolve(__dirname, '..');

// A minimal stand-in for a three.Scene — VoxelWorld only ever add()/remove()s.
function fakeScene() {
	const children = new Set();
	return { add: (o) => children.add(o), remove: (o) => children.delete(o), children };
}

// The core invariant: for every key the world knows about, the batch slot it
// points at must actually hold that key, and the InstancedMesh's live instance
// count must equal the number of keys in that batch. If swap-pop ever fails to
// repair an index, this catches it.
function assertConsistent(world) {
	for (const [key, entry] of world.index) {
		const batch = world.batches[entry.type];
		expect(batch.keys[entry.i], `index for ${key} points at the right slot`).toBe(key);
	}
	for (const batch of world.batches) {
		const live = batch.mesh ? batch.mesh.count : 0;
		expect(live, `batch ${batch.type} instance count tracks key count`).toBe(batch.keys.length);
	}
	// Every key appears exactly once across all batches.
	const all = world.batches.flatMap((b) => b.keys);
	expect(new Set(all).size).toBe(all.length);
	expect(all.length).toBe(world.index.size);
}

describe('grid math', () => {
	it('keyOf / parseKey round-trip including negatives', () => {
		for (const c of [[0, 0, 0], [1, 2, 3], [-5, 7, -12], [MAX_GRID_XZ, MAX_GRID_Y - 1, -MAX_GRID_XZ]]) {
			expect(parseKey(keyOf(...c))).toEqual(c);
		}
	});

	it('cellToWorld lands gy=0 flush on the ground plane', () => {
		const v = cellToWorld(2, 0, -3);
		expect(v.x).toBeCloseTo(2 * BLOCK);
		expect(v.z).toBeCloseTo(-3 * BLOCK);
		// Base sits at y=0: centre is half a block up.
		expect(v.y).toBeCloseTo(BLOCK / 2);
		expect(cellToWorld(0, 1, 0).y).toBeCloseTo(BLOCK + BLOCK / 2);
	});

	it('cellInBounds enforces integers, the height ceiling, and the circular area', () => {
		expect(cellInBounds(0, 0, 0)).toBe(true);
		expect(cellInBounds(1.5, 0, 0)).toBe(false);          // non-integer
		expect(cellInBounds(0, -1, 0)).toBe(false);           // below the floor
		expect(cellInBounds(0, MAX_GRID_Y, 0)).toBe(false);   // at/over the ceiling
		expect(cellInBounds(0, MAX_GRID_Y - 1, 0)).toBe(true);
		expect(cellInBounds(MAX_GRID_XZ, 0, 0)).toBe(true);   // on the radius
		expect(cellInBounds(MAX_GRID_XZ, 0, MAX_GRID_XZ)).toBe(false); // corner is outside the circle
		expect(cellInBounds(MAX_GRID_XZ + 1, 0, 0)).toBe(false);
	});
});

describe('VoxelWorld', () => {
	it('places, repaints, and reports count/typeAt', () => {
		const w = new VoxelWorld(fakeScene());
		expect(w.count).toBe(0);
		w.setBlock(0, 0, 0, 1);
		w.setBlock(1, 0, 0, 4);
		expect(w.count).toBe(2);
		expect(w.typeAt(0, 0, 0)).toBe(1);
		expect(w.typeAt(9, 9, 9)).toBe(-1);
		assertConsistent(w);

		// Repaint moves the block between type batches without growing the world.
		w.setBlock(0, 0, 0, 7);
		expect(w.count).toBe(2);
		expect(w.typeAt(0, 0, 0)).toBe(7);
		expect(w.batches[1].keys).not.toContain('0,0,0');
		expect(w.batches[7].keys).toContain('0,0,0');
		assertConsistent(w);

		// Idempotent: setting the same type again is a no-op.
		w.setBlock(0, 0, 0, 7);
		expect(w.count).toBe(2);
		assertConsistent(w);
		w.dispose();
	});

	it('repairs the swap-pop index when removing from the middle of a batch', () => {
		const w = new VoxelWorld(fakeScene());
		// Three blocks of the same type → same batch, slots 0,1,2.
		w.setBlock(0, 0, 0, 2);
		w.setBlock(1, 0, 0, 2);
		w.setBlock(2, 0, 0, 2);
		// Remove the middle one: the last (2,0,0) must swap into slot 1.
		w.removeBlock(1, 0, 0);
		expect(w.count).toBe(2);
		expect(w.hasBlock('1,0,0')).toBe(false);
		expect(w.index.get('2,0,0').i).toBe(1); // swapped into the freed slot
		assertConsistent(w);
		// Removing the (now) moved block still leaves a consistent world.
		w.removeBlock(2, 0, 0);
		w.removeBlock(0, 0, 0);
		expect(w.count).toBe(0);
		assertConsistent(w);
		w.dispose();
	});

	it('survives a randomized place/remove/repaint churn with the invariant intact', () => {
		const w = new VoxelWorld(fakeScene());
		// Deterministic LCG so the test is reproducible without Math.random.
		let seed = 1234567;
		const rnd = () => (seed = (seed * 1103515245 + 12345) & 0x7fffffff) / 0x7fffffff;
		const live = new Map();
		for (let step = 0; step < 800; step++) {
			const gx = Math.floor(rnd() * 7) - 3;
			const gz = Math.floor(rnd() * 7) - 3;
			const gy = Math.floor(rnd() * 4);
			const key = keyOf(gx, gy, gz);
			if (rnd() < 0.5) {
				const t = Math.floor(rnd() * BLOCK_TYPE_COUNT);
				w.setBlock(gx, gy, gz, t);
				live.set(key, t);
			} else {
				w.removeBlock(gx, gy, gz);
				live.delete(key);
			}
		}
		expect(w.count).toBe(live.size);
		for (const [key, t] of live) expect(w.typeAt(...parseKey(key))).toBe(t);
		assertConsistent(w);
		w.dispose();
	});

	it('clear() empties every batch', () => {
		const w = new VoxelWorld(fakeScene());
		for (let i = 0; i < 20; i++) w.setBlock(i % 5, 0, Math.floor(i / 5), i % BLOCK_TYPE_COUNT);
		expect(w.count).toBe(20);
		w.clear();
		expect(w.count).toBe(0);
		assertConsistent(w);
		w.dispose();
	});

	it('ignores out-of-palette types defensively', () => {
		const w = new VoxelWorld(fakeScene());
		w.setBlock(0, 0, 0, -1);
		w.setBlock(0, 0, 0, BLOCK_TYPE_COUNT);
		expect(w.count).toBe(0);
		w.dispose();
	});
});

describe('composite pieces (R20)', () => {
	it('rotateXZ is a pure quarter-turn that round-trips after 4 steps', () => {
		expect(rotateXZ(1, 0, 0)).toEqual([1, 0]);
		expect(rotateXZ(1, 0, 1)).toEqual([0, -1]);
		expect(rotateXZ(1, 0, 2)).toEqual([-1, 0]);
		expect(rotateXZ(1, 0, 3)).toEqual([0, 1]);
		// Negative + wrapping rotations normalise to the same four orientations.
		expect(rotateXZ(2, 3, -1)).toEqual(rotateXZ(2, 3, 3));
		expect(rotateXZ(2, 3, 4)).toEqual([2, 3]);
	});

	it('every piece resolves to in-pool, integer, type-bearing cells', () => {
		for (const piece of COMPOSITE_PIECES) {
			const cells = compositeCells(piece.id, [5, 0, 5], 0, 3);
			expect(cells.length).toBeGreaterThan(0);
			expect(cells.length).toBeLessThanOrEqual(MAX_COMPOSITE_CELLS);
			for (const c of cells) {
				expect(Number.isInteger(c.x) && Number.isInteger(c.y) && Number.isInteger(c.z)).toBe(true);
				expect(c.t).toBe(3); // inherits the selected block type
			}
			// No piece repeats a cell within itself.
			const keys = new Set(cells.map((c) => keyOf(c.x, c.y, c.z)));
			expect(keys.size).toBe(cells.length);
		}
	});

	it('rotation preserves a piece\'s cell count and keeps it on the grid', () => {
		for (const piece of COMPOSITE_PIECES) {
			const base = compositeCells(piece.id, [0, 0, 0], 0, 0).length;
			for (let rot = 1; rot < 4; rot++) {
				expect(compositeCells(piece.id, [0, 0, 0], rot, 0).length).toBe(base);
			}
		}
	});

	it('an unknown piece id yields no cells (safe no-op)', () => {
		expect(compositeCells('nope', [0, 0, 0], 0, 0)).toEqual([]);
		expect(compositeCells('wall', null, 0, 0)).toEqual([]);
	});

	it('VoxelWorld.canPlaceAll gates on bounds, occupancy, and budget', () => {
		const w = new VoxelWorld(fakeScene());
		const cells = compositeCells('wall', [4, 0, 4], 0, 0);
		expect(w.canPlaceAll(cells, MAX_BLOCKS)).toBe(true);
		// Out of bounds (beyond the circular plaza) → rejected wholesale.
		expect(w.canPlaceAll(compositeCells('wall', [MAX_GRID_XZ + 5, 0, 0], 0, 0), MAX_BLOCKS)).toBe(false);
		// Budget that can't fit the fresh cells → rejected.
		expect(w.canPlaceAll(cells, 3)).toBe(false);
		// Already-occupied cells don't count against a fresh budget.
		for (const c of cells) w.setBlock(c.x, c.y, c.z, c.t);
		expect(w.canPlaceAll(cells, w.count)).toBe(true); // repaint-in-place fits exactly
		w.dispose();
	});
});

describe('client ↔ server constant parity', () => {
	// The server validates every edit against its own copies of these caps. If the
	// client's diverge, players get a build experience that lies (placeable cells
	// the server rejects, or a budget bar that disagrees with the real limit).
	const server = readFileSync(resolve(ROOT, 'multiplayer/src/rooms/WalkRoom.js'), 'utf8');
	const num = (name) => {
		const m = server.match(new RegExp(`const ${name}\\s*=\\s*(\\d+)`));
		expect(m, `${name} present in WalkRoom.js`).toBeTruthy();
		return Number(m[1]);
	};

	it('grid bounds, block budget, and palette size match WalkRoom', () => {
		expect(MAX_GRID_XZ).toBe(num('MAX_GRID_XZ'));
		expect(MAX_GRID_Y).toBe(num('MAX_GRID_Y'));
		expect(MAX_BLOCKS).toBe(num('MAX_BLOCKS'));
		expect(BLOCK_TYPE_COUNT).toBe(num('BLOCK_TYPE_COUNT'));
		expect(BLOCK_TYPES.length).toBe(BLOCK_TYPE_COUNT);
	});

	it('the largest composite piece fits the server\'s place-batch cap', () => {
		// The server rejects any batch larger than MAX_BATCH_CELLS, so the biggest
		// piece the client can stamp must never exceed it — else a legit piece would
		// be silently refused.
		expect(MAX_COMPOSITE_CELLS).toBeLessThanOrEqual(num('MAX_BATCH_CELLS'));
	});
});