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.
Event souvenirs: the wearable you keep for having been there
Some things should not be for sale.
When a live event runs in /play, everyone who walks into the event world while
it is happening is handed a free commemorative wearable. It lands on your
account, it is yours forever, and you can wear it in every coin world from then
on. When the event ends, it is never granted again. There is no purchase path,
no second chance, no listing in the boutique. The only way to have one is to
have been there.
That constraint is the entire product. A cosmetic you can buy later says nothing about you. This one says exactly one thing, permanently, to every player who walks past you.
The first one is the Meetup Laurel: a gold laurel circlet, open at the
front, with three pearl berries in the gap. It was configured for the
$THREE First Holders Meetup on 2026-08-09, but the
multiplayer service was not redeployed with the grant code before that window,
so the grant never ran and nobody holds one. The window has closed, and the
laurel stays retired rather than being handed out later under a different
event's name.
The second is the Meetup Star Shades: gold star-shaped frames with smoked
lenses, worn in the eyewear slot so they sit alongside any headwear. They are
the souvenir for the $THREE Community Meetup #2 on 2026-09-25, 16:00 to 17:00
UTC. The lesson from the first event is now a pre-flight step (see
Verifying it): the multiplayer service must be running a build
that contains the grant before the window opens.
For players
- Open the event world while the event is live. The countdown chip and the lobby banner both link straight to it.
- A card slides in over the corner of the HUD the moment the souvenir lands: what you got, why, and a Wear it button. It is not a modal, so it never interrupts what you were doing, and it retires itself after a few seconds (it pauses while your pointer or keyboard focus is on it).
- Dismissed it? It is waiting in My Fits, badged as new, in the Headwear row.
You are granted it once. Reconnecting, refreshing, or coming back the next day does not give you a second one and does not show the card again.
For whoever runs the event
Everything lives in one file: public/event.json, the
same config that drives the countdown pill, the agenda drawer, and the fireworks
finale.
Between events that file carries an explicit no-event state (an all-null
window), which is the platform's resting state. The file itself always exists
so /event.json answers 200 in every visitor console. No event is scheduled
right now, so nothing is being granted. Running one starts by writing a real
config into the file, souvenir block included:
{
"id": "three-first-meetup",
"name": "$THREE First Holders Meetup",
"startsAt": "2026-08-09T17:00:00Z",
"endsAt": "2026-08-09T19:30:00Z",
"link": "/play?coin=FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump&name=three.ws&symbol=three",
"souvenir": { "cosmeticId": "laurel-meetup" }
}
That is the whole configuration. Three fields already had to be right for the countdown to work, and the drop reuses all three:
| Field | What the drop reads from it |
|---|---|
startsAt / endsAt |
The claim window, half-open: [startsAt, endsAt). At the instant the event ends, the souvenir stops being granted. |
link |
The world. The coin query parameter names the only world the drop applies in, so it can never target a world the event does not advertise. |
souvenir.cosmeticId |
The item. Must be a tier: 'event' entry in the cosmetics catalog. |
Omit the souvenir block entirely to run an event with no drop.
Running a drop, start to finish
- Author the item in
multiplayer/src/cosmetics-catalog.jswithtier: 'event'andprice: 0. See Adding a new souvenir. - Point the config at it with the
souvenirblock above. - Check it parses before the night of the event, not during it:
The suite's last block reads the realnpx vitest run tests/event-souvenir.test.jspublic/event.jsonand fails if the shipped config would grant nothing. It skips itself while the file carries the no-event resting state, so a green run between events proves the drop logic, not your window: write the config first, then run it and read the count. - Deploy. The game server fetches the config over HTTP and re-reads it
every two minutes, so moving a window does not need a game-server redeploy.
EVENT_CONFIG_TTL_MStightens that interval while you are setting up. - Watch it land. Every grant logs one line:
[walk_world <roomId>] souvenir laurel-meetup → <account> (three-first-meetup)
What the server refuses to do
These are guards, not warnings: each one silently grants nothing rather than doing the wrong thing.
- Grant outside the window. Before
startsAtor at/afterendsAt, nothing. - Grant in another world. Standing in an unrelated coin world during the event earns nothing, even though the event is live.
- Grant a boutique item. If
cosmeticIdnames apremiumcosmetic, the whole drop is treated as unconfigured. A typo cannot hand every attendee a 400-$THREEStetson. - Grant twice. The grant is idempotent on the account, so reconnects and room hops produce one unlock and one announcement.
- Block a join. An unreachable or malformed config means no drop, never an error and never a delay: the world opens normally.
How it works
public/event.json ──HTTP──▶ multiplayer/src/event-drop.js (window + world + item)
│
WalkRoom.onJoin
│ dropClaimable(drop, world, now)?
▼
grantCosmetic(profile, id) (idempotent)
│ newly unlocked?
┌───────────────┴───────────────┐
▼ ▼
persist to account send `souvenir` to that client
│
▼
src/game/event-souvenir.js (the card)
cosmetics-wardrobe.js (the "New" badge)
The grant is server-side only. A client never asks for a souvenir and cannot
claim one: it learns it has one because the server tells it. The souvenir
message is sent on the transition from not-owned to owned and at no other time,
which is what lets the client treat it as a moment rather than state to
reconcile.
Ownership then behaves exactly like a purchased cosmetic: it is stored on the account profile, survives restarts and world switches, is re-validated on every equip, and is published on the shared schema so peers render it. A client asserting the item in a join loadout without owning it is silently dressed in the slot default.
Why the window lives in the config and not in code
The countdown chip, the agenda, the fireworks and the drop all derive from the
same startsAt/endsAt. If the drop had its own copy of the schedule, the two
could disagree, and the failure mode is the worst one available: a player who
watched the countdown hit zero, walked in, and got nothing. Reading one file
makes that class of bug unrepresentable.
Adding a new souvenir
An event-tier cosmetic is an ordinary catalog entry with a tier that keeps it out of the shop:
{
id: 'laurel-meetup',
name: 'Meetup Laurel',
slot: 'headwear',
rarity: 'legendary',
tier: 'event', // granted, never sold
price: 0, // and so never listed in the boutique
visual: { prop: '/accessories/laurel-meetup.glb', anchor: 'head' },
thumb: '/accessories/thumbs/laurel-meetup.png',
}
If it needs an asset, both the model and its poster are generated from the repo, so neither can drift from the other:
node scripts/generate-accessory-glbs.mjs laurel-meetup.glb # the GLB (68 KB)
node scripts/render-accessory-thumbs.mjs laurel-meetup # the poster PNG
Passing a filename regenerates only that one, leaving every other committed
binary untouched. The geometry is authored procedurally in
scripts/generate-accessory-glbs.mjs
alongside the hats and glasses; repeated elements (the laurel's eighteen leaves)
are built in a loop and merged into a single primitive so one look costs one
material.
Do not add an event souvenir to
public/accessories/presets.json. That
catalog is the Avatar Studio's, it is not ownership-gated, and listing a
souvenir there would hand it to everyone.
Verifying it
Three layers, all real. None of them edits public/event.json, so no run can
leave a live window behind.
npx vitest run tests/event-souvenir.test.js # window gating, idempotency, economy separation
node scripts/play-souvenir-conformance.mjs # the contract, against a real game server
node scripts/play-souvenir-ui-check.mjs # the card and the wardrobe, in a real browser
node scripts/play-souvenir-e2e.mjs # the whole feature through the real /play world
Before a real window, check production too. The first event's grant never
ran because the multiplayer service was still on a build from before the grant
code landed. Compare the live revision's creation time with the last commit under
multiplayer/src, and redeploy (cd multiplayer && ./deploy-cloudrun.sh) if
the repo is ahead:
gcloud run services describe three-ws-multiplayer --region us-central1 \
--format='value(status.latestReadyRevisionName,metadata.annotations."serving.knative.dev/lastModifier")'
git log -1 --format='%h %ci' -- multiplayer/src
The conformance run boots Colyseus on a private port against an event config
it serves itself, then joins with the real colyseus.js client and walks the
contract: granted once on join, announced once, equips, published on the shared
schema, seen by a second player, nothing granted in a different world at the same
instant, nothing more on reconnect (and still worn, so the grant persisted), and
after the window closes nothing for a newcomer while an earlier attendee still
owns, wears, and can re-equip theirs. No browser and no GPU, so it runs anywhere.
The UI check mounts the real drop card and the real wardrobe panel in headless Chromium and drives them: the poster loads, "Wear it" fires exactly one equip, the card retires itself, Escape dismisses it, an owned souvenir renders as equipped with "Event souvenir" instead of a price, a locked one says "Not for sale" and routes nowhere, and a locked premium item still opens the shop (so that rule is targeted, not a broken click handler).
The e2e run is the full-fat version: Vite plus Colyseus on private ports and
the actual /play world in a browser. It is the slowest of the three because it
compiles the whole /play module graph and holds a WebGL scene open; on a busy
machine prefer the two above, which cover the same ground between them.
Where the code lives
| Piece | Location |
|---|---|
| Window, world and item resolution | multiplayer/src/event-drop.js |
| Join-time grant | _grantEventSouvenir in multiplayer/src/rooms/WalkRoom.js |
The event tier + catalog entry |
multiplayer/src/cosmetics-catalog.js |
| Unlock + persistence | grantCosmetic / restoreProfile in multiplayer/src/economy.js |
| The drop card | src/game/event-souvenir.js |
| Wardrobe treatment ("New", "Not for sale") | src/game/cosmetics-wardrobe.js |
| Event config | public/event.json |
| Asset generators | scripts/generate-accessory-glbs.mjs, scripts/render-accessory-thumbs.mjs |
| Verification | tests/event-souvenir.test.js, scripts/play-souvenir-conformance.mjs, scripts/play-souvenir-ui-check.mjs, scripts/play-souvenir-e2e.mjs |
Related
- Live events in /play covers the rest of what that config file drives: the countdown, the agenda drawer, the fireworks.
- The in-game economy covers the two currencies and
the
$THREEboutique the souvenir deliberately stays out of. - Coin communities covers the worlds the events happen in.