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
// Economy & progression for the /play coin worlds.
//
// /play is a free-roam, per-coin social world where a player's pack and purse are
// PRIVATE, no peer needs to see them, so we keep all of it OFF the shared
// WalkState schema and stream each owner only their own state via targeted
// messages.
//
// That keeps the /walk experience (which shares the same schema) untouched, costs
// peers zero extra wire bytes, and lets the economy grow (cooking, gathering,
// commerce) without ever repricing the movement-critical position deltas.
//
// A "profile" here is a plain JS object, not a Schema, so these helpers operate
// on ordinary arrays. The shapes mirror items.js/playerStore.js so a fish caught on
// /play means the same thing it does in /game, and a profile persists through the
// same account-keyed playerStore.
import {
STACKABLE_ITEMS, isEdible, scaledHeal, armorValue,
} from './items.js';
import {
DEFAULT_LOADOUT, SLOTS, getCosmetic, canWear, sanitizeLoadout, freeCosmeticIds,
isUnlockableCosmetic,
} from './cosmetics-catalog.js';
export const INV_SIZE = 24;
export const HOTBAR_SIZE = 6;
export const MAX_STACK = 999;
export const LEVEL_CAP = 99;
export const SKILLS = ['combat', 'woodcutting', 'mining', 'fishing', 'cooking'];
// The armor layer's ceiling, a vest tops you up to here, and incoming damage eats
// armor before HP (see combat.js applyDamage). One capped bar, so it reads cleanly.
export const MAX_ARMOR = 100;
// Starter kit handed to a brand-new player so the loop is exercisable the moment
// they land: a fishing rod (cast at any pond), the gathering tools, and BOTH a
// melee (sword) and ranged (pistol) weapon so the W07 combat loop, swing, shoot,
// heal, re-armor, is playable on arrival. Tools occupy the hotbar.
const STARTER_HOTBAR = ['rod', 'axe', 'pickaxe', 'sword', 'pistol'];
// Backpack seed so a new player can fire and survive their first fight without a
// shop run: a clip of pistol ammo and one body-armor vest.
const STARTER_INV = [{ item: 'ammo', qty: 24 }, { item: 'vest', qty: 1 }];
// XP curve, the canonical progression for the platform: level n needs
// 50 * n^1.8 cumulative XP, capped at LEVEL_CAP.
export function levelForXp(xp) {
let lvl = 1;
while (lvl < LEVEL_CAP && xp >= Math.floor(50 * Math.pow(lvl, 1.8))) lvl++;
return lvl;
}
// Inverse of levelForXp: cumulative XP required to BE at a given level. Lets the
// client draw an exact progress bar without re-deriving the curve.
export function xpForLevel(level) {
const lvl = Math.max(1, Math.min(LEVEL_CAP, level | 0));
return lvl <= 1 ? 0 : Math.floor(50 * Math.pow(lvl - 1, 1.8));
}
function emptySlots(n) {
return Array.from({ length: n }, () => ({ item: '', qty: 0 }));
}
// A fresh profile with the starter kit. `playerId` is the stable persistence key
// (wallet account or guest id) carried on the profile so save paths never need it
// threaded separately.
export function newProfile(playerId = '') {
const hotbar = emptySlots(HOTBAR_SIZE);
STARTER_HOTBAR.forEach((item, i) => { hotbar[i] = { item, qty: 1 }; });
const inv = emptySlots(INV_SIZE);
STARTER_INV.forEach((seed, i) => { inv[i] = { item: seed.item, qty: seed.qty }; });
return {
playerId,
gold: 0,
bank: 0, // banked cash, protected on death (carried `gold` drops). W04 extends.
hp: 100,
maxHp: 100,
armor: 0, // armor layer that absorbs damage before HP; refilled by a vest.
maxArmor: MAX_ARMOR,
heat: 0, // wanted/heat meter (0..MAX_HEAT), raised by crimes, decays over time.
inv,
hotbar,
activeSlot: 0, // the rod, ready to cast
xp: Object.fromEntries(SKILLS.map((s) => [s, 0])),
levels: Object.fromEntries(SKILLS.map((s) => [s, 1])),
// Wheel of Fortune (W09/Task 19): epoch ms the next free spin unlocks. Unlike
// the ephemeral per-action `cd` map (WalkRoom.js, reset every reconnect,
// fine for a sub-second gather cooldown), this MUST survive a disconnect: a
// 12h cooldown that resets on reconnect would be free to farm. Persisted
// through serializeProfile/restoreProfile below.
nextFreeSpinAt: 0,
// Cosmetic identity (W03), purely visual. `owned` lists the premium ids this
// account has unlocked (free cosmetics are implicitly owned by everyone, so
// they're never stored here); `equipped` is the per-slot loadout peers render.
cosmetics: { owned: [], equipped: { ...DEFAULT_LOADOUT } },
};
}
// Premium ids this profile may wear: its unlocked set plus every free cosmetic.
// Returned as a Set for O(1) canWear checks on the equip hot path.
export function ownedCosmeticSet(profile) {
const owned = new Set(freeCosmeticIds());
const list = profile?.cosmetics?.owned;
if (Array.isArray(list)) for (const id of list) if (getCosmetic(id)) owned.add(id);
return owned;
}
// Grant an unlockable cosmetic into an account's owned list. Two callers: the
// W04 boutique after a $THREE payment settles (premium tier), and the event-drop
// grant when a player is in the world during a live meetup (event tier).
// Idempotent; ignores free or unknown ids, a free cosmetic is implicitly owned
// and storing it would bloat every save with nothing. Returns true when it newly
// unlocked something, so the caller can skip a persist that would change nothing.
export function grantCosmetic(profile, id) {
const c = getCosmetic(id);
if (!c || !isUnlockableCosmetic(id)) return false;
if (!profile.cosmetics) profile.cosmetics = { owned: [], equipped: { ...DEFAULT_LOADOUT } };
if (!Array.isArray(profile.cosmetics.owned)) profile.cosmetics.owned = [];
if (profile.cosmetics.owned.includes(id)) return false;
profile.cosmetics.owned.push(id);
return true;
}
// Bridge the R22 ownership ledger (real x402 purchases, keyed by account in
// Redis) into a profile's unlocked set. `ledgerIds` is the raw SMEMBERS of
// `cosmetics:owned:<account>`; only ids that are premium cosmetics in THIS
// catalog are granted (the ledger may also hold ids from a sibling catalog the
// rig can't render, those are ignored, never errored). Idempotent via
// grantCosmetic. Returns the count newly unlocked, so a caller can skip a persist
// when nothing changed.
//
// Deliberately PREMIUM-ONLY: this ledger records purchases, and an event
// souvenir has no purchase path. Filtering here rather than relying on the
// ledger's contents means a stray write on the x402 side can never mint a
// "you had to be there" item for someone who wasn't.
export function mergeOwnedFromLedger(profile, ledgerIds) {
if (!Array.isArray(ledgerIds) || !ledgerIds.length) return 0;
let granted = 0;
for (const id of ledgerIds) {
if (getCosmetic(id)?.tier !== 'premium') continue;
if (grantCosmetic(profile, id)) granted++;
}
return granted;
}
// Equip `id` into its slot if the profile is allowed to wear it. Returns the new
// equipped map on success, or null when the id is unknown or unowned (the server
// then rejects the equip). Mutates profile.cosmetics.equipped.
export function equipCosmetic(profile, id) {
const c = getCosmetic(id);
if (!c) return null;
if (!canWear(id, ownedCosmeticSet(profile))) return null;
if (!profile.cosmetics) profile.cosmetics = { owned: [], equipped: { ...DEFAULT_LOADOUT } };
profile.cosmetics.equipped = { ...profile.cosmetics.equipped, [c.slot]: id };
return profile.cosmetics.equipped;
}
// Rebuild a profile from a persisted blob (playerStore `profile` field). Tolerant
// of partial/legacy/missing data, every field is clamped and defaulted so a
// corrupt save can never crash a join; missing → a fresh starter profile.
export function restoreProfile(saved, playerId = '') {
if (!saved || typeof saved !== 'object') return newProfile(playerId);
const base = newProfile(playerId);
const fill = (target, src) => {
for (let i = 0; i < target.length; i++) {
const s = src && src[i];
const item = s && typeof s.item === 'string' ? s.item : '';
target[i] = { item, qty: item && Number.isFinite(s.qty) ? Math.max(0, Math.min(MAX_STACK, s.qty | 0)) : 0 };
}
};
if (Array.isArray(saved.inv)) fill(base.inv, saved.inv);
if (Array.isArray(saved.hotbar)) fill(base.hotbar, saved.hotbar);
if (Number.isFinite(saved.activeSlot)) base.activeSlot = Math.max(-1, Math.min(HOTBAR_SIZE - 1, saved.activeSlot | 0));
// Clamp BEFORE truncating: `| 0` is ToInt32, so applying it first wrapped any
// balance past 2^31 negative and then "clamped" it to zero, silently wiping
// the richest saves. Floor-then-clamp saturates at the ceiling instead.
if (Number.isFinite(saved.gold)) base.gold = Math.max(0, Math.min(0xffffffff, Math.floor(saved.gold)));
if (Number.isFinite(saved.bank)) base.bank = Math.max(0, Math.min(0xffffffff, Math.floor(saved.bank)));
if (Number.isFinite(saved.maxHp) && saved.maxHp > 0) base.maxHp = saved.maxHp | 0;
if (Number.isFinite(saved.hp)) base.hp = Math.max(0, Math.min(base.maxHp, saved.hp | 0));
if (Number.isFinite(saved.maxArmor) && saved.maxArmor > 0) base.maxArmor = saved.maxArmor | 0;
if (Number.isFinite(saved.armor)) base.armor = Math.max(0, Math.min(base.maxArmor, saved.armor | 0));
if (Number.isFinite(saved.heat)) base.heat = Math.max(0, Math.min(99, saved.heat));
if (Number.isFinite(saved.nextFreeSpinAt)) base.nextFreeSpinAt = Math.max(0, saved.nextFreeSpinAt);
if (saved.xp && typeof saved.xp === 'object') {
for (const skill of SKILLS) {
const v = Number.isFinite(saved.xp[skill]) ? Math.max(0, saved.xp[skill]) : 0;
base.xp[skill] = v;
base.levels[skill] = levelForXp(v);
}
}
// Cosmetics: keep only premium ids that still exist in the catalog as owned,
// then sanitize the equipped loadout against what this account may actually
// wear (drops anything unowned/renamed to the slot default).
if (saved.cosmetics && typeof saved.cosmetics === 'object') {
// Keep every unlockable tier, not just premium: an event souvenir has no
// re-grant path once its window closes, so dropping it here would silently
// destroy an item the owner can never get back.
const owned = Array.isArray(saved.cosmetics.owned)
? saved.cosmetics.owned.filter((id) => isUnlockableCosmetic(id))
: [];
base.cosmetics.owned = [...new Set(owned)];
base.cosmetics.equipped = sanitizeLoadout(saved.cosmetics.equipped, ownedCosmeticSet(base));
}
return base;
}
// The persisted slice written through to the account-keyed player store.
export function serializeProfile(profile) {
const slots = (arr) => arr.map((s) => ({ item: s.item, qty: s.qty }));
return {
inv: slots(profile.inv),
hotbar: slots(profile.hotbar),
activeSlot: profile.activeSlot,
gold: profile.gold,
bank: profile.bank,
hp: profile.hp,
maxHp: profile.maxHp,
armor: profile.armor,
maxArmor: profile.maxArmor,
heat: profile.heat,
nextFreeSpinAt: profile.nextFreeSpinAt,
xp: { ...profile.xp },
cosmetics: {
owned: [...(profile.cosmetics?.owned || [])],
equipped: { ...(profile.cosmetics?.equipped || DEFAULT_LOADOUT) },
},
};
}
// Is there room in the backpack for at least one of `item`? Stackables fit in any
// empty slot OR a non-full existing stack; non-stackables need an empty slot.
export function hasRoomFor(profile, item) {
if (STACKABLE_ITEMS.has(item)) {
for (const s of profile.inv) {
if (!s.item) return true;
if (s.item === item && s.qty < MAX_STACK) return true;
}
return false;
}
return profile.inv.some((s) => !s.item);
}
// Add `qty` of `item` to the backpack, filling existing stacks first. Returns the
// quantity that did NOT fit (0 = everything landed).
export function addItem(profile, item, qty) {
let left = qty;
const inv = profile.inv;
if (STACKABLE_ITEMS.has(item)) {
for (const s of inv) {
if (left <= 0) break;
if (s.item === item && s.qty < MAX_STACK) {
const room = MAX_STACK - s.qty;
const m = Math.min(room, left);
s.qty += m; left -= m;
}
}
while (left > 0) {
const empty = inv.find((s) => !s.item);
if (!empty) break;
const m = Math.min(MAX_STACK, left);
empty.item = item; empty.qty = m; left -= m;
}
} else {
while (left > 0) {
const empty = inv.find((s) => !s.item);
if (!empty) break;
empty.item = item; empty.qty = 1; left -= 1;
}
}
return left;
}
// Total quantity of `item` held across the backpack (hotbar tools aren't counted,
// resources and food live in the pack). Used to gate cooking ("any raw fish?").
export function countItem(profile, item) {
let n = 0;
for (const s of profile.inv) if (s.item === item) n += s.qty;
return n;
}
// Remove up to `qty` of `item` from the backpack, draining stacks until satisfied or
// the item runs out. Returns the quantity actually removed (≤ qty). Used by cooking
// (consume raw fish) and any future recipe/sink. Mutates the profile.
export function removeItem(profile, item, qty) {
let need = qty;
for (const s of profile.inv) {
if (need <= 0) break;
if (s.item !== item) continue;
const take = Math.min(s.qty, need);
s.qty -= take;
need -= take;
if (s.qty <= 0) { s.item = ''; s.qty = 0; }
}
return qty - need;
}
// Resolve a client slot reference { zone:'inv'|'hotbar', i } to the live slot
// object, or null when out of range. Validated server-side so a
// crafted index can never read outside the arrays.
export function resolveSlot(profile, ref) {
if (!ref || typeof ref !== 'object') return null;
const i = ref.i | 0;
if (ref.zone === 'inv' && i >= 0 && i < INV_SIZE) return profile.inv[i];
if (ref.zone === 'hotbar' && i >= 0 && i < HOTBAR_SIZE) return profile.hotbar[i];
return null;
}
// Grant XP in a skill. Mutates the profile and returns the detail the owner's
// client needs to animate the gain and (when crossed) the level-up, including the
// current level's XP boundaries so the bar is exact without a round-trip.
export function grantXp(profile, skill, amount) {
if (!SKILLS.includes(skill)) return null;
profile.xp[skill] = (profile.xp[skill] || 0) + amount;
const xp = profile.xp[skill];
const level = levelForXp(xp);
const leveledUp = level > (profile.levels[skill] || 1);
profile.levels[skill] = level;
const maxed = level >= LEVEL_CAP;
return {
skill, amount, xp, level, leveledUp,
levelXp: xpForLevel(level),
nextXp: maxed ? null : xpForLevel(level + 1),
};
}
// The full snapshot the owner's client renders on join (and after any change it
// can't infer): purse, vitals, pack, hotbar, and per-skill level + bar boundaries.
export function profileSnapshot(profile) {
const skills = {};
for (const skill of SKILLS) {
const level = profile.levels[skill] || 1;
const maxed = level >= LEVEL_CAP;
skills[skill] = {
level,
xp: profile.xp[skill] || 0,
levelXp: xpForLevel(level),
nextXp: maxed ? null : xpForLevel(level + 1),
};
}
return {
gold: profile.gold,
bank: profile.bank,
hp: profile.hp,
maxHp: profile.maxHp,
armor: profile.armor,
maxArmor: profile.maxArmor,
heat: profile.heat,
inv: profile.inv.map((s) => ({ item: s.item, qty: s.qty })),
hotbar: profile.hotbar.map((s) => ({ item: s.item, qty: s.qty })),
activeSlot: profile.activeSlot,
skills,
cap: LEVEL_CAP,
// Cosmetic loadout + unlocked set, so the owner's wardrobe shows what they
// own and have equipped without a second round-trip.
cosmetics: {
owned: [...(profile.cosmetics?.owned || [])],
equipped: { ...(profile.cosmetics?.equipped || DEFAULT_LOADOUT) },
},
};
}
// Use the item in `slot`: eat an edible to restore HP (scaled by cooking level), or
// don a vest to refill the armor layer. Returns what happened so the room can toast
// it. Mutates the profile; consumes one of the item on success.
export function consumeSlot(profile, slot) {
if (!slot || !slot.item) return { ok: false, reason: 'inedible' };
// Body armor, refill the armor bar instead of HP.
const armorPts = armorValue(slot.item);
if (armorPts > 0) {
const cap = profile.maxArmor || MAX_ARMOR;
if (profile.armor >= cap) return { ok: false, reason: 'armorFull' };
const before = profile.armor;
profile.armor = Math.min(cap, profile.armor + armorPts);
const gained = profile.armor - before;
slot.qty -= 1;
if (slot.qty <= 0) { slot.item = ''; slot.qty = 0; }
return { ok: true, kind: 'armor', gained };
}
if (!isEdible(slot.item)) return { ok: false, reason: 'inedible' };
if (profile.hp >= profile.maxHp) return { ok: false, reason: 'full' };
const before = profile.hp;
profile.hp = Math.min(profile.maxHp, profile.hp + scaledHeal(slot.item, profile.levels.cooking || 1));
const gained = profile.hp - before;
slot.qty -= 1;
if (slot.qty <= 0) { slot.item = ''; slot.qty = 0; }
return { ok: true, kind: 'heal', gained };
}
// --- Death, banking & vitals (W07) ----------------------------------------
// Strip the carried valuables a tombstone inherits when this player dies: all
// carried cash (`gold`) plus everything in the BACKPACK. Equipped hotbar tools and
// weapons are kept so a respawn isn't toothless, and BANKED cash is untouched,
// that's the whole risk/reward point of banking. Mutates the profile (zeroing the
// dropped slice) and returns { gold, items:[{item,qty}] } for the tombstone.
export function dropCarried(profile) {
const gold = profile.gold | 0;
profile.gold = 0;
const items = [];
for (const s of profile.inv) {
if (s.item && s.qty > 0) items.push({ item: s.item, qty: s.qty });
s.item = ''; s.qty = 0;
}
return { gold, items };
}
// Saturating gold credit: every reward path adds through here so a balance can
// approach the 32-bit ceiling but never exceed it (restoreProfile clamps to the
// same ceiling, so nothing is ever lost to wraparound on reload).
export function creditGold(profile, amount) {
const add = Number.isFinite(amount) ? Math.max(0, Math.floor(amount)) : 0;
profile.gold = Math.min(0xffffffff, (profile.gold || 0) + add);
return profile.gold;
}
// Restore a player to fighting shape after respawn: full HP and a cleared armor bar
// (you lose your vest on death, re-armor from the pack or a vendor).
export function reviveProfile(profile) {
profile.hp = profile.maxHp;
profile.armor = 0;
}
// Move cash between the carried purse and the protected bank. `amount > 0` deposits
// (purse → bank); `amount < 0` withdraws. Clamps to what's actually available so it
// can never mint or strand cash. Returns the signed amount actually moved.
export function bankTransfer(profile, amount) {
const amt = amount | 0;
if (amt > 0) {
const moved = Math.min(amt, profile.gold | 0);
profile.gold -= moved; profile.bank += moved;
return moved;
}
if (amt < 0) {
const moved = Math.min(-amt, profile.bank | 0);
profile.bank -= moved; profile.gold += moved;
return -moved;
}
return 0;
}