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.

21.2 KB
Raw Blame

Walk Leaderboard

Every step your avatar takes on three.ws is measured, rolled up, and ranked. The Walk Leaderboard is the public board for it: walkers ordered by distance walked, sites visited, or time on their feet, over today, this week, or all time. Signed-in accounts and anonymous walkers compete on the same board, and your own row is always pinned to the bottom of the page even when your rank is off-screen.

Live at three.ws/walk-leaderboard. Backed by one endpoint, GET /api/walk/leaderboard, over the walk_metrics rollup that POST /api/walk/metrics writes.

Code: pages/walk-leaderboard.html (page and its inline module), api/walk/leaderboard.js (ranking), api/walk/metrics.js (ingest), src/walk.js (the accumulator in the walk runtime), api/_lib/migrations/20260621140000_walk_metrics.sql (schema).


What is measured

Three metrics, all derived from the same rollup table. Pick one with the Distance / Sites / Time control; it becomes the ranked column.

Metric Column and aggregate What it actually counts
distance sum(distance_meters) Metres the avatar moved horizontally in the 3D scene, integrated per frame from the controller's resolved displacement. Rendered as metres under 1 km, kilometres above.
time sum(duration_sec) Seconds spent moving. Idle time is not counted (see the motion gate below). Rendered as seconds, minutes, or hours.
sites count(distinct coalesce(embed_origin, site_hostname)), non-null only Distinct third-party hosts the avatar walked on. embed_origin is derived server-side from the request's Origin or Referer; site_hostname is the host an external pilot (such as a browser extension) reports.

Two consequences of how sites is defined, stated plainly because they are easy to misread:

  • three.ws itself never counts as a site. deriveEmbedOrigin() returns null for three.ws, www.three.ws, and localhost, so a walk on the platform's own pages adds distance and time but contributes nothing to the sites metric. That is deliberate: "unique sites" is meant to measure reach across the web, not our own surfaces.
  • A row only reaches the sites metric if a client supplies one of those two dimensions. The metric is a real query over real columns, so as soon as an off-platform embed or pilot posts from its own host, its walkers rank on it. In the current tree the only client that flushes metrics is the walk runtime served from three.ws, so the sites column is sparse in practice while distance and time are fully populated.

Values are rounded to two decimals in the response. A walker with a zero (or absent) value for the selected metric and window is excluded from the ranking entirely (having <aggregate> > 0), which is why the daily board is short early in a UTC day.

The delta column

Every row carries deltaFromYesterday: the same metric earned today minus the same metric earned yesterday, both as UTC days. It is momentum, not a total, and it is computed identically for all three time windows, so the "vs. yesterday" column means the same thing whether you are looking at the daily, weekly, or all-time board. Zero renders as a neutral dash rather than +0.


The three views

?period= selects the window, all boundaries in UTC:

View period Window
Today daily Rows whose day is the current UTC date.
This Week weekly (default) The current UTC date and the previous 6 days, so a rolling 7 days rather than a calendar week.
All Time all-time No lower bound.

The page defaults to This Week / Distance. Switching either control refetches from offset 0. Both control groups are ARIA radiogroups (one filter, one selection) with roving tabindex: arrow keys and Home/End move within a group, and the board sets aria-busy on the table while a request is open.

Only the newest request may paint. Each load aborts the one before it and carries a generation number, so switching period and metric in quick succession always lands on the filter you last clicked, never on a stale page of rows, a column header naming the previous metric, or a skeleton that never resolves. Superseded requests show as cancelled in the network panel; that is the mechanism working, not a failure.

A summary line above the board reports the qualifying walker count, the active metric and window, and the time of the last refresh. Because the board promises live updates, it re-fetches the first page every 45 s while the tab is visible, and once more on return from a hidden tab, both silently: a refresh that fails leaves the last good board in place instead of replacing it with an error. The refresh is skipped once you have paged past the first 50 rows, so Show more results are never yanked out from under you.

Ranking rules:

  • Walkers are sorted by the window value descending, with ties broken deterministically by walker key (u:<userId> or a:<anonId>), so equal totals never shuffle between requests.
  • Ranks are sequential positions in that sorted list (1, 2, 3, ...). The top three render medals instead of a number.
  • total is the count of all qualifying walkers, not the page size, so hasMore is exact.
  • Pagination is limit (1 to 100, default 50) and offset. Show more appends the next page in place.

