diff --git a/CHANGELOG.md b/CHANGELOG.md index 2bb026c..bd529f9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,17 @@ versioned release tag yet, so entries are organized as pre-alpha snapshots. ### Added +- Unity `NetworkPlayer` now carries prototype level, combat stats, BodyTime, + lifecycle, SECOND balance, reincarnation count, visual key, and agent-control + state as networked fields. +- Prototype HUD now shows level, HP, energy, attack, defense, agility, + BodyTime, lifecycle, SECOND balance, and reincarnation count. +- Unity `CharacterMemorySync` now applies Nakama profile body state onto the + authoritative local player after profile load. +- Prototype BodyTime and reincarnation debug panel for exercising earn, spend, + drain, zero-time death, and reincarnation from Play Mode. +- Actor profile registry for NPC-like actors, including body, stats, traits, + soul, memory, policy, runtime, and activity state. - Prototype NPC brain phase tracing for `Sense -> Decide -> Validate -> Act -> Reflect -> Cooldown`, with a serialized toggle for local debugging. - Model-backed JSON intent path for `/v1/agent/decide`. @@ -25,9 +36,20 @@ versioned release tag yet, so entries are organized as pre-alpha snapshots. cooldown, activity logging, and zero-time body death. - Nakama `secondspawn_reincarnate` RPC for a prototype zero-time death to fresh body flow using a 5-day SECOND cost against a 7-day starting test balance. +- Unity `6000.5.0b8` project baseline. +- PR review fallback policy for local `code-review`, Gemini, and Codex Cloud + review availability. +- Roadmap tracking model for using GitHub Projects as the issue, PR, review, + and milestone execution layer. +- GitHub Project #5 tracking guide with source-of-truth split, recommended + fields, views, seed issues, and CLI project-scope note. ### Changed +- Local Unity prototype can show a player with persisted profile stats after + joining the hub scene. +- Current visible progression baseline is level and body-bound stats. Advanced + body progression, cultivation tiers, and Nibirium XP remain deferred. - Gateway config now supports `AGENT_DECISION_MODEL`. - Gateway docs and Cloud Run env examples now describe the model-backed decision path. @@ -43,17 +65,29 @@ versioned release tag yet, so entries are organized as pre-alpha snapshots. lifecycle state in the shared profile DTO. - Unity gateway client now exposes SECOND balance, reincarnation count, and a Nakama reincarnation wrapper for prototype UI and playtest flows. +- Gateway player profile schema now accepts `second_balance_seconds` and + `reincarnation_count` in Unity-originated agent context payloads. +- Nakama storage writes now use create/update version handling compatible with + refreshed local runtime state. ### Verification -- `go test ./...` in `backend/gateway`. -- `npm test` in `backend/nakama`. -- Unity MCP refresh and Play Mode smoke for NPC brain phase traces. +- `go test -count=1 ./...` and `go vet ./...` in `backend/gateway`. +- Cloud Run staging gateway `/readyz` and `/v1/agent/decide` smoke on revision + `second-spawn-gateway-00008-cnn`. +- `npm run build` and `npm test` in `backend/nakama`. +- Local Nakama runtime `secondspawn_health` smoke with the current module. +- Unity Play Mode smoke for `ZoneTest_Hub`, including profile/stat sync, + BodyTime UI, reincarnation debug flow, and NPC brain traces. +- Markdown lint and dash scan for docs updates. ### Known Issues -- PR #5 has merged into `dev`; the next review gate is the profile bootstrap - and agent activity branch. +- Real combat damage, enemy rewards, loot drops, quest progress, and player + time-loot from other users are not implemented yet. +- Unity UI is still prototype IMGUI, not production HUD. +- Supabase anonymous auth can be used when configured, but the local prototype + still supports Nakama device fallback for development. - Gateway route-level JWT enforcement is not complete. - LLM rate limiting and token budget enforcement are tracked in issue #6. - Real voice still waits for an ephemeral-token provider flow. diff --git a/ROADMAP.md b/ROADMAP.md index feccf03..ee61698 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1,11 +1,47 @@ # SECOND SPAWN Roadmap Status: Pre-alpha, vertical slice foundation in development. +Last updated: 2026-05-17. This roadmap tracks implementation status. Detailed design remains in `docs/`, especially `docs/design/02-vertical-slice-spec.md` and `docs/design/03-systems-index.md`. +## Tracking Model + +- `ROADMAP.md` tracks public milestone status and should stay readable without + GitHub access. +- `CHANGELOG.md` tracks what changed after code, docs, or prototype merges. +- `docs/design/12-game-design-document.md` tracks the living GDD and current + design truth. +- GitHub Projects should track daily execution through issues, PRs, priorities, + owners, milestone views, and review state. +- Primary execution project: [DOS Project #5](https://github.com/orgs/DOS/projects/5). +- GitHub issues should become the unit of work for roadmap items once they are + ready to implement. +- Pull requests should link issues and move project status through automation + where possible. + +Recommended GitHub Project fields: + +| Field | Values | +| ---- | ---- | +| Status | Inbox, Ready, In Progress, In Review, Blocked, Done | +| Area | Unity, Nakama, Gateway, AI Agent, Design, Docs, DevOps, Economy, Combat, UX | +| Milestone | Foundation, Vertical Slice, Alpha, Beta, Post-Launch | +| Priority | P0, P1, P2, P3 | +| Size | XS, S, M, L, XL | +| Review Gate | Not Ready, Local Review, Gemini, Codex, Approved, Waived | +| Verification | Not Run, Docs Lint, Backend Tests, Unity Smoke, Playtest | + +Recommended views: + +- Vertical Slice Board: group by Status and filter Milestone = Vertical Slice. +- Engineering Table: sort by Priority, Area, and Size. +- Review Queue: filter Status = In Review or Review Gate not Approved. +- Roadmap: timeline or roadmap view grouped by Milestone. +- Risks and Blockers: filter Status = Blocked or Priority = P0. + ## Completed Foundation - [x] Public repo structure with Unity in `Unity/`, backend modules in @@ -36,6 +72,37 @@ especially `docs/design/02-vertical-slice-spec.md` and - [x] Project docs and ADRs for Fusion, Unity 6.5 beta, Nakama OSS, LLM safety, AI offline control, agent workflow, and backend boundaries. - [x] Backend tests for gateway contracts and Nakama runtime behavior. +- [x] Unity project baseline upgraded to Unity `6000.5.0b8`. +- [x] Cloud Run staging gateway smoke-tested with the current Unity player + context payload. +- [x] Local Nakama runtime smoke-tested with the current TypeScript module. +- [x] PR review fallback policy documented for local `code-review`, Gemini, and + Codex Cloud review availability. + +## Current Playable Prototype Snapshot + +- [x] `ZoneTest_Hub` enters Play Mode with a Fusion-spawned local player. +- [x] The spawned player has networked level, combat stats, BodyTime, lifecycle, + SECOND balance, reincarnation count, visual key, and agent-control flag. +- [x] Unity prototype HUD shows level, HP, energy, attack, defense, agility, + BodyTime, lifecycle, SECOND balance, and reincarnation count. +- [x] Unity `CharacterMemorySync` pulls the Nakama player profile and applies + current-body stats, BodyTime, lifecycle, SECOND balance, reincarnation count, + and visual key onto the authoritative local `NetworkPlayer`. +- [x] New player profile bootstrap creates a current body with level 1 stats: + vitality 10, force 8, agility 8, focus 8, resilience 8, health 100, energy + 50, attack 10, and defense 5. +- [x] Prototype account reserve starts with 604800 SECOND seconds, equal to + 7 days, and reincarnation currently costs 432000 SECOND seconds, equal to + 5 days. +- [x] BodyTime earn, spend, drain, zero-time death, and reincarnation debug + controls exist in Play Mode for smoke testing. +- [x] Actor profile registry exists for NPC-like actors, including body, stats, + traits, soul, memory, policy, runtime, and activity state. +- [x] `_AgentNPC_Prototype` can bind to an actor profile, patrol, speak, and use + the model-backed gateway decision path with deterministic fallback. +- [ ] Real combat damage, enemy rewards, loot drops, quest progress, and player + time-loot from other users are not implemented yet. ## Current Review Gate @@ -47,6 +114,8 @@ especially `docs/design/02-vertical-slice-spec.md` and - [x] Defer cultivation/Nibirium runtime progression from the current vertical slice. - [x] Merge reincarnation placeholder flow into `dev`. +- [x] Merge Unity `6000.5.0b8` upgrade and backend smoke fixes into `dev`. +- [x] Merge PR review fallback policy into `dev`. ## Vertical Slice - Current Milestone @@ -74,11 +143,15 @@ MVP, and a visible offline-agent prototype. - [x] Add BodyTime meter MVP with one earn source and one spend sink. - [x] Add reincarnation placeholder flow: death -> SECOND token check -> respawn with current-body reset. -- [ ] Surface BodyTime, lifecycle, SECOND balance, reincarnation count, and +- [x] Surface BodyTime, lifecycle, SECOND balance, reincarnation count, and debug reincarnation controls in the Unity prototype. - [ ] Design server-authoritative PvP or contested-zone loot rules where BodyTime and SECOND can be taken from other users after validated combat or zone events. Clients and LLMs must never self-report this loot. +- [ ] Implement the first server-authoritative combat reward path that can grant + BodyTime after a validated enemy kill or objective completion. +- [ ] Implement the first server-authoritative contested loot rule for taking + BodyTime or SECOND from another user after a validated PvP or zone event. - [ ] Add one dungeon instance with one boss and grounded dialogue. - [ ] Add one Hunter NFT skin equip placeholder with DOS Chain escrow design still server-authoritative. diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index a090bed..deb89d1 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -39,5 +39,6 @@ - [Agent Handoff](setup/agent-handoff.md) - [Fusion Install](setup/fusion-install.md) - [Game Gateway Cloud Run Deployment](setup/game-gateway-cloud-run.md) +- [GitHub Project Tracking](setup/github-project-tracking.md) - [Paid Asset Setup](setup/paid-assets.md) - [Unity Conventions](setup/unity-conventions.md) diff --git a/docs/design/02-vertical-slice-spec.md b/docs/design/02-vertical-slice-spec.md index f8dac94..ce74c97 100644 --- a/docs/design/02-vertical-slice-spec.md +++ b/docs/design/02-vertical-slice-spec.md @@ -1,7 +1,8 @@ # Vertical Slice Spec: SECOND SPAWN -*Status: Spec (slice not yet built)* +*Status: Spec with prototype progress* *Created: 2026-05-14* +*Last updated: 2026-05-17* *Target completion: 3-6 months from setup (T+3 to T+6 from 2026-05-14)* > Note: This is the SPEC version (planning the slice). After slice is built, rename to `02-vertical-slice-report.md` and fill the report template (build velocity, playtest results, recommendation PROCEED/PIVOT/KILL). @@ -36,6 +37,37 @@ This is two questions in one: **does the design loop fun?** AND **is the archite --- +## Current Prototype Progress - 2026-05-17 + +Already implemented: + +- Unity `ZoneTest_Hub` can spawn a Fusion local player. +- The spawned player has networked level, combat stats, BodyTime, lifecycle, + SECOND balance, reincarnation count, visual key, and agent-control state. +- Prototype HUD displays level, HP, energy, attack, defense, agility, + BodyTime, lifecycle, SECOND balance, and reincarnation count. +- Nakama profile bootstrap persists player profile, current body, stats, traits, + soul, memory, agent policy, runtime, activity, BodyTime, and reincarnation + counters. +- Unity can load the Nakama profile and apply current-body stats to the local + authoritative player. +- BodyTime earn, spend, drain, zero-time death, and reincarnation are available + through server-side prototype RPCs and Unity debug controls. +- NPC-like actor profiles exist, and `_AgentNPC_Prototype` can patrol, speak, + and use the gateway decision path with deterministic fallback. + +Still missing from the playable slice: + +- Real combat damage and server-authoritative enemy rewards. +- Normal-play BodyTime earn and spend sources outside debug controls. +- Player-vs-player or contested-zone time-loot rules. +- Questline, dungeon, boss, and grounded dialogue content. +- Production HUD and reincarnation presentation flow. +- NFT skin equip and escrow. +- Dedicated server deployment and 4-20 player load validation. + +--- + ## Scope OUT (explicitly cut from slice) - Guild / PvP (50v50 deferred) @@ -73,7 +105,7 @@ The slice is considered "done" when ALL of the following are true and verified b - [ ] Multiplayer 4-20 players per zone holds 60Hz tick under load test (Fusion bots simulating 50 players for stress). ### Process (verifiable in repo state) -- [ ] All slice work merged to `main` via PR with `code-review` skill pass before merge (per JOY hard rule #4). +- [ ] All slice work merged to `main` via PR with `code-review` skill pass before merge. - [ ] All ADRs that the slice motivated are written in `docs/adr/` (current count: 4; expect 6-10 by slice complete). - [ ] Per-system GDDs in `docs/design/` for Combat, AI agent, Reincarnation, Time-as-currency, NFT escrow, LLM NPC. (Time-as-currency is drafted; advanced body progression is deferred.) - [ ] Vertical Slice Report (`02-vertical-slice-report.md`) written with build velocity, playtest data, recommendation. diff --git a/docs/design/03-systems-index.md b/docs/design/03-systems-index.md index f0ab103..5122f6a 100644 --- a/docs/design/03-systems-index.md +++ b/docs/design/03-systems-index.md @@ -1,7 +1,8 @@ # Systems Index: SECOND SPAWN -*Status: Draft (bootstrapped from CLAUDE.md tech stack + gameplay arch)* +*Status: Living index* *Created: 2026-05-14* +*Last updated: 2026-05-17* --- @@ -29,30 +30,30 @@ This index enumerates every system the game needs, categorizes by Core/Gameplay/ | # | System | Category | Priority | Status | Design Doc | Depends On | | --- | ---- | ---- | ---- | ---- | ---- | ---- | -| 1 | NetworkRunner / Photon Fusion 2 setup | Core | MVP | Not started | (TDD pending) | - | -| 2 | Player Controller (minimal baseline, Simple KCC spike, Opsive UCC evaluation later) | Core | MVP | Drafted | [07-player-controller-prototype.md](07-player-controller-prototype.md) | NetworkRunner | -| 3 | Camera (top-down ARPG) | Core | MVP | Not started | (TDD pending) | Player Controller | -| 4 | Input system (Unity Input System) | Core | MVP | Not started | - | Player Controller | -| 5 | Zone scene management (1 zone vertical slice) | Core | MVP | Not started | (TDD pending) | NetworkRunner | +| 1 | NetworkRunner / Photon Fusion 2 setup | Core | MVP | Prototype | (TDD pending) | - | +| 2 | Player Controller (minimal baseline, Simple KCC spike, Opsive UCC evaluation later) | Core | MVP | Prototype | [07-player-controller-prototype.md](07-player-controller-prototype.md) | NetworkRunner | +| 3 | Camera (top-down ARPG) | Core | MVP | Prototype | (TDD pending) | Player Controller | +| 4 | Input system (Unity Input System) | Core | MVP | Prototype | - | Player Controller | +| 5 | Zone scene management (1 zone vertical slice) | Core | MVP | Prototype | (TDD pending) | NetworkRunner | | 6 | Combat (ARPG action) | Gameplay | MVP | Not started | (TDD pending) | Player Controller, Networked state | | 7 | NPC dialogue (Convai SDK + intent validation) | Gameplay | MVP | Not started | (TDD pending) | api.dos.ai / Go LLM Gateway (phase 2 ready) | | 8 | Quest system (linear, 3-5 quests slice scope) | Gameplay | VS | Not started | (TDD pending) | NPC dialogue, persistence | | 9 | Dungeon instance (1 dungeon, 1 boss) | Gameplay | VS | Not started | (TDD pending) | Combat, NPC dialogue, Photon | | 10 | Boss LLM dialogue (Convai grounded) | Gameplay | VS | Not started | (TDD pending) | NPC dialogue | -| 11 | AI agent for offline players (server-side) | Gameplay | VS | Drafted | [10-character-profile-agent-memory.md](10-character-profile-agent-memory.md) | NetworkRunner, api.dos.ai / Go LLM Gateway, intent schema | +| 11 | AI agent for offline players (server-side) | Gameplay | VS | Prototype | [10-character-profile-agent-memory.md](10-character-profile-agent-memory.md) | NetworkRunner, api.dos.ai / Go LLM Gateway, intent schema | | 37 | OpenClaw-connected NPC bridge (user-owned agents as NPC actors) | Gameplay / Meta | Alpha | Concept | [10-character-profile-agent-memory.md](10-character-profile-agent-memory.md) | Auth, Nakama, api.dos.ai / Go LLM Gateway, NPC dialogue, LLM safety | | 12 | Level/stat progression | Progression | MVP | Prototype | (covered by profile/runtime contracts) | Persistence | -| 13 | Reincarnation flow (death -> SECOND -> new body) | Progression | VS | Not started | (TDD pending) | Level/stats, NFT escrow, Persistence | +| 13 | Reincarnation flow (death -> SECOND -> new body) | Progression | VS | Prototype | [12-game-design-document.md](12-game-design-document.md) | Level/stats, NFT escrow, Persistence | | 14 | SECOND token economy | Economy | VS | Not designed | (GDD pending - JOY input) | DOS Chain integration | -| 36 | Time-as-currency (`BodyTime`) | Economy | VS | Drafted | [08-time-as-currency.md](08-time-as-currency.md) | Reincarnation, Combat, Persistence | +| 36 | Time-as-currency (`BodyTime`) | Economy | VS | Prototype | [08-time-as-currency.md](08-time-as-currency.md) | Reincarnation, Combat, Persistence | | 15 | NFT inventory (Hunter skin slice scope) | Economy | VS | Not started | (TDD pending) | thirdweb-api MCP, Persistence | | 16 | NFT escrow (lock on equip, release on unequip) | Economy | VS | Not started | (TDD pending) | NFT inventory, DOS Chain | | 17 | Loot / drop tables | Economy | VS | Not started | (TDD pending) | Combat, persistence | -| 18 | Profile persistence (Nakama OSS + Postgres) | Persistence | MVP | Drafted | [10-character-profile-agent-memory.md](10-character-profile-agent-memory.md) | Auth | +| 18 | Profile persistence (Nakama OSS + Postgres) | Persistence | MVP | Prototype | [10-character-profile-agent-memory.md](10-character-profile-agent-memory.md) | Auth | | 19 | Inventory persistence | Persistence | MVP | Not started | (TDD pending) | Profile, NFT inventory | | 20 | Quest progress persistence | Persistence | MVP | Not started | (TDD pending) | Profile, Quest system | | 21 | Level/stat persistence | Persistence | MVP | Prototype | (covered by profile/runtime contracts) | Profile | -| 22 | Auth (Nakama + DOS Chain wallet, Supabase sidecar if useful) | Persistence | MVP | Not started | (TDD pending - reuse DOS.Me pattern as identity bridge reference) | Nakama, thirdweb | +| 22 | Auth (Nakama + DOS Chain wallet, Supabase sidecar if useful) | Persistence | MVP | Prototype | (TDD pending - reuse DOS.Me pattern as identity bridge reference) | Nakama, thirdweb | | 23 | HUD (combat, level/stats, BodyTime) | UI | VS | Prototype | (deferred template `_deferred/hud-design.md`) | Combat, Profile | | 24 | Inventory UI | UI | VS | Not started | (deferred template `_deferred/ux-spec.md`) | Inventory persistence | | 25 | NPC dialogue UI | UI | VS | Not started | (deferred) | NPC dialogue | @@ -61,8 +62,8 @@ This index enumerates every system the game needs, categorizes by Core/Gameplay/ | 28 | AI agent activity log UI | UI | VS | Not started | (deferred) | AI agent | | 29 | Audio (SFX, ambient, music - placeholder for slice) | Audio | VS | Not started | (deferred template `_deferred/sound-bible.md`) | - | | 30 | Chat (Nakama channel first, Supabase Realtime sidecar only if useful) | Narrative / UI | VS | Not started | (TDD pending) | Nakama | -| 31 | LLM intent validation (api.dos.ai / Go LLM Gateway pattern) | Meta / Engineering | MVP | Not started | (TDD pending - reuse DOSRouter) | LLM provider | -| 32 | LLM safety (rate limit, prompt injection defense) | Meta / Engineering | MVP | Not started | (TDD pending - reuse DOSafe patterns) | api.dos.ai / Go LLM Gateway | +| 31 | LLM intent validation (api.dos.ai / Go LLM Gateway pattern) | Meta / Engineering | MVP | Prototype | [11-npc-agent-brain-architecture.md](11-npc-agent-brain-architecture.md) | LLM provider | +| 32 | LLM safety (rate limit, prompt injection defense) | Meta / Engineering | MVP | Partial | (TDD pending - reuse DOSafe patterns) | api.dos.ai / Go LLM Gateway | | 33 | Anti-cheat / server-authority verification | Meta / Engineering | MVP | (Architectural) | [docs/ARCHITECTURE.md "Critical Invariants"](../ARCHITECTURE.md#critical-invariants) | All gameplay systems | | 34 | Telemetry / monitoring (Sentry + Grafana) | Meta | Alpha | Deferred | - | All systems | | 35 | Onboarding / tutorial | Meta | VS | Deferred (assume slice = no tutorial) | - | All gameplay systems | @@ -198,12 +199,14 @@ Effort estimate: S = 1-3 days, M = 4-7 days, L = 1-2 weeks, XL = 2-4 weeks (solo | Metric | Count | | ---- | ---- | -| Total systems identified | 36 | -| Design docs started | 6 (deferred advanced body progression, overview design, player controller prototype, time-as-currency, Pirate Adventure reference review, character profile / agent memory) | +| Total systems identified | 37 | +| Systems with prototype implementation | 14 | +| Design docs started | 12 | | Design docs reviewed | 0 | | Design docs approved | 0 | | MVP systems with TDD started | 0 | | Vertical Slice systems with TDD started | 0 | +| Execution tracker | GitHub Projects recommended for issue, PR, review, and milestone tracking | --- diff --git a/docs/design/08-time-as-currency.md b/docs/design/08-time-as-currency.md index 1830009..b786414 100644 --- a/docs/design/08-time-as-currency.md +++ b/docs/design/08-time-as-currency.md @@ -1,9 +1,9 @@ # Time-as-Currency -*Status: Draft* +*Status: Prototype implemented* *Created: 2026-05-14* *Author: Codex* -*Last Verified: 2026-05-14 against MetaDOS wiki and SECOND SPAWN concept docs* +*Last Verified: 2026-05-17 against Nakama BodyTime runtime, Unity HUD, and reincarnation debug flow* *Implements Pillar: Time is life, time is money* > **Quick reference** - Layer: `Core Economy` - Priority: `Vertical Slice` - Key deps: `Reincarnation`, `Loot`, `Profile persistence`, `Server-authoritative gameplay` @@ -68,15 +68,42 @@ The fantasy is not "gold with another name." It is "your life is liquid." The first vertical slice should implement a very small version: -- One `BodyTime` meter on the player. +- One `BodyTime` meter on the player. Implemented in the prototype HUD. - Time decreases only inside a designated danger area or dungeon room. - Killing enemies or completing a small objective grants time. - A test vendor or shrine lets the player spend time on one useful service. -- Reaching zero time triggers the reincarnation placeholder flow. +- Reaching zero time triggers the reincarnation placeholder flow. Implemented + through the Nakama prototype RPC and Unity debug panel. - Offline AI agent activity can consume time while farming. No marketplace, tokenomics, or complex exchange rate is required for the first pass. +## Prototype Implementation Status + +Implemented: + +- Nakama `secondspawn_bodytime_event` validates prototype earn, spend, drain, + and debug fatal-drain events. +- BodyTime is stored on the current body profile with remaining seconds, max + seconds, and danger drain rate. +- BodyTime cannot be changed on a dead body before reincarnation. +- Duplicate earn events are rate-limited by source cooldown. +- BodyTime reaching zero marks the current body dead. +- Unity `CharacterMemorySync` can call the BodyTime RPC and apply the returned + profile state to the authoritative local player. +- Unity prototype HUD displays BodyTime and lifecycle. +- Unity debug panel can exercise earn, spend, drain, fatal drain, and + reincarnation while combat rewards are still absent. + +Not implemented: + +- Real enemy kills or objective completion rewards. +- Real spend sink inside normal play. +- Transfer between party members. +- Player-vs-player or contested-zone time loot. +- Conversion between `BodyTime` and SECOND token. +- Final tuning for drain, earn, and spend values. + --- ## Currency Model @@ -170,6 +197,7 @@ Design constraints: | ---- | ---- | ---- | ---- | | Does `BodyTime` tick down everywhere or only in danger zones? | JOY | Before implementation | Danger zones first. | | Can players transfer time in solo slice? | JOY | Before party feature | Defer until party exists. | +| Can players loot time from other users? | JOY + Codex | Before PvP or contested-zone prototype | Allow only after server-validated combat or zone events. | | Can `BodyTime` convert to `SECOND token` or vice versa? | JOY | Economy design phase | Keep separate for now. | | How visible should the `In Time` inspiration be? | JOY | Narrative pass | Mechanic inspiration only, not direct theme copy. | diff --git a/docs/design/10-character-profile-agent-memory.md b/docs/design/10-character-profile-agent-memory.md index 555a7c9..67d624a 100644 --- a/docs/design/10-character-profile-agent-memory.md +++ b/docs/design/10-character-profile-agent-memory.md @@ -3,7 +3,7 @@ *Status: Prototype implemented* *Created: 2026-05-15* *Author: Codex* -*Last Verified: 2026-05-16 against `AGENTS.md`, ADR 0003, ADR 0004, `08-time-as-currency.md`, Cloud Run staging gateway, and Unity C# assembly build* +*Last Verified: 2026-05-17 against `AGENTS.md`, ADR 0003, ADR 0004, `08-time-as-currency.md`, Cloud Run staging gateway, Nakama runtime smoke, and Unity Play Mode profile sync* > **Quick reference** - Layer: `Persistence / AI Agent` - Priority: `MVP foundation` - Key deps: `Auth`, `Fusion server authority`, `LLM gateway`, `Time-as-Currency`, `Reincarnation` @@ -53,7 +53,6 @@ This preserves: | `AgentPolicy` | Yes | Player | What the offline agent is allowed to do while player is away | | `BodyProfile` | No | Game server | Current synthetic body, visual archetype, BodyTime, lifecycle | | `CharacterStats` | Mostly no | Game server | Combat and movement-affecting numbers for current body | -| `CharacterStats` | Mostly no | Game server | Current-body level and combat stats | | `MemoryRecord` | Yes, with decay | Backend | Small curated memory facts for LLM context | | `AgentRuntime` | Yes, across bodies until reset policy exists | Backend | Counters for profile bootstrap, activity, decisions, fallback decisions, and offline time | | `AgentActivity` | Yes, bounded recent history | Backend | Compact audit trail for offline-agent sessions and Unity/Nakama bootstrap events | @@ -105,7 +104,6 @@ Required fields: | `body_id` | Unique current body ID | | `archetype_id` | Gameplay archetype or class key | | `visual_prefab_key` | Local Unity visual prefab key, used for random spawn visuals later | -| `stats` | Current body combat stats | | `body_time` | Current BodyTime state | | `stats` | Current level and combat stats | | `lifecycle` | `alive`, `dying`, `reincarnating`, or `dead` | @@ -387,6 +385,15 @@ Implemented surfaces: - Unity `SecondSpawnGatewayClient` authenticates with Nakama, reads/writes Nakama profile memory when a Nakama session exists, and calls the cloud gateway for NPC text chat, voice-session contract, and prototype LLM decision. +- Unity `CharacterMemorySync` loads the Nakama profile and applies the current + body state onto the authoritative local `NetworkPlayer`. +- The current player prototype starts at level 1 with vitality 10, force 8, + agility 8, focus 8, resilience 8, health 100, energy 50, attack 10, and + defense 5. +- The prototype HUD shows level, HP, energy, attack, defense, agility, + BodyTime, lifecycle, SECOND balance, and reincarnation count. +- The current prototype account reserve starts with 604800 SECOND seconds and + reincarnation costs 432000 SECOND seconds. - Unity `PrototypeLLMAgentDriver` can toggle prototype agent control with `P`. - Unity `PrototypeNPCChatClient` can trigger prototype NPC chat with `O` and voice-session status with `V`. diff --git a/docs/design/12-game-design-document.md b/docs/design/12-game-design-document.md index 437dd23..ebb407e 100644 --- a/docs/design/12-game-design-document.md +++ b/docs/design/12-game-design-document.md @@ -2,6 +2,7 @@ *Status: Pre-alpha GDD* *Created: 2026-05-16* +*Last updated: 2026-05-17* *Source of truth level: Consolidates current design decisions from `docs/design/`, `AGENTS.md`, and accepted architecture direction. Per-system docs remain authoritative for implementation details.* --- @@ -45,6 +46,24 @@ When the player is offline, a bounded AI agent can continue controlling the char | Phase 1 NPC dialogue | Convai SDK for MVP NPC dialogue | | Chain integration | DOS Chain via thirdweb for wallet, NFT, and SECOND token surfaces | +### Current Implementation Snapshot - 2026-05-17 + +This snapshot tracks what exists in the running prototype today. It is not a +promise that the same UI or tuning will ship. + +| Area | Current State | +| ---- | ---- | +| Unity scene | `ZoneTest_Hub` can enter Play Mode and spawn a Fusion local player. | +| Player visible stats | The prototype HUD shows level, HP, energy, attack, defense, agility, BodyTime, lifecycle, SECOND balance, and reincarnation count. | +| Player profile sync | Unity loads the Nakama profile and applies current-body stats, BodyTime, lifecycle, SECOND balance, reincarnation count, and visual key to the authoritative local `NetworkPlayer`. | +| Default player body | New profiles start at level 1 with vitality 10, force 8, agility 8, focus 8, resilience 8, health 100, energy 50, attack 10, and defense 5. | +| BodyTime loop | Nakama supports prototype earn, spend, drain, duplicate-earn cooldown, zero-time death, and activity logging. | +| Reincarnation loop | Nakama supports dead-body reincarnation into a fresh prototype body. The current test balance is 7 days of SECOND and the current test cost is 5 days. | +| NPC/actor profiles | NPC-like actors can have their own body, stats, traits, soul, memory, policy, runtime, and activity records. | +| Prototype NPC brain | `_AgentNPC_Prototype` can patrol, speak, and use the gateway decision path with deterministic fallback. | +| Backend foundation | Nakama owns durable game profile state. The Go gateway owns AI contracts and Cloud Run smoke tests. | +| Not implemented yet | Real combat damage, enemy loot, quest rewards, production HUD, player-vs-player time loot, wallet escrow, dungeon boss, and dedicated server deployment. | + --- ## 3. Target Fantasy @@ -250,6 +269,8 @@ Death can be caused by combat failure, BodyTime reaching zero, or offline-agent - SECOND token is denominated in seconds and is distinct from current-body `BodyTime` unless a future ADR explicitly merges them. - Reincarnation should consume enough SECOND to create a new playable body-time package. - Candidate reincarnation package is 5-7 days of playable body lifetime. The vertical-slice recommendation is 7 days by default, then tune toward 5 days only if early testing shows the loop is too forgiving. +- Current prototype values are intentionally test-only: 7 days starting SECOND + balance and 5 days reincarnation cost. ### Open Reincarnation Decisions @@ -285,6 +306,15 @@ Vertical slice direction: - Spend time through one useful service. - Trigger reincarnation placeholder when time reaches zero. +Current prototype status: + +- The HUD meter and lifecycle fields are visible in Play Mode. +- Nakama applies earn, spend, drain, and zero-time death through + `secondspawn_bodytime_event`. +- A prototype debug panel can exercise the loop before combat rewards exist. +- Real enemy rewards and player time-loot are still future server-authoritative + rules, not client-side grants. + Open BodyTime decisions: - Drain contexts beyond danger zones: [TODO: JOY input] @@ -688,6 +718,28 @@ In scope: The vertical slice should prove the signature hooks in one compact loop. It does not need content volume. +### Current Completion Notes + +Already proven in prototype: + +- Fusion player spawn and movement in `ZoneTest_Hub`. +- Profile-backed player stats visible on the prototype HUD. +- Nakama profile, body, soul, memory, policy, runtime, activity, BodyTime, and + reincarnation storage paths. +- Prototype NPC/agent brain loop with gateway model decision and deterministic + fallback. +- BodyTime and reincarnation smoke path through debug controls. + +Still required before this feels like a game: + +- First server-authoritative combat damage path. +- First enemy or objective that grants BodyTime. +- First spend sink that is part of normal play instead of debug UI. +- First death/reincarnation presentation flow. +- First questline, dungeon, boss, and grounded dialogue beat. +- First player-vs-player or contested-zone time-loot rule, if included in the + slice. + --- ## 21. Out of Scope diff --git a/docs/setup/github-project-tracking.md b/docs/setup/github-project-tracking.md new file mode 100644 index 0000000..4b0323b --- /dev/null +++ b/docs/setup/github-project-tracking.md @@ -0,0 +1,75 @@ +# GitHub Project Tracking + +*Status: Active* +*Created: 2026-05-17* + +This document defines how SECOND SPAWN uses GitHub Projects for day-to-day +execution tracking. + +## Primary Project + +- Project: [DOS Project #5](https://github.com/orgs/DOS/projects/5) +- Repository: [DOS/Second-Spawn](https://github.com/DOS/Second-Spawn) +- Purpose: issue, pull request, review, milestone, and verification tracking. + +## Source-of-Truth Split + +| Surface | Purpose | +| ---- | ---- | +| `ROADMAP.md` | Public milestone state and high-level progress | +| `CHANGELOG.md` | What changed after merges | +| `docs/design/12-game-design-document.md` | Living GDD and current design truth | +| GitHub issues | Unit of work ready for implementation or investigation | +| GitHub pull requests | Proposed changes and review history | +| GitHub Project #5 | Daily execution dashboard across issues and PRs | + +GitHub Projects should not replace the GDD or ADRs. It should make the current +work queue visible and easier to monitor. + +## Recommended Fields + +| Field | Values | +| ---- | ---- | +| Status | Inbox, Ready, In Progress, In Review, Blocked, Done | +| Area | Unity, Nakama, Gateway, AI Agent, Design, Docs, DevOps, Economy, Combat, UX | +| Milestone | Foundation, Vertical Slice, Alpha, Beta, Post-Launch | +| Priority | P0, P1, P2, P3 | +| Size | XS, S, M, L, XL | +| Review Gate | Not Ready, Local Review, Gemini, Codex, Approved, Waived | +| Verification | Not Run, Docs Lint, Backend Tests, Unity Smoke, Playtest | + +## Recommended Views + +- Vertical Slice Board: group by `Status`, filter `Milestone = Vertical Slice`. +- Engineering Table: sort by `Priority`, `Area`, and `Size`. +- Review Queue: filter `Status = In Review` or `Review Gate` not approved. +- Roadmap: timeline or roadmap layout grouped by `Milestone`. +- Risks and Blockers: filter `Status = Blocked` or `Priority = P0`. + +## Current Seed Issues + +Open issues that should be added to the project: + +- [#6 Track gateway agent-decision rate limiting and token budget](https://github.com/DOS/Second-Spawn/issues/6) +- [#7 Track Unity Fusion CodeGen AssetDatabase path error during Play Mode smoke](https://github.com/DOS/Second-Spawn/issues/7) +- [#9 Track Nakama runtime UUID helper migration](https://github.com/DOS/Second-Spawn/issues/9) +- [#13 Track distributed agent decision limiter storage](https://github.com/DOS/Second-Spawn/issues/13) + +## Automation Notes + +GitHub CLI project automation requires a token with project scopes. If `gh` +returns a missing `read:project` or project scope error, refresh auth before +trying to inspect or mutate Project #5: + +```powershell +gh auth refresh -s read:project,project +``` + +After the scope is available, use the project as the operating dashboard: + +- Add new implementation issues to Project #5. +- Link pull requests back to issues. +- Move PR-linked issues into review when a PR opens. +- Mark verification field after docs lint, backend tests, Unity smoke, or + playtest runs. +- Keep closed issues in the project for progress charts.