Project Context for AI Agents

This file contains critical rules and patterns that AI agents must follow when implementing game code in this project. Focus on unobvious details that agents might otherwise miss.

---

Technology Stack & Versions

• Unity Editor 6000.5.6f1; do not upgrade or downgrade without an explicit architecture decision and verified project backup.
• Universal Render Pipeline 17.5.0.
• Unity Input System 1.20.0; do not introduce legacy Input Manager handling.
• Unity AI Navigation 2.0.14; use the baked NavMesh and authored placement pads.
• Unity UI (uGUI) 2.5.0 with TextMesh Pro for all Baseline runtime UI.
• Unity Test Framework 1.7.0.
• Target: local Windows desktop, keyboard and mouse, reference layout 1600×900.
• No networking, save/load, backend, analytics dependency, or runtime MCP dependency.
• CoplayDev MCP for Unity and Context7 are optional development tools only.

Any package change affecting these choices must update the architecture and be verified against Unity 6000.5.6f1.

Critical Implementation Rules

Engine-Specific Rules

• TestGame.Domain must not reference UnityEngine; it owns all authoritative rules and mutable session state.
• TestGame.Unity and TestGame.Presentation are peer adapters over Domain. Only TestGame.Bootstrap may reference all three and compose the application.
• SceneCompositionRoot validates serialized references, converts definitions, creates one GameSession, wires adapters/presenters explicitly, and disposes the session on scene unload.
• Do not use gameplay singletons, service locators, DontDestroyOnLoad, Find*, or repeated runtime component discovery.
• MonoBehaviours use private [SerializeField] references. Cache same-object GetComponent results during initialization.
• ScriptableObjects are immutable authoring inputs. Convert them once to pure C# definitions; Domain retains no ScriptableObject, prefab, sprite, or other UnityEngine.Object.
• Gameplay code never reads Time directly. A Unity adapter advances the domain clock with scaled Time.deltaTime; tests use a fake clock.
• Prefer explicit session updates over independent gameplay coroutines. Use coroutines only for presentation sequences that own no authoritative state.
• Unity animation, NavMesh, physics queries, and UI reflect or report engine facts; they never own gameplay truth.
• Use uGUI passive views and presenters. Views submit commands and render snapshots; they never mutate Domain state.
• BaselineSandbox.unity is the single Baseline scene. Do not add bootstrap or loading scenes until a real second-scene requirement exists.

Performance Rules

• Performance gate: average ≥60 FPS and 1% low ≥55 FPS during the documented ten-minute Windows development-build workload on Tim’s reference PC.
• Record CPU, GPU, RAM, Windows version, build profile, profiler method, and workload with every gate result; Editor FPS is not acceptance evidence.
• Treat 16.67 ms as the 60-FPS frame budget. Profile before adding complexity.
• Do not perform scene-wide searches, LINQ, string construction, collection allocation, or repeated GetComponent calls in per-frame/hot paths.
• AI acquisition uses bounded physics queries at a controlled cadence, never a global search every frame.
• Avoid per-frame logs, events, snapshots, UI rebuilds, and timer notifications. Publish meaningful state transitions and refresh only affected presentation.
• Consume large elapsed-time deltas safely, including multiple resource-generation intervals; a timed completion must still happen exactly once.
• Use direct serialized assets and prefabs. Do not add Resources.Load, Addressables, streaming, or runtime NavMesh rebuilding for the Baseline.
• Do not pool authoritative entities. Pool transient presentation objects only after profiling proves a meaningful allocation problem, and reset all visible state before reuse.
• Keep collision layers narrow and physics queries bounded. Use simple colliders.
• Memory and load-time targets are not gates unless measurement exposes a play-blocking issue.

Code Organization Rules

• Place every first-party file under Assets/TestGame/.
• Runtime assemblies and dependency direction:
  • Domain: pure C# rules, state, commands, events, snapshots.
  • Unity: engine adapters, ScriptableObject types, navigation, physics, input.
  • Presentation: uGUI views, presenters, formatting, notifications.
  • Bootstrap: composition only; references the other three.
• Organize within each boundary by feature: Economy, Inventory, Equipment, Effects, Units, Combat, Skills, Quests, Placement.
• Put rules in Domain even when a Unity callback triggers them. Put player-facing formatting in Presentation, not Domain or Unity.
• Use Common only after two real consumers exist; never create generic Manager, Helper, Util, or dumping-ground folders/classes.
• One public top-level C# type per file; filename must match the type.
• Namespace format: TestGame.<Boundary>.<Feature>.
• Commands: imperative name plus Command (StartCraftCommand).
• Events: immutable past-tense facts (CraftCompleted).
• Tests: Method_WhenCondition_ExpectedResult.
• Stable IDs: typed value objects whose serialized values are lowercase kebab-case.
• Asset naming:
  • Definitions: <Type>_<Id>
  • Materials: M_<Name>
  • Textures: T_<Name>
  • Sprites: S_<Name>
  • Animator controllers: AC_<Subject>
  • UI prefabs: UI_<Role>
• Use canonical GDD vocabulary exactly: Building, Crafted Good, Inventory, Mythical Storage, Quest, Recipe, Skill, and Timber.
• Editor-only code belongs in Editor/ subfolders and must not enter runtime assemblies. Third-party types must be isolated behind Unity adapters.

Testing Rules

• Put pure rule/transaction tests in Assets/TestGame/Tests/EditMode/<Feature>. These tests must not load scenes or depend on Unity frame time.
• Put engine integration tests in Tests/PlayMode/<Integration>: composition, Input, navigation, placement, presentation, and complete journeys.
• Use builders/fixtures to create minimal valid sessions, fake clocks for exact durations, and deterministic ID generators for reproducible assertions.
• Edit Mode coverage must include resource accounting, job timing, cancellation, exact-slot restoration, modifiers, rounding, HP clamping, Quest counters, duplicate delivery, and state transitions.
• Play Mode coverage must include scene wiring, representative NavMesh routes after all Buildings are placed, Morale radius integration, defeat/recovery, UI synchronization, and one production-to-Quest journey.
• Every corrected transaction, state-transition, or event-idempotency defect requires a regression test.
• Assert failed commands leave all involved state unchanged and return the exact stable blocker/remedy code.
• Assert timed completion and event consequences happen exactly once, including when advancing the fake clock by a large delta.
• Do not mock domain value objects or state unnecessarily; fake only boundaries such as clocks, IDs, logging, and Unity adapters.
• MCP may invoke Test Runner, but tests must run without MCP.
• Manual validation owns comprehension, causality, resize behavior, perceived aggression-versus-preparation difference, and creator motivation.
• Stabilization gate: three consecutive end-to-end sessions without blockers, corruption, or external state intervention.

Platform & Build Rules

• Baseline target is local Windows desktop only. Do not add mobile, console, WebGL, controller, online-service, or cross-platform abstractions.
• Use the Unity Input System action asset. Separate world, camera, unit-command, hotkey, and UI actions sufficiently to prevent UI clicks from issuing world commands.
• Required input is keyboard and mouse. Remapping and complete keyboard-only UI navigation are deferred; visible focus is required wherever keyboard operation exists.
• Reference layout is 1600×900. uGUI anchors, layout groups, and CanvasScaler must preserve Storage, selection, active Quests, and active timers when the supported window is resized.
• Essential state cannot exist only on hover, through color, or through audio.
• Functional audio is optional and uses built-in Unity Audio. The full loop must remain understandable while silent.
• Use Windows Development Builds for performance evidence and record the exact build profile. Do not use Editor performance as the gate.
• Development diagnostics compile only under UNITY_EDITOR || DEVELOPMENT_BUILD; non-development player builds contain no debug panel or state-changing test controls.
• MCP, Inspector, Console, and development tools cannot count as player-facing validation or be required to complete a session.
• Launching starts a fresh session. Do not add gameplay persistence, PlayerPrefs state, cloud services, or restart/title/options flows.

Critical Don’t-Miss Rules

• Only command handlers mutate authoritative session state. Validate every precondition before one atomic commit; rejected commands mutate nothing.
• Expected refusals return typed CommandResult values with stable code, blocker, and remedy. Exceptions mean broken invariants; never swallow them.
• Production jobs record committed inputs and exact destination at start. Cancellation restores every committed resource/item fully and exactly.
• Final Crafting reserves a specific Inventory slot before consuming inputs. Completion fills that slot; it never searches for another.
• T2 Armor consumes the exact unequipped T1 item and reserves its original slot. Cancellation restores that exact item instance to that exact slot.
• Resource/Inventory/Building/job changes must commit atomically. Do not use event subscribers to finish domain-critical transaction work.
• Monster defeat and Craft completion update qualifying session counters inside their originating transaction before publishing events.
• Events are immutable, strongly typed, past-tense, synchronous, session-scoped, and post-commit. Subscriber order must never affect gameplay.
• Persistent snapshots are authoritative. Typed change payloads selectively explain player-visible transitions; UI must not reconstruct state from events.
• Base maximum HP is immutable. Calculate each percentage modifier independently from base HP using round-half-up, then sum. Recalculate instead of incrementally patching cached totals.
• Sword, Armor, and one Flag may coexist; multiple Flag effects do not stack. Removing effects clamps current HP to the new maximum, never below 1 for a living unit.
• Inventory ownership is Empty → Reserved → Occupied; focus, equipment, and eligibility are orthogonal attributes, not competing ownership states.
• Entity state uses guarded finite-state machines, not boolean flag combinations. Animation and NavMesh state follow/report gameplay state; they do not own it.
• Placement is pad-based. Do not implement free placement, runtime NavMesh rebuilding, relocation, demolition, or route validation by hope.
• Every player-visible mutation exposes exact cause and before/after values where relevant. Invalid actions name both blocker and remedy.
• Keep canonical Baseline scope: no workers, transport, queues, recruitment, technology tree, logistics, multiplayer, saves, analytics services, or generic RPG/RTS framework.
• Do not generalize for hypothetical extensions. Add abstractions only for a demonstrated Baseline need or a separately approved extension milestone.
• Consult _bmad-output/game-architecture.md when a rule is unclear; do not invent a competing local convention.

---

Usage Guidelines

For AI agents:

• Read this file before implementing or reviewing game code.
• Follow every applicable rule; prefer the more restrictive interpretation when ambiguity remains.
• Consult the architecture and GDD rather than inventing a competing convention.
• Update this file only when an approved technology or implementation pattern changes.

For humans:

• Keep this file limited to unobvious, actionable agent guidance.
• Update it when the technology stack, architecture, or Baseline contract changes.
• Periodically remove obsolete or redundant rules.

Last Updated: 2026-08-02