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
// WalkRoom, authoritative state for the three.ws /walk experience.
//
// Players send 'move' messages 15× per second. The server validates each
// update (max-step clamp, world bounds, name length, message rate) and
// merges the result into the shared MapSchema. Colyseus's binary delta
// protocol broadcasts only fields that actually changed to every other
// client in the same room, at the configured patch rate.
//
// Generic world objects (R01), balls, placed props, pickups, ride the same
// pattern on their own `objects` map (see schemas.js WorldObject). The full
// obj:spawn / obj:update / obj:remove wire contract (payload shape, who's
// authorized, rate limits and caps) is documented at the
// "── Generic world objects (R01 protocol) ──" comment block below, right
// above _handleObjSpawn, read that before adding a new object-driven
// feature (R02 client manager, R05 ball physics, R17 persistence and later
// briefs all build on that single channel).
import { Room } from '@colyseus/core';
import { Player, Block, Vehicle, Mob, Tombstone, WorldObject, WalkState } from '../schemas.js';
import {
VEHICLE_SPAWNS, vehicleSpec, isVehicleType, vehicleRestHeight,
VEHICLE_WORLD_BOUND_M, VEHICLE_ENTER_RANGE_M,
vehicleMaxStepM, vehicleMaxSpeedMps,
} from '../vehicles.js';
import { cleanAvatarUrl } from '../avatar-url.js';
import {
MAX_WORLD_OBJECTS, MAX_OBJECTS_PER_PLAYER, OBJ_SCALE_MIN, OBJ_SCALE_MAX,
BUILD_CLEAR_RADIUS_MAX, buildClearRadius, normalizePropAssetUrl,
} from '../build-limits.js';
import { blockStore } from '../block-store.js';
import { worldPersistence } from '../persistence.js';
import { verifyHolderPass } from '../holder-pass.js';
import { socialHub } from '../social-hub.js';
import { verifyPresenceTicket } from '../presence-token.js';
import { verifyPlayPass } from '../play-pass.js';
import { containsHateSlur } from '../display-name-safety.js';
import { newGuestId, signGuestToken, verifyGuestToken } from '../guest-token.js';
import { consumeSettlement } from '../settlement-guard.js';
import { installUnknownMessageGuard, PLAY_PASS_EVICT_CODE } from '../room-compat.js';
import { registerWalkRoom, unregisterWalkRoom } from '../walk-registry.js';
import {
restoreProfile, serializeProfile, profileSnapshot,
addItem, hasRoomFor, resolveSlot, grantXp, consumeSlot,
countItem, removeItem,
dropCarried, reviveProfile, creditGold, bankTransfer, grantCosmetic,
equipCosmetic, ownedCosmeticSet, mergeOwnedFromLedger,
HOTBAR_SIZE,
} from '../economy.js';
import {
serializeLoadout, getCosmetic, canWear, DEFAULT_LOADOUT,
} from '../cosmetics-catalog.js';
import {
clientStoreCatalog, sellPrice, isSellable, buyEntry,
boutiqueListings, boutiquePrice,
} from '../shop.js';
import {
buildTokenPurchase, verifyTokenPurchase, isWalletAddress, tokenConfigured, TOKEN_DECIMALS,
} from '../game-token.js';
import { readOwnedCosmetics } from '../cosmetics-ownership.js';
import { currentEventDrop, dropClaimable, warmEventDrop } from '../event-drop.js';
import {
itemLabel, fishCatchChance, fishDoubleChance,
gatherChance, gatherDoubleChance, coalBonusChance, cookBurnChance,
weaponDef, mobStats, rollLoot,
} from '../items.js';
import {
fishingSpotInRange, treeInRange, rockInRange, firepitInRange,
vendorInRange, atmInRange,
DANGER_ZONES, SPAWN_POINT, dangerZoneAt, isSafeZone, isDangerZone, randomPointInZone,
PLAZA_STAGE,
} from '../world-features.js';
import { registerActivityHandlers, ACTIVITY_COOLDOWN_MS } from '../activities.js';
import { registerSpinHandlers } from '../spin-wheel.js';
import {
selectTarget, rollDamage, applyDamage, addHeat, decayHeat, heatStars,
} from '../combat.js';
import {
registerCombatHandlers, seedMobs, tickMobs, tickHeat, MOB_TICK_MS, HEAT_TICK_MS,
} from '../combat-handlers.js';
import { interactZoneInRange, zoneAt } from '../quest-zones.js';
import {
missionDef, isHeist, utcDayKey,
restoreQuestState, serializeQuestState,
acceptMission, abandonMission, applyEvent, recordCompletion,
missionReward, splitPot, questSnapshot, runView, objectiveMatches,
pruneClosedEventRuns,
} from '../quests.js';
import { eventLiveNow, eventWindow, refreshEventWindow } from '../event-window.js';
import { reportEventRun, fetchEventBoard } from '../event-score.js';
import { hydratePlayer, loadPlayer, savePlayer, flushPlayer } from '../playerStore.js';
import { publishFeedEvent } from '../feed.js';
import { reportQuestComplete } from '../quest-notify.js';
// Platform entry gate (wallet-first sign-in + game-token balance). When a game
// token is pinned (PLAY_GATE_MINT, falling back to THREE_MINT) every join must
// carry a valid play pass, minted by api/play/verify after proving wallet
// ownership and a balance ≥ PLAY_GATE_MIN of that token. An unset mint leaves
// walk_world open exactly as before, so /walk and un-pinned deploys are
// unaffected. Read at boot: gate config doesn't change without a redeploy.
const PLAY_GATE_MINT = (process.env.PLAY_GATE_MINT || process.env.THREE_MINT || '').trim();
const PLAY_GATE_MIN = (() => {
const n = Number(process.env.PLAY_GATE_MIN);
return Number.isFinite(n) && n > 0 ? n : 1;
})();
// Room ceiling. When a room fills, Colyseus's joinOrCreate silently spawns a
// second instance with the same (coin, tier) filter: players past the cap land
// in a parallel copy of the world with no UI signal that their friends are in
// the other one. Until that spillover has a real client-side story, keep the
// cap high enough that a live-event crowd fits in ONE room: at 100 clients the
// move-sync cost is ~40KB/s down per client (99 peers × ~28B × 15Hz), well
// inside both the container and a normal connection. Override per-deploy with
// WALK_ROOM_MAX_CLIENTS; the env guard clamps nonsense values.
const MAX_CLIENTS_PER_ROOM = (() => {
const n = Number(process.env.WALK_ROOM_MAX_CLIENTS);
return Number.isFinite(n) && n >= 2 && n <= 500 ? Math.floor(n) : 100;
})();
const PATCH_RATE_HZ = 15;
const PATCH_RATE_MS = 1000 / PATCH_RATE_HZ;
// --- Collaborative voxel building -----------------------------------------
// Builds live on an integer grid centred on the world origin. The server works
// purely in grid cells (unit-agnostic); the client maps a cell to metres via
// its BLOCK size. These caps must mirror the client's (build-voxels.js):
// - a circular build area of MAX_GRID_XZ cells radius (keeps builds on the
// plaza, away from the far hills),
// - a height ceiling of MAX_GRID_Y cells,
// - BLOCK_TYPE_COUNT palette entries,
// - and a hard per-world block budget so one room can't balloon memory or the
// join-time state sync.
const MAX_GRID_XZ = 30;
const MAX_GRID_Y = 24;
const BLOCK_TYPE_COUNT = 10;
const MAX_BLOCKS = 6000;
// Building is bursty (drag-to-place), so allow a higher rate than movement but
// still cap it so a scripted client can't flood the room.
const EDITS_PER_SEC_LIMIT = 20;
// Generic world objects (R01): the shared channel for balls, props and pickups.
// The caps and scale bounds live in ../build-limits.js so the client enforces the
// identical numbers while building solo against the durable world store (P3.1);
// the rate limit is server-only and mirrors the edit limiter so a scripted client
// can't flood spawns.
const OBJ_OPS_PER_SEC_LIMIT = 30; // per-client spawn/update/remove rate
const OBJ_STR_MAX = 48; // clamp length of id/type/kind strings
const OBJ_Y_MIN = -5;
const OBJ_Y_MAX = 240;
const SERVER_OBJECT_OWNER = 'server'; // ownerId sentinel: room-owned, no client writes
// Transient object kinds are ephemeral (physics balls, fx) and are NEVER persisted
// (R17). Everything else is a durable build piece saved per coin world.
const TRANSIENT_OBJECT_KINDS = new Set(['ball', 'projectile', 'confetti', 'fx', 'spark', 'pickup']);
const OBJ_ID_RE = /^[A-Za-z0-9_-]{1,48}$/;
// Composite pieces (walls, stairs, doors) place several cells at once through the
// place-batch channel. A single stamp is capped at this many cells, and stamps
// are rate-limited separately from single edits, so a crafted client can't smuggle
// an oversized or rapid-fire write through it. Mirrors MAX_COMPOSITE_CELLS on the
// client, with headroom so appending a larger piece there doesn't desync.
const MAX_BATCH_CELLS = 32;
const BATCHES_PER_SEC_LIMIT = 4;
// ── R05: server-authoritative beach ball physics ──────────────────────────────
// One ball per room, kind:'ball', ownerId:'server'. Clients send 'ball:kick' with
// an impulse vector; the server validates + caps it, then integrates position each
// physics tick and streams updates through the objects map via the schema delta.
//
// ball:kick { vx, vy, vz }
// Any joined player, BALL_KICKS_PER_SEC rate limit. The server caps impulse
// magnitude and ensures a minimum upward component, then adds it to the
// authoritative velocity. Ball id is fixed (BALL_ID), one per room.
//
// Velocity kept in _ballVx/y/z server vars, written to the WorldObject schema
// each tick. A settled ball (speed < BALL_IDLE_SPEED_SQ on ground) skips
// integration to avoid micro-drift and unnecessary Colyseus patches.
const BALL_ID = 'ball_0';
const BALL_RADIUS = 0.5;
const BALL_TICK_MS = 1000 / 20; // 20 Hz physics
const BALL_GRAVITY = 9.8;
const BALL_BOUNCE = 0.55; // vertical energy retained on ground bounce
const BALL_WALL_BOUNCE = 0.80; // energy retained on world-edge bounce
const BALL_ROLLING_FRICTION = 2.0; // per-second horizontal speed decay on ground
const BALL_AIR_DRAG = 0.12; // per-second speed decay while airborne
const BALL_MAX_IMPULSE = 12; // m/s, cap on a single client kick
const BALL_POST_KICK_CAP = 18; // m/s, absolute total velocity cap post-kick
const BALL_MIN_UPY = 0.8; // minimum upward component on any kick
const BALL_KICK_REACH_M = 3.5; // must stand beside the ball to kick it (mirrors LOOT_REACH_M-style gates)
const BALL_WORLD_RADIUS = 54; // keep inside the visible arena
const BALL_SPAWN_X = 0;
const BALL_SPAWN_Y = BALL_RADIUS;
const BALL_SPAWN_Z = 5;
const BALL_OOB_Y = -10; // respawn below this y
const BALL_IDLE_SPEED_SQ = 0.04; // (m/s)^2, skip integration when settled
const BALL_KICKS_PER_SEC = 3;
// --- Build permissions & anti-grief (R19) ---------------------------------
// The per-world MAX_BLOCKS budget above protects the room; these caps protect it
// from a SINGLE builder. A per-player ceiling stops one user consuming the whole
// world; a per-column ceiling stops them stacking a 24-high wall to fence the
// plaza off; protected discs keep the spawn and the coin totem from being buried
// or caged. Every rejection is surfaced to the client (edit-reject), never silent.
const PER_PLAYER_BLOCK_CAP = 1200; // how many cells one player may own at once
const COLUMN_CAP = 14; // blocks allowed in a single (x,z) column (< MAX_GRID_Y)
const PROTECTED_RADIUS_CELLS = 3; // keep this many cells clear around each protected point
// The build grid is centred on the world origin and maps a cell to metres via the
// client's BLOCK size (1.5 m). The spawn point is the origin; the coin totem
// renders at world z = -12 → grid z = round(-12 / 1.5) = -8. Protect both columns
// at every height so neither can be buried or walled in.
export const BLOCK_SIZE_M = 1.5; // client BLOCK: one grid cell ↔ metres
// Each disc carries its own radius (in cells) so a landmark bigger than the
// default keeps a guard that matches its real footprint. The plaza stage's disc
// is derived from world-features.PLAZA_STAGE, so moving the venue moves its
// protection with it and the two can never drift.
const PROTECTED_POINTS = [
{ x: 0, z: 0, r: PROTECTED_RADIUS_CELLS },
{ x: 0, z: -8, r: PROTECTED_RADIUS_CELLS },
{
x: Math.round(PLAZA_STAGE.x / BLOCK_SIZE_M),
z: Math.round(PLAZA_STAGE.z / BLOCK_SIZE_M),
r: Math.ceil(PLAZA_STAGE.r / BLOCK_SIZE_M),
},
];
// The prop/object build channel (obj:spawn kind:'block') works in world METRES, not
// grid cells, so its grief guard has its own protected discs and density tile. The
// protected world points are the spawn (origin) and the rendered totem (world z=-12);
// the radius matches the voxel discs (PROTECTED_RADIUS_CELLS cells). PER_TILE_PROP_CAP
// stops a builder piling props onto one spot to bury a landmark or wall an area off,
// the per-player count (MAX_OBJECTS_PER_PLAYER) and world cap bound the rest.
const PROTECTED_RADIUS_M = PROTECTED_RADIUS_CELLS * BLOCK_SIZE_M;
const PROTECTED_POINTS_M = [
{ x: 0, z: 0, r: PROTECTED_RADIUS_M },
{ x: 0, z: -12, r: PROTECTED_RADIUS_M },
{ x: PLAZA_STAGE.x, z: PLAZA_STAGE.z, r: PLAZA_STAGE.r },
];
const PROP_TILE_M = BLOCK_SIZE_M; // density tile size for props, in metres
const PER_TILE_PROP_CAP = 4; // durable props allowed on one tile
// Creator moderation: a clear-area sweep is bounded so even the creator's
// broad-brush tool can't nuke a whole world in one malformed call; 'all' is the
// explicit full-clear path. The reach a caller has EARNED is tiered
// (build-limits.buildClearRadius: visitor / holder-world / coin creator);
// BUILD_CLEAR_RADIUS_MAX is the absolute ceiling applied on top of it.
// The three.ws API the multiplayer server reads the coin's on-chain creator from,
// so "is this player the coin's creator" is proven server-side, not claimed by a
// client. Mirrors persistence.js's WORLD_API_BASE.
const WORLD_API_BASE = (process.env.WORLD_API_BASE || 'https://three.ws').replace(/\/$/, '');
// Anti-cheat: reject any movement update that would move the player farther
// than this in a single message. The client sends moves at ~15Hz, so even at
// the run speed (4 m/s) a legitimate delta is ~0.27 m. We allow generous
// headroom for packet timing jitter.
const MAX_STEP_M = 1.2;
// Tag mini-game (R08). Server-authoritative proximity: a tag is only valid when
// the "it" player's authoritative server position is within TAG_RANGE_M of a
// target. TAG_IMMUNITY_MS prevents the just-untagged player from being immediately
// re-tagged. TAG_MIN_PLAYERS is the threshold to start/continue the game.
// TAG_LB_INTERVAL_MS refreshes leaderboard time values for all clients periodically.
const TAG_RANGE_M = 2.0;
const TAG_IMMUNITY_MS = 2000;
const TAG_MIN_PLAYERS = 2;
const TAG_LB_INTERVAL_MS = 8000;
// King of the Totem mini-game (R07). Server-authoritative area control: the SOLE
// occupant of the king-zone at the totem base earns points each tick; two or more
// inside is "contested" and nobody scores. Rounds run on a fixed timer with a
// short intermission between them. The zone is centred on the totem (rendered at
// world (0, -12), see PROTECTED_POINTS) so its radius matches the client ring.
// Occupancy is judged from the server's authoritative player positions, so a
// client can never score from outside the zone. KING_TICK_MS is the scoring +
// timer cadence; KING_POINTS_PER_SEC is awarded scaled by real elapsed time so a
// dropped tick never over- or under-pays. A round needs ≥ KING_MIN_PLAYERS present
// to start, but once running it tolerates players leaving down to zero (it simply
// ends with no winner). Dead/downed players (W07) can't hold the zone.
// How long a freshly joined client is given to attach its message handlers and
// say 'ready' before the room broadcasts to it regardless. See _stillDeaf.
//
// Generous on purpose. A client only reaches this point after downloading and
// running the world bundle, and on a budget phone or a bad connection the gap
// between the room accepting the join and the client wiring its handlers is
// seconds, not milliseconds: at 320px on a loaded machine it ran past 30 ticks.
// Waiting costs a client on an older bundle (which never says 'ready') nothing
// it cannot recover, since each of these broadcasts is periodic state that comes
// round again and the king sync is sent directly in onJoin either way.
const JOIN_SETTLE_MS = 8000;
// How long a client that never says 'ready' waits for its join snapshot. Matches
// the broadcast window: sending sooner than that is sending into the same gap
// this whole handshake exists to avoid, which is exactly what a 1.2s fallback did
// when it was tried. A client that does say 'ready' never waits for this.
const JOIN_SNAPSHOT_MS = JOIN_SETTLE_MS;
const KING_ZONE = { x: 0, z: -12, r: 3.5 };
const KING_ROUND_MS = 90_000;
const KING_INTERMISSION_MS = 12_000;
const KING_TICK_MS = 1000;
const KING_POINTS_PER_SEC = 10;
const KING_MIN_PLAYERS = 1;
// Open-world district bounds (W01). The /play world is no longer the 60 m disc:
// it's a square district the client renders streets/buildings across. These
// mirror DISTRICT.half in src/game/world-zones.js, keep the two in sync so the
// authoritative bounds and the rendered ground agree. The anti-teleport MAX_STEP
// clamp above is independent and still applies on every move.
const WORLD_HALF_M = 200;
const WORLD_BOUND_M = WORLD_HALF_M - 2; // small margin so an edge-pressed avatar never clips the rim
// Authoritative day/night clock. One full day every DAY_LENGTH_MS, derived from
// the wall clock so every room (and every client in it) agrees on the time of
// day without us syncing a phase. Broadcast once a second as state.worldTime (a
// [0,1) day fraction); clients advance it smoothly between updates.
const DAY_LENGTH_MS = 600_000; // 10-minute day → a visible cycle, not a frantic one
// Rate limit incoming 'move' messages per client to twice the expected rate
// so legitimate jitter passes but a flooding client gets dropped.
const MOVES_PER_SEC_LIMIT = PATCH_RATE_HZ * 2;
const MOVE_WINDOW_MS = 1000;
const MOTION_VALUES = new Set(['idle', 'walk', 'run']);
// --- Economy & activities (off-schema) ------------------------------------
// A player's pack, purse and skills are PRIVATE to them, peers never render
// them in this free-roam world, so they live off the synced WalkState schema
// (kept in this.econ) and stream to the owning client via targeted messages.
// This keeps the shared /walk schema untouched and peers' wire cost at zero.
// Per-cast reel time. Read from the shared cadence table in activities.js (which the
// chop/mine/cook handlers already arm from) so there is exactly one copy of every
// gather cadence in the codebase.
const FISH_COOLDOWN_MS = ACTIVITY_COOLDOWN_MS.fish;
const CONSUME_COOLDOWN_MS = 1100; // pace between bites, no instant heal-spam
// Per-action rate ceilings (messages/sec/client), a flooding client is dropped.
// vsync rides at the same 15Hz the move netcode uses; allow 2× for jitter, like
// MOVES_PER_SEC_LIMIT. enter/exit are deliberate, rare actions.
const ACTION_RATES = {
fish: 6, consume: 6, equip: 30, chop: 6, mine: 6, cook: 8, pickupRod: 4, vsync: PATCH_RATE_HZ * 2,
venter: 4, vexit: 4, quest: 8, questInteract: 6, clear: 2,
// The event leaderboard panel: a manual refresh plus its own poll while open.
// The room caches the upstream read (event-score.js), so this ceiling bounds the
// per-client chatter, not the API load.
eventBoard: 4,
// General store, bank/ATM, and the $THREE boutique (W04), low-frequency,
// currency-mutating actions, throttled tighter than the gather loop.
store: 6, storeBuy: 6, storeSell: 6, bank: 6, boutique: 4, boutiqueQuote: 3, boutiqueSettle: 3,
// Combat (W07): attack rides at a swing/shot cadence a touch above the fastest
// weapon's cooldown (pistol ~430ms); loot is a deliberate, rare action.
attack: 5, loot: 4,
// Wheel of Fortune (W09), deliberate, low-frequency, currency/payment-mutating
// actions, throttled like the boutique's above.
spinInfo: 4, spinFree: 3, spinPaidPrep: 3, spinPaidSettle: 3,
// Read-only snapshot requests. profile is cheap but unbounded outbound;
// questBoard runs boardOffers over the whole mission registry per call, so an
// unlimited loop was a one-client DoS on the room's single thread.
profile: 4, questBoard: 4,
// Identity mutations. Each write dirties a synced string field that fans out
// to every client in the room, so an unthrottled flood is a broadcast
// amplifier: 2/s covers every legitimate use (a typo fix, a mid-session
// avatar swap) with a wide margin.
rename: 2, avatar: 2, voiceState: 4,
};
// Spatial voice signaling. The room only relays SDP/ICE between two peers (the
// audio itself flows peer-to-peer over WebRTC), so the cap just has to clear a
// connection handshake's burst of candidates without letting a client flood the
// relay. SDP/ICE are small; anything larger than the cap is rejected outright.
const VOICE_SIGNALS_PER_SEC_LIMIT = 60;
const MAX_VOICE_SIGNAL_BYTES = 16_000;
// Solana mint addresses are base58, 32, 44 chars. Anything else (including '')
// collapses to the default mainland world.
const MINT_RE = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
function cleanCoin(v) {
const s = typeof v === 'string' ? v.trim() : '';
return MINT_RE.test(s) ? s : '';
}
// Access tier. Only 'holders' is gated; anything else (including '') is the open
// General world. A coin's General and Holders worlds are kept in separate room
// instances by filterBy(['coin','tier']), see multiplayer/src/index.js.
function cleanTier(v) {
return v === 'holders' ? 'holders' : '';
}
function clean(str, maxLen) {
if (typeof str !== 'string') return '';
// Strip control chars, collapse whitespace, trim, cap length.
return str
.replace(/[\x00-\x1f\x7f]+/g, ' ')
.replace(/\s+/g, ' ')
.trim()
.slice(0, maxLen);
}
// Numeric guards for world-object payloads: a finite value or the fallback, and a
// clamp into [lo, hi]. Kept tiny and local so the object handlers read cleanly.
function objNum(v, fallback) {
return Number.isFinite(v) ? v : fallback;
}
function objClamp(v, lo, hi) {
return v < lo ? lo : v > hi ? hi : v;
}
function round3(n) {
return Math.round(n * 1000) / 1000;
}
function pickPlayerColor(sessionId) {
// Deterministic pleasant hue from sessionId, every client renders the
// same player in the same color without us needing to sync it explicitly.
let h = 0;
for (let i = 0; i < sessionId.length; i++) {
h = (h * 31 + sessionId.charCodeAt(i)) >>> 0;
}
const hue = h % 360;
// HSL → 0xRRGGBB. Sat 65%, lightness 60% gives high-contrast jersey colors.
return hslToHex(hue / 360, 0.65, 0.6);
}
function hslToHex(h, s, l) {
const k = (n) => (n + h * 12) % 12;
const a = s * Math.min(l, 1 - l);
const f = (n) => {
const v = l - a * Math.max(-1, Math.min(k(n) - 3, 9 - k(n), 1));
return Math.round(v * 255);
};
return (f(0) << 16) | (f(8) << 8) | f(4);
}
export class WalkRoom extends Room {
// Players are matched into the same room instance only when their `coin`
// join option matches, so each coin community is an isolated world while a
// single room definition serves them all. Coin-less players share the
// default mainland instance.
//
// Tier gate: the General world ('') is open to everyone. The Holders world
// ('holders') admits a client only with a valid holder pass, an HMAC-signed
// token the API mints after pricing the user's authenticated wallet against
// HOLDER_MIN_USD of this exact coin. We verify the pass here, before onJoin,
// and reject otherwise. Returning false makes Colyseus answer the
// join with an auth error the client surfaces as the locked gate.
//
// INSTANCE method, not static, and that is load-bearing: Colyseus 0.16 calls
// a *static* onAuth as onAuth(token, options, context), where token is the
// HTTP bearer token (undefined for our clients). The old static declaration
// here received that undefined as "client", so every path that assigned
// client.userData (the play gate and the whole holder tier) threw a
// TypeError on join. The instance form receives the real client at WS join
// time and its return value is stored as client.auth.
onAuth(client, options) {
// Platform token gate (orthogonal to the per-coin holder tier below). When a
// game token is pinned, no client reaches any world, General or Holders,
// without a play pass proving a signed-in wallet holds ≥ the floor. Throw
// (not return false) so a refusal arrives as a `play_pass`-prefixed error the
// client routes back to its sign-in gate. The verified wallet is bound to the
// session as the account id, never taken from an unsigned join option.
//
// KNOWN LANDMINE (2026-07-10): this gate is enforced against every client of
// this shared room, but only `/play` (src/game/community-net.js) actually
// carries a `playPass` in its join options, it has the whole wallet
// sign-in + pass-minting flow. `/walk` (src/walk-net.js) has never had that
// UI and sends no `playPass` field at all. As long as PLAY_GATE_MINT is unset
// (the default today) this is inert, every join sails past the `if` below.
// The moment an operator sets PLAY_GATE_MINT/THREE_MINT, every `/walk` join
// and reconnect will throw `play_pass_required` and the page will look
// completely offline, while `/play` keeps working. Fixing this properly means
// porting real sign-in UI into `/walk` (or extracting the pass-minting flow
// out of coincommunities.js into a shared module both pages call), a
// deliberate product decision about whether `/walk` stays a simpler,
// no-sign-in surface, not a one-line wiring fix. Do this BEFORE flipping the
// platform gate on in production, not after someone reports `/walk` is dead.
if (PLAY_GATE_MINT) {
const pass = verifyPlayPass(options?.playPass);
if (!pass) throw new Error('play_pass_required');
if (pass.mint !== PLAY_GATE_MINT) throw new Error('play_pass_mismatch');
if (!(typeof pass.balance === 'number' && pass.balance >= PLAY_GATE_MIN)) {
throw new Error('play_pass_required');
}
client.userData = { ...(client.userData || {}), account: pass.wallet, playBalance: pass.balance, playExp: pass.exp };
}
const tier = cleanTier(options?.tier);
if (tier !== 'holders') return true; // open General world
// A holder world must name a real coin. Throw (rather than return false) so
// every holder-gate refusal reaches the client as a `holder_pass`-prefixed
// error its gate UI routes on, a uniform denial contract.
const coin = cleanCoin(options?.coin);
if (!coin) throw new Error('holder_pass_required');
const pass = verifyHolderPass(options?.holderPass);
if (!pass) {
throw new Error('holder_pass_required');
}
// The pass is for this exact coin's holder tier, a pass minted for coin A
// can't unlock coin B's holder world.
if (pass.mint !== coin || pass.tier !== 'holders') {
throw new Error('holder_pass_mismatch');
}
// Carry the verified holding + signed floor through to onJoin/onCreate so
// in-world affordances and the displayed requirement come from the pass,
// never from unsigned client options.
client.userData = {
...(client.userData || {}),
holderUsd: pass.usd,
holderWallet: pass.wallet,
holderMinUsd: pass.minUsd,
holderMinTokens: pass.minTokens,
holderAmount: pass.amount,
};
return true;
}
constructor() {
super();
this.maxClients = MAX_CLIENTS_PER_ROOM;
this._moveCounters = new Map(); // sessionId → { windowStart, count }
this._chatCooldowns = new Map();
this._kickCounters = new Map(); // R05: sessionId → { windowStart, count } for ball:kick rate limit
// R05 ball physics (server-authoritative). Velocity lives here (off-schema);
// position is written directly onto the WorldObject each tick and auto-broadcast.
this._ballVx = 0; this._ballVy = 0; this._ballVz = 0;
// Off-schema economy: sessionId → runtime profile (pack/purse/skills + the
// stable persistence id + per-action cooldowns). Never synced to peers.
this.econ = new Map();
this._actionCounters = new Map(); // sessionId → { [action]: { windowStart, count } }
// On-chain settlement replay protection lives in settlement-guard.js, one
// durable, process-wide (and Redis-backed, when configured) consumption
// ledger shared by the boutique and the paid wheel, replacing the per-room
// nonce Maps that let one payment re-grant across rooms and restarts.
// Build permissions & anti-grief (R19). Ownership and density are tracked
// off-schema (peers don't render them) but persisted with the build so they
// survive a restart. blockOwners: key → owner id. blockCounts: owner id → how
// many cells they hold (drives the per-player cap, keyed by stable owner so it
// outlives a disconnect while their build stands). columnCounts: "x,z" → height.
this.blockOwners = new Map();
this.blockCounts = new Map();
this.columnCounts = new Map();
// The coin's on-chain creator wallet, resolved once on create. '' until known
// (or for the ownerless mainland world); gates the clear-area moderation tool.
this.coinCreator = '';
// Co-op heist instances live on the room, not on a profile: a SHARED run a
// crew advances together. Keyed by mission id (one live instance per heist per
// world). Each value: { missionId, members:Set<sessionId>, run }, the run
// carries its own per-stage seen-zone dedupe (quests.js applyEvent).
this.heists = new Map();
// Tag mini-game (R08): off-schema state. _tagImmunity tracks who is immune
// (sessionId → epoch ms immunity expires). _tagTime tracks cumulative time-as-it
// per session ({ timeMs: number, becameIt: epoch|null }).
this._tagImmunity = new Map();
this._tagTime = new Map();
// sessionId → the guest token minted for this join, so the 'ready' handshake
// can hand it over again if the client was not listening the first time.
this._guestTokens = new Map();
// Join-settling bookkeeping for the same handshake: who has announced their
// handlers, and when each session joined (see _stillDeaf).
this._readyClients = new Set();
this._joinedAt = new Map();
// Sessions whose join snapshot has gone out, so the 'ready' handshake and
// the fallback timer cannot both send it.
this._joinSnapshotSent = new Set();
// King of the Totem (R07): off-schema round + score state. `phase` is the
// round machine ('idle' waiting for players | 'active' round running |
// 'intermission' showing the winner). `scores` is sessionId → accumulated
// points for the CURRENT round (floats; rounded only for display). `kingId`
// is the current sole occupant (null when empty or contested). `winner` is
// the last completed round's result, surfaced during the intermission.
this._king = {
phase: 'idle',
roundId: 0,
startedAt: 0,
endsAt: 0,
nextAt: 0,
lastTickAt: 0,
scores: new Map(),
kingId: null,
winner: null,
};
}
async onCreate(options) {
this.setState(new WalkState());
this.setPatchRate(PATCH_RATE_MS);
this.autoDispose = true;
// Reachable by the operator /internal/announce webhook for live events.
registerWalkRoom(this);
// Version-skew tolerance: a message type this build doesn't know must be
// ignored, never close the session (Colyseus's default 4002 kill looked
// like "session expired" to pre-fix clients). See room-compat.js.
installUnknownMessageGuard(this, 'walk_world');
// Pull the live event config now, off the join path, so the first player
// through the door during a meetup gets their souvenir from a warm cache
// instead of waiting on an HTTP round-trip. Non-blocking and fail-open.
warmEventDrop();
// A coin world's identity (name, symbol, image) comes from the coin's own
// record, fetched in _resolveCoinCreator, never from the first client to
// land here: join options are unsigned, so trusting them would let that
// client mislabel a real mint's world for everyone in the room.
this.state.coin = cleanCoin(options?.coin);
this.state.coinName = '';
this.state.coinSymbol = '';
this.state.coinImage = '';
// Tier identity. The Holders world records the USD floor it gated on (from
// the joining pass) so the client HUD can state the requirement; the General
// world leaves both blank/zero.
this.state.tier = cleanTier(options?.tier);
if (this.state.tier === 'holders') {
// The displayed floor comes from the signed pass (the issuer's real
// HOLDER_MIN_USD), not the client's unsigned `holderMinUsd` option which a
// malicious first-joiner could otherwise use to misstate the requirement
// for everyone in the room. Fall back to the server's own env, then 8.
const signedPass = verifyHolderPass(options?.holderPass);
const signed = signedPass?.minUsd;
const envMin = Number(process.env.HOLDER_MIN_USD);
this.state.holderMinUsd = Number.isFinite(signed) && signed > 0
? signed
: (Number.isFinite(envMin) && envMin > 0 ? envMin : 8);
// R24: when the creator pinned a token threshold, record it from the signed
// pass (never the unsigned option) so the HUD states "hold N $SYM to enter".
const signedTokens = signedPass?.minTokens;
this.state.holderMinTokens = Number.isFinite(signedTokens) && signedTokens > 0 ? signedTokens : 0;
}
// Persisted-build key. General and Holders are separate worlds for the same
// coin, so their voxel builds must persist independently, otherwise the two
// rooms would load and flush over each other's creation.
this.worldKey = this.state.tier === 'holders' ? `${this.state.coin}#holders` : this.state.coin;
// Join-snapshot handshake.
//
// Everything this room sends a client during onJoin (guest token, profile,
// quests, build permissions, the King of the Totem sync) goes out while the
// client is still inside `await client.joinOrCreate(...)`, before it has
// attached a single onMessage handler. Colyseus drops a message no handler
// claims and warns; on a machine slow enough to matter the whole snapshot
// lands in that gap. Measured on 2026-09-02 against this room: guestToken,
// profile, quests and build-perms each reported "onMessage() not registered"
// twice in one session, so a guest lost the very token that lets their
// device reclaim its progression, and the HUD came up without a purse.
//
// The client says 'ready' once its handlers are attached, and we send the
// snapshot again. Deliberately additive: the original onJoin sends are
// untouched, so a client on an older bundle that never says 'ready' behaves
// exactly as before, and a client that does gets the data whatever the
// timing. Every payload is a full snapshot, so receiving it twice is a
// repaint with identical values, never a double-grant.
this.onMessage('ready', (client) => {
this._readyClients.add(client.sessionId);
this._flushJoinSnapshot(client, { force: true });
});
this.onMessage('move', (client, payload) => this._handleMove(client, payload));
this.onMessage('rename', (client, payload) => this._handleRename(client, payload));
this.onMessage('emote', (client, payload) => this._handleEmote(client, payload));
this.onMessage('chat', (client, payload) => this._handleChat(client, payload));
this.onMessage('avatar', (client, payload) => this._handleAvatar(client, payload));
this.onMessage('play-pass', (client, payload) => this._handlePlayPassRefresh(client, payload));
this.onMessage('place', (client, payload) => this._handlePlace(client, payload));
this.onMessage('place-batch', (client, payload) => this._handlePlaceBatch(client, payload));
this.onMessage('remove', (client, payload) => this._handleRemove(client, payload));
this.onMessage('build-clear', (client, payload) => this._handleBuildClear(client, payload));
this.onMessage('voice-state', (client, payload) => this._handleVoiceState(client, payload));
this.onMessage('voice-signal', (client, payload) => this._handleVoiceSignal(client, payload));
// Economy & activities (off-schema). The owning client drives these and
// receives the authoritative result via profile/inv/xpgain/levelup/notice.
this.onMessage('fish', (client) => this._handleFish(client));
registerActivityHandlers(this); // W06 gather/craft: chop, mine, cook
registerSpinHandlers(this); // W09 Wheel of Fortune: spinInfo, spinFree, spinPaidPrep, spinPaidSettle
registerCombatHandlers(this); // W07 combat: attack, loot
this.onMessage('equip', (client, payload) => this._handleEquip(client, payload));
this.onMessage('consume', (client, payload) => this._handleConsume(client, payload));
// General store, bank/ATM, and the $THREE boutique (W04). Cash trades and
// banking settle purely off-schema; the boutique settles a real on-chain
// $THREE payment (game-token.js) before granting a premium cosmetic.
this.onMessage('storeReq', (client) => { if (this._actionOk(client.sessionId, 'store')) this._sendStore(client); });
this.onMessage('storeBuy', (client, payload) => this._handleStoreBuy(client, payload));
this.onMessage('storeSell', (client, payload) => this._handleStoreSell(client, payload));
this.onMessage('bank', (client, payload) => this._handleBank(client, payload));
this.onMessage('boutiqueReq', (client) => { if (this._actionOk(client.sessionId, 'boutique')) this._sendBoutique(client); });
this.onMessage('boutiqueQuote', (client, payload) => this._handleBoutiqueQuote(client, payload));
this.onMessage('boutiqueSettle', (client, payload) => this._handleBoutiqueSettle(client, payload));
// Equip/unequip a cosmetic from the owned-inventory (R23). Server-authoritative:
// validates ownership, persists the loadout to the account, re-publishes it on
// the schema so peers re-render, and echoes the owner a fresh profile.
this.onMessage('equip-cosmetic', (client, payload) => this._handleEquipCosmetic(client, payload));
// Full-loadout broadcast (R03): replaces the player's entire equipped state in
// one shot, re-validated against ownership, mirrors how `avatar` is sent.
this.onMessage('set-cosmetics', (client, payload) => this._handleSetCosmetics(client, payload));
this.onMessage('profileReq', (client) => { if (this._actionOk(client.sessionId, 'profile')) this._sendProfile(client); });
// Quests, jobs & heists (W05, off-schema). The board, accepting/abandoning a
// mission, and acting at a quest object all flow through here; the server is the
// sole authority for objective progress and reward grants.
this.onMessage('questReq', (client) => { if (this._actionOk(client.sessionId, 'questBoard')) this._sendQuests(client); });
this.onMessage('questAccept', (client, payload) => this._handleQuestAccept(client, payload));
this.onMessage('questAbandon', (client, payload) => this._handleQuestAbandon(client, payload));
this.onMessage('questInteract', (client) => this._handleQuestInteract(client));
// The live event's leaderboard, proxied for the in-world panel so the client
// reads the SAME ranking the web endpoint serves (api/play/event-leaderboard).
this.onMessage('eventBoardReq', (client) => this._sendEventBoard(client));
// Vehicles. The driver streams 'vsync' (the Rapier-simulated transform); the
// server validates per-type speed/bounds and relays. 'venter'/'vexit' take and
// release the wheel, gated by proximity and single-occupancy.
this.onMessage('venter', (client, payload) => this._handleVehicleEnter(client, payload));
this.onMessage('vexit', (client, payload) => this._handleVehicleExit(client, payload));
this.onMessage('vsync', (client, payload) => this._handleVehicleSync(client, payload));
// Generic world objects (R01): spawn/move/remove balls, props and pickups on
// the shared `objects` map. Durable build props placed here persist per coin
// world (R17); transient kinds (the R05 ball) live only for the session.
this.onMessage('obj:spawn', (client, payload) => this._handleObjSpawn(client, payload));
this.onMessage('obj:update', (client, payload) => this._handleObjUpdate(client, payload));
this.onMessage('obj:remove', (client, payload) => this._handleObjRemove(client, payload));
// R05 physics ball: client sends kick intent with impulse; server validates,
// applies velocity, and integrates physics on its own tick. Clients never move
// the ball directly, ownerId is 'server', blocking obj:update from them.
this.onMessage('ball:kick', (client, payload) => this._handleBallKick(client, payload));
// Broadcast reactions (R04): a client sends an emoji; the server rate-limits
// and rebroadcasts to all clients in the room (including the sender).
this.onMessage('reaction', (client, payload) => this._handleReaction(client, payload));
this._emoteCooldowns = new Map();
this._reactionCooldowns = new Map();
this._editCounters = new Map(); // sessionId → { windowStart, count }
this._batchCounters = new Map(); // sessionId → { windowStart, count } for composite stamps
this._voiceCounters = new Map(); // sessionId → { windowStart, count }
this._objCounters = new Map(); // sessionId → { windowStart, count } for obj:* ops
this._objSeq = 0; // monotonic counter for server-minted object ids
// Rehydrate this coin's persisted build before the first client renders the
// world, so newcomers always drop into the community's existing creation.
try {
const saved = await blockStore.load(this.worldKey);
for (const [key, rec] of saved) {
const b = new Block();
b.t = rec.t;
this.state.blocks.set(key, b);
// Rehydrate ownership + density so the per-player cap, column cap, and
// the "only the placer (or creator) may delete" rule hold for a build
// that was placed before this process started.
this._trackPlacement(key, rec.o || '');
}
if (saved.size) {
console.log(`[walk_world ${this.roomId} coin=${this.state.coin || 'mainland'}] restored ${saved.size} blocks`);
}
} catch (err) {
console.warn(`[walk_world ${this.roomId}] block restore failed:`, err?.message);
}
// Rehydrate this coin's durable placed objects (R17), the build props the
// community left behind, from the per-world persistence store before the
// first client renders, mirroring how blocks are restored above. The store is
// keyed by world id; mainland (empty coin) gets a stable fallback key. Blocks
// and objects share the world key but live in separate backends, so they
// don't collide. load() never throws (it falls back to its memory mirror).
this._objKey = this.worldKey || 'mainland';
try {
const { doc } = await worldPersistence.load(this._objKey);
this._restoreObjects(doc);
} catch (err) {
console.warn(`[walk_world ${this.roomId}] object restore failed:`, err?.message);
}
// Warm the event-window cache before the first player asks for the jobs board.
// The gate fails closed on a cold miss, so priming it here is the difference
// between a live event's jobs appearing instantly and appearing a minute late.
refreshEventWindow().catch(() => { /* the gate stays closed until it reads */ });
// Tell builders, honestly, whether this world survives a server restart.
// load() above already awaited the store's readiness probe, so durability
// is settled by now.
await blockStore.ready();
this.state.persistent = blockStore.durable;
// Tell clients this build answers 'ready' (see the handshake registration
// above). Gating on a schema flag rather than a version guess is what makes
// the client safe to deploy before or after this server.
this.state.acceptsReady = true;
// Seed this world's drivable fleet. Vehicles are world entities (everyone sees
// them) so they ride on the synced state, parked until someone takes the wheel.
// Spawned for every coin world, driving is a core verb, not a flagship-only
// affordance. v1 fleet is ephemeral per room (re-spawned fresh each time the
// room is created); persistence of parked vehicles is a later concern.
this._seedVehicles();
// W07: seed the PvE mob roster into the danger zones, then start the AI +
// heat-decay ticks. Two independent intervals (mob AI is coarser than the
// per-second heat decay) so tuning one never nudges the other's cadence.
seedMobs(this);
this.clock.setInterval(() => tickMobs(this, MOB_TICK_MS), MOB_TICK_MS);
this.clock.setInterval(() => tickHeat(this, HEAT_TICK_MS), HEAT_TICK_MS);
// R05: spawn the shared beach ball at world centre and start its physics tick.
// Server-owned (ownerId = SERVER_OBJECT_OWNER) so no client can move or remove
// it via the generic obj:update / obj:remove channels.
this._spawnBall();
this.clock.setInterval(() => this._tickBall(), BALL_TICK_MS);
// Resolve this coin's on-chain creator so the build-permission layer can grant
// the creator world-wide moderation (delete any piece, clear an area). Fetched
// once, off the hot path; a failure just leaves the world without a creator
// (no moderation tool), never blocks the room. The mainland world has no coin
// and therefore no creator.
this._resolveCoinCreator();
// Re-check policy for the token gate. The game server has no RPC of its own,
// so "still holding the token" is re-proven by the client minting a fresh
// play pass (which re-reads the chain) before the current one's 10-min TTL
// runs out and reconnecting, onAuth then re-validates. To actively evict a
// wallet that offloaded below the floor mid-session, we sweep once a minute
// and disconnect any client whose bound pass has expired without a refresh.
// The client refreshes ahead of expiry, so a holder never sees this; only a
// wallet that stopped qualifying (or a forged-then-expired pass) gets dropped.
if (PLAY_GATE_MINT) {
this.clock.setInterval(() => {
const nowS = Date.now() / 1000;
for (const client of this.clients) {
const exp = client.userData?.playExp;
if (typeof exp === 'number' && exp < nowS) {
try { client.leave(PLAY_PASS_EVICT_CODE, 'play_pass_required'); } catch {}
}
}
}, 60_000);
}
// Tag mini-game (R08): refresh the leaderboard time values for all clients
// periodically so the displayed "time as it" increments visibly even without
// a tag event. Only fires when the game is active (an "it" player exists).
this.clock.setInterval(() => {
if (this._itPlayer()) this._broadcastTagState();
}, TAG_LB_INTERVAL_MS);
// Dance floor beat, every 4 s, aligned across all clients in the room so
// avatars standing on the disco pad start the same crossfade at the same
// wall-clock moment. Clip rotates through the four dance animations.
const DANCE_FLOOR_CLIPS = ['av-dance-shuffle', 'av-rap-dance', 'av-headbang', 'dance'];
let _beatIdx = 0;
this.clock.setInterval(() => {
this.broadcast('floor:beat', { clip: DANCE_FLOOR_CLIPS[_beatIdx++ % DANCE_FLOOR_CLIPS.length] },
{ except: this._stillDeaf() });
}, 4000);
// King of the Totem (R07): the single authoritative clock that runs the round
// machine, awards points to a sole zone occupant, ends a round on time, and
// schedules the next one. One interval drives scoring, the countdown, and the
// idle→active→intermission transitions so the timing can never drift apart.
this.clock.setInterval(() => this._kingTick(), KING_TICK_MS);
}
async onJoin(client, options) {
// A hate-slur display name never reaches a nameplate: fall back to the
// guest handle, same narrow whole-word gate the platform uses on indexed
// third-party names (see display-name-safety.js).
let name = clean(options?.name, 24) || `guest-${client.sessionId.slice(0, 4)}`;
if (containsHateSlur(name)) name = `guest-${client.sessionId.slice(0, 4)}`;
const player = new Player();
player.id = client.sessionId;
player.name = name;
player.color = pickPlayerColor(client.sessionId);
player.x = 0;
player.y = 0;
player.z = 0;
player.yaw = 0;
player.motion = 'idle';
player.avatar = cleanAvatarUrl(options?.avatar);
player.agent = clean(options?.agent, 64);
// The account id is the wallet verified in onAuth, bound server-side, never
// from a client option, so it's a trustworthy persistence + social-graph key.
player.account = clean(client.userData?.account, 64);
player.tsServer = Date.now();
this.state.players.set(client.sessionId, player);
// Friends presence (Task 15): a presence ticket signed by the three.ws API
// proves which account this socket belongs to, independent of the wallet
// holder gate. Register it so friends see this player as online in this
// coin world and can DM them live. Spoof-proof, the account id comes from
// the verified ticket, never a raw client option.
const presence = verifyPresenceTicket(options?.presence);
if (presence?.uid) {
client.userData = { ...(client.userData || {}), accountUid: presence.uid };
socialHub.register(presence.uid, client, this.state.coinName || 'Mainland');
// Verified three.ws profile (W10): publish the ticket's username on the
// schema so every peer can open this player's real profile, follow them,
// and DM them. Trustworthy by construction, it came out of the signed
// ticket, so nobody can wear a handle they don't own. A signed-in player
// who never picked a nameplate gets their account display name instead of
// an anonymous guest-xxxx handle.
player.username = clean(presence.username, 30);
if (!clean(options?.name, 24) && presence.displayName && !containsHateSlur(presence.displayName)) {
player.name = clean(presence.displayName, 24) || player.name;
}
}
// Economy profile (off-schema). Keyed to a VERIFIED account only: the wallet
// from onAuth when the platform gate is on, else a wallet proven by a signed
// play pass the client volunteered, else a server-minted guest id sealed in
// an HMAC guest token (guest-token.js). A raw `pid` join option is never an
// account key anymore, it let any client load, spend, and overwrite any
// victim's saved profile (gold, bank, items, cosmetics) just by asserting
// their id. Legacy `guest-…` pids migrate once (see _resolveIdentity).
const identity = await this._resolveIdentity(client, options);
const playerId = identity.playerId;
// Bind the verified persistence key to the session, then retire this same
// player's superseded session if they are reconnecting into a socket the
// transport has not reaped yet. Keyed on the identity resolved above, never
// on a raw client-asserted pid, so it can't be aimed at anyone else.
client.userData = { ...(client.userData || {}), playerKey: playerId };
this._evictPriorSession(client, playerId, clean(options?.prevSession, 32));
if (identity.wallet && !client.userData?.account) {
// The play pass proved this wallet even though the platform gate is off,
// bind it as the session account so ownership + moderation checks and the
// on-schema account field agree with the persistence key.
client.userData = { ...(client.userData || {}), account: identity.wallet };
player.account = clean(identity.wallet, 64);
}
if (identity.guestToken) {
// Hand the (re-)signed token back so the client persists it and replays
// it on the next join. Re-issued every join so an active guest's 90-day
// expiry never creeps up on them.
// Held, not sent: it goes out with the rest of the join snapshot once the
// client can hear it. See _scheduleJoinSnapshot.
this._guestTokens.set(client.sessionId, identity.guestToken);
}
try { await hydratePlayer(playerId); } catch { /* memory-only fallback */ }
// A slower-arriving leave could fire while we awaited; bail if so.
if (!this.state.players.has(client.sessionId)) return;
const saved = loadPlayer(playerId);
const profile = restoreProfile(saved?.profile, playerId);
// Second belt on the respawn-window disconnect bug: a profile that somehow
// persisted at (or drifted to) zero HP would otherwise come back walking
// but one hit from an instant re-death loop. Death already took its toll
// when the tombstone spilled; rejoining always means standing back up.
if (!(profile.hp > 0)) reviveProfile(profile);
profile.cd = { fish: 0, consume: 0, chop: 0, mine: 0, cook: 0, attack: 0, pickupRod: 0 }; // per-action cooldown clocks (runtime only)
// Quest log (W05): the player's accepted/completed missions + daily state,
// persisted alongside the pack/purse. Stale dailies roll over to today on load.
profile.quests = restoreQuestState(saved?.profile?.quests, utcDayKey());
profile._zone = null; // last quest zone the player was inside (enter-zone edge detect)
this.econ.set(client.sessionId, profile);
// Cosmetics ownership (R22 → R23): fold the premium cosmetics this account
// bought over the x402 rail into its unlocked set, so a purchase persists and
// equips in EVERY world the account joins, not just the one it was bought in.
// The ledger is keyed by the same account id as the profile (playerId), reads
// fail-open (own nothing extra) and never block the join. Persist only when a
// new unlock actually landed so a returning player keeps it across restarts.
try {
const newlyOwned = mergeOwnedFromLedger(profile, await readOwnedCosmetics(playerId));
if (newlyOwned > 0) this._persistEcon(client.sessionId);
} catch (err) {
console.warn(`[walk_world] cosmetics ledger seed failed for ${playerId}:`, err?.message);
}
// A slower-arriving leave could have fired while we awaited the ledger.
if (!this.state.players.has(client.sessionId)) return;
// Event souvenir: if a community event is live in THIS world right now,
// everyone who walks in keeps a free commemorative wearable. Runs before
// the loadout is applied so a player who already owns it can arrive with
// it equipped from a prior session.
await this._grantEventSouvenir(client, profile);
if (!this.state.players.has(client.sessionId)) return;
// Cosmetics (W03): apply any loadout the player chose pre-join (in the
// character creator) on top of their persisted one, validating each id
// against what they own, free cosmetics always pass, premium only when
// unlocked, so a join option can never put an unowned cosmetic on a player.
// Then publish the equipped loadout on the schema so peers render the look.
this._applyJoinCosmetics(profile, options?.cosmetics);
player.cosmetics = serializeLoadout(profile.cosmetics.equipped);
// W07: publish the wanted-star count peers can see (dead defaults false).
// A restored profile can carry saved heat from a prior session's crimes.
player.heat = heatStars(profile.heat);
const tierTag = this.state.tier === 'holders' ? ' tier=holders' : '';
console.log(
`[walk_world ${this.roomId} coin=${this.state.coin || 'mainland'}${tierTag}] +join ${client.sessionId} ${name} (n=${this.state.players.size})`,
);
// "Someone is hanging out in <world>", social proof + FOMO on the site-wide
// ticker. Throttled per world so a popular coin emits at most once a minute,
// not once per arrival. Mainland falls back to a friendly label.
publishFeedEvent(
{
type: 'world-join',
ts: Date.now(),
actor: name,
coin: this.state.coin || '',
coinName: this.state.coinName || (this.state.coin ? '' : 'Mainland'),
},
this.state.coin || 'mainland',
);
// Tag mini-game (R08): register this session and start the game if we now
// have enough players. This runs AFTER the hydratePlayer await so the player
// is confirmed still present. Uses a random initial assignment so the first
// player to join isn't always "it" on arrival.
this._joinedAt.set(client.sessionId, Date.now());
this._tagTime.set(client.sessionId, { timeMs: 0, becameIt: null });
if (this.state.players.size >= TAG_MIN_PLAYERS && !this._itPlayer()) {
this._assignIt(this._randomTagPlayer(null));
}
// King of the Totem (R07): give the new arrival a zero score row for the
// current round and immediately sync them the live game state (zone bounds,
// phase, countdown, scoreboard) so their HUD is correct mid-round instead of
// blank until the next broadcast. If the room was idle and now has enough
// players, the next tick starts a round; sync reflects that on the following
// beat. Sending zone + phase here is what lets a late joiner render the ring
// and timer without waiting up to a full second.
if (this._king.phase === 'active') this._king.scores.set(client.sessionId, 0);
// Everything this room owes the new arrival (guest token, profile, quests,
// build permissions, the king sync) goes out together, once they can hear
// it. Sending from here put all of it on the wire while the client was
// still inside its own join await with no handlers attached, so Colyseus
// dropped the lot and warned on their console.
this._scheduleJoinSnapshot(client);
}
// Retire the reconnecting client's OWN previous session.
//
// A socket that dies uncleanly (phone slept, tab froze, wifi handover) stays
// half-open: the transport still reads it as OPEN and only reaps it when its
// ping retries expire, several seconds later. The client reconnects well inside
// that window, so the room briefly holds two sessions for one person, the
// returning player sees a frozen ghost of themselves at spawn, and so does
// everyone else. Liveness cannot be probed synchronously here (that is exactly
// what the half-open socket hides), so the reconnecting client tells us which
// session was its own and we retire that one.
//
// `prevSession` alone would be a kick primitive: session ids are published on
// the player schema, so anyone could name a stranger's. It is only honoured
// together with a matching persistent player key, the wallet the server itself
// verified in onAuth, or a guest id that is never broadcast to peers. A second
// tab or a second device is untouched: each carries its own prior session id.
_evictPriorSession(client, playerKey, prevSession) {
if (!playerKey || !prevSession || prevSession === client.sessionId) return;
for (const other of this.clients) {
if (other === client || other.sessionId !== prevSession) continue;
if (other.userData?.playerKey !== playerKey) continue;
console.log(`[walk_world ${this.roomId}] retiring superseded session ${other.sessionId}`);
try { other.leave(1000); } catch { /* already gone */ }
return;
}
}
onLeave(client) {
if (client.userData?.accountUid) socialHub.unregister(client.userData.accountUid, client);
// Tag mini-game (R08): capture wasIt BEFORE state.players.delete below, so
// we know if someone needs reassigning. Cleanup runs after the delete.
const _tagWasIt = this.state.players.get(client.sessionId)?.it ?? false;
// Resolve this owner's object key up front, _ownerKey reads the econ profile,
// which the block below deletes, so capture it before reaping their objects.
const ownerKey = this._ownerKey(client.sessionId);
// Free any vehicle this player was driving so it parks where it was left and
// becomes available again, otherwise a disconnect would lock a car forever.
this._releaseVehicleOf(client.sessionId);
// Drop the player from any co-op heist instance they were in, so the shared run
// doesn't hold a phantom crew member (and disposes when the last one leaves).
this._leaveHeists(client.sessionId);
// Persist the final economy state and arm a durable flush so progress survives
// the disconnect and the room being torn down when the last player leaves.
const profile = this.econ.get(client.sessionId);
if (profile) {
this._persistEcon(client.sessionId);
if (profile.playerId) { try { flushPlayer(profile.playerId); } catch { /* best-effort */ } }
this.econ.delete(client.sessionId);
}
// Reap this owner's transient objects (R01): balls and fx they spawned die
// with their session. Their durable build props stay as part of the world
// (R17), that's the whole point of persistence.
this._reapOwnerTransients(ownerKey);
this.state.players.delete(client.sessionId);
// Tag mini-game (R08): finalize this player's tracked time, purge immunity,
// and reassign "it" if they were the tagged player and enough peers remain.
this._tagImmunity.delete(client.sessionId);
this._finalizeTagTime(client.sessionId);
if (_tagWasIt) {
if (this.state.players.size >= TAG_MIN_PLAYERS) {
this._assignIt(this._randomTagPlayer(null));
} else {
for (const [, p] of this.state.players) { p.it = false; p.itSince = 0; }
this._broadcastTagState();
}
}
this._tagTime.delete(client.sessionId);
this._guestTokens.delete(client.sessionId);
this._readyClients.delete(client.sessionId);
this._joinedAt.delete(client.sessionId);
this._joinSnapshotSent.delete(client.sessionId);
// King of the Totem (R07): drop their current-round score and demote them if
// they were holding the zone. Their accumulated points are forfeited (a player
// who leaves can't win), and the next tick re-evaluates occupancy from scratch,
// so a departing king never freezes the crown. The round itself keeps running.
this._king.scores.delete(client.sessionId);
if (this._king.kingId === client.sessionId) {
this._king.kingId = null;
if (this._king.phase === 'active') this._broadcastKing('tick');
}
this._moveCounters.delete(client.sessionId);
this._chatCooldowns.delete(client.sessionId);
this._editCounters?.delete(client.sessionId);
this._batchCounters?.delete(client.sessionId);
this._emoteCooldowns?.delete(client.sessionId);
this._reactionCooldowns?.delete(client.sessionId);
this._voiceCounters?.delete(client.sessionId);
this._objCounters?.delete(client.sessionId);
this._actionCounters.delete(client.sessionId);
this._kickCounters?.delete(client.sessionId);
console.log(
`[walk_world ${this.roomId}] -leave ${client.sessionId} (n=${this.state.players.size})`,
);
}
async onDispose() {
unregisterWalkRoom(this);
// Persist the final build so the community's creation survives the room
// being torn down when the last player leaves. Awaited (Colyseus waits on
// the returned promise) so the Redis write lands before the room is gone,
// fire-and-forget here would race the process exiting on a redeploy.
try {
await blockStore.flush(this.worldKey);
} catch (err) {
console.warn(`[walk_world ${this.roomId}] final flush failed:`, err?.message);
}
// Flush the durable placed objects (R17) the same way, any spawn/move/remove
// whose debounce hadn't fired lands before the room is gone, so leaving and
// re-entering (or a redeploy) shows the same build.
try {
await worldPersistence.flush(this._objKey);
} catch (err) {
console.warn(`[walk_world ${this.roomId}] final object flush failed:`, err?.message);
}
// Flush any economy profiles still resident (a redeploy can dispose a room
// with players mid-session) so no progression is lost between the last
// change and the room going away.
try {
await Promise.allSettled([...this.econ.values()]
.map((p) => p.playerId && flushPlayer(p.playerId)).filter(Boolean));
} catch { /* best-effort */ }
console.log(`[walk_world ${this.roomId}] disposed`);
}
_handleMove(client, payload) {
const player = this.state.players.get(client.sessionId);
if (!player) return;
// W07: a downed player is off their feet until the respawn timer clears
// them (killPlayer teleports to SPAWN_POINT itself), reject stray moves so
// a "ragdolled" peer can't be walked around mid-death.
if (player.dead) return;
if (!this._rateOk(client.sessionId)) return;
if (!payload || typeof payload !== 'object') return;
const { x, y, z, yaw, motion } = payload;
if (
typeof x !== 'number' ||
typeof y !== 'number' ||
typeof z !== 'number' ||
typeof yaw !== 'number' ||
!Number.isFinite(x) ||
!Number.isFinite(y) ||
!Number.isFinite(z) ||
!Number.isFinite(yaw)
) {
return;
}
// Max-step clamp, reject teleports.
const dx = x - player.x;
const dz = z - player.z;
if (Math.hypot(dx, dz) > MAX_STEP_M) {
// Don't update position, but allow yaw/motion changes (legitimate
// when the client respawns or recovers from a temporary disconnect).
player.yaw = yaw;
if (MOTION_VALUES.has(motion)) player.motion = motion;
player.tsServer = Date.now();
return;
}
// World bounds clamp, the square open-world district (W01).
player.x = Math.max(-WORLD_BOUND_M, Math.min(WORLD_BOUND_M, x));
player.z = Math.max(-WORLD_BOUND_M, Math.min(WORLD_BOUND_M, z));
player.y = Math.max(-10, Math.min(10, y)); // keep avatars near the ground plane
player.yaw = yaw;
if (MOTION_VALUES.has(motion)) player.motion = motion;
player.tsServer = Date.now();
// Quest progress: detect entering a NEW quest zone (edge-triggered off the
// authoritative position, so a "goto" objective can't be faked from the client).
this._checkZoneEntry(client);
// Tag mini-game (R08): if this mover is "it", check whether they've caught
// an adjacent player. All proximity math uses the server's authoritative
// positions, the client can never claim a tag.
if (player.it) this._checkTag(client.sessionId, player);
}
// Edge-detect quest-zone entry on the server's authoritative position. Emits a
// single 'enter-zone' event when the player crosses into a zone they weren't in
// last tick, never per-frame while standing in it, so survey/patrol objectives
// advance exactly once per visit. Cheap (a handful of zones); only does work when
// the current zone actually changed.
// ─── Tag mini-game helpers (R08) ────────────────────────────────────────────
/** Return the sessionId of the current "it" player, or null if nobody is. */
_itPlayer() {
for (const [id, p] of this.state.players) {
if (p.it) return id;
}
return null;
}
/** Return a random sessionId from state.players, excluding `excludeId`. */
_randomTagPlayer(excludeId) {
const eligible = [];
for (const [id] of this.state.players) {
if (id !== excludeId) eligible.push(id);
}
if (!eligible.length) return null;
return eligible[Math.floor(Math.random() * eligible.length)];
}
/** Assign "it" to `newItId`. Clears the old "it", sets immunity on them,
* starts tracking time for the new one, then broadcasts the new state. */
_assignIt(newItId) {
if (!newItId) return;
const now = Date.now();
// Clear current "it" and give them temporary immunity.
for (const [id, p] of this.state.players) {
if (p.it && id !== newItId) {
p.it = false;
p.itSince = 0;
this._finalizeTagTime(id);
this._tagImmunity.set(id, now + TAG_IMMUNITY_MS);
}
}
// Promote the new "it".
const newIt = this.state.players.get(newItId);
if (!newIt) return;
newIt.it = true;
newIt.itSince = now;
const ts = this._tagTime.get(newItId) || { timeMs: 0, becameIt: null };
ts.becameIt = now;
this._tagTime.set(newItId, ts);
// Notify the newly-tagged client so they get the "YOU'RE IT!" alert.
try {
const clients = this.clients.filter(c => c.sessionId === newItId);
if (clients.length) clients[0].send('tag', { event: 'became-it', itId: newItId });
} catch { /* best-effort */ }
this._broadcastTagState();
}
/** Check whether the "it" player (itId, itPlayer) is close enough to any other
* non-immune player to transfer the tag. Proximity uses the server's positions. */
_checkTag(itId, itPlayer) {
const now = Date.now();
for (const [id, p] of this.state.players) {
if (id === itId) continue;
const immunity = this._tagImmunity.get(id) || 0;
if (now < immunity) continue;
const dx = p.x - itPlayer.x;
const dz = p.z - itPlayer.z;
if (Math.hypot(dx, dz) <= TAG_RANGE_M) {
this._assignIt(id);
break;
}
}
}
/** Accumulate elapsed "it" time for a player into their running total.
* Safe to call even when the player was never "it" (becameIt stays null). */
_finalizeTagTime(sessionId) {
const ts = this._tagTime.get(sessionId);
if (!ts || ts.becameIt === null) return;
ts.timeMs += Date.now() - ts.becameIt;
ts.becameIt = null;
}
/** Broadcast the full tag state (who's "it" + live leaderboard) to all clients. */
_broadcastTagState() {
const itId = this._itPlayer();
const now = Date.now();
const rows = [];
for (const [id] of this.state.players) {
const ts = this._tagTime.get(id);
if (!ts) continue;
let totalMs = ts.timeMs;
if (ts.becameIt !== null) totalMs += now - ts.becameIt;
if (totalMs > 0) {
const p = this.state.players.get(id);
rows.push({ id, name: p?.name || id, timeMs: totalMs });
}
}
rows.sort((a, b) => b.timeMs - a.timeMs);
// Same settling window as the beat and king ticks: this is a periodic state
// broadcast, so a client that misses one gets the next.
this.broadcast('tag', { event: 'state', itId, leaderboard: rows.slice(0, 8) },
{ except: this._stillDeaf() });
}
// ─── King of the Totem helpers (R07) ────────────────────────────────────────
/** Sessions whose authoritative position is inside the king-zone right now.
* Read from the server's clamped positions (never client claims) and skip
* downed players, so the zone can't be held by a corpse or faked from afar. */
_kingOccupants() {
const inside = [];
for (const [id, p] of this.state.players) {
if (p.dead) continue;
const dx = p.x - KING_ZONE.x;
const dz = p.z - KING_ZONE.z;
if (Math.hypot(dx, dz) <= KING_ZONE.r) inside.push(id);
}
return inside;
}
/** The current-round scoreboard: present players sorted high→low, rounded for
* display, capped to the top 8 the HUD shows. A player with no points yet
* still appears (score 0) so the board reads as "everyone's in the running". */
_kingScoreRows() {
const rows = [];
for (const [id, p] of this.state.players) {
const score = this._king.scores.get(id) || 0;
rows.push({ id, name: p.name || id.slice(0, 6), score: Math.round(score) });
}
rows.sort((a, b) => b.score - a.score || a.name.localeCompare(b.name));
return rows.slice(0, 8);
}
/** One authoritative beat: drives scoring, the countdown, and every phase
* transition. Idempotent per second, safe even if a tick is delayed. */
_kingTick() {
const now = Date.now();
const k = this._king;
if (k.phase === 'active') {
// Award the sole occupant points for the real time since the last tick
// (clamped so a stalled interval can't dump a huge lump sum). Contested
// (2+) or empty (0) means nobody scores and there's no king this beat.
const occ = this._kingOccupants();
if (occ.length === 1) {
const dt = Math.min(2, Math.max(0, (now - k.lastTickAt) / 1000));
const id = occ[0];
k.scores.set(id, (k.scores.get(id) || 0) + KING_POINTS_PER_SEC * dt);
k.kingId = id;
} else {
k.kingId = null;
}
k.lastTickAt = now;
if (now >= k.endsAt) this._endKingRound();
else this._broadcastKing('tick');
return;
}
if (k.phase === 'intermission') {
// Hold on the winner, then start the next round once enough players remain
// (otherwise drop back to idle and wait for arrivals).
if (now >= k.nextAt) {
if (this.state.players.size >= KING_MIN_PLAYERS) this._startKingRound();
else { k.phase = 'idle'; this._broadcastKing('idle'); }
}
return;
}
// idle: kick off a round as soon as the world has someone to play.
if (this.state.players.size >= KING_MIN_PLAYERS) this._startKingRound();
}
/** Begin a fresh round: reset scores, stamp the timer, announce the start. */
_startKingRound() {
const now = Date.now();
const k = this._king;
k.phase = 'active';
k.roundId += 1;
k.startedAt = now;
k.endsAt = now + KING_ROUND_MS;
k.lastTickAt = now;
k.kingId = null;
k.winner = null;
k.scores = new Map();
for (const [id] of this.state.players) k.scores.set(id, 0);
this._broadcastKing('start');
}
/** End the active round: pick the highest-scoring PRESENT player as winner
* (a score of 0 across the board ⇒ no winner, an honest "nobody held it"),
* enter the intermission, and announce the result so clients celebrate. */
_endKingRound() {
const now = Date.now();
const k = this._king;
const rows = this._kingScoreRows();
const top = rows.length && rows[0].score > 0 ? rows[0] : null;
k.winner = top ? { id: top.id, name: top.name, score: top.score } : null;
k.phase = 'intermission';
k.kingId = null;
k.nextAt = now + KING_INTERMISSION_MS;
this._broadcastKing('end');
}
/** Shared snapshot of the live game state for both broadcasts and per-client
* sync. Always carries the zone bounds so a client can render the ring without
* hardcoding them, plus the phase, countdown anchors, scoreboard and king. */
_kingSnapshot(event) {
const k = this._king;
return {
event,
phase: k.phase,
roundId: k.roundId,
now: Date.now(),
endsAt: k.endsAt,
nextAt: k.nextAt,
durationMs: KING_ROUND_MS,
zone: KING_ZONE,
kingId: k.kingId,
winner: k.winner,
scores: this._kingScoreRows(),
};
}
/** Broadcast the current game state to everyone in the room. */
_broadcastKing(event) {
this.broadcast('game:king', this._kingSnapshot(event), { except: this._stillDeaf() });
}
/** Clients that have joined but cannot hear us yet.
*
* A room broadcast lands on a client that is still inside its own join await,
* before any onMessage handler exists; Colyseus drops it and logs a warning on
* their console. The join snapshot is handled by the 'ready' handshake, but the
* timed broadcasts (the dance beat, the King of the Totem tick) fire on their
* own schedule and would keep hitting that gap.
*
* So skip a session until it announces itself, and give up waiting after
* JOIN_SETTLE_MS regardless. The deadline is what keeps a client on an older
* bundle, which never sends 'ready', from being excluded forever; it misses at
* most a couple of seconds of a state that re-broadcasts every tick anyway, and
* its king sync is sent directly in onJoin. */
_stillDeaf() {
// Called from the broadcast hot path, including by the unit harnesses that
// drive the round machine on a bare room without the constructor's fields.
// Nobody to hold back is the right answer for all of those.
if (!this._joinedAt?.size || !this.clients) return [];
const now = Date.now();
const out = [];
for (const c of this.clients) {
if (this._readyClients.has(c.sessionId)) continue;
const at = this._joinedAt.get(c.sessionId);
if (at != null && now - at < JOIN_SETTLE_MS) out.push(c);
}
return out;
}
/** Queue the join snapshot for a client that has just arrived.
*
* It is sent the moment they say 'ready', and at JOIN_SNAPSHOT_MS regardless
* for a client on an older bundle that never will. The fallback is short
* because this is the data the HUD is blank without (purse, jobs, build
* allowance), so nobody should be made to wait the full broadcast window
* for it. */
_scheduleJoinSnapshot(client) {
this.clock.setTimeout(() => this._flushJoinSnapshot(client), JOIN_SNAPSHOT_MS);
}
/** Send everything this room owes a new arrival.
*
* The fallback sends at most once. The 'ready' handshake always sends, even
* if the fallback already fired: on a slow client the timer can expire while
* the handlers are still being attached, and a one-shot flush would then have
* spent itself on a client that could not yet hear it. Every payload is a
* snapshot of current state, so a second copy is a repaint, never a grant. */
_flushJoinSnapshot(client, { force = false } = {}) {
const id = client.sessionId;
if (!force && this._joinSnapshotSent.has(id)) return;
if (!this.state.players.has(id)) return; // left before we could tell them anything
this._joinSnapshotSent.add(id);
const token = this._guestTokens.get(id);
if (token) { try { client.send('guestToken', { token }); } catch { /* gone */ } }
try {
this._sendProfile(client);
this._sendQuests(client);
this._sendBuildPerms(client);
this._sendKingSync(client);
} catch { /* a client that vanished between the checks above and here */ }
}
/** Send the current game state to one client (on join), so a mid-round arrival
* sees the correct zone, timer and scoreboard immediately. */
_sendKingSync(client) {
try { client.send('game:king', this._kingSnapshot('sync')); } catch { /* best-effort */ }
}
// ─────────────────────────────────────────────────────────────────────────────
_checkZoneEntry(client) {
const profile = this.econ.get(client.sessionId);
if (!profile) return;
const player = this.state.players.get(client.sessionId);
if (!player) return;
const zone = zoneAt(player.x, player.z);
const id = zone ? zone.id : null;
if (id === profile._zone) return; // no transition
profile._zone = id;
if (id) {
// Authoritative: was this session in the driver's seat of a vehicle at the
// moment it crossed the zone boundary? Never trusted from the client.
const inVehicle = !!this._vehicleDrivenBy(client.sessionId);
this._questEvent(client, profile, { type: 'enter-zone', zone: id, inVehicle });
}
}
// --- Quests, jobs & heists (W05) -------------------------------------------
// The quest engine (quests.js) is pure data + state transitions; this section is
// the room's authority glue: it feeds REAL gameplay events into the engine, pays
// rewards through the same purse/XP idioms the activities use, and manages the
// co-op heist instances that live on the room (this.heists), not on a profile.
// The quest engine's event context: is the platform event running right now?
// Read from the server's own cached copy of public/event.json (event-window.js),
// never from anything a client sent, so the event jobs appear, pay and vanish on
// the real clock. A stale or unreadable config answers "closed".
_questCtx() {
return { eventLive: eventLiveNow() };
}
// Send the owning client its jobs board + active runs ({offers, active, day,
// eventLive}, the shape community-net.js documents). Solo runs come straight from
// the engine's snapshot (which also rolls stale daily state over to today); a heist
// run is overlaid with the crew's SHARED instance so every member's tracker
// shows the same live progress, plus the current crew size.
_sendQuests(client) {
const profile = this.econ.get(client.sessionId);
if (!profile) return;
const ctx = this._questCtx();
// An event job cannot advance or pay once the window shuts, so a run left over
// from it is dropped here rather than left in the tracker as a task that will
// never complete. Told once, not silently.
const dropped = pruneClosedEventRuns(profile.quests, ctx);
if (dropped.length) {
this._persistEcon(client.sessionId);
client.send('notice', {
kind: 'quest', ok: false,
text: 'The event has ended, its jobs have closed for now.',
});
}
const snap = questSnapshot(profile.quests, utcDayKey(), ctx);
for (let i = 0; i < snap.active.length; i++) {
const inst = this.heists.get(snap.active[i].id);
if (inst) {
snap.active[i] = { ...runView(inst.run, missionDef(inst.missionId)), crew: inst.members.size };
}
}
client.send('quests', snap);
}
// Accept a mission off the board. The engine owns the eligibility rules (already
// active, prereqs, daily/once repeats); a refusal is surfaced as a notice, never
// a silent no-op. Accepting a heist joins (or founds) this world's one shared
// instance, the crew advances a single run together and splits the pot at payout.
_handleQuestAccept(client, payload) {
const profile = this.econ.get(client.sessionId);
if (!profile) return;
if (!this._actionOk(client.sessionId, 'quest')) return;
const id = typeof payload?.id === 'string' ? payload.id.slice(0, 64) : '';
const mission = missionDef(id);
if (!mission) return;
const res = acceptMission(profile.quests, id, utcDayKey(), this._questCtx());
if (!res.ok) {
const text = res.reason === 'active' ? 'You already took that job.'
: res.reason === 'daily-done' ? 'That job is done for today, check back tomorrow.'
: res.reason === 'done' ? 'You’ve already completed that job.'
: res.reason === 'event-closed' ? 'That job only runs during the live event.'
: 'That job isn’t available to you yet.';
client.send('notice', { kind: 'quest', ok: false, text });
return;
}
if (isHeist(id)) {
let inst = this.heists.get(id);
if (!inst) {
// First accept founds the instance; the founder's fresh run IS the shared
// run every later member advances (it's never persisted, see quests.js).
inst = { missionId: id, members: new Set(), run: res.run };
this.heists.set(id, inst);
}
inst.members.add(client.sessionId);
// The crew grew, every member's tracker shows the new headcount.
this._sendQuestsToCrew(inst, client.sessionId);
}
this._persistEcon(client.sessionId);
client.send('notice', { kind: 'quest', ok: true, text: `Accepted: ${mission.title}` });
this._sendQuests(client);
}
// Abandon an active mission. Solo progress is simply dropped (a daily can be
// re-accepted the same day); leaving a heist removes this member from the shared
// crew, the rest keep the run, and the instance dissolves with its last member.
_handleQuestAbandon(client, payload) {
const profile = this.econ.get(client.sessionId);
if (!profile) return;
if (!this._actionOk(client.sessionId, 'quest')) return;
const id = typeof payload?.id === 'string' ? payload.id.slice(0, 64) : '';
if (!abandonMission(profile.quests, id).ok) return;
if (isHeist(id)) this._leaveHeistCrew(id, client.sessionId);
this._persistEcon(client.sessionId);
this._sendQuests(client);
}
// Act at the quest object the player is standing at (courier pickup/dropoff, a
// heist terminal, the vault door). The zone comes from the SERVER's authoritative
// position, the client's prompt is a hint, never the authority, and the event
// carries the zone's action so objectiveMatches can tell a pickup from a dropoff.
_handleQuestInteract(client) {
const player = this.state.players.get(client.sessionId);
const profile = this.econ.get(client.sessionId);
if (!player || !profile) return;
if (!this._actionOk(client.sessionId, 'questInteract')) return;
const zone = interactZoneInRange(player.x, player.z);
if (!zone) {
client.send('notice', { kind: 'quest', ok: false, text: 'There’s nothing to use here.' });
return;
}
const inVehicle = !!this._vehicleDrivenBy(client.sessionId);
this._questEvent(client, profile, { type: 'interact', zone: zone.id, action: zone.action, inVehicle });
}
// Feed one real gameplay event (a catch, a zone entry, an interact) into every
// run it could advance. Called from the move path, so it stays cheap: a player
// has a handful of active runs at most, and live heist instances are bounded by
// the mission registry. Solo runs live on the profile; heists advance the crew's
// shared run, any member's action moves everyone, and the finale gates on
// assembly (the whole crew at the door, judged from server positions).
_questEvent(client, profile, event) {
const dayKey = utcDayKey();
const eventLive = eventLiveNow();
let changed = false;
for (const [id, run] of Object.entries(profile.quests.active)) {
const mission = missionDef(id);
if (!mission || mission.kind === 'heist') continue; // heists advance via the shared instance below
// An event job is frozen the moment its window shuts: no progress, no
// payout. The run itself is dropped on the next board read (_sendQuests).
if (mission.event && !eventLive) continue;
const res = applyEvent(run, mission, event);
if (!res.matched) continue;
changed = true;
if (res.missionComplete) this._completeMission(client, profile, mission, dayKey);
}
for (const inst of this.heists.values()) {
if (!inst.members.has(client.sessionId)) continue;
const mission = missionDef(inst.missionId);
if (!mission) continue;
// The finale only lands with the whole crew assembled at its zone, checked
// BEFORE applying, so a lone cracker gets a hint instead of a silent miss.
const obj = mission.objectives[inst.run.stage];
if (obj?.finale && objectiveMatches(obj, event) && !this._heistFinaleReady(client, inst, mission, obj)) continue;
const res = applyEvent(inst.run, mission, event);
if (!res.matched) continue;
if (res.missionComplete) {
this._completeHeist(client, inst, mission, dayKey);
} else {
// Shared progress: the whole crew's trackers move together. The actor's
// own re-send rides on the tail below.
this._sendQuestsToCrew(inst, client.sessionId);
changed = true;
}
}
if (changed) {
this._persistEcon(client.sessionId);
this._sendQuests(client);
}
}
// Pay out a finished solo mission: record it in the lifetime + daily log, grant
// the purse + XP through the standard idioms, toast the client, and echo the
// milestone to the site ticker. The quests re-send rides on the caller's tail.
_completeMission(client, profile, mission, dayKey) {
recordCompletion(profile.quests, mission, dayKey);
const reward = missionReward(mission);
if (reward.gold > 0) creditGold(profile, reward.gold);
if (reward.xp) this._grantXp(client, profile, reward.xp.skill, reward.xp.amount);
this._sendInv(client, profile);
client.send('questComplete', {
id: mission.id, title: mission.title, reward, kind: mission.kind, coop: false, event: !!mission.event,
});
this._publishMissionComplete(client, mission, reward.gold, false);
if (mission.event) this._scoreEventRun(client, profile, mission, reward.gold);
}
// Pay out a finished heist to the LIVE crew: the pot splits evenly (remainder to
// the first member, splitPot loses no gold to rounding), each member's own
// completion log records it, and each gets their share + XP through their own
// client. The instance is consumed, a crew founds a fresh one to run it again.
_completeHeist(client, inst, mission, dayKey) {
const members = [...inst.members];
const reward = missionReward(mission);
const shares = splitPot(reward.gold, members.length);
members.forEach((sid, i) => {
const memberProfile = this.econ.get(sid);
if (!memberProfile) return;
recordCompletion(memberProfile.quests, mission, dayKey);
if (shares[i] > 0) creditGold(memberProfile, shares[i]);
const memberClient = this.clients.find((c) => c.sessionId === sid);
if (memberClient) {
try {
if (reward.xp) this._grantXp(memberClient, memberProfile, reward.xp.skill, reward.xp.amount);
this._sendInv(memberClient, memberProfile);
memberClient.send('questComplete', {
id: mission.id, title: mission.title,
reward: { ...reward, gold: shares[i] },
kind: mission.kind, coop: true, crew: members.length,
});
this._sendQuests(memberClient);
} catch { /* best-effort */ }
}
this._persistEcon(sid);
});
// One ticker line for the whole crew (the total pot), not one per member.
this._publishMissionComplete(client, mission, reward.gold, true);
this.heists.delete(inst.missionId);
}
// The finale gate: a heist only finishes with a big-enough crew ALL standing at
// the finale zone, server positions, never client claims. A failed gate tells
// the actor why, so "nothing happened" is never the answer at the vault door.
_heistFinaleReady(client, inst, mission, obj) {
const need = Math.max(1, mission.party | 0 || 1);
if (inst.members.size < need) {
client.send('notice', { kind: 'quest', ok: false, text: `This job needs a crew of ${need}, recruit before the finale.` });
return false;
}
for (const sid of inst.members) {
const p = this.state.players.get(sid);
const zone = p ? zoneAt(p.x, p.z) : null;
if (!zone || zone.id !== obj.zone) {
client.send('notice', { kind: 'quest', ok: false, text: 'Your whole crew must be at the door for this.' });
return false;
}
}
return true;
}
// Re-send the quest snapshot to every member of a heist crew (optionally skipping
// one, the actor, whose re-send rides on the caller). Best-effort per client so
// a mid-send disconnect can't break the loop for the rest of the crew.
_sendQuestsToCrew(inst, exceptSessionId = null) {
for (const sid of inst.members) {
if (sid === exceptSessionId) continue;
const c = this.clients.find((cc) => cc.sessionId === sid);
if (!c) continue;
try { this._sendQuests(c); } catch { /* best-effort */ }
}
}
// Drop one member from one heist crew; dissolves the instance with its last
// member, otherwise tells the remainder their headcount changed.
_leaveHeistCrew(missionId, sessionId) {
const inst = this.heists.get(missionId);
if (!inst || !inst.members.delete(sessionId)) return;
if (inst.members.size === 0) {
this.heists.delete(missionId);
return;
}
this._sendQuestsToCrew(inst);
}
// Drop a departing session from EVERY heist crew (onLeave) so no shared run holds
// a phantom member. Never throws, it runs inside the leave teardown.
_leaveHeists(sessionId) {
for (const id of [...this.heists.keys()]) {
try { this._leaveHeistCrew(id, sessionId); } catch { /* best-effort */ }
}
}
// "Someone pulled off <mission>" on the site-wide ticker (the reader documents
// mission-complete as { mission, gold, coop, coin }). Throttled per
// player+mission so a repeatable grind can't spam the global feed.
_publishMissionComplete(client, mission, gold, coop) {
const player = this.state.players.get(client.sessionId);
publishFeedEvent(
{
type: 'mission-complete',
ts: Date.now(),
actor: player?.name || 'A player',
mission: mission.title,
gold,
coop,
coin: this.state.coin || '',
},
`${player?.account || client.sessionId}:${mission.id}`,
);
// Per-user bell notification, distinct from the anonymous ticker above,
// only fires for a player whose presence ticket verified a real account.
const accountUid = client.userData?.accountUid;
if (accountUid) {
reportQuestComplete({ accountUid, mission: mission.title, gold, coop, coin: this.state.coin || '' });
}
}
// --- Live event: quest line + leaderboard ----------------------------------
// The event jobs pay ordinary in-world gold through the same path as every other
// mission (above); this section only RANKS them. Nothing here pays a prize: the
// board names the winners and the owner settles them by hand after the event.
// Score one finished event quest on the durable leaderboard. Keyed to the same
// verified account the profile persists under (never a client-asserted id), and
// fire-and-forget: the player has already been paid in-world, so a slow or down
// API costs a ranking update, never the reward. The player's own updated totals
// come back on the reply and are pushed straight to their panel.
_scoreEventRun(client, profile, mission, gold) {
const account = profile?.playerId;
if (!account) return;
const player = this.state.players.get(client.sessionId);
const win = eventWindow();
reportEventRun({
eventId: win?.id || '',
account,
name: player?.name || '',
missionId: mission.id,
gold,
}).then((result) => {
if (!result?.ok) return;
try { client.send('eventScore', { runs: result.runs, cash: result.cash, eventId: result.eventId }); } catch { /* client left */ }
}).catch(() => { /* reported inside the bridge */ });
}
// Serve the in-world leaderboard panel. Proxies the same public endpoint the web
// reads (cached in event-score.js so a crowded plaza is one upstream read per few
// seconds) and pins the caller's own row by their verified account key, which
// never leaves the server. An unreachable board answers { ok: false } so the panel
// renders its error state instead of an invented ranking.
async _sendEventBoard(client) {
if (!this._actionOk(client.sessionId, 'eventBoard')) return;
const profile = this.econ.get(client.sessionId);
if (!profile) return;
const board = await fetchEventBoard({ account: profile.playerId || '', limit: 10 });
try {
if (!board) {
client.send('eventBoard', { ok: false, reason: 'unavailable' });
return;
}
client.send('eventBoard', { ok: true, ...board });
} catch { /* client left mid-read */ }
}
_handleRename(client, payload) {
const player = this.state.players.get(client.sessionId);
if (!player) return;
if (!this._actionOk(client.sessionId, 'rename')) return;
const name = clean(payload?.name, 24);
if (!name) return;
// Same narrow whole-word hate-slur gate the platform applies to indexed
// display names. A refused rename is a silent no-op: the previous name
// stands, and there is nothing to explain to someone probing the filter.
if (containsHateSlur(name)) return;
player.name = name;
}
_handleEmote(client, payload) {
const player = this.state.players.get(client.sessionId);
if (!player) return;
const name = clean(payload?.name, 32);
if (!name) return;
const now = Date.now();
const lastEmote = this._emoteCooldowns.get(client.sessionId) || 0;
if (now - lastEmote < 2000) return;
this._emoteCooldowns.set(client.sessionId, now);
player.emote = name;
player.emoteTs = now;
}
_handleReaction(client, payload) {
const player = this.state.players.get(client.sessionId);
if (!player) return;
const ALLOWED = ['🎉', '😂', '🔥', '❤️', '👏', '🤔'];
const emoji = typeof payload?.emoji === 'string' ? payload.emoji.trim() : '';
if (!ALLOWED.includes(emoji)) return;
const now = Date.now();
const last = this._reactionCooldowns.get(client.sessionId) || 0;
if (now - last < 500) return;
this._reactionCooldowns.set(client.sessionId, now);
this.broadcast('reaction', { id: client.sessionId, emoji });
}
_handleChat(client, payload) {
const player = this.state.players.get(client.sessionId);
if (!player) return;
const text = clean(payload?.text, 200);
if (!text) return;
// Narrow whole-word hate-slur gate (see display-name-safety.js): deliberately
// NOT a profanity filter (crypto chat is crude by nature), but a slur is
// never relayed to fifty screens with our nameplate UI around it.
if (containsHateSlur(text)) return;
// One message per 700ms per client, enough for conversation, not spam.
const now = Date.now();
const last = this._chatCooldowns.get(client.sessionId) || 0;
if (now - last < 700) return;
this._chatCooldowns.set(client.sessionId, now);
// Relay to everyone (including the sender, so their own bubble is driven
// by the same authoritative event the others see).
this.broadcast('chat', { id: client.sessionId, name: player.name, text, ts: now });
}
_handleAvatar(client, payload) {
// Lets a client swap avatar mid-session (e.g. after picking a new one)
// without rejoining the room.
const player = this.state.players.get(client.sessionId);
if (!player) return;
if (!this._actionOk(client.sessionId, 'avatar')) return;
const url = cleanAvatarUrl(payload?.avatar);
if (url) player.avatar = url;
if (typeof payload?.agent === 'string') player.agent = clean(payload.agent, 64);
}
// --- Spatial voice (WebRTC) ---------------------------------------------
// The room never touches audio: it only flips a per-player "in voice" flag so
// peers know who to connect to, and relays SDP/ICE between two specific peers.
_handleVoiceState(client, payload) {
const player = this.state.players.get(client.sessionId);
if (!player) return;
if (!this._actionOk(client.sessionId, 'voiceState')) return;
player.voice = !!(payload && payload.on);
}
_handleVoiceSignal(client, payload) {
if (!this.state.players.has(client.sessionId)) return;
if (!payload || typeof payload !== 'object') return;
const to = typeof payload.to === 'string' ? payload.to : '';
if (!to || to === client.sessionId) return;
const data = payload.data;
if (!data || typeof data !== 'object') return;
if (!this._voiceOk(client.sessionId)) return;
// SDP/ICE are small; reject anything oversized rather than relay it.
let size = 0;
try { size = JSON.stringify(data).length; } catch { return; }
if (size > MAX_VOICE_SIGNAL_BYTES) return;
const target = this.clients.find((c) => c.sessionId === to);
if (!target) return;
target.send('voice-signal', { from: client.sessionId, data });
}
_voiceOk(sessionId) {
const now = Date.now();
let bucket = this._voiceCounters.get(sessionId);
if (!bucket || now - bucket.windowStart > 1000) {
bucket = { windowStart: now, count: 0 };
this._voiceCounters.set(sessionId, bucket);
}
bucket.count++;
return bucket.count <= VOICE_SIGNALS_PER_SEC_LIMIT;
}
// --- Economy & activities ------------------------------------------------
// Send the owning client its full economy snapshot (purse, vitals, pack,
// hotbar, per-skill level + bar boundaries). Sent on join and on demand.
_sendProfile(client) {
const profile = this.econ.get(client.sessionId);
if (!profile) return;
client.send('profile', profileSnapshot(profile));
}
// Send just the mutable economy slice after a change the client can't infer
// (a catch, an eat, a purse change), lighter than a full profile resend.
_sendInv(client, profile) {
client.send('inv', {
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,
gold: profile.gold,
hp: profile.hp,
maxHp: profile.maxHp,
// W07: armor + wanted heat ride along on every inv delta so the combat
// HUD never has to guess at a value a hit/consume/loot just changed.
armor: profile.armor,
maxArmor: profile.maxArmor,
heat: profile.heat,
});
}
// Grant XP and tell the earner: the gain (for the float), their new cumulative
// XP + level boundaries (for an exact bar), and a level-up when one is crossed.
_grantXp(client, profile, skill, amount) {
const res = grantXp(profile, skill, amount);
if (!res) return;
client.send('xpgain', {
skill: res.skill, amount: res.amount, xp: res.xp,
level: res.level, levelXp: res.levelXp, nextXp: res.nextXp,
});
if (res.leveledUp) {
client.send('levelup', { skill: res.skill, level: res.level });
// Broadcast milestone level-ups (every 10th + the level-99 cap) to the
// site-wide ticker. Early levels come fast and would be noise; milestones
// are real achievements worth celebrating publicly. Throttled per
// player+skill so a burst can't spam the global feed.
if (res.level === 99 || res.level % 10 === 0) {
const player = this.state.players.get(client.sessionId);
publishFeedEvent(
{
type: 'level-up',
ts: Date.now(),
actor: player?.name || 'A player',
skill: res.skill,
level: res.level,
coin: this.state.coin || '',
},
`${player?.account || client.sessionId}:${res.skill}`,
);
}
}
}
// Cast a line. Validates (rod on the active slot, beside a pond, off cooldown,
// room in the pack) then rolls a catch against fishing skill + pond quality.
// Every cast arms the per-cast cooldown so casting has cadence on the real
// clock; the client renders the line/bobber while the result rides back here.
_handleFish(client) {
const player = this.state.players.get(client.sessionId);
const profile = this.econ.get(client.sessionId);
if (!player || !profile) return;
if (!this._actionOk(client.sessionId, 'fish')) return;
const now = Date.now();
if (now < profile.cd.fish) return; // still reeling in the previous cast
const active = profile.hotbar[profile.activeSlot];
if (!active || active.item !== 'rod') {
client.send('notice', { kind: 'tool', ok: false, text: 'Equip a fishing rod to cast.' });
return;
}
const spot = fishingSpotInRange(player.x, player.z);
if (!spot) {
client.send('notice', { kind: 'fish', ok: false, text: 'Move next to the water to cast.' });
return;
}
if (!hasRoomFor(profile, 'fish')) {
client.send('notice', { kind: 'full', text: 'Your inventory is full.' });
return;
}
profile.cd.fish = now + FISH_COOLDOWN_MS;
const lvl = profile.levels.fishing || 1;
const quality = spot.quality || 1;
if (Math.random() < fishCatchChance(lvl, quality)) {
const want = 1 + (Math.random() < fishDoubleChance(lvl, quality) ? 1 : 0);
const leftover = addItem(profile, 'fish', want);
const caught = want - leftover;
if (caught <= 0) {
client.send('notice', { kind: 'full', text: 'Your inventory is full.' });
return;
}
const xp = Math.round((10 + Math.floor(Math.random() * 6) + lvl * 0.3) * quality) * caught;
this._grantXp(client, profile, 'fishing', xp);
this._sendInv(client, profile);
client.send('notice', { kind: 'fish', ok: true, caught, text: caught > 1 ? `Caught ${caught} ${itemLabel('fish').toLowerCase()}!` : `Caught a ${itemLabel('fish').toLowerCase()}.` });
// Quest progress: a real catch advances any active "collect fish" objective.
this._questEvent(client, profile, { type: 'collect', item: 'fish', qty: caught });
} else {
this._grantXp(client, profile, 'fishing', 2);
client.send('notice', { kind: 'fish', ok: false, caught: 0, text: 'The fish got away.' });
}
this._persistEcon(client.sessionId);
}
// Event souvenir grant. When a community event is live in THIS world, every
// player who joins keeps a free commemorative wearable, a souvenir, not a
// sale: there is no purchase path for it before, during or after.
//
// Server-authoritative and idempotent by construction. The window and the
// world both come from the platform's single event config (event-drop.js
// reading /event.json), never from a client option, and the grant itself is
// grantCosmetic(), which is a no-op on an account that already owns the item.
// So a reconnect, a room hop, or ten rejoins produce exactly one unlock and
// exactly one announcement, the `souvenir` message only goes out on the
// transition from not-owned to owned.
//
// Fail-open on every axis: no config, an unreachable config, a closed window,
// or the wrong world all mean "grant nothing" and never delay the join.
async _grantEventSouvenir(client, profile) {
let drop;
try {
drop = await currentEventDrop();
} catch (err) {
console.warn('[walk_world] event drop config read failed:', err?.message);
return;
}
if (!dropClaimable(drop, this.state.coin, Date.now())) return;
if (!grantCosmetic(profile, drop.cosmeticId)) return; // already theirs
// No _sendProfile here: onJoin sends the authoritative snapshot a few lines
// later, once the loadout has been applied, and the wardrobe reads the new
// item from that one. A second echo would only re-render it for nothing.
this._persistEcon(client.sessionId);
client.send('souvenir', {
id: drop.cosmeticId,
name: drop.cosmeticName,
slot: drop.slot,
eventId: drop.eventId,
eventName: drop.eventName,
});
console.log(
`[walk_world ${this.roomId}] souvenir ${drop.cosmeticId} → ${profile.playerId} (${drop.eventId})`,
);
}
// Dress the player from a pre-join loadout wire (the character-creator / a
// world hand-off in `cosmetics` join option), merged on top of their persisted
// loadout and validated per id against what they own, free cosmetics always
// pass, premium only when unlocked, so a join option can never put an unowned
// cosmetic on a player. Mutates profile.cosmetics.equipped in place.
_applyJoinCosmetics(profile, wire) {
if (!profile.cosmetics) profile.cosmetics = { owned: [], equipped: {} };
if (typeof wire !== 'string' || !wire) return;
const owned = ownedCosmeticSet(profile);
for (const raw of wire.split(',')) {
const id = raw.trim();
const c = getCosmetic(id);
if (c && canWear(id, owned)) profile.cosmetics.equipped[c.slot] = id;
}
}
// Equip/unequip one cosmetic into its slot (R23). The economy validates the id
// is owned (or free) before it moves, an unowned id is rejected, never worn,
// then we re-publish the loadout on the schema (peers re-render the fit), echo
// the owner a fresh profile (inventory reflects the new equipped state), and
// persist to the account so it survives logout and applies in every world.
// Unequip is just equipping the slot's `none` default (always free).
async _handleEquipCosmetic(client, payload) {
const profile = this.econ.get(client.sessionId);
if (!profile) return;
if (!this._actionOk(client.sessionId, 'equip')) return;
const id = typeof payload?.id === 'string' ? payload.id.slice(0, 64) : '';
if (!getCosmetic(id)) {
client.send('notice', { kind: 'cosmetic', ok: false, text: 'That cosmetic doesn’t exist.' });
return;
}
let equipped = equipCosmetic(profile, id);
// Owned-miss on a premium item: the player may have JUST bought it over the
// x402 rail this session, before the profile's unlocked set was refreshed.
// Re-read the R22 ledger once and retry, so a fresh purchase equips without a
// rejoin. (Free items never miss; a genuinely-unowned premium id still falls
// through to the honest rejection below.)
if (!equipped && getCosmetic(id)?.tier === 'premium') {
try {
if (mergeOwnedFromLedger(profile, await readOwnedCosmetics(profile.playerId)) > 0) {
// The await could have outlived the session, bail if they left.
if (!this.econ.has(client.sessionId)) return;
equipped = equipCosmetic(profile, id);
}
} catch (err) {
console.warn('[walk_world] cosmetics ledger recheck failed:', err?.message);
}
}
if (!equipped) {
client.send('notice', { kind: 'cosmetic', ok: false, text: 'You don’t own that cosmetic yet.' });
return;
}
const player = this.state.players.get(client.sessionId);
if (player) player.cosmetics = serializeLoadout(profile.cosmetics.equipped);
this._sendProfile(client);
this._persistEcon(client.sessionId);
}
// Replace the player's entire equipped loadout in one shot (R03). The wire
// is re-validated against the catalog and account ownership before applying,
// any unknown id, any id in the wrong slot, and any unowned premium id are
// silently dropped to the slot default. This is the full-loadout counterpart to
// equip-cosmetic (which changes one slot); the schema update and persist follow
// the same path so peers always re-render the authoritative look.
_handleSetCosmetics(client, payload) {
const profile = this.econ.get(client.sessionId);
if (!profile) return;
if (!this._actionOk(client.sessionId, 'equip')) return;
const wire = typeof payload?.cosmetics === 'string' ? payload.cosmetics.slice(0, 256) : '';
if (!profile.cosmetics) profile.cosmetics = { owned: [], equipped: {} };
// Reset every slot to its bare default, then merge the requested ids.
// Ownership is re-checked per id so a tampered wire can never put an
// unowned cosmetic on a player.
profile.cosmetics.equipped = { ...DEFAULT_LOADOUT };
this._applyJoinCosmetics(profile, wire);
const player = this.state.players.get(client.sessionId);
if (player) player.cosmetics = serializeLoadout(profile.cosmetics.equipped);
this._persistEcon(client.sessionId);
}
// Select a hotbar slot (what the player is "holding"). -1 clears the hand.
_handleEquip(client, payload) {
const profile = this.econ.get(client.sessionId);
if (!profile) return;
if (!this._actionOk(client.sessionId, 'equip')) return;
const i = payload?.slot | 0;
if (i < -1 || i >= HOTBAR_SIZE) return;
profile.activeSlot = i;
this._sendInv(client, profile);
}
// Eat an edible from a referenced slot, healing scaled by cooking level.
_handleConsume(client, payload) {
const profile = this.econ.get(client.sessionId);
if (!profile) return;
if (!this._actionOk(client.sessionId, 'consume')) return;
const now = Date.now();
if (now < profile.cd.consume) return;
const slot = resolveSlot(profile, payload?.slot);
if (!slot) return;
const res = consumeSlot(profile, slot);
if (!res.ok) {
const text = res.reason === 'full' ? 'You’re already at full health.' : 'That can’t be eaten.';
client.send('notice', { kind: 'eat', ok: false, text });
return;
}
profile.cd.consume = now + CONSUME_COOLDOWN_MS;
this._sendInv(client, profile);
client.send('notice', { kind: 'eat', ok: true, text: `+${res.gained} HP.` });
this._persistEcon(client.sessionId);
}
// --- General store & bank/ATM (W04) --------------------------------------
//
// Cash economy, entirely off-schema like the rest of the purse/pack: the
// server prices every trade from shop.js (never a client-supplied number),
// mutates the profile, and echoes the owner a fresh inv/profile snapshot.
// The general store's catalog, sell prices + the buy list, so the client
// renders exactly what the server will charge/pay, no drift possible.
_sendStore(client) {
client.send('store', clientStoreCatalog());
}
// Buy `item` from the general store for cash. Validates the catalog entry,
// the purse, and pack room before moving anything, a rejected buy costs
// nothing and leaves the pack untouched.
// Is this session standing at a counter? Trading and banking are walk-up
// actions like every other station in the world, and the check has to live
// server-side: the NPC panel is the only way an honest client opens them, but
// "you must be at the bank" is exactly what makes the death drop a real risk,
// so it can't rest on the client choosing to enforce it.
_atCounter(client, kind) {
const player = this.state.players.get(client.sessionId);
if (!player) return false;
const near = kind === 'bank' ? atmInRange(player.x, player.z) : vendorInRange(player.x, player.z);
if (near) return true;
client.send('notice', {
kind, ok: false,
text: kind === 'bank'
? 'Step up to the bank teller to move cash.'
: 'Step up to a general store counter to trade.',
});
return false;
}
_handleStoreBuy(client, payload) {
const profile = this.econ.get(client.sessionId);
if (!profile) return;
if (!this._actionOk(client.sessionId, 'storeBuy')) return;
if (!this._atCounter(client, 'store')) return;
const item = typeof payload?.item === 'string' ? payload.item.slice(0, 32) : '';
const entry = buyEntry(item);
if (!entry) {
client.send('notice', { kind: 'store', ok: false, text: 'That item isn’t for sale.' });
return;
}
if (profile.gold < entry.price) {
client.send('notice', { kind: 'store', ok: false, text: `Not enough cash, ${entry.price} needed.` });
return;
}
if (!hasRoomFor(profile, entry.item)) {
client.send('notice', { kind: 'full', text: 'Your inventory is full.' });
return;
}
const leftover = addItem(profile, entry.item, entry.qty);
const bought = entry.qty - leftover;
if (bought <= 0) {
client.send('notice', { kind: 'full', text: 'Your inventory is full.' });
return;
}
profile.gold -= entry.price;
this._sendInv(client, profile);
client.send('notice', { kind: 'store', ok: true, text: `Bought ${bought > 1 ? bought + ' ' : ''}${itemLabel(entry.item)} for ${entry.price} cash.` });
this._persistEcon(client.sessionId);
}
// Sell a stack from a referenced pack slot for cash. `qty` sells up to that
// many (defaults to the whole stack); the price always comes from
// SELL_PRICES server-side, never a client-supplied amount.
_handleStoreSell(client, payload) {
const profile = this.econ.get(client.sessionId);
if (!profile) return;
if (!this._actionOk(client.sessionId, 'storeSell')) return;
if (!this._atCounter(client, 'store')) return;
const slot = resolveSlot(profile, payload?.slot);
if (!slot || !slot.item) {
client.send('notice', { kind: 'store', ok: false, text: 'Nothing there to sell.' });
return;
}
if (!isSellable(slot.item)) {
client.send('notice', { kind: 'store', ok: false, text: `The store won’t buy ${itemLabel(slot.item).toLowerCase()}.` });
return;
}
const want = Number.isFinite(payload?.qty) && payload.qty > 0 ? Math.min(payload.qty | 0, slot.qty) : slot.qty;
const item = slot.item;
const removed = removeItem(profile, item, want);
if (removed <= 0) return;
const total = sellPrice(item) * removed;
creditGold(profile, total);
this._sendInv(client, profile);
client.send('notice', { kind: 'store', ok: true, text: `Sold ${removed} ${itemLabel(item).toLowerCase()} for ${total} cash.` });
this._persistEcon(client.sessionId);
}
// Move cash between the carried purse and the protected bank (the ATM).
// Positive amounts deposit, negative withdraw; bankTransfer clamps to
// what's actually available so it can never mint or strand cash. Banked
// cash is untouched by a death drop (economy.js dropCarried), the whole
// risk/reward point of using the bank.
_handleBank(client, payload) {
const profile = this.econ.get(client.sessionId);
if (!profile) return;
if (!this._actionOk(client.sessionId, 'bank')) return;
if (!this._atCounter(client, 'bank')) return;
const amount = Number.isFinite(payload?.amount) ? payload.amount | 0 : 0;
if (!amount) return;
const moved = bankTransfer(profile, amount);
if (moved === 0) {
client.send('notice', { kind: 'bank', ok: false, text: amount > 0 ? 'No cash on hand to deposit.' : 'Nothing banked to withdraw.' });
return;
}
this._sendProfile(client);
client.send('notice', {
kind: 'bank',
ok: true,
text: moved > 0 ? `Deposited ${moved} cash, protected from drops.` : `Withdrew ${-moved} cash.`,
});
this._persistEcon(client.sessionId);
}
// --- $THREE boutique (W04) -------------------------------------------------
//
// Premium in-game cosmetics (multiplayer/src/cosmetics-catalog.js), priced
// and unlocked entirely separately from the R21, 25 avatar-shop/x402 rail
// (which sells a different catalog, settled in USDC, for the standalone
// character creator). This is the purpose-built W04 rail: the buyer's own
// Solana wallet sends ONE real $THREE transaction (game-token.js), split
// between the holder-rewards pool and the treasury, and the server re-reads
// that transaction from RPC before granting anything, never trusting a
// client "it worked" claim.
// The boutique catalog (priced in $THREE) + this account's owned ids.
_sendBoutique(client) {
const profile = this.econ.get(client.sessionId);
client.send('boutique', {
listings: boutiqueListings(),
owned: [...(profile?.cosmetics?.owned || [])],
configured: tokenConfigured(),
});
}
// Price + build the unsigned $THREE purchase transaction for one boutique
// item. `wallet` is whichever Solana wallet the player has connected in the
// browser, it pays; the unlock always lands on THIS session's profile
// regardless of who fronts the tokens (the same "anyone can settle a quote"
// model buildSpinPayment already uses). The price is read from the server
// catalog only, a client can never move it.
async _handleBoutiqueQuote(client, payload) {
const profile = this.econ.get(client.sessionId);
if (!profile) return;
if (!this._actionOk(client.sessionId, 'boutiqueQuote')) return;
const id = typeof payload?.id === 'string' ? payload.id.slice(0, 64) : '';
const price = boutiquePrice(id);
if (!price) {
client.send('notice', { kind: 'boutique', ok: false, text: 'That item isn’t in the boutique.' });
return;
}
if (ownedCosmeticSet(profile).has(id)) {
client.send('notice', { kind: 'boutique', ok: false, text: 'You already own that.' });
return;
}
const wallet = typeof payload?.wallet === 'string' ? payload.wallet.trim() : '';
if (!isWalletAddress(wallet)) {
client.send('notice', { kind: 'boutique', ok: false, text: 'Connect a Solana wallet to buy with $THREE.' });
return;
}
if (!tokenConfigured()) {
client.send('notice', { kind: 'boutique', ok: false, text: 'The $THREE boutique is offline right now.' });
return;
}
let built;
try {
const amountRaw = BigInt(Math.round(price * 10 ** TOKEN_DECIMALS));
built = await buildTokenPurchase({
buyerWallet: wallet,
amountRaw,
purpose: 'boutique',
// cosmeticId rides to settle; forAccount seals the quote to THIS
// session's profile so a leaked settled quote can't be redeemed by
// another account (verifyTokenPurchase enforces it).
extra: { cosmeticId: id, forAccount: profile.playerId },
});
} catch (err) {
console.warn('[walk_world] boutique quote failed:', err?.message);
}
if (!built) {
client.send('notice', { kind: 'boutique', ok: false, text: 'Could not price that purchase, try again in a moment.' });
return;
}
client.send('boutiqueQuote', { id, price, quoteToken: built.quoteToken, txBase64: built.txBase64 });
}
// Settle a signed $THREE purchase: re-verify the on-chain transaction against
// the sealed quote against live RPC (never the client's "it worked"), then
// grant the cosmetic exactly once per settled nonce.
async _handleBoutiqueSettle(client, payload) {
const profile = this.econ.get(client.sessionId);
if (!profile) return;
if (!this._actionOk(client.sessionId, 'boutiqueSettle')) return;
const quoteToken = typeof payload?.quoteToken === 'string' ? payload.quoteToken : '';
const txSig = typeof payload?.txSig === 'string' ? payload.txSig : '';
if (!quoteToken || !txSig) return;
let result;
try {
result = await verifyTokenPurchase({ quoteToken, txSig, purpose: 'boutique', forAccount: profile.playerId });
} catch (err) {
console.warn('[walk_world] boutique settle failed:', err?.message);
client.send('notice', { kind: 'boutique', ok: false, text: 'Could not verify that payment, try again.' });
return;
}
if (!result?.ok) {
client.send('notice', { kind: 'boutique', ok: false, text: `Payment didn’t verify (${result?.reason || 'unknown'}).` });
return;
}
// Durable, process-wide replay guard (settlement-guard.js). The old
// per-room Map let the same settled payment re-grant in every other coin
// world and after a restart; consumeSettlement is one atomic consumption
// across rooms, restarts, and instances (when Redis is configured).
const fresh = await consumeSettlement({ nonce: result.nonce, txSig, purpose: 'boutique' });
if (!fresh) {
client.send('notice', { kind: 'boutique', ok: false, text: 'That purchase already settled.' });
return;
}
const cosmeticId = result.quote?.cosmeticId;
if (ownedCosmeticSet(profile).has(cosmeticId)) {
client.send('notice', { kind: 'boutique', ok: true, text: 'Payment verified, you already owned this.' });
return;
}
const granted = cosmeticId ? grantCosmetic(profile, cosmeticId) : false;
if (!granted) {
client.send('notice', { kind: 'boutique', ok: false, text: 'Payment verified, but that item couldn’t be unlocked. Contact support.' });
return;
}
this._sendProfile(client);
client.send('notice', { kind: 'boutique', ok: true, text: `Unlocked ${getCosmetic(cosmeticId)?.name || 'the item'}, check your wardrobe.` });
this._persistEcon(client.sessionId);
}
// Resolve the stable persistence identity for a joining session. Trust order:
// 1. The wallet onAuth verified (platform gate on).
// 2. A wallet sealed in a valid play pass the client sent voluntarily,
// possession of the HMAC-signed pass proves the wallet even when the
// gate is off, so signed-in players keep one profile across deploys.
// 3. A guest id sealed in a signed guest token (minted below on a prior
// join). The token, not the id, is the credential.
// 4. One-time migration for legacy clients that persisted a bare `guest-…`
// localStorage pid: honored ONLY if the saved record has never been
// token-upgraded (so a bare claim on an upgraded id gets a fresh guest,
// not the victim's profile), never for wallet-shaped ids, and sealed
// into a signed token on the spot.
// 5. A brand-new server-minted guest id.
// Lanes 3-5 return a fresh token for the client to persist and replay.
async _resolveIdentity(client, options) {
const authed = clean(client.userData?.account, 80);
if (authed) return { playerId: authed, wallet: '', guestToken: '' };
const pass = verifyPlayPass(options?.playPass);
const wallet = clean(pass?.wallet, 80);
if (wallet) return { playerId: wallet, wallet, guestToken: '' };
const sealed = verifyGuestToken(options?.guestToken);
if (sealed) return { playerId: sealed, wallet: '', guestToken: signGuestToken(sealed) };
const legacy =
typeof options?.pid === 'string' && /^guest-[a-z0-9]{4,60}$/i.test(options.pid) ? options.pid : '';
if (legacy) {
try { await hydratePlayer(legacy); } catch { /* memory-only fallback */ }
const rec = loadPlayer(legacy);
if (!rec?.guestUpgraded) {
// Stamp the record so this bare id can never be claimed again; the
// device that holds it from here on holds the signed token instead.
savePlayer(legacy, { ...(rec || {}), guestUpgraded: true });
return { playerId: legacy, wallet: '', guestToken: signGuestToken(legacy) };
}
}
const gid = newGuestId();
return { playerId: gid, wallet: '', guestToken: signGuestToken(gid) };
}
// Write this session's economy profile through to the account-keyed store,
// merging onto any existing record so unrelated fields for the same account
// are preserved. Synchronous + debounced.
_persistEcon(sessionId) {
const profile = this.econ.get(sessionId);
if (!profile || !profile.playerId) return;
const player = this.state.players.get(sessionId);
const prev = loadPlayer(profile.playerId) || {};
savePlayer(profile.playerId, {
...prev,
name: player?.name || prev.name,
gold: profile.gold,
// Fold the quest log into the persisted profile blob so accepted jobs +
// daily state survive a disconnect (economy.js round-trips it opaquely).
profile: { ...serializeProfile(profile), quests: serializeQuestState(profile.quests) },
});
}
// --- Vehicles ------------------------------------------------------------
// Seed the parked fleet from the shared spawn registry. Colors come from each
// type's signature color so the world reads consistently across clients.
_seedVehicles() {
for (const spawn of VEHICLE_SPAWNS) {
if (!isVehicleType(spawn.type)) continue;
const spec = vehicleSpec(spawn.type);
const v = new Vehicle();
v.id = spawn.id;
v.type = spawn.type;
v.color = Number.isInteger(spawn.color) ? spawn.color : spec.color;
v.x = spawn.x;
// Rest the chassis on its suspension, not embedded in the asphalt, see
// vehicleRestHeight's doc for the geometry this mirrors.
v.y = vehicleRestHeight(spawn.type);
v.z = spawn.z;
// Resting heading → quaternion about the up axis.
const half = (spawn.yaw || 0) / 2;
v.qx = 0; v.qy = Math.sin(half); v.qz = 0; v.qw = Math.cos(half);
v.speed = 0;
v.driver = '';
v.health = 100;
v.tsServer = Date.now();
this.state.vehicles.set(v.id, v);
}
}
// Take the wheel of a parked vehicle. Gated by: the vehicle exists, it isn't
// already occupied, and the player is standing within range of it. A player can
// only drive one vehicle, so any prior one is released first. The grant is the
// authoritative `driver` field flipping to this session, the client waits for
// that echo (plus a targeted ack) before it starts simulating.
_handleVehicleEnter(client, payload) {
const player = this.state.players.get(client.sessionId);
if (!player) return;
if (!this._actionOk(client.sessionId, 'venter')) return;
const id = typeof payload?.id === 'string' ? payload.id : '';
const v = this.state.vehicles.get(id);
if (!v) { client.send('vehicle', { event: 'deny', id, reason: 'gone' }); return; }
if (v.driver && v.driver !== client.sessionId) {
client.send('vehicle', { event: 'deny', id, reason: 'occupied' });
return;
}
// Proximity gate, can't claim a car from across the map.
const dist = Math.hypot(player.x - v.x, player.z - v.z);
if (dist > VEHICLE_ENTER_RANGE_M) {
client.send('vehicle', { event: 'deny', id, reason: 'range' });
return;
}
this._releaseVehicleOf(client.sessionId, id); // give up any other car first
v.driver = client.sessionId;
v.tsServer = Date.now();
// Peers pose a player from `motion`, and a driver never sends 'move' again
// until they step out, so seat them here. 'drive' is server-authored only:
// MOTION_VALUES deliberately excludes it, so a player on foot cannot claim
// to be sitting in a car they aren't in.
player.motion = 'drive';
player.tsServer = v.tsServer;
client.send('vehicle', { event: 'enter', id });
}
// Leave the wheel. The client sends its final resting transform; the server
// parks the car there, clears the driver, and authors the player's drop point
// beside the door so the next ordinary 'move' is continuous (no teleport
// rejection). The drop is server-computed and bounds-clamped, a client can't
// use exit to warp.
_handleVehicleExit(client, payload) {
const player = this.state.players.get(client.sessionId);
if (!player) return;
if (!this._actionOk(client.sessionId, 'vexit')) return;
const v = this._vehicleDrivenBy(client.sessionId);
if (!v) return;
// Accept the final transform through the same validation as a sync so the car
// can't be parked somewhere impossible on the way out.
this._applyVehicleTransform(v, payload, /* park */ true);
v.driver = '';
v.speed = 0;
v.tsServer = Date.now();
// Drop the avatar just left of the car (chassis-left), clamped to the same
// square world bound as ordinary movement.
const yaw = this._vehicleYaw(v);
const off = (vehicleSpec(v.type).dims.w / 2) + 0.6;
const dx = Math.max(-WORLD_BOUND_M, Math.min(WORLD_BOUND_M, v.x + Math.cos(yaw) * off));
const dz = Math.max(-WORLD_BOUND_M, Math.min(WORLD_BOUND_M, v.z - Math.sin(yaw) * off));
player.x = dx;
player.z = dz;
player.y = 0;
player.motion = 'idle';
player.tsServer = Date.now();
client.send('vehicle', { event: 'exit', id: v.id, x: dx, z: dz });
}
// Adopt the driver's streamed transform. Server-authoritative validation: only
// the seated driver may write; reject NaNs; reject a jump larger than the type's
// top speed allows over the send window (teleport) and an implausible reported
// speed (speed hack). A rejected position is simply not applied, the car holds
// its last authoritative transform, which the cheating client then sees snap back.
_handleVehicleSync(client, payload) {
if (!this._actionOk(client.sessionId, 'vsync')) return;
const v = this._vehicleDrivenBy(client.sessionId);
if (!v) return;
if (!this._applyVehicleTransform(v, payload, /* park */ false)) return;
// Carry the driver's avatar with the car so peers render them in the seat and
// stepping out is continuous. The avatar sits at the seat height above the
// chassis; ordinary move validation is bypassed here because the vehicle's own
// speed clamp already policed this displacement.
const player = this.state.players.get(client.sessionId);
if (player) {
player.x = v.x;
player.z = v.z;
player.y = Math.max(0, Math.min(3, v.y + vehicleSpec(v.type).seat.y));
player.motion = 'drive';
player.tsServer = v.tsServer;
// The ordinary 'move' handler drives zone-entry detection, but a seated
// driver never sends 'move', they stream 'vsync' instead. Without this, a
// vehicle-flagged goto objective could never be reached by driving through
// it. Check here too so cross-town delivery jobs actually progress.
this._checkZoneEntry(client);
}
}
// Validate + write a transform onto a vehicle. Returns false (and leaves the
// vehicle untouched) when the update is malformed or fails an anti-cheat clamp.
_applyVehicleTransform(v, payload, park) {
if (!payload || typeof payload !== 'object') return false;
const { x, y, z, qx, qy, qz, qw, speed } = payload;
const nums = [x, y, z, qx, qy, qz, qw];
if (nums.some((n) => typeof n !== 'number' || !Number.isFinite(n))) return false;
// Teleport clamp, derived from REAL elapsed time. The old fixed per-message
// window multiplied by the vsync rate limit (30/s) let a scripted sender
// legally cover ~10x top speed by maxing the step on every message, fast
// enough to farm the repeatable cross-town delivery jobs in seconds. Allow
// what the type's top speed covers since the last accepted update (with a
// floor for packet jitter and a cap so a long-parked car can't "bank" a
// cross-map teleport), and validate the DERIVED speed, not just the
// self-reported scalar.
const dtS = Math.max(0.05, Math.min(0.5, (Date.now() - (v.tsServer || 0)) / 1000));
const dx = x - v.x, dz = z - v.z;
const stepM = Math.hypot(dx, dz);
if (stepM > vehicleMaxSpeedMps(v.type) * dtS) return false;
// Speed-hack clamp on the reported forward speed (peers render from it).
const sp = typeof speed === 'number' && Number.isFinite(speed) ? speed : 0;
if (Math.abs(sp) > vehicleMaxSpeedMps(v.type)) return false;
// World bounds, the same square district clamp ordinary movement uses, so a
// car can reach the avenue spawns at x/z=±90 without being pulled toward the
// centre by a stale circular radius.
v.x = Math.max(-VEHICLE_WORLD_BOUND_M, Math.min(VEHICLE_WORLD_BOUND_M, x));
v.z = Math.max(-VEHICLE_WORLD_BOUND_M, Math.min(VEHICLE_WORLD_BOUND_M, z));
v.y = Math.max(-2, Math.min(8, y));
// Normalize the quaternion defensively so a denormalized client value can't
// poison every peer's renderer.
const ql = Math.hypot(qx, qy, qz, qw) || 1;
v.qx = qx / ql; v.qy = qy / ql; v.qz = qz / ql; v.qw = qw / ql;
v.speed = park ? 0 : sp;
v.tsServer = Date.now();
return true;
}
_vehicleDrivenBy(sessionId) {
for (const [, v] of this.state.vehicles) {
if (v.driver === sessionId) return v;
}
return null;
}
// Release any vehicle driven by this session (except `keepId`, when re-claiming).
_releaseVehicleOf(sessionId, keepId = null) {
let released = false;
for (const [, v] of this.state.vehicles) {
if (v.driver === sessionId && v.id !== keepId) {
v.driver = '';
v.speed = 0;
v.tsServer = Date.now();
released = true;
}
}
// Out of the seat, out of the seated pose. An eviction sweep (disconnect,
// switching cars) is the one path that clears a driver without going through
// the exit handler, so a peer would otherwise keep seeing them sitting.
const player = released ? this.state.players.get(sessionId) : null;
if (player && player.motion === 'drive') player.motion = 'idle';
}
// Heading (radians about the up axis) extracted from a vehicle's quaternion.
_vehicleYaw(v) {
return Math.atan2(2 * (v.qw * v.qy + v.qx * v.qz), 1 - 2 * (v.qy * v.qy + v.qx * v.qx));
}
// Per-action sliding-window rate limit (messages/sec/client). A flooding client
// is silently dropped for the offending action; legitimate cadence passes.
_actionOk(sessionId, action) {
const limit = ACTION_RATES[action] || 10;
const now = Date.now();
let buckets = this._actionCounters.get(sessionId);
if (!buckets) { buckets = {}; this._actionCounters.set(sessionId, buckets); }
let b = buckets[action];
if (!b || now - b.windowStart > 1000) { b = { windowStart: now, count: 0 }; buckets[action] = b; }
b.count++;
return b.count <= limit;
}
// Validate a {x,y,z} grid cell from a place/remove message. Returns the packed
// key string when the cell is a legal, in-bounds integer coordinate, else null.
_cellKey(payload) {
if (!payload || typeof payload !== 'object') return null;
const { x, y, z } = payload;
if (![x, y, z].every((v) => Number.isInteger(v))) return null;
if (y < 0 || y >= MAX_GRID_Y) return null;
if (Math.abs(x) > MAX_GRID_XZ || Math.abs(z) > MAX_GRID_XZ) return null;
// Circular build area, matching the round plaza the client clamps movement to.
if (Math.hypot(x, z) > MAX_GRID_XZ) return null;
return `${x},${y},${z}`;
}
// Tell one client an edit didn't land, and why, so the build HUD can explain a
// block that never appeared instead of leaving the player guessing. The client
// throttles these into a single toast, so a flood reply is harmless.
_rejectEdit(client, reason) {
client.send('edit-reject', { reason });
}
// Adopt a mid-session play-pass refresh. The client re-mints a pass (re-reading
// the chain) ahead of the 10-min TTL and pushes it here so this live session's
// bound expiry tracks the fresh credential, without this, the once-a-minute
// expiry sweep evicts a still-qualifying player at the original TTL, which is
// what kicked anyone in a long building session. We re-verify exactly as onAuth
// does: a valid pass for this gate's mint, at or above the floor, bound to the
// same wallet. Anything else is silently ignored, the stale expiry stands and
// the sweep handles it, so a forged refresh can't extend or hijack a session.
_handlePlayPassRefresh(client, payload) {
if (!PLAY_GATE_MINT) return;
const pass = verifyPlayPass(payload?.playPass);
if (!pass) return;
if (pass.mint !== PLAY_GATE_MINT) return;
if (!(typeof pass.balance === 'number' && pass.balance >= PLAY_GATE_MIN)) return;
// The refreshed pass must belong to the wallet this session authenticated as,
// so a leaked pass from another holder can't graft onto this connection.
if (client.userData?.account && pass.wallet !== client.userData.account) return;
client.userData = { ...(client.userData || {}), playBalance: pass.balance, playExp: pass.exp };
}
_handlePlace(client, payload) {
if (!this.state.players.has(client.sessionId)) return;
if (!this._editOk(client.sessionId)) { this._rejectEdit(client, 'rate'); return; }
const key = this._cellKey(payload);
if (key === null) { this._rejectEdit(client, 'bounds'); return; }
const t = payload.t;
if (!Number.isInteger(t) || t < 0 || t >= BLOCK_TYPE_COUNT) { this._rejectEdit(client, 'type'); return; }
const owner = this._ownerKey(client.sessionId);
const existing = this.state.blocks.get(key);
if (existing) {
// Re-painting an existing cell. It doesn't grow the world, but it DOES
// rewrite someone's build, only the piece's owner (or the coin creator)
// may change it, so a passer-by can't recolour another player's work.
if (existing.t === t) return; // no-op
if (!this._mayModify(client, key)) { this._rejectEdit(client, 'owned'); return; }
existing.t = t;
blockStore.set(this.worldKey, key, t, this.blockOwners.get(key) || owner);
return;
}
// New cell. Enforce, in order: the per-world budget, the protected spawn/totem
// discs, the per-player ownership cap, and the per-column density cap. Each is
// surfaced to the builder with its own reason, never a silent drop.
if (this.state.blocks.size >= MAX_BLOCKS) { this._rejectEdit(client, 'budget'); return; }
const reason = this._placementBlock(owner, payload.x, payload.z);
if (reason) { this._rejectEdit(client, reason); return; }
const b = new Block();
b.t = t;
this.state.blocks.set(key, b);
this._trackPlacement(key, owner);
blockStore.set(this.worldKey, key, t, owner);
this._sendBuildPerms(client);
}
// Place a composite piece, a handful of cells in one atomic, all-or-nothing
// stamp. Validated exactly like a single place (in-bounds integer cell, real
// type) for EVERY cell before anything lands, plus a whole-batch budget check,
// so a wall never half-appears and the per-world cap can't be straddled. Rate
// limited on its own bucket; the schema patch broadcasts each new block to all
// clients just like single edits, so there's no separate sync path.
_handlePlaceBatch(client, payload) {
if (!this.state.players.has(client.sessionId)) return;
if (!this._batchOk(client.sessionId)) { this._rejectEdit(client, 'rate'); return; }
const cells = payload?.cells;
if (!Array.isArray(cells) || cells.length === 0 || cells.length > MAX_BATCH_CELLS) {
this._rejectEdit(client, 'bounds');
return;
}
// First pass: validate every cell and count how many are new, so the budget,
// per-player cap, per-column density, protected-zone, and ownership checks all
// cover the WHOLE stamp before anything lands, a single bad cell rejects the
// lot. Cumulative tallies (ownerAdds, per-column) are tracked across the batch
// so a single stamp can't straddle a cap the same way a sequence of singles can't.
const owner = this._ownerKey(client.sessionId);
const validated = [];
let fresh = 0;
let ownerAdds = 0;
const colAdds = new Map();
for (const cell of cells) {
const key = this._cellKey(cell);
if (key === null) { this._rejectEdit(client, 'bounds'); return; }
const t = cell.t;
if (!Number.isInteger(t) || t < 0 || t >= BLOCK_TYPE_COUNT) { this._rejectEdit(client, 'type'); return; }
const existing = this.state.blocks.get(key);
if (existing) {
// Repaint of an occupied cell needs the same ownership gate as a single edit.
if (existing.t !== t && !this._mayModify(client, key)) { this._rejectEdit(client, 'owned'); return; }
} else {
const col = `${cell.x},${cell.z}`;
const extraCol = colAdds.get(col) || 0;
const reason = this._placementBlock(owner, cell.x, cell.z, ownerAdds, extraCol);
if (reason) { this._rejectEdit(client, reason); return; }
fresh++;
ownerAdds++;
colAdds.set(col, extraCol + 1);
}
validated.push({ key, t, cell });
}
if (this.state.blocks.size + fresh > MAX_BLOCKS) { this._rejectEdit(client, 'budget'); return; }
// Second pass: apply. All cells are known-valid now, so this can't partially fail.
for (const { key, t, cell } of validated) {
const existing = this.state.blocks.get(key);
if (existing) {
if (existing.t === t) continue;
existing.t = t;
blockStore.set(this.worldKey, key, t, this.blockOwners.get(key) || owner);
} else {
const b = new Block();
b.t = t;
this.state.blocks.set(key, b);
this._trackPlacement(key, owner);
blockStore.set(this.worldKey, key, t, owner);
}
}
this._sendBuildPerms(client);
}
_handleRemove(client, payload) {
if (!this.state.players.has(client.sessionId)) return;
if (!this._editOk(client.sessionId)) { this._rejectEdit(client, 'rate'); return; }
const key = this._cellKey(payload);
if (key === null) { this._rejectEdit(client, 'bounds'); return; }
if (!this.state.blocks.has(key)) return;
// Ownership: only the placer may break their piece, except the coin creator,
// who moderates the whole world. Enforced server-side off the persisted owner,
// never the client's word.
if (!this._mayModify(client, key)) { this._rejectEdit(client, 'owned'); return; }
const owner = this.blockOwners.get(key) || '';
this.state.blocks.delete(key);
this._untrackPlacement(key, owner, payload.x, payload.z);
blockStore.delete(this.worldKey, key);
this._sendBuildPerms(client);
}
// ── Generic world objects (R01 protocol) ────────────────────────────────────
//
// The shared `objects` MapSchema carries every non-player, non-voxel world
// entity: thrown balls, placed build props, pickups, fx. Three client messages
// drive it; the server is authoritative on ids, ownership, bounds and lifetime.
//
// obj:spawn { id?, type?, kind?, x, y, z, yaw?, scale?, vx?, vy?, vz? }
// Any joined player. x/y/z required + finite. The server assigns ownerId
// (the sender's account, else sessionId), accepts a sane unused `id` or
// mints one, clamps position to the world bound and scale to [0.1, 10],
// and stamps ts. Rejected (obj:reject {reason}) when the room is at
// MAX_WORLD_OBJECTS or the player at MAX_OBJECTS_PER_PLAYER. Clients can
// never spawn a 'server'-owned object.
// obj:update { id, x?, y?, z?, yaw?, scale?, vx?, vy?, vz? }
// Owner only. Server-owned objects (ownerId === 'server', e.g. the R05
// physics ball) are moved by the server's own simulation, never a client.
// Position re-clamped to bounds, scale to range.
// obj:remove { id }
// Owner, or the coin creator (world moderation). No one else can.
//
// Limits: each handler is rate-limited per client (OBJ_OPS_PER_SEC_LIMIT),
// positions are bounds-clamped, NaN/Infinity payloads are dropped, and totals
// are capped per room and per player. Lifetime: on owner disconnect their
// transient objects are reaped (_reapOwnerTransients); durable build props stay
// and are persisted per coin world (R17). A `kind` in TRANSIENT_OBJECT_KINDS
// (or a 'server'-owned object) is transient and never written to storage.
_handleObjSpawn(client, payload) {
if (!this.state.players.has(client.sessionId)) return;
if (!this._objOk(client.sessionId)) return;
if (!payload || typeof payload !== 'object') return;
// Position is mandatory and must be finite, a NaN slips past clamps.
if (!Number.isFinite(payload.x) || !Number.isFinite(payload.y) || !Number.isFinite(payload.z)) return;
if (this.state.objects.size >= MAX_WORLD_OBJECTS) { client.send('obj:reject', { reason: 'world_full' }); return; }
const owner = this._ownerKey(client.sessionId);
let owned = 0;
for (const [, o] of this.state.objects) if (o.ownerId === owner) owned++;
if (owned >= MAX_OBJECTS_PER_PLAYER) { client.send('obj:reject', { reason: 'player_full' }); return; }
const obj = new WorldObject();
// Accept a client-supplied id only if it's a sane, unused token; otherwise the
// server mints a collision-free one. Either way ids stay server-controlled.
let id = (typeof payload.id === 'string' && OBJ_ID_RE.test(payload.id)) ? payload.id : '';
if (!id || this.state.objects.has(id)) id = `o_${client.sessionId.slice(0, 6)}_${++this._objSeq}`;
obj.id = id;
obj.type = typeof payload.type === 'string' ? payload.type.slice(0, OBJ_STR_MAX) : '';
// Ownership is assigned here; a client can never claim the 'server' sentinel.
obj.ownerId = owner;
obj.kind = typeof payload.kind === 'string' ? payload.kind.slice(0, OBJ_STR_MAX) : '';
// P3.3: a player-uploaded model. This is the one client string every OTHER
// client will fetch, so it is validated against the storage allow-list here
// and refused outright otherwise: never silently dropped, or the uploader
// would watch their prop appear as a grey box for reasons no one explained.
if (payload.url != null && payload.url !== '') {
const url = normalizePropAssetUrl(payload.url);
if (!url) { client.send('obj:reject', { reason: 'asset_url' }); return; }
obj.url = url;
}
obj.scale = objClamp(objNum(payload.scale, 1), OBJ_SCALE_MIN, OBJ_SCALE_MAX);
obj.yaw = objNum(payload.yaw, 0);
this._clampObjPos(obj, payload);
// Grief guard (R19): a durable build prop may not bury the spawn or totem, nor
// pile onto a tile past the density cap so it can't wall an area off. Checked on
// the clamped position so a client can't dodge it with an out-of-bounds value.
// Transient kinds (ball, fx) and server objects are exempt, only build props.
if (this._objectIsPersistent(obj)) {
const reason = this._propPlacementBlock(obj.x, obj.z);
if (reason) { client.send('obj:reject', { reason }); return; }
}
obj.vx = objNum(payload.vx, 0);
obj.vy = objNum(payload.vy, 0);
obj.vz = objNum(payload.vz, 0);
obj.ts = Date.now();
this.state.objects.set(obj.id, obj);
if (this._objectIsPersistent(obj)) this._persistObjects();
}
_handleObjUpdate(client, payload) {
if (!this._objOk(client.sessionId)) return;
if (!payload || typeof payload.id !== 'string') return;
const obj = this.state.objects.get(payload.id);
if (!obj) return;
// Server-owned objects (the R05 ball) are driven by the server, never a
// client; and only the owner may move their own object.
if (obj.ownerId === SERVER_OBJECT_OWNER) return;
if (obj.ownerId !== this._ownerKey(client.sessionId)) return;
this._clampObjPos(obj, payload);
if (Number.isFinite(payload.yaw)) obj.yaw = payload.yaw;
if (Number.isFinite(payload.scale)) obj.scale = objClamp(payload.scale, OBJ_SCALE_MIN, OBJ_SCALE_MAX);
obj.vx = objNum(payload.vx, obj.vx);
obj.vy = objNum(payload.vy, obj.vy);
obj.vz = objNum(payload.vz, obj.vz);
obj.ts = Date.now();
if (this._objectIsPersistent(obj)) this._persistObjects();
}
_handleObjRemove(client, payload) {
if (!this._objOk(client.sessionId)) return;
if (!payload || typeof payload.id !== 'string') return;
const obj = this.state.objects.get(payload.id);
if (!obj) return;
// The owner may remove their own object; the coin creator may remove any as
// world moderation. No one else can.
if (obj.ownerId !== this._ownerKey(client.sessionId) && !this._isCreator(client)) return;
const wasPersistent = this._objectIsPersistent(obj);
this.state.objects.delete(payload.id);
// Persist the removal too, so a deleted prop doesn't resurrect on re-entry.
if (wasPersistent) this._persistObjects();
}
// Per-client token bucket for obj:* ops, mirroring the edit limiter.
_objOk(sessionId) {
const now = Date.now();
let bucket = this._objCounters.get(sessionId);
if (!bucket || now - bucket.windowStart > 1000) {
bucket = { windowStart: now, count: 0 };
this._objCounters.set(sessionId, bucket);
}
bucket.count++;
return bucket.count <= OBJ_OPS_PER_SEC_LIMIT;
}
_clampObjPos(obj, payload) {
obj.x = objClamp(objNum(payload.x, obj.x), -WORLD_BOUND_M, WORLD_BOUND_M);
obj.y = objClamp(objNum(payload.y, obj.y), OBJ_Y_MIN, OBJ_Y_MAX);
obj.z = objClamp(objNum(payload.z, obj.z), -WORLD_BOUND_M, WORLD_BOUND_M);
}
// A durable build piece (worth persisting, R17) is any object that isn't a
// server-owned entity and isn't a transient kind (ball, fx, projectile…).
_objectIsPersistent(obj) {
return obj.ownerId !== SERVER_OBJECT_OWNER && !TRANSIENT_OBJECT_KINDS.has(obj.kind);
}
// Delete a disconnecting owner's transient objects; their persistent build props
// remain as part of the world (R17).
_reapOwnerTransients(owner) {
const doomed = [];
for (const [id, o] of this.state.objects) {
if (o.ownerId === owner && !this._objectIsPersistent(o)) doomed.push(id);
}
for (const id of doomed) this.state.objects.delete(id);
}
// Snapshot the durable build props for storage, transient and server-owned
// objects are excluded. Coordinates are rounded to keep the doc compact.
_snapshotObjects() {
const out = [];
for (const [id, o] of this.state.objects) {
if (!this._objectIsPersistent(o)) continue;
const rec = {
id,
type: o.type,
kind: o.kind,
ownerId: o.ownerId,
x: round3(o.x), y: round3(o.y), z: round3(o.z),
yaw: round3(o.yaw),
scale: round3(o.scale),
};
// Only uploaded props carry a url; omitting it for the catalog props keeps
// the doc compact (the common case is a one-word `type`).
if (o.url) rec.url = o.url;
out.push(rec);
if (out.length >= MAX_WORLD_OBJECTS) break;
}
return out;
}
// Arm a debounced durable write of this world's build props (R17). The producer
// runs at flush time so the latest state lands; worldPersistence coalesces a
// burst of edits into one backend write.
_persistObjects() {
worldPersistence.save(this._objKey, () => ({ objects: this._snapshotObjects() }));
}
// Rebuild the `objects` map from a persisted doc on room create. Persisted
// objects are at rest, so velocity restores to zero and ts is re-stamped.
_restoreObjects(doc) {
const list = Array.isArray(doc?.objects) ? doc.objects : null;
if (!list || !list.length) return;
let n = 0;
for (const o of list) {
if (n >= MAX_WORLD_OBJECTS) break;
if (!o || typeof o.id !== 'string' || !o.id) continue;
const obj = new WorldObject();
obj.id = o.id.slice(0, OBJ_STR_MAX);
obj.type = typeof o.type === 'string' ? o.type.slice(0, OBJ_STR_MAX) : '';
obj.kind = typeof o.kind === 'string' ? o.kind.slice(0, OBJ_STR_MAX) : '';
obj.ownerId = typeof o.ownerId === 'string' ? o.ownerId.slice(0, OBJ_STR_MAX) : '';
obj.x = objNum(o.x, 0);
obj.y = objClamp(objNum(o.y, 0), OBJ_Y_MIN, OBJ_Y_MAX);
obj.z = objNum(o.z, 0);
obj.yaw = objNum(o.yaw, 0);
obj.scale = objClamp(objNum(o.scale, 1), OBJ_SCALE_MIN, OBJ_SCALE_MAX);
// Re-validate the stored asset url on the way back in: the allow-list can
// tighten between the save and the restore, and a doc written by the
// browser build path (P3.1) is user input like any other.
obj.url = normalizePropAssetUrl(o.url) || '';
obj.ts = Date.now();
this.state.objects.set(obj.id, obj);
n++;
}
if (n) console.log(`[walk_world ${this.roomId} coin=${this.state.coin || 'mainland'}] restored ${n} objects`);
}
// Creator-only moderation: clear a disc of blocks around a grid point, or the
// whole world. Validated server-side, the creator identity comes from the coin's
// on-chain creator matching this client's verified wallet, never a client claim.
// Bounded radius keeps even a malformed call from over-reaching; 'all' is the
// explicit full wipe. Every removed cell streams out via the blocks state, so all
// clients see the area clear without a bespoke broadcast.
_handleBuildClear(client, payload) {
if (!this.state.players.has(client.sessionId)) return;
if (!this._isCreator(client)) { this._rejectEdit(client, 'notcreator'); return; }
if (!this._actionOk(client.sessionId, 'clear')) { this._rejectEdit(client, 'rate'); return; }
if (!payload || typeof payload !== 'object') return;
const all = payload.all === true;
let cx = 0, cz = 0, r = 0;
if (!all) {
cx = Number(payload.x); cz = Number(payload.z); r = Number(payload.r);
if (!Number.isFinite(cx) || !Number.isFinite(cz) || !Number.isFinite(r)) return;
// Clamp to the tier this caller earned (P3.2), then to the absolute
// ceiling, a client asking for more gets the honest maximum, never more.
const earned = Math.min(this._clearRadiusFor(client), BUILD_CLEAR_RADIUS_MAX);
r = Math.max(1, Math.min(earned, Math.round(r)));
}
let cleared = 0;
for (const key of [...this.state.blocks.keys()]) {
const [bx, bz] = key.split(',').map(Number);
if (!all && Math.hypot(bx - cx, bz - cz) > r) continue;
const owner = this.blockOwners.get(key) || '';
this.state.blocks.delete(key);
this._untrackPlacement(key, owner, bx, bz);
blockStore.delete(this.worldKey, key);
cleared++;
}
// Durable props (obj:spawn build pieces) live in the objects map, not the voxel
// grid, so a sweep that only touched blocks would leave a prop-griefed area
// untouched. Clear them on the same disc, mapped from grid cells to world metres
// (the centre/radius arrive in cells), and never the ball or transient fx.
let clearedObjs = 0;
const wx = cx * BLOCK_SIZE_M, wz = cz * BLOCK_SIZE_M, wr = r * BLOCK_SIZE_M;
for (const [id, o] of [...this.state.objects]) {
if (!this._objectIsPersistent(o)) continue;
if (!all && Math.hypot(o.x - wx, o.z - wz) > wr) continue;
this.state.objects.delete(id);
clearedObjs++;
}
if (clearedObjs) this._persistObjects();
client.send('build-cleared', { count: cleared, objects: clearedObjs, all });
this._sendBuildPerms(client); // the creator's own tally may have changed
if (cleared || clearedObjs) {
const where = all ? ' (all)' : ` near ${cx},${cz} r=${r}`;
console.log(`[walk_world ${this.roomId}] creator cleared ${cleared} block(s) + ${clearedObjs} prop(s)${where}`);
}
}
// --- Build-permission bookkeeping ---------------------------------------
// The stable id a placed block is owned by: the player's persistence id (wallet
// account when the gate is on, else their guest id), falling back to the session
// id before the economy profile lands. Stable across reconnects so a returning
// builder still owns their pieces.
_ownerKey(sessionId) {
return this.econ.get(sessionId)?.playerId || sessionId;
}
// Whether this client may modify the block at `key`, its owner, or the creator.
// An ownerless cell (a legacy/pre-ownership restore) is creator-only, so restored
// builds stay protected from griefing while the creator can still moderate them.
_mayModify(client, key) {
if (this._isCreator(client)) return true;
const owner = this.blockOwners.get(key) || '';
return owner !== '' && owner === this._ownerKey(client.sessionId);
}
// Is this client the coin's on-chain creator? Requires a verified wallet (the
// account bound in onAuth) matching the creator we resolved on room create.
_isCreator(client) {
if (!this.coinCreator) return false;
const player = this.state.players.get(client.sessionId);
return !!player && !!player.account && player.account === this.coinCreator;
}
// True if (x,z) is inside a protected disc (spawn, totem, or the plaza stage),
// placement there is refused at every height so no landmark can be buried or
// fenced in.
_isProtectedColumn(x, z) {
for (const p of PROTECTED_POINTS) {
if (Math.hypot(x - p.x, z - p.z) <= p.r) return true;
}
return false;
}
// Shared anti-grief gate for a NEW cell (the per-world budget is checked by the
// caller, since it spans a whole batch). `extraOwner` / `extraColumn` are cells
// already committed earlier in the same batch, so a composite stamp can't straddle
// a cap. Returns an edit-reject reason, or null when the placement is allowed.
_placementBlock(owner, x, z, extraOwner = 0, extraColumn = 0) {
if (this._isProtectedColumn(x, z)) return 'protected';
if ((this.blockCounts.get(owner) || 0) + extraOwner >= PER_PLAYER_BLOCK_CAP) return 'playercap';
if ((this.columnCounts.get(`${x},${z}`) || 0) + extraColumn >= COLUMN_CAP) return 'dense';
return null;
}
// Grief guard for the prop/object build channel (obj:spawn), mirroring the voxel
// guard but in world metres: keep durable props off the spawn/totem discs and cap
// how many may pile onto one tile so a builder can't bury a landmark or wall a spot
// off. Returns an obj:reject reason, or null when the placement is allowed.
_propPlacementBlock(x, z) {
for (const p of PROTECTED_POINTS_M) {
if (Math.hypot(x - p.x, z - p.z) <= p.r) return 'protected';
}
const tx = Math.round(x / PROP_TILE_M);
const tz = Math.round(z / PROP_TILE_M);
let here = 0;
for (const [, o] of this.state.objects) {
if (!this._objectIsPersistent(o)) continue;
if (Math.round(o.x / PROP_TILE_M) === tx && Math.round(o.z / PROP_TILE_M) === tz) here++;
}
if (here >= PER_TILE_PROP_CAP) return 'dense';
return null;
}
// Record a placement against its owner + column tallies (used by the caps).
_trackPlacement(key, owner) {
this.blockOwners.set(key, owner);
if (owner) this.blockCounts.set(owner, (this.blockCounts.get(owner) || 0) + 1);
const ck = key.split(',', 3); // "x,y,z" -> column "x,z"
const col = `${ck[0]},${ck[2]}`;
this.columnCounts.set(col, (this.columnCounts.get(col) || 0) + 1);
}
// Reverse a placement's bookkeeping when a cell is removed.
_untrackPlacement(key, owner, x, z) {
this.blockOwners.delete(key);
if (owner) {
const n = (this.blockCounts.get(owner) || 0) - 1;
if (n > 0) this.blockCounts.set(owner, n); else this.blockCounts.delete(owner);
}
const col = `${x},${z}`;
const c = (this.columnCounts.get(col) || 0) - 1;
if (c > 0) this.columnCounts.set(col, c); else this.columnCounts.delete(col);
}
// Tell one client what they're allowed to do and how much of their build budget
// they've used, so the HUD can surface the per-player cap and reveal the creator
// moderation control, no silent limits. Sent on join and after their tally moves.
_sendBuildPerms(client) {
const owner = this._ownerKey(client.sessionId);
const creator = this._isCreator(client);
client.send('build-perms', {
creator,
cap: PER_PLAYER_BLOCK_CAP,
used: this.blockCounts.get(owner) || 0,
// P3.2: the radius this caller has actually earned, not a flat constant.
// The client renders this number in the confirm prompt, and
// _handleBuildClear clamps to the same call, one source of truth, so the
// HUD can never promise reach the server would refuse.
clearMaxRadius: this._clearRadiusFor(client),
holderWorld: this.state.tier === 'holders',
});
}
// The clear-area reach (in build-grid cells) this client has earned: the coin's
// verified creator gets the widest sweep, a player inside the coin's gated
// Holders world gets the middle tier (they passed a signed holder pass at join),
// everyone else gets the base radius. Server-proven inputs only.
_clearRadiusFor(client) {
return buildClearRadius({
creator: this._isCreator(client),
holder: this.state.tier === 'holders',
});
}
// Resolve the coin's on-chain creator from the three.ws API (the same pump.fun
// coin record the lobby reads). Best-effort: a miss leaves the world without a
// creator and therefore without the clear-area tool. Re-broadcasts permissions to
// everyone already seated once known, so a creator who joined first still gets
// their moderation control the moment it resolves.
async _resolveCoinCreator() {
const mint = this.state.coin;
if (!mint) return; // mainland, no coin, no creator
try {
const ctrl = new AbortController();
const timer = setTimeout(() => ctrl.abort(), 6000);
let body;
try {
const res = await fetch(`${WORLD_API_BASE}/api/pump/coin?mint=${encodeURIComponent(mint)}`, {
headers: { accept: 'application/json' }, signal: ctrl.signal,
});
if (!res.ok) return;
body = await res.json();
} finally { clearTimeout(timer); }
this._applyCoinIdentity(body);
const creator = typeof body?.creator === 'string' ? body.creator.trim() : '';
if (!MINT_RE.test(creator)) return; // a creator is a base58 wallet, same shape as a mint
this.coinCreator = creator;
for (const client of this.clients) this._sendBuildPerms(client);
} catch (err) {
console.warn(`[walk_world ${this.roomId}] creator lookup failed:`, err?.message);
}
}
// Stamp the room's coin identity from the coin record (same field fallbacks the
// in-world client reads from the pump.fun body). Text is control-stripped and
// length-capped; the image must be an http(s) URL.
_applyCoinIdentity(coin) {
this.state.coinName = clean(coin?.name, 48);
this.state.coinSymbol = clean(coin?.symbol, 16);
const image = coin?.image_uri || coin?.image || coin?.imageUri;
this.state.coinImage =
cleanAvatarUrl(image) ||
(typeof image === 'string' && /^https?:\/\//.test(image) ? image.slice(0, 1024) : '');
}
_editOk(sessionId) {
const now = Date.now();
let bucket = this._editCounters.get(sessionId);
if (!bucket || now - bucket.windowStart > 1000) {
bucket = { windowStart: now, count: 0 };
this._editCounters.set(sessionId, bucket);
}
bucket.count++;
return bucket.count <= EDITS_PER_SEC_LIMIT;
}
// Separate token bucket for composite stamps, so a legitimate wall (a dozen
// cells at once) isn't starved by the per-cell single-edit limit, while still
// capping how fast a client can fire whole pieces.
_batchOk(sessionId) {
const now = Date.now();
let bucket = (this._batchCounters ||= new Map()).get(sessionId);
if (!bucket || now - bucket.windowStart > 1000) {
bucket = { windowStart: now, count: 0 };
this._batchCounters.set(sessionId, bucket);
}
bucket.count++;
return bucket.count <= BATCHES_PER_SEC_LIMIT;
}
_rateOk(sessionId) {
const now = Date.now();
let bucket = this._moveCounters.get(sessionId);
if (!bucket || now - bucket.windowStart > MOVE_WINDOW_MS) {
bucket = { windowStart: now, count: 0 };
this._moveCounters.set(sessionId, bucket);
}
bucket.count++;
return bucket.count <= MOVES_PER_SEC_LIMIT;
}
// ── R05: beach ball physics ──────────────────────────────────────────────────
// Spawn (or reset) the room's single server-owned ball at world centre.
// Called on room create and on respawn (out-of-bounds or fallen through floor).
_spawnBall() {
const existing = this.state.objects.get(BALL_ID);
if (existing) {
existing.x = BALL_SPAWN_X; existing.y = BALL_SPAWN_Y; existing.z = BALL_SPAWN_Z;
existing.vx = 0; existing.vy = 0; existing.vz = 0;
existing.ts = Date.now();
} else {
const ball = new WorldObject();
ball.id = BALL_ID;
ball.kind = 'ball';
ball.type = 'beach';
ball.ownerId = SERVER_OBJECT_OWNER;
ball.x = BALL_SPAWN_X; ball.y = BALL_SPAWN_Y; ball.z = BALL_SPAWN_Z;
ball.vx = 0; ball.vy = 0; ball.vz = 0;
ball.yaw = 0; ball.scale = 1;
ball.ts = Date.now();
this.state.objects.set(BALL_ID, ball);
}
this._ballVx = 0; this._ballVy = 0; this._ballVz = 0;
}
// Physics tick at 20 Hz. Integrates gravity, rolling friction, ground bounce,
// and world-edge reflection. Writes position+velocity into the schema so
// Colyseus broadcasts only the delta. Settled balls skip integration.
_tickBall() {
const ball = this.state.objects.get(BALL_ID);
if (!ball) { this._spawnBall(); return; }
// Respawn if out of bounds
const rSq = ball.x * ball.x + ball.z * ball.z;
if (ball.y < BALL_OOB_Y || rSq > (BALL_WORLD_RADIUS + 6) * (BALL_WORLD_RADIUS + 6)) {
console.log(`[walk_world ${this.roomId}] ball out of bounds, respawning`);
this._spawnBall();
return;
}
// Skip integration when settled on the ground
const speedSq = this._ballVx * this._ballVx + this._ballVy * this._ballVy + this._ballVz * this._ballVz;
const onGround = ball.y <= BALL_RADIUS + 0.02;
if (speedSq < BALL_IDLE_SPEED_SQ && onGround) return;
const dt = BALL_TICK_MS / 1000;
// Gravity
this._ballVy -= BALL_GRAVITY * dt;
// Drag / rolling friction
if (onGround) {
const fric = 1 - BALL_ROLLING_FRICTION * dt;
this._ballVx *= fric;
this._ballVz *= fric;
} else {
const drag = 1 - BALL_AIR_DRAG * dt;
this._ballVx *= drag;
this._ballVz *= drag;
}
// Integrate position
ball.x += this._ballVx * dt;
ball.y += this._ballVy * dt;
ball.z += this._ballVz * dt;
// Ground bounce
if (ball.y < BALL_RADIUS) {
ball.y = BALL_RADIUS;
if (this._ballVy < 0) {
this._ballVy = -this._ballVy * BALL_BOUNCE;
// Kill micro-bounces so the ball settles cleanly
if (Math.abs(this._ballVy) < 0.3) this._ballVy = 0;
}
}
// World-edge reflection (radial normal bounce)
const r = Math.sqrt(rSq);
if (r > BALL_WORLD_RADIUS) {
const k = BALL_WORLD_RADIUS / r;
ball.x *= k; ball.z *= k;
const nx = ball.x / BALL_WORLD_RADIUS;
const nz = ball.z / BALL_WORLD_RADIUS;
const dot = this._ballVx * nx + this._ballVz * nz;
if (dot > 0) {
this._ballVx = (this._ballVx - 2 * dot * nx) * BALL_WALL_BOUNCE;
this._ballVz = (this._ballVz - 2 * dot * nz) * BALL_WALL_BOUNCE;
}
}
// Write velocity into schema so clients can extrapolate between updates
ball.vx = this._ballVx;
ball.vy = this._ballVy;
ball.vz = this._ballVz;
ball.ts = Date.now();
}
// Handle a kick intent from a client. Server validates and caps the impulse,
// then applies it to the authoritative ball velocity. Never trusts the client's
// raw values, only direction + a capped magnitude survive.
_handleBallKick(client, payload) {
if (!this.state.players.has(client.sessionId)) return;
if (!this._kickOk(client.sessionId)) return;
if (!payload || typeof payload !== 'object') return;
const ball = this.state.objects.get(BALL_ID);
if (!ball) return;
let { vx, vy, vz } = payload;
if (!Number.isFinite(vx) || !Number.isFinite(vy) || !Number.isFinite(vz)) return;
// Cap impulse magnitude
const mag = Math.hypot(vx, vy, vz);
if (mag > BALL_MAX_IMPULSE) {
const k = BALL_MAX_IMPULSE / mag;
vx *= k; vy *= k; vz *= k;
} else if (mag < 0.1) {
return; // reject zero-length impulse
}
// Ensure a meaningful upward component so the ball always lifts off the ground
if (vy < BALL_MIN_UPY) vy = BALL_MIN_UPY;
this._ballVx += vx;
this._ballVy += vy;
this._ballVz += vz;
// Absolute cap on total velocity post-kick to prevent launch exploits
const totalMag = Math.hypot(this._ballVx, this._ballVy, this._ballVz);
if (totalMag > BALL_POST_KICK_CAP) {
const k = BALL_POST_KICK_CAP / totalMag;
this._ballVx *= k; this._ballVy *= k; this._ballVz *= k;
}
}
// Per-client sliding-window rate limit for ball:kick messages.
_kickOk(sessionId) {
const now = Date.now();
let bucket = this._kickCounters.get(sessionId);
if (!bucket || now - bucket.windowStart > 1000) {
bucket = { windowStart: now, count: 0 };
this._kickCounters.set(sessionId, bucket);
}
bucket.count++;
return bucket.count <= BALL_KICKS_PER_SEC;
}
}