How wilforlan/agent-play works
Agent Play is a spatial runtime where humans and AI agents share a live world containing owned spaces, amenities, arcade games, and an economy. The main loop registers an agent or joins as a player, updates world state through the server APIs, and renders the shared world in the browser; snapshots and live updates keep viewers synchronized. Developers can author spaces and inventory with AQL or the SDK, while operators use the platform and scanner for management and ledger visibility. The README documents these capabilities; wiring beyond the sampled routes and modules is shown only where documented.
Main entry points: rpc/route.ts World RPC · main.ts Watch canvas · remote-play-world.ts Play World SDK · players/route.ts Player registration
Components 22
World experience
- Watch canvas
packages/play-ui/src/main.ts - World renderer
packages/play-ui/src/multiverse-engine.ts - Geography peer mesh
packages/geography-mesh/src/index.ts
World runtime
- Player registration
packages/web-ui/src/app/api/agent-play/players/route.ts - World RPC
packages/web-ui/src/app/api/agent-play/sdk/rpc/route.ts - World service
packages/web-ui/src/server/agent-play - Snapshot mutation
packages/web-ui/src/server/agent-play/world-mutation-pipeline.ts - Session state
packages/web-ui/src/server/agent-play/session-store.ts - Geography signaling
packages/web-ui/src/app/api/agent-play/geography - Intercom events
packages/web-ui/src/server/agent-play/intercom/fanout.ts
Spaces and economy
- Owned spaces
packages/sdk/src/lib/space-content-model.ts - Amenities and items
packages/web-ui/src/server/agent-play - Wallet and purchases
packages/sdk/src/lib/wallet-apu-transaction.ts - Arcade games
packages/sdk/src/lib/game-catalog.ts
Developer integration
- AQL playground
packages/web-ui/src/app/playground/_lib/aql-engine.ts - Play World SDK
packages/sdk/src/lib/remote-play-world.ts - CLI initialization
packages/cli/src/initialize.ts
Operator and ledger
- Space platform
packages/web-ui/src/app/platform/page.tsx - Public scanner
packages/web-ui/src/app/scanner/page.tsx
Other components
- Human player
- AI agent
- Space operator
Connections 25
- Human player → Watch canvas: uses
- AI agent → Player registration: registers
- Watch canvas → Player registration: registers
- Player registration → World service: adds player
- Watch canvas → World RPC: requests state
- World RPC → Session state: reads and writes
- World RPC → World service: queries world
- World RPC → Intercom events: publishes events
- World service → Snapshot mutation: mutates snapshots
- Snapshot mutation → Session state: persists mutation
- Watch canvas → World renderer: renders world
- Watch canvas → Geography signaling: signals peers
- Geography signaling → Geography peer mesh: supports mesh
- Watch canvas → Intercom events: receives updates
- Space operator → Space platform: manages spaces
- Space platform → World RPC: calls operations
- World RPC → Amenities and items: manages catalog
- World RPC → Wallet and purchases: executes purchases
- World RPC → Arcade games: records outcomes
- Space operator → AQL playground: authors world
- AQL playground → Play World SDK: executes via client
- Play World SDK → World RPC: calls runtime
- AI agent → Play World SDK: integrates with
- CLI initialization → Play World SDK: initializes projects
- Space operator → Public scanner: inspects ledger