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
// WorldPersistence — generic per-world JSON persistence for Colyseus rooms (T3).
//
// Rooms that need durable, non-voxel world state (placed props, gated-world pass
// rosters, mutable realm layout) use this instead of the voxel-specific
// block-store. A room typically:
//
// import { worldPersistence } from '../persistence.js';
// // onCreate:
// const { doc, etag } = await worldPersistence.load(this.worldKey);
// if (doc) this.restoreFrom(doc);
// // on change:
// worldPersistence.save(this.worldKey, () => this.snapshot()); // debounced
// // onDispose:
// await worldPersistence.flush(this.worldKey);
//
// Durable storage lives in the Vercel API (api/world/[action] → Postgres index +
// R2 blob). This process keeps only a memory mirror + the last-seen etag for
// optimistic concurrency, and signs a short-lived service token per request so
// the API trusts the write. The token format is mirrored byte-for-byte by the
// API verifier (api/_lib/world-service-auth.js).
//
// Two tiers, like block-store:
// 1. In-process memory — the latest doc-producer + last doc, so a re-created
// room rehydrates instantly and a brief API outage doesn't lose the build.
// 2. The persistence API — survives this process dying / redeploying.
import crypto from 'node:crypto';
const API_BASE = (process.env.WORLD_API_BASE || 'https://three.ws').replace(/\/$/, '');
const SAVE_DEBOUNCE_MS = 4000;
// owner_id the game server stamps on every world row it creates (api/_lib/world-store.js).
const SERVICE_OWNER = 'service:world';
const TOKEN_TTL_SEC = 120;
function secret() {
return (
process.env.MULTIPLAYER_SHARED_SECRET ||
process.env.HOLDER_PASS_SECRET ||
'dev-insecure-multiplayer-secret'
);
}
// base64url(JSON{svc:'world',exp}).base64url(HMAC). Mirrors presence-token.js.
function signServiceToken() {
const exp = Math.floor(Date.now() / 1000) + TOKEN_TTL_SEC;
const payload = Buffer.from(JSON.stringify({ svc: 'world', exp }), 'utf8').toString('base64url');
const sig = crypto.createHmac('sha256', secret()).update(payload).digest('base64url');
return `${payload}.${sig}`;
}
class WorldPersistence {
constructor() {
// worldId → { produce: () => doc, lastDoc, etag, version, dirty }
this._mem = new Map();
this._timers = new Map();
// Flips true after a verified API round-trip; a room reads it to honestly
// tell builders whether their work survives a restart.
this._durable = false;
this._warnedUnconfigured = false;
}
get durable() {
return this._durable;
}
_entry(worldId) {
let e = this._mem.get(worldId);
if (!e) {
e = { produce: null, lastDoc: null, etag: null, version: 0, dirty: false };
this._mem.set(worldId, e);
}
return e;
}
// Load a world's current doc from the API, falling back to the in-memory
// mirror if the network read fails. Returns { doc, etag, version }.
async load(worldId) {
const e = this._entry(worldId);
try {
const res = await fetch(`${API_BASE}/api/world/load?worldId=${encodeURIComponent(worldId)}`, {
headers: { accept: 'application/json' },
});
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const body = await res.json();
e.etag = body.etag ?? null;
e.version = body.version ?? 0;
e.lastDoc = body.doc ?? null;
this._durable = true;
return { doc: e.lastDoc, etag: e.etag, version: e.version };
} catch (err) {
// Memory tier: a re-created room in the same process still rehydrates.
console.warn(`[world-persistence] load failed for ${worldId}: ${err?.message} — using memory mirror`);
return { doc: e.lastDoc, etag: e.etag, version: e.version };
}
}
// Record the latest doc producer and schedule a debounced durable write.
// Synchronous so callers don't await on the hot path of an edit. `produce` is
// called at flush time so the most recent state is what lands.
save(worldId, produce) {
if (typeof produce !== 'function') {
throw new TypeError('worldPersistence.save(worldId, produce): produce must be a function returning the doc');
}
const e = this._entry(worldId);
e.produce = produce;
e.dirty = true;
this._schedule(worldId);
}
_schedule(worldId) {
if (this._timers.has(worldId)) return;
const handle = setTimeout(() => {
this._timers.delete(worldId);
this.flush(worldId).catch(() => {});
}, SAVE_DEBOUNCE_MS);
if (typeof handle.unref === 'function') handle.unref();
this._timers.set(worldId, handle);
}
// Write the current world doc to the API now. Called by the debounce timer and
// on room dispose so the final state always lands.
async flush(worldId) {
const pending = this._timers.get(worldId);
if (pending) {
clearTimeout(pending);
this._timers.delete(worldId);
}
const e = this._mem.get(worldId);
if (!e || !e.dirty || !e.produce) return;
const doc = e.produce();
e.lastDoc = doc;
// One retry: if a concurrent writer moved the etag, re-read it and
// overwrite (a single always-on instance owns each world, so last-writer-
// wins is the right policy here rather than a merge).
for (let attempt = 0; attempt < 2; attempt++) {
const outcome = await this._postSave(worldId, doc, e.etag);
if (outcome === 'ok') {
e.dirty = false;
return;
}
if (outcome === 'conflict' && attempt === 0) {
const fresh = await this.load(worldId);
e.etag = fresh.etag;
continue;
}
return; // network/other error or repeated conflict — keep dirty, retry next change
}
}
async _postSave(worldId, doc, ifMatch) {
try {
const res = await fetch(`${API_BASE}/api/world/save`, {
method: 'POST',
headers: {
'content-type': 'application/json',
authorization: `Bearer ${signServiceToken()}`,
},
// `owner` stamps a first save as service-owned, so no signed-in browser
// account can later claim or overwrite a game-server-managed world.
body: JSON.stringify({ worldId, doc, ifMatch: ifMatch ?? null, owner: SERVICE_OWNER }),
});
if (res.ok) {
const body = await res.json();
const e = this._entry(worldId);
e.etag = body.etag ?? e.etag;
e.version = body.version ?? e.version;
this._durable = true;
return 'ok';
}
if (res.status === 409) return 'conflict';
if (res.status === 401 || res.status === 403) {
if (!this._warnedUnconfigured) {
this._warnedUnconfigured = true;
console.error(
`[world-persistence] save rejected (${res.status}) — set MULTIPLAYER_SHARED_SECRET to match the API, or worlds are MEMORY-ONLY.`,
);
}
this._durable = false;
return 'error';
}
console.warn(`[world-persistence] save for ${worldId} failed: HTTP ${res.status}`);
this._durable = false;
return 'error';
} catch (err) {
console.warn(`[world-persistence] save for ${worldId} failed: ${err?.message}`);
this._durable = false;
return 'error';
}
}
// Flush every dirty world. Call on SIGTERM (redeploy) so edits whose debounce
// hasn't fired aren't lost.
async flushAll() {
await Promise.allSettled([...this._mem.keys()].map((id) => this.flush(id)));
}
}
// One store shared by every room in the process — that shared memory is what lets
// a build outlive its room between disposal and the next join.
export const worldPersistence = new WorldPersistence();