Game Agent

A coding agent that builds playable 3D browser games from a single prompt, and keeps refining them in chat.

"A space shooter where I dodge asteroids" → playable game, live in your browser, in ~2 minutes. Then "add homing missiles and a pause menu" → live update.

For the architecture and the engineering decisions behind this build, see NOTES.md.

---

---

What it does

• One-prompt builds. Describe a 3D game; the agent writes a complete App.tsx and deploys it to a Freestyle sandbox VM running Expo Web.
• Iterative refinement. Reprompt with anything ("add explosions", "make bullets home toward enemies", "different colors") and the running game updates without a fresh build.
• Per-update summaries. Every build/update produces a 3-5 bullet summary in chat so you actually know what changed.
• Pause / Settings / Restart shipped by default. Every generated game ships with a pause menu, rebindable controls, and (when applicable) a Game Over screen with Restart. No need to ask.
• Persistent sessions. Reload the page; your game and chat history are still there. "+ New Chat" starts fresh.

---

Tech stack

• Frontend: Next.js 15 (App Router) + React 19 + Tailwind v4
• Backend: Convex (Agent component + Workflows)
• LLM: Claude Sonnet 4.5 via @ai-sdk/anthropic (extended thinking enabled for the modify path)
• Sandbox: Freestyle VMs running Expo Web + Metro + Three.js / expo-three / expo-gl
• Deploy: Vercel (Next.js) + Convex managed deployment

---

Project structure

convex/
  agent.ts          # generateCode action: 2 system prompts, skeleton, extraction
  workflow.ts       # gameWorkflow: orchestrates generate → deploy/hotReload
  freestyle.ts      # deploy() + hotReload()
  sessions.ts       # session state (idle/generating/building/running/error)
  messages.ts       # thread message listing for streaming chat
  schema.ts         # session table + thread refs

src/
  app/
    page.tsx              # session/thread state, localStorage persistence
    layout.tsx
    globals.css
  components/
    ChatPanel.tsx         # streaming chat, suggestion chips, "+ New Chat"
    PreviewPanel.tsx      # iframe + warmup overlay
    GameAgentLogo.tsx     # the ◆ logo

---

Setup (run locally)

# 1. Install
npm install

# 2. Convex dev (creates a personal dev deployment, prompts for env vars)
npx convex dev
# In another shell:

# 3. Set the secrets on your Convex dev deployment
npx convex env set ANTHROPIC_API_KEY sk-ant-...
npx convex env set FREESTYLE_API_KEY <your-freestyle-key>

# 4. Start Next.js
npm run dev

Open http://localhost:3000.

Required env vars

Var	Where to set	Used by
ANTHROPIC_API_KEY	Convex (dev/prod)	convex/agent.ts
FREESTYLE_API_KEY	Convex (dev/prod)	convex/freestyle.ts
NEXT_PUBLIC_CONVEX_URL	.env.local (auto-set by convex dev)	client

For Vercel deployment, also set CONVEX_DEPLOY_KEY in Vercel and override the build command to npx convex deploy --cmd 'npm run build' --cmd-url-env-var-name NEXT_PUBLIC_CONVEX_URL.

---

Known limitations

• Sessions persist per-browser (localStorage). No cross-device sync; would need a real auth layer.
• Freestyle VMs idle-time-out after a while; reprompting against a dead VM surfaces an error and the user hits "+ New Chat" to recover.
• First build is ~2 minutes (Metro cold start). Subsequent reprompts hot-reload in ~2-3s.
• Anthropic prompt cache is enabled on the system prompt to keep reprompt costs reasonable, but a long chain of reprompts on a 2000-line file is still token-heavy.
• The agent's generated games don't currently load external 3D assets. Three.js primitives only.