Prototype agent, controller, and Nakama backend foundation

.claude/CLAUDE.md

@@ -39,6 +39,7 @@ International-friendly framing. Explained via science (Nibirium, biotech, consci
 - Guild PvP up to 50v50
 - Top-down ARPG action combat
 - Time-as-currency economy: body time can be earned, spent, transferred later, and lost on body death unless explicit conversion rules say otherwise
+- OpenClaw-connected NPCs: a user may connect their own OpenClaw agent into the game as an NPC-like world actor, subject to identity, consent, moderation, rate limit, and server-side intent validation
 - Pet system: NFT-based, 1 equip slot, NOT looted from bosses (marketplace + breeding only)
 - Mount system: movement only, no mounted combat (reduce animation workload)
 
@@ -66,11 +67,14 @@ International-friendly framing. Explained via science (Nibirium, biotech, consci
 
 ### Backend
 
-- **Supabase Auth** (reuse DOS.Me pattern, do not invent new auth)
-- **Supabase Postgres** (durable state: profile, inventory, quest progress, NFT lock state, cultivation tier)
-- **Supabase Realtime** (chat global, presence, friend, party invite, notification - NOT for combat / movement sync)
-- **Supabase Storage** (avatar, screenshot, UGC)
-- **Go LLM Gateway** (reuse DOSRouter pattern, self-host VPS, low-latency)
+- **Game backend:** Nakama OSS (ADR 0010). This is the default backend foundation for game APIs, social primitives, storage objects, activity logs, and future groups / leaderboards / matchmaking.
+- **Nakama deployment mode:** self-hosted OSS for prototype and early development. Heroic Cloud is a future managed upgrade path only, not the current default.
+- **Backend boundary:** Nakama is the game backend. `api.dos.ai` / Go LLM Gateway is the shared DOS.AI AI/LLM gateway only. Photon Fusion 2 dedicated server remains authoritative for in-zone movement, combat, physics, and tick simulation.
+- **Custom game backend rule:** Do not create a separate game API gateway unless a Nakama runtime module cannot reasonably handle the feature. Default to Nakama server runtime modules (TypeScript / Go / Lua) for game backend extensions: auth hooks, RPCs, inventory, profile, stats, social, matchmaking, leaderboards, activity logs, and moderation. Initial Nakama modules use exact TypeScript 6.0.3 and emit Nakama-compatible JavaScript.
+- **Supabase:** compatible sidecar for DOS.Me-style identity bridge, wallet/profile integration, storage, analytics, or external product data when useful. Supabase is no longer the primary game backend baseline.
+- **Hiro / Satori:** Commercial / license-dependent candidates only. Do not assume they are open-source drop-in dependencies.
+- **Postgres** (durable Nakama database; local container for development or approved Supabase Postgres project if isolation and connection behavior are verified)
+- **Go LLM Gateway / `api.dos.ai`** (shared AI service; provider keys, model routing, prompt safety, voice token minting, AI-specific endpoints only)
 - **Redis** (session, rate limit, transient cache)
 
 ### LLM
@@ -82,21 +86,31 @@ International-friendly framing. Explained via science (Nibirium, biotech, consci
 
 **Phase 2 (post-MVP):**
 
-- Migrate to Go gateway, models:
+- Migrate LLM calls to `api.dos.ai` / Go LLM Gateway, models:
   - Haiku 4.5 for NPC chat (fast, cheap)
   - Sonnet 4.6 for boss / quest / cultivation master dialog
 - RAG memory: Supabase pgvector or Qdrant
 - Voice: OpenAI Realtime API via ephemeral token (NOT API key in client) OR ElevenLabs
 - Client AI: Unity Sentis for small perception (optional, phase 3)
 
+### OpenClaw-Connected NPCs (CONCEPT)
+
+- Each OpenClaw agent can become a user-owned NPC-like actor in SECOND SPAWN.
+- A player may connect their OpenClaw agent to the game so it can appear as a companion, hub NPC, merchant-like persona, quest-adjacent character, or social world citizen.
+- OpenClaw agents must never mutate authoritative game state directly. They emit dialogue or structured intent only.
+- Nakama owns game identity, permissions, rate limits, activity logs, and moderation state for connected agents.
+- Fusion server validates any in-world action intent before movement, interaction, combat, inventory, currency, quest, or BodyTime state changes.
+- `api.dos.ai` / Go LLM Gateway handles provider calls, prompt safety, memory retrieval, and context shaping for OpenClaw-connected NPC behavior.
+- This is an ecosystem bridge, not a replacement for NPC dialogue, offline player agents, or the game backend.
+
 ### LLM Safety (CRITICAL)
 
 - **Server-side intent validation ONLY** - never trust LLM output as authoritative
 - **Never let LLM directly mutate game state** (no auto-grant item, gold, XP)
 - Per-NPC memory budget cap
 - Rate limit per player (LLM token + request count)
 - Prompt injection defense (reuse DOSafe patterns)
-- All LLM calls go through Go gateway, never direct from Unity client
+- All LLM calls go through `api.dos.ai` / Go LLM Gateway, never direct from Unity client
 
 ### AI Agent for Offline Players (CORE FEATURE)
 
@@ -115,7 +129,7 @@ International-friendly framing. Explained via science (Nibirium, biotech, consci
   - Hunter skins - Option 1 (preset hero characters, may hybrid with Option 3 later)
   - Weapons
   - Pets (1 equip slot, marketplace + breeding only, no boss drop)
-- **Wallet auth:** Sign-message pattern via thirdweb or Supabase + DOS Chain
+- **Wallet auth:** Sign-message pattern via thirdweb, Nakama auth bridge, or Supabase + DOS Chain sidecar
 - **In-game lock:** Escrow contract when equipped, release on unequip
 - **SECOND token:** Used for reincarnation cost (token economy needs design). Keep distinct from `BodyTime` unless a future ADR explicitly merges them.
 
@@ -140,7 +154,8 @@ International-friendly framing. Explained via science (Nibirium, biotech, consci
 ### Deploy
 
 - **Game server:** Linux headless Unity build on Hetzner VPS, Dockerized
-- **Backend Go gateway:** VPS or Modal
+- **Nakama backend:** self-hosted OSS first; Heroic Cloud only if operations become worth paying for
+- **AI/LLM gateway:** `api.dos.ai` shared Go gateway
 - **LLM API:** Convai phase 1, then Anthropic + OpenAI phase 2
 - **Monitoring:** Sentry (error) + Grafana (metrics)
 
@@ -178,7 +193,7 @@ International-friendly framing. Explained via science (Nibirium, biotech, consci
 
 - Coplay unity-mcp (Unity Editor bridge)
 - thirdweb-api (DOS Chain wallet, NFT logic)
-- Supabase MCP (database, auth, edge functions)
+- Supabase MCP (sidecar database, auth, edge functions when used)
 - Cloudflare MCP (future R2 migration)
 
 ## Reference Materials
@@ -222,15 +237,15 @@ International-friendly framing. Explained via science (Nibirium, biotech, consci
 - Unity Multiplayer Play Mode tutorial
 - Coplay unity-mcp + Claude Code setup guide
 - DOSRouter Go gateway pattern (JOY's existing repo)
-- DOS.Me Supabase auth pattern (JOY's existing repo)
+- DOS.Me Supabase auth pattern (JOY's existing repo, reference for identity bridge only)
 
 ## Project Conventions
 
 ### Naming
 
 - Repo: `Second-Spawn` (matches GitHub repo name as-is)
 - Repo root: `D:\Projects\Second-Spawn`
-- Unity project subfolder: `D:\Projects\Second-Spawn\Unity` (PascalCase, NOT at repo root - multi-stack repo: Unity at `Unity/`, Go gateway at `backend/`, docs at `docs/`)
+- Unity project subfolder: `D:\Projects\Second-Spawn\Unity` (PascalCase, NOT at repo root - multi-stack repo: Unity at `Unity/`, Nakama modules at `backend/nakama/`, docs at `docs/`)
 - C# code: Microsoft conventions (PascalCase classes, camelCase fields with `_` prefix for private serialized)
 - Branches: `feat/<short-desc>`, `fix/<short-desc>`, `chore/<short-desc>`
 - **Unity-specific conventions** (folder structure, asmdef pattern, scene organization, naming rules): see [docs/setup/unity-conventions.md](docs/setup/unity-conventions.md). MUST follow before creating, renaming, or organizing any Unity asset, script, or folder.
@@ -285,7 +300,7 @@ Scope:
 - 2 cultivation tiers playable (Awakening + Enhancement)
 - NFT Hunter skin equip + escrow
 - Multiplayer 4-20 players per zone
-- Basic chat (Supabase Realtime)
+- Basic chat (Nakama channels first, Supabase sidecar only if useful)
 
 OUT of scope for vertical slice:
 
@@ -301,9 +316,9 @@ OUT of scope for vertical slice:
 
 1. **NEVER copy MetaDOS gameplay code.** Extract patterns only. Reference path: `D:\Projects\MetaDOS` (read-only).
 2. **NEVER let LLM mutate authoritative game state.** Server validates all intent.
-3. **NEVER put API keys (Anthropic, OpenAI, Convai, ElevenLabs) in Unity client.** All LLM calls go through Go gateway.
+3. **NEVER put API keys (Anthropic, OpenAI, Convai, ElevenLabs) in Unity client.** All LLM calls go through `api.dos.ai` / Go LLM Gateway.
 4. **NEVER use Host Mode for production.** Server Mode dedicated only.
-5. **NEVER add Nakama, OpenAuth, or new auth / social stack.** Reuse Supabase + DOS.Me patterns.
+5. **NEVER add or replace backend / auth / social stack without an ADR and JOY approval.** Nakama OSS is the accepted game backend baseline per ADR 0010. Heroic Cloud, Hiro, Satori, OpenAuth, PlayFab, AccelByte, or a Supabase-first rollback require a new ADR.
 6. **NEVER change Unity Asset Serialization away from Force Text.** Breaks LFS + diff.
 7. **NEVER claim "done" without reviewer pass** (JOY is non-coder, cannot review code himself).
 8. **ALWAYS edit BOTH `.claude/CLAUDE.md` and `AGENTS.md` together when updating project context.** They are sister files - Claude Code auto-loads CLAUDE.md, Codex CLI / Cursor / Copilot auto-load AGENTS.md. Edit one without the other = drift; the un-updated file lies to whichever agent reads it. Both files MUST be identical except for the sister-file comment header at line 1.
@@ -316,5 +331,6 @@ OUT of scope for vertical slice:
 - Hunter NFT integration approach: Option 1 (preset hero) vs Hybrid 1+3 (modular pieces)
 - Phase 2 LLM model split (when to use Haiku vs Sonnet)
 - Voice NPC vendor (OpenAI Realtime vs ElevenLabs vs self-host)
+- Backend deployment path: self-hosted Nakama OSS vs Heroic Cloud later. Hiro / Satori require license and pricing review before adoption.
 - Dedicated server hosting (Hetzner specs, region)
 - Photon Fusion 2 license tier when scaling beyond Cloud free 20 CCU

.github/workflows/backend-test.yml

@@ -31,7 +31,11 @@ jobs:
       - name: Verify go.mod is tidy
         run: |
           go mod tidy
-          git diff --exit-code go.mod go.sum
+          if [ -f go.sum ]; then
+            git diff --exit-code -- go.mod go.sum
+          else
+            git diff --exit-code -- go.mod
+          fi
 
       - name: Vet
         run: go vet ./...

.gitignore

@@ -91,6 +91,16 @@ backend/dist/
 # Photon credentials (if checked-in template)
 PhotonServerSettings.asset.local
 
+# Paid Unity Asset Store assets (installed locally via Package Manager > My Assets)
+Unity/Assets/ExplosiveLLC/
+Unity/Assets/ExplosiveLLC.meta
+
+# Local clean visual prefabs generated from ignored Asset Store character packs.
+Unity/Assets/_SecondSpawn/Art/Characters/GeneratedVisuals/
+Unity/Assets/_SecondSpawn/Art/Characters/GeneratedVisuals.meta
+Unity/Assets/_SecondSpawn/Art/Characters/GeneratedVisualsV2/
+Unity/Assets/_SecondSpawn/Art/Characters/GeneratedVisualsV2.meta
+
 # Claude Code worktrees (ephemeral, per-session branches)
 .claude/worktrees/
 
@@ -99,3 +109,12 @@ PhotonServerSettings.asset.local
 
 # Codex CLI working dir (auto-regenerated mirror of .claude/skills/, do not commit)
 .agents/
+
+# Local agent/editor scratch artifacts
+.tmp-import/
+Unity/Assets/Screenshots/
+Unity/Assets/Screenshots.meta
+Unity/Assets/_Recovery/
+Unity/Assets/_Recovery.meta
+Unity/Assets/AI Toolkit/
+Unity/Assets/AI Toolkit.meta