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.

8.2 KB
Raw Blame

Live events in /play

A live event turns the $THREE home town from a world you can visit into a place something is happening in: a countdown you can see from anywhere in the plaza, an agenda that tells you what is on right now and what is next, a banner when each segment starts, and a synchronized fireworks show everyone watches together.

Everything below is driven by one file, public/event.json. Schedule a window in it, redeploy, and the event exists. Reset it and the world goes back to normal with no code change and no dead pixels.

Between events the file carries an explicit no-event state, and that is the resting state. The file always exists (four /play readers fetch /event.json per load, and its absence would put a 404 in every visitor's console), but its window is explicitly null, so every surface below mounts nothing and the world runs as a plain world. Scheduling an event means writing a real window into the file (npm run event:schedule -- --start <ISO> --duration <minutes> --apply); ending one means resetting it (npm run event:schedule -- --clear --apply). Nothing in this document is live until a real window is scheduled.


Configuring an event

public/event.json is the single source of truth. The same file feeds the lobby banner and wayfinding pill (src/game/event-countdown.js), this in-world layer, and the server-side souvenir grant, so those three can never disagree about when the event is.

Write it to schedule an event. There is no file in the repo to edit, so start from the shape below:

{
  "id": "three-first-meetup",
  "name": "$THREE First Holders Meetup",
  "tagline": "The first live gathering in the three.ws world.",
  "startsAt": "2026-08-09T17:00:00Z",
  "endsAt": "2026-08-09T19:30:00Z",
  "link": "/play?coin=FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump&name=three.ws&symbol=three",
  "linkLabel": "Join the $THREE world",
  "souvenir": { "cosmeticId": "laurel-meetup" },
  "agenda": [
    { "atMin": 0,   "title": "Doors open in the plaza", "detail": "Say hi in chat", "icon": "👋" },
    { "atMin": 20,  "title": "King of the Totem showdown", "detail": "Hold the gold ring", "icon": "👑" },
    { "atMin": 105, "title": "Fireworks finale", "detail": "Look up", "icon": "🎆" }
  ]
}
Field Meaning
id Seeds the deterministic fireworks show. Change it and every client gets a different (but still shared) sky.
name / tagline Shown on the chip, the agenda drawer, and the photo stamp.
startsAt / endsAt ISO-8601 UTC. A missing or inverted endsAt defaults to six hours after the start.
agenda[].atMin Minutes after startsAt. Order does not matter; segments are sorted. Invalid or untitled entries are dropped rather than breaking the event.
agenda[].icon One emoji. Used on the segment row and its moment banner.
souvenir.cosmeticId Optional. A free commemorative wearable granted once to everyone who joins the world named by link while the event is live, kept forever, never granted again after endsAt. Must be a tier: 'event' cosmetic; anything else grants nothing. See Event souvenirs.

id, agenda, and tagline are optional: an event with none of them still runs its countdown, its go-live moment, and its fireworks.

What a player sees

The layer walks six phases, all derived from the wall clock by eventState() so two people standing in the plaza always agree on which one they are in.

Phase When What shows
far more than 24 h out nothing
upcoming within 24 h chip: "Starts in 6h 12m", tappable for the agenda
preshow final 30 min chip glows gold; a toast tells the player to stick around
live between start and end chip reads LIVE with the next segment's countdown; agenda marks the running segment; moment banners fire; fireworks run
afterglow 20 min after the end chip invites a commemorative photo
ended after that the layer tears itself down completely

The chip docks itself under the King of the Totem card when that card is up, so the two never overlap, and it hides under zen mode (Z) with every other overlay. While it is mounted, the generic countdown pill stands down: one countdown on screen at a time.

The fireworks show

Fireworks are deterministic, not networked. Time is cut into four-second buckets; each bucket is hashed with the event id into the same launch plan on every machine (fireworkPlan()), so the whole plaza watches one synchronized sky without a single packet. This is the same trick the shared day/night clock (src/shared/world-clock.js) uses for the sun.

Density scales with the moment: sparse through the event, ramping into a barrage over the closing fifteen minutes, plus one-off volleys on the go-live moment and each segment change. Power-saver mode halves it, no more than 14 shells are ever alive at once, and a backgrounded tab never replays the backlog it missed while requestAnimationFrame was paused.

The agenda drawer

Tapping the chip opens a right-docked drawer with the full agenda (past segments dimmed, the running one highlighted, future ones counting down in local time), a live $THREE pulse row (price, 24 h change, market cap from /api/three-signal, hidden entirely if that data is unavailable), a commemorative photo action, and a Buy $THREE button that opens /play's existing on-chain trade widget. Escape closes it.

Previewing without waiting

Add ?meetup=now to the /play URL to shift the configured event to start twenty seconds from load, keeping its duration and agenda. ?meetup=<ISO> shifts it to a specific instant instead. This runs through applyPreviewOverride(), which every surface that reads the event shares, so a preview never drifts from the real thing.

It shifts a configured event; it does not invent one. While public/event.json carries the no-event resting state, ?meetup=now has nothing to move and the world loads as usual, so schedule a window first.

http://localhost:3000/play?coin=FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump&name=three.ws&symbol=three&meetup=now

Verifying before an event

The audit drives the real layer through a real browser, so it needs a real window in public/event.json before you run it (see the note under Previewing).

npm run dev            # terminal 1: vite on :3000
npm run dev:walk-all   # terminal 2: the Colyseus world server on :2567
npm run audit:meetup   # terminal 3: drives a real browser through the whole layer

The audit enters the home town with ?meetup=now and asserts the chip mounts and counts down, the generic pill stands down, the chip clears the totem card, the agenda opens with every segment, Escape closes it, the chip flips to LIVE at the start instant, the go-live banner fires, fireworks reach the scene, zen mode hides everything, the photo action opens photo mode, and the chip still fits at 390 px. Screenshots land in .meetup-audit/ (gitignored). Exit code 0 means every check passed.

Point it at another origin with --base https://three.ws.

Extending it

  • A different world. The home-town gate is one call (isHomeTown()) in meetup-event.js's frame loop. Widen it to run an event in any coin world.
  • More agenda segments. Config only; no code change.
  • A new moment type. _moment(icon, title, sub) paints the gold banner; call it from wherever the new trigger lives.
  • Reusing the schedule elsewhere. meetup-schedule.js imports neither the DOM nor three.js, so a landing page or jumbotron can render the same countdown from the same config.