# Runtime, progress, achievements, and analytics

## Player/runtime state

- Create, retrieve, update, and look up players by user/wallet.
- Retrieve player history and current game/scene state.
- Load a scene manifest and published play route.
- Start NPC dialogue, return dialogue plus HEARTS deltas/triggers, and resolve route/scene transition.
- Generate a runtime scene when requested.

## Multiplayer/realtime

- Connect to Studio or player WebSocket rooms.
- Join/leave, move, interact, start/end dialogue, send emotes, and heartbeat.
- Lock/release NPCs and return busy/error states.
- Broadcast player movement, NPC state, scene transitions, and world messages.
- List active players, room statistics, recent events, and batch player events.
- Reconnect, resynchronize, and represent stale/disconnected state.

## HEARTS and progress

- Read/update HEARTS facets and rubric; seed defaults and inspect aggregate stats.
- Calculate and persist HEARTS changes from dialogue, challenges, quests, events, and assets.
- Load/save/delete game progress by player/wallet and game.
- Record challenge completion, collected coins/items, scene/quest state, and history.
- Show growth by facet and rubric explanation.

## Scores and leaderboards

- Submit one or batch scores; increment scores where supported.
- List score records and delete/reset eligible scores.
- Configure leaderboards per game: metric, type, period, ordering, and visibility.
- View overall/top/nearby ranks, player rank/history, scoreboard, and game statistics.
- Take leaderboard snapshots and reset a period.

## Achievements

- Create/list/edit/delete achievements and create defaults for a game.
- Configure triggers, conditions, thresholds, hidden state, rewards, icon, and ordering.
- Check triggers, update progress, unlock, mark seen, and list player achievement state.

## Analytics and observability

- Start/end play sessions and inspect session detail.
- Record one or batch analytics events.
- Load/save analytics progress.
- View game overview, scene analytics, challenge analytics, HEARTS analytics, and combined game analytics.
- View Studio realtime page, active player counts, event stream, and world broadcasts.
- Inspect LangSmith traces for AI graphs and execution traces for skills/operators.

## New UI requirements

- Separate creator analytics from player-facing progress and public leaderboards.
- Define identity reconciliation across user ID, wallet user ID, player ID, and agent identity.
- Show consent/privacy/retention for analytics and public leaderboard data.
- Support live, delayed, offline, duplicate, corrected, reset, and season/period states.
- Provide drill-down from aggregate metric to event/session/source where permissions allow.

