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
// world-store — generic, durable per-world JSON persistence (T3).
//
// A "world" is any place that needs to remember its state across room disposal
// and server restarts: a coin's collaborative build, a realm's mutable layout, a
// gated world's pass roster. Each world is one JSON document addressed by an
// opaque `worldId` (e.g. a coin mint, "<mint>#holders", or a realm id).
//
// ── Storage split ────────────────────────────────────────────────────────────
// The roadmap calls for R2 for large blob docs and Postgres for indexed/queried
// data; this module honours that split per-document by size:
//
// • Postgres `world_docs` is ALWAYS the source of truth for the index row —
// etag, version, owner, timestamps — and is the single linearization point
// for optimistic concurrency. Small docs are stored inline (`inline_doc`
// jsonb) so the hot path is one indexed round-trip.
// • Docs past INLINE_MAX_BYTES are offloaded to R2 at a CONTENT-ADDRESSED key
// (`worlds/<id>/<etag>.json`). Because the key embeds the content hash,
// concurrent writers never clobber each other's bytes; the committed index
// row decides which blob is canonical. The previous blob is GC'd after a
// successful supersede.
//
// ── Optimistic concurrency ───────────────────────────────────────────────────
// `etag` is a content hash. A writer reads (gets an etag), mutates, and saves
// with `ifMatch: <that etag>`. If the stored etag has since changed, the
// conditional commit affects zero rows and we throw ConflictError (HTTP 409).
// • ifMatch omitted/null → "create": succeeds only if no row exists yet
// (a concurrent create surfaces as a conflict).
// • ifMatch === '*' → unconditional overwrite (last-writer-wins).
//
// ── Testability ──────────────────────────────────────────────────────────────
// All storage goes through a tiny BACKEND interface (readRow/readBlob/writeBlob/
// deleteBlob/upsert/remove). The default backend is Postgres + R2; tests inject
// an in-memory backend with the same compare-and-set contract. The CAS semantics
// live in the backend (it's an atomicity concern); the orchestration — size
// limits, hashing, inline/offload routing, blob GC, conflict mapping — lives in
// createWorldStore() and is exercised by the unit tests.
//
// ── Auth ─────────────────────────────────────────────────────────────────────
// Reads are public (worlds are shared, visible places). Writes go through
// canWriteWorld() — the permission hook T16 tightens. The authoritative game
// server writes as a service principal (always permitted); a browser session
// writes subject to ownership.
import { sql } from './db.js';
import { putObject, getObjectBuffer, deleteObject } from './r2.js';
import { createHash } from 'node:crypto';
export const SCHEMA_VERSION = 1;
// A whole world doc is capped so one save is one bounded write. Placed-object
// builds at the catalog's per-world object cap serialize well under this.
export const MAX_DOC_BYTES = 2 * 1024 * 1024; // 2 MB
// Below this a doc rides inline in Postgres; above it goes to R2.
export const INLINE_MAX_BYTES = 96 * 1024; // 96 KB
// worldId is used in an R2 object key and a primary key — keep it to a tight,
// path-safe alphabet (base58 mints, realm slugs, the "#holders" tier suffix).
const WORLD_ID_RE = /^[A-Za-z0-9:_#.-]{1,128}$/;
export class ConflictError extends Error {
constructor(message = 'world changed since last read') {
super(message);
this.name = 'ConflictError';
this.status = 409;
this.code = 'world_conflict';
}
}
export class TooLargeError extends Error {
constructor(message = 'world document exceeds size limit') {
super(message);
this.name = 'TooLargeError';
this.status = 413;
this.code = 'world_too_large';
}
}
export class PermissionError extends Error {
constructor(message = 'not permitted to write this world') {
super(message);
this.name = 'PermissionError';
this.status = 403;
this.code = 'forbidden';
}
}
export function isValidWorldId(worldId) {
return typeof worldId === 'string' && WORLD_ID_RE.test(worldId);
}
function assertWorldId(worldId) {
if (!isValidWorldId(worldId)) {
const e = new Error('invalid worldId');
e.status = 400;
e.code = 'validation_error';
throw e;
}
}
// Deterministic bytes for a doc. Stable enough that an unchanged doc hashes the
// same across saves, so a no-op save keeps the etag steady.
function serialize(doc) {
return Buffer.from(JSON.stringify(doc), 'utf8');
}
export function etagOf(bytes) {
return createHash('sha256').update(bytes).digest('hex').slice(0, 24);
}
function r2KeyFor(worldId, etag) {
// Mints/tier keys can contain ':' and '#'; encode so the key is path-clean.
return `worlds/${encodeURIComponent(worldId)}/${etag}.json`;
}
// Forward-migrate a doc loaded under an older schema. Identity today; this is the
// seam that keeps old builds loadable when the doc shape evolves.
export function migrateDoc(doc /* , fromVersion */) {
return doc;
}
// The permission hook. T16 replaces the body with the real model (holder
// threshold, owner allowlist, open) — keep the signature stable.
// isService — the request came from the authoritative game server.
// account — the authenticated user id, or null for anonymous.
// currentOwner — owner_id on the existing row, or null for a new/unowned world.
// exists : a row for this world already exists. A row with no owner was
// created by the game server (older saves carried no owner), so
// it is service-managed, not an unclaimed world a user may seed.
export function canWriteWorld({ isService = false, account = null, currentOwner = null, exists = false } = {}) {
if (isService) return true; // the game server is authoritative
if (!account) return false; // anonymous browsers can't write
if (!currentOwner) return !exists; // brand-new world: first writer may seed it
return account === currentOwner; // otherwise owner-only (T16 widens this)
}
// ── orchestration (storage-agnostic) ─────────────────────────────────────────
// Build a world store over any backend implementing the contract below.
export function createWorldStore(backend) {
// Load a world's current document, or null if it has never been saved.
async function loadWorld(worldId) {
assertWorldId(worldId);
const row = await backend.readRow(worldId);
if (!row) return null;
let doc;
if (row.inline_doc != null) {
doc = typeof row.inline_doc === 'string' ? JSON.parse(row.inline_doc) : row.inline_doc;
} else {
const buf = await backend.readBlob(row.r2_key);
doc = JSON.parse(Buffer.from(buf).toString('utf8'));
}
if (row.schema_version < SCHEMA_VERSION) doc = migrateDoc(doc, row.schema_version);
return {
worldId,
schemaVersion: SCHEMA_VERSION,
version: Number(row.doc_version),
etag: row.etag,
size: row.size_bytes,
ownerId: row.owner_id ?? null,
updatedAt: row.updated_at,
doc,
};
}
// Load a world's index metadata WITHOUT materializing its document. Callers
// that only need the concurrency/ownership columns (the save permission gate)
// use this so a 2 MB build does not cost an R2 GET plus a full JSON.parse on
// every autosave. Returns null when the world has never been saved.
async function loadWorldMeta(worldId) {
assertWorldId(worldId);
const row = await backend.readRow(worldId);
if (!row) return null;
return {
worldId,
schemaVersion: Number(row.schema_version),
version: Number(row.doc_version),
etag: row.etag,
size: row.size_bytes,
ownerId: row.owner_id ?? null,
updatedAt: row.updated_at,
};
}
// Persist a world document. Throws TooLargeError or ConflictError.
// ifMatch — the etag the caller last read (see concurrency notes above).
// writer — the principal recorded as updated_by (account id or 'service').
// owner — owner_id to set ON CREATE only; ignored for existing rows.
async function saveWorld({ worldId, doc, ifMatch = null, writer = null, owner = null }) {
assertWorldId(worldId);
const bytes = serialize(doc);
if (bytes.length > MAX_DOC_BYTES) {
throw new TooLargeError(`world document is ${bytes.length} bytes (max ${MAX_DOC_BYTES})`);
}
const etag = etagOf(bytes);
const inline = bytes.length <= INLINE_MAX_BYTES;
const r2Key = inline ? null : r2KeyFor(worldId, etag);
// Look up the prior blob key so we can GC it after a successful supersede.
const prior = await backend.readRow(worldId);
const priorR2 = prior ? prior.r2_key : null;
// Offloaded body lands first (content-addressed → no clobber), so the index
// row we commit next always points at bytes that already exist.
if (!inline) {
await backend.writeBlob(r2Key, bytes);
}
const res = await backend.upsert({
worldId,
schemaVersion: SCHEMA_VERSION,
etag,
size: bytes.length,
inlineDoc: inline ? doc : null,
r2Key,
owner,
writer,
ifMatch,
});
if (!res.committed) {
// A row exists but the guard failed → someone wrote between read and save.
// Drop the orphan blob this losing write may have created.
if (!inline && r2Key !== priorR2) {
try { await backend.deleteBlob(r2Key); } catch { /* best-effort */ }
}
throw new ConflictError();
}
// Supersede succeeded — retire the previous distinct blob.
if (priorR2 && priorR2 !== r2Key) {
try { await backend.deleteBlob(priorR2); } catch { /* best-effort GC */ }
}
return {
worldId,
schemaVersion: SCHEMA_VERSION,
version: Number(res.version),
etag: res.etag,
size: bytes.length,
ownerId: res.ownerId ?? null,
updatedAt: res.updatedAt,
};
}
// Remove a world entirely (its index row and any offloaded blob).
async function deleteWorld(worldId) {
assertWorldId(worldId);
const r2Key = await backend.remove(worldId);
if (r2Key === false) return false;
if (r2Key) {
try { await backend.deleteBlob(r2Key); } catch { /* best-effort */ }
}
return true;
}
return { loadWorld, loadWorldMeta, saveWorld, deleteWorld };
}
// ── default backend: Postgres index + R2 blob ────────────────────────────────
export const postgresR2Backend = {
async readRow(worldId) {
const rows = await sql`
SELECT world_id, schema_version, doc_version, etag, size_bytes,
inline_doc, r2_key, owner_id, updated_at
FROM world_docs
WHERE world_id = ${worldId}
LIMIT 1
`;
return rows.length ? rows[0] : null;
},
async readBlob(r2Key) {
return getObjectBuffer(r2Key);
},
async writeBlob(r2Key, bytes) {
await putObject({ key: r2Key, body: bytes, contentType: 'application/json' });
},
async deleteBlob(r2Key) {
await deleteObject(r2Key);
},
// Compare-and-set upsert. The WHERE guard on DO UPDATE is the concurrency
// gate: '*' overwrites unconditionally; otherwise the stored etag must equal
// ifMatch (NULL for a create → never matches an existing row → conflict).
async upsert({ worldId, schemaVersion, etag, size, inlineDoc, r2Key, owner, writer, ifMatch }) {
const guard = ifMatch === '*' ? sql`TRUE` : sql`world_docs.etag = ${ifMatch}`;
const inlineParam = inlineDoc == null ? null : JSON.stringify(inlineDoc);
const rows = await sql`
INSERT INTO world_docs (
world_id, schema_version, doc_version, etag, size_bytes,
inline_doc, r2_key, owner_id, updated_by, created_at, updated_at
) VALUES (
${worldId}, ${schemaVersion}, 1, ${etag}, ${size},
${inlineParam}::jsonb, ${r2Key}, ${owner}, ${writer}, now(), now()
)
ON CONFLICT (world_id) DO UPDATE SET
schema_version = ${schemaVersion},
doc_version = world_docs.doc_version + 1,
etag = EXCLUDED.etag,
size_bytes = EXCLUDED.size_bytes,
inline_doc = EXCLUDED.inline_doc,
r2_key = EXCLUDED.r2_key,
updated_by = EXCLUDED.updated_by,
updated_at = now()
WHERE ${guard}
RETURNING doc_version, etag, owner_id, updated_at
`;
if (!rows.length) return { committed: false };
const row = rows[0];
return {
committed: true,
version: Number(row.doc_version),
etag: row.etag,
ownerId: row.owner_id ?? null,
updatedAt: row.updated_at,
};
},
async remove(worldId) {
const rows = await sql`
DELETE FROM world_docs WHERE world_id = ${worldId}
RETURNING r2_key
`;
if (!rows.length) return false;
return rows[0].r2_key;
},
};
const defaultStore = createWorldStore(postgresR2Backend);
export const loadWorld = defaultStore.loadWorld;
export const loadWorldMeta = defaultStore.loadWorldMeta;
export const saveWorld = defaultStore.saveWorld;
export const deleteWorld = defaultStore.deleteWorld;