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.

4.8 KB
Raw Blame
/**
 * Pure utility helpers for the Avatar Studio — no DOM, no Three.js, no side
 * effects. Exported so they can be unit-tested in isolation.
 */

import { normalizeProportions } from './avatar-proportions.js';
import { sanitizeSculptDoc } from './avatar-sculpt-doc.js';

export const DRAFT_KEY = 'avatar-studio-draft';
export const DRAFT_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000; // 7 days

// `garments` (additive catalog wearables, see specs/GARMENT_MANIFEST.md) are
// driven by the Studio's Wardrobe tab; `outfit` (a baked preset id) still has
// no UI anywhere. Both are carried through hydrate/collapse/clone verbatim: a
// PATCH replaces `appearance` wholesale, so dropping either here would silently
// undress an avatar opened in Studio's edit mode and saved.

/** Copy the garment list, isolating each {slot, id} entry from the source. */
function copyGarments(list) {
	return Array.isArray(list)
		? list.filter((g) => g && typeof g === 'object').map((g) => ({ ...g }))
		: [];
}

/** Collapse a working appearance to only non-empty fields. Returns null if nothing set. */
export function collapseAppearance(a) {
	if (!a) return null;
	const out = {};
	if (typeof a.outfit === 'string' && a.outfit) out.outfit = a.outfit;
	if (a.accessories?.length) out.accessories = [...a.accessories];
	if (a.morphs && Object.keys(a.morphs).length) out.morphs = { ...a.morphs };
	if (a.colors && Object.keys(a.colors).length) out.colors = { ...a.colors };
	if (a.hidden?.length) out.hidden = [...a.hidden];
	if (a.garments?.length) out.garments = copyGarments(a.garments);
	// Skeleton-space build (src/avatar-proportions.js). Normalizing here is what
	// makes the record canonical: out-of-range and neutral (1.0) values are
	// dropped, so an untouched body serializes to nothing and the appearance
	// hash stays stable across a slider that was dragged and put back.
	const proportions = normalizeProportions(a.proportions);
	if (Object.keys(proportions).length) out.proportions = proportions;
	// Free-sculpt deltas (src/avatar-sculpt-brush.js). Sanitizing here is what
	// keeps the record canonical: an undecodable or stale-version document
	// collapses to nothing rather than riding along and failing at bake time.
	const sculpt = sanitizeSculptDoc(a.sculpt);
	if (sculpt) out.sculpt = sculpt;
	return Object.keys(out).length ? out : null;
}

/** Hydrate a saved appearance record into a mutable working object. */
export function hydrateAppearance(raw) {
	if (!raw || typeof raw !== 'object') {
		return {
			outfit: null, accessories: [], morphs: {}, colors: {}, hidden: [],
			garments: [], proportions: {}, sculpt: null,
		};
	}
	return {
		outfit: typeof raw.outfit === 'string' && raw.outfit ? raw.outfit : null,
		accessories: Array.isArray(raw.accessories) ? [...raw.accessories] : [],
		morphs: raw.morphs && typeof raw.morphs === 'object' ? { ...raw.morphs } : {},
		colors: raw.colors && typeof raw.colors === 'object' ? { ...raw.colors } : {},
		hidden: Array.isArray(raw.hidden) ? [...raw.hidden] : [],
		garments: copyGarments(raw.garments),
		proportions: normalizeProportions(raw.proportions),
		sculpt: sanitizeSculptDoc(raw.sculpt),
	};
}

/** Deep clone a working appearance. */
export function cloneAppearance(a) {
	return {
		outfit: a.outfit ?? null,
		accessories: [...a.accessories],
		morphs: { ...a.morphs },
		colors: { ...a.colors },
		hidden: [...a.hidden],
		garments: copyGarments(a.garments),
		proportions: { ...(a.proportions || {}) },
		// The sculpt document is immutable once serialized: the brush replaces
		// it wholesale rather than mutating in place, so sharing the reference
		// is safe and a structural clone of tens of KB per history step is not.
		sculpt: a.sculpt || null,
	};
}

/** True when two appearances are semantically identical. */
export function appearanceEqual(a, b) {
	return JSON.stringify(collapseAppearance(a)) === JSON.stringify(collapseAppearance(b));
}

/** Parse the edit avatar ID from a URLSearchParams (or query string). */
export function parseEditId(searchOrParams) {
	const p = typeof searchOrParams === 'string'
		? new URLSearchParams(searchOrParams)
		: searchOrParams;
	const v = p.get('edit');
	return v && v.trim() ? v.trim() : null;
}

/** Read a persisted draft from a storage-like object (localStorage interface). */
export function readDraft(storage) {
	try {
		const raw = storage.getItem(DRAFT_KEY);
		if (!raw) return null;
		const draft = JSON.parse(raw);
		if (!draft?.ts) return null;
		if (Date.now() - draft.ts > DRAFT_MAX_AGE_MS) {
			storage.removeItem(DRAFT_KEY);
			return null;
		}
		return draft;
	} catch {
		return null;
	}
}

/** Write a draft to storage. */
export function writeDraft(storage, appearance, name) {
	try {
		storage.setItem(DRAFT_KEY, JSON.stringify({ appearance, name, ts: Date.now() }));
	} catch {}
}

/** Remove a draft from storage. */
export function clearDraft(storage) {
	try { storage.removeItem(DRAFT_KEY); } catch {}
}