Identity on the board

  • Signed-in walkers show @username (or their display name when no username is set), link to /u/<username>, and carry an avatar thumbnail: the most recently created non-deleted avatar the account owns that has a thumbnail, which is not necessarily the avatar they walked with.
  • Anonymous walkers rank too, under a derived handle: walker- plus the last four alphanumeric characters of their anonymous id. No profile link, and an initial-letter fallback tile instead of a thumbnail.
  • Your own row is resolved from a session cookie, a bearer token, or the anonId query parameter, and returned as me even when it falls outside the requested page. me.onPage tells the client whether it is already visible above. A walker with an identity but no qualifying metrics in the window comes back as me with rank: null, value: 0, and unranked: true, which the page renders as a dash rather than hiding you.

The page reads localStorage['twx_walk_anon'] to pass anonId. It only reads, never creates, that key: the walk runtime is what mints it. So the pinned row appears for anonymous walkers who have actually walked, and simply does not appear for a first-time visitor.

Every state on the board

State What renders Why it is shaped that way
Loading Eight shimmering skeleton rows under the live column headers, with aria-busy="true" on the table. Paging swaps the Show more label for a loading label and disables the button. The header stays put so the board does not jump when rows land.
Populated Ranked rows, the summary line, and your own pinned row when you have one.
Empty The table is hidden entirely and a state card takes the card over, with copy written for the metric you asked for and a second action back to All Time whenever you are on a narrower window. An all-headers, no-rows table is noise, and the reason a board is empty differs per metric: distance and time ask you to walk, sites explains that only walks away from three.ws count and points at the walk companion. A quiet day is not a dead end.
Error The same card shape with the failure reason and a Retry button that re-runs the request in place. The board is public and unauthenticated, so a retry genuinely is the fix for nearly every failure here.

Row semantics are a real ARIA table: table on the grid, columnheader on the header cells, row and cell on each entry. The top three render a medal glyph in place of the number and carry their rank as screen-reader text, so a medal never reaches assistive tech as an empty cell, and the delta column pairs its +/- glyph with a spoken "up 120 m since yesterday". A polite live region announces the shape of each successful load (how many rows, of how many walkers, by which metric and window) instead of firing on all fifty rows individually.


How a walk session is counted

The board never talks to the walk runtime directly. One ingest feeds it.

1. Per-frame accumulation. accumulateWalkMetrics(dt) runs once per rendered frame in the walk runtime. It takes the horizontal displacement between this frame's avatar position and the last one (hypot(dx, dz)) and adds it to a pending distance, plus dt to a pending duration, but only when all three of these hold:

  • the step is larger than 0.001 m, so a standing avatar accrues no phantom distance from float jitter;
  • the step is smaller than 5 m, so a teleport, a spawn, or a world swap is discarded rather than banked as a sprint;
  • the controller's motion state is walk or run, so time only accrues while actually moving.

2. Session counting. The first qualifying movement flips a counted flag. The first flush that carries it sends sessions: 1, and a sessionFlushed flag makes sure the same page load never counts a second session. So a session is "one page load in which the avatar genuinely moved", not a timer and not a page view.

3. Flush cadence. Batches go to POST /api/walk/metrics every 60 s via fetch with keepalive, and once more on pagehide or on visibilitychange to hidden via navigator.sendBeacon, so the final partial minute survives a tab close or an app backgrounding. Pending counters reset on dispatch. A flush with nothing to report is skipped entirely, and a failed flush is swallowed: metrics never surface an error to the walker.

4. Rollup on the server. Each batch UPSERTs into a per-(walker, UTC day, environment, embed origin, avatar) row in walk_metrics, adding its increments onto whatever is there. The unique index is over the COALESCE'd dimension tuple (Postgres treats NULLs as distinct, which would otherwise spawn a new row per batch and break the rollup). An hour of walking is therefore a handful of rows, not thousands, and the leaderboard aggregates over a compact indexed table.

5. Attribution. A signed-in session or bearer wins and the batch is keyed to user_id. Otherwise it is keyed to the client's anonId, a stable id persisted in localStorage (or a per-page id when storage is blocked). A batch with neither identity is accepted with 202 and explicitly not recorded.

The same batch also carries any achievement thresholds the runtime crossed this session. The ingest persists them once each into walk_achievements under a per-(walker, code) unique index, from an allowlist of four codes: distance_1km, distance_5km, sites_10, and all_environments. The walk runtime currently fires three of them (1 km walked, 5 km walked, and all six environments in one session), each with a toast; sites_10 is accepted by the ingest but has no client that fires it. And for signed-in walkers a batch with real metrics counts as a qualifying daily activity for the cross-surface streak.

What feeds the board today

Only the walk runtime in src/walk.js flushes metrics, so the board is fed by the pages that load it: /temporary (including the /wk/:avatar short link, which redirects there) and /marketplace-walk. The chrome-less embed runtime, src/walk-embed.js, is a deliberate fork of the same engine for iframes and does not currently flush, so /walk/app, the iframe embeds on the /walk landing page, and /pocket (the handheld console whose screen is a /walk-embed iframe) do not accrue leaderboard distance.


What prevents trivially faking distance

As coded, in layers. Each one bounds a different kind of nonsense:

Guard Where Effect
Teleport rejection: a single frame moving 5 m or more is discarded accumulateWalkMetrics in src/walk.js A world swap, respawn, or position restore cannot be laundered into distance.
Jitter floor: steps at or below 0.001 m are ignored same A parked avatar earns nothing, so leaving a tab open all day adds zero distance.
Motion gate: only walk and run states accumulate same Idle, gesture, and cutscene time do not count toward the time metric.
Per-batch ceilings: distanceMeters at most 50000, durationSec at most 86400, sessions at most 50 zod schema in api/walk/metrics.js A batch claiming an implausible jump is rejected outright with 400 validation_error, not clamped and stored. A brisk walk is about 1.4 m/s, so even a ten-minute batch is well under a kilometre.
Strict schema same Unknown fields are rejected (.strict()), so the ingest has no room for extra dimensions a caller might invent.
Server-derived origin deriveEmbedOrigin() in api/walk/metrics.js embedOrigin is accepted in the schema for forward compatibility and then ignored: the stored value always comes from the request's Origin or Referer. A caller cannot attribute walks to a host it does not control, so the sites metric cannot be inflated with invented hostnames.
Identity requirement same A batch with neither a session nor an anonId is a no-op 202. Nothing anonymous-and-unkeyed can enter the rollup.
Rate limit: 60 requests per minute per IP limits.irlInteractIp Matches the roughly one-per-minute flush cadence plus retries, and caps how many batches one address can land.
Achievement allowlist same Only the four known codes persist, and each unlocks once per walker, so badges cannot be farmed by replaying a batch.
Idempotent rollup unique index in the migration Batches merge into one row per dimension tuple per day, so the table cannot be flooded into a different shape.

What these guards do and do not claim. POST /api/walk/metrics is a public, open-CORS ingest keyed on a client-supplied anonymous id, because embeds post from third-party hosts and anonymous walkers are first-class on the board. The guards above bound the size, rate, and attribution of any single claim; they do not cryptographically prove that a walk happened. There is no cross-batch plausibility check (for example, distance against elapsed duration) and no server-side replay of the controller. Treat the board as a gamified activity ranking, not as an audited measurement. If you need a movement claim that a third party can verify, that is a different product: World Lines issue agent-signed proofs of physical presence with server-derived co-location.


API

GET /api/walk/leaderboard

Public. Open CORS (GET, OPTIONS). Rate limited at 240 requests per minute per IP. Cached at the edge with public, max-age=15, s-maxage=30, stale-while-revalidate=60, so the board is live without every switch of a control hitting the database.

Parameter Values Default
period daily | weekly | all-time weekly
metric distance | sites | time distance
limit 1 to 100 50
offset 0 or greater 0
anonId a stable anonymous walker id, to pin that walker's row none

Identity for the pinned me row comes from an Authorization: Bearer token, the session cookie, or anonId, in that order.

curl -s 'https://three.ws/api/walk/leaderboard?period=weekly&metric=distance&limit=3'
{
  "period": "weekly",
  "metric": "distance",
  "total": 128,
  "limit": 3,
  "offset": 0,
  "hasMore": true,
  "rows": [
    {
      "rank": 1,
      "key": "u:8f14e45f-ceea-467a-9c4b-2b0a1d5f7c31",
      "userId": "8f14e45f-ceea-467a-9c4b-2b0a1d5f7c31",
      "anonId": null,
      "username": "ada",
      "handle": "@ada",
      "profileUrl": "/u/ada",
      "avatarId": "c9d2a71e-3b44-4f88-9a01-6de5f2b7c410",
      "avatar": "https://<avatar-cdn-domain>/u/8f14e45f-ceea-467a-9c4b-2b0a1d5f7c31/thumb.webp",
      "value": 18452.31,
      "deltaFromYesterday": 1240.5
    },
    {
      "rank": 2,
      "key": "a:anon_4f6c2b19-77d3-4a2e-9b58-0c1e7a3d55e2",
      "userId": null,
      "anonId": "anon_4f6c2b19-77d3-4a2e-9b58-0c1e7a3d55e2",
      "username": null,
      "handle": "walker-55e2",
      "profileUrl": null,
      "avatarId": null,
      "avatar": null,
      "value": 15990.08,
      "deltaFromYesterday": -320.75
    },
    {
      "rank": 3,
      "key": "u:2b6f0cc9-04e0-4b1f-9c8a-77d5b2e13a90",
      "userId": "2b6f0cc9-04e0-4b1f-9c8a-77d5b2e13a90",
      "anonId": null,
      "username": null,
      "handle": "three.ws walker",
      "profileUrl": null,
      "avatarId": null,
      "avatar": null,
      "value": 14201.4,
      "deltaFromYesterday": 0
    }
  ],
  "me": null
}

Pin an anonymous walker's own row:

curl -s 'https://three.ws/api/walk/leaderboard?period=daily&metric=time&limit=1&anonId=anon_4f6c2b19-77d3-4a2e-9b58-0c1e7a3d55e2'
{
  "period": "daily",
  "metric": "time",
  "total": 41,
  "limit": 1,
  "offset": 0,
  "hasMore": true,
  "rows": [
    {
      "rank": 1,
      "key": "u:8f14e45f-ceea-467a-9c4b-2b0a1d5f7c31",
      "userId": "8f14e45f-ceea-467a-9c4b-2b0a1d5f7c31",
      "anonId": null,
      "username": "ada",
      "handle": "@ada",
      "profileUrl": "/u/ada",
      "avatarId": "c9d2a71e-3b44-4f88-9a01-6de5f2b7c410",
      "avatar": "https://<avatar-cdn-domain>/u/8f14e45f-ceea-467a-9c4b-2b0a1d5f7c31/thumb.webp",
      "value": 5402.7,
      "deltaFromYesterday": 900.1
    }
  ],
  "me": {
    "rank": 7,
    "key": "a:anon_4f6c2b19-77d3-4a2e-9b58-0c1e7a3d55e2",
    "userId": null,
    "anonId": "anon_4f6c2b19-77d3-4a2e-9b58-0c1e7a3d55e2",
    "username": null,
    "handle": "walker-55e2",
    "profileUrl": null,
    "avatarId": null,
    "avatar": null,
    "value": 1843.2,
    "deltaFromYesterday": 612.4,
    "onPage": false
  }
}

Errors: 400 bad_period, 400 bad_metric, 429 when the public per-IP limit trips. Out-of-range limit and offset are clamped rather than rejected.

POST /api/walk/metrics (the ingest)

The board's write side, shared with the per-creator embed analytics dashboard. Open CORS so third-party embeds can post. Body fields relevant to the leaderboard:

Field Type Notes
distanceMeters number, 0 to 50000 Increment since the last flush.
durationSec number, 0 to 86400 Increment since the last flush.
sessions integer, 0 to 50 Send 1 once per page load that produced real movement.
anonId string, 8 to 64 chars Required when there is no session or bearer.
envId string Walk environment name, a rollup dimension.
avatarId uuid The avatar being walked, a rollup dimension.
siteHostname string The host an external pilot reports, feeding the sites metric.
achievements array, up to 8 Codes from the allowlist; anything else is dropped.
eventName, value string, number Creator-defined conversion event for the analytics funnel, not the leaderboard.
embedOrigin string Accepted and ignored; the stored origin is always server-derived.
curl -s https://three.ws/api/walk/metrics \
  -H 'content-type: application/json' \
  -d '{"distanceMeters":412.5,"durationSec":295.4,"sessions":1,"envId":"park","anonId":"anon_4f6c2b19-77d3-4a2e-9b58-0c1e7a3d55e2"}'
{ "ok": true, "recorded": true }

A batch with no identity returns 202 with { "ok": false, "reason": "no walker identity", "recorded": false }. A batch that violates a ceiling returns 400 validation_error naming the field.


Privacy and identity

No geolocation is involved anywhere on this surface. Distance is virtual-world displacement in a 3D scene, not GPS, so nothing here touches the presence machinery that gates the real-world features. What the board stores about a walker is an account id or a client-generated anonymous id, plus per-day totals and rollup dimensions.

The anonymous id is generated and persisted by the walk runtime in localStorage under twx_walk_anon and is the only thing linking an anonymous walker's rows across visits. Clearing site data ends that continuity: the old rows stay on the board under their old derived handle and a new id starts from zero. Public rows expose only the derived walker-xxxx handle, never the full id, and never an IP.


Related

  • Add the Walk Companion to your site, the hands-on path from a copy-paste iframe to the @three-ws/walk package, including the surfaces that produce the metrics ranked here.
  • The walk documentation set on the site, served from public/docs/walk/: /docs/walk (index), /docs/walk/getting-started, /docs/walk/walk-page, /docs/walk/embed-iframe, /docs/walk/embed-sdk, /docs/walk/companion-mode, /docs/walk/chrome-extension, /docs/walk/postmessage-events, /docs/walk/changelog, and /docs/walk/analytics, which covers the per-creator dashboard fed by the same ingest.
  • The creator-side view of this data: three.ws/walk-analytics, backed by GET /api/walk/analytics.
  • World Lines, for movement claims that carry a verifiable agent signature rather than a leaderboard rank.