Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

12.9 KB
Raw Blame

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

  1. Open the event world while the event is live. The countdown chip and the lobby banner both link straight to it.
  2. 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).
  3. 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

  1. Author the item in multiplayer/src/cosmetics-catalog.js with tier: 'event' and price: 0. See Adding a new souvenir.
  2. Point the config at it with the souvenir block above.
  3. Check it parses before the night of the event, not during it:
    npx vitest run tests/event-souvenir.test.js
    
    The suite's last block reads the real public/event.json and 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.
  4. 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_MS tightens that interval while you are setting up.
  5. 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 startsAt or at/after endsAt, 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 cosmeticId names a premium cosmetic, the whole drop is treated as unconfigured. A typo cannot hand every attendee a 400-$THREE Stetson.
  • 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 $THREE boutique the souvenir deliberately stays out of.
  • Coin communities covers the worlds the events happen in.