Driftlands — Master Architecture

Document Status

• Version: 1.0 (all sections approved 2026-08-27 via /create-architecture)
• Last Updated: 2026-08-27
• Engine: Unity 6.3 LTS (6000.3) · URP 2D Renderer (Render Graph) · NGO 2.x · Input System · Addressables · C#
• GDDs Covered: tide-scheduler, combat-system, harvesting-system, crafting-system, base-building (full); netcode-session, camera, save-persistence, player-movement, inventory-hauling, land-dock-undock, enemy-ai, ui-hud (quick-specs); tide-tint (art bible §4.3/§8.B.3, index rows 14/15)
• ADRs Referenced: ADR-0001 … ADR-0007, ADR-0015 (Accepted 2026-08-28), ADR-0013, ADR-0014 (Accepted 2026-09-01 via architecture-review-2026-09-01.md) — 5 remaining: rows 8–12 (see Required ADRs)
• Technical Director Sign-Off: 2026-08-27 — APPROVED WITH CONDITIONS (ADRs 1–7 Accepted before the first implementation story; QQ-12 shapes in ADR 3; QQ-01/02/03 answered from the 6000.3 / NGO 2.x docs before ADRs 2/8/9 leave Proposed)
• Lead Programmer Feasibility: 2026-08-27 — CONCERNS ACCEPTED (five items, none infeasible; document revised same day: §3.1 drain ordering marked provisional, harvest-node replication re-hedged → ADR 10, QQ-11/12/13 added, ADR 2/3/4 scopes extended)

Engine Knowledge Gap Summary

Engine: Unity 6.3 LTS · LLM training covers: ~Unity 6.0 · Post-cutoff: 6.1, 6.2, 6.3.

Rule: every decision in a HIGH domain in this document is marked ⚠️ NEEDS VERIFICATION and lands as an ADR input, not a settled fact.

Technical Requirements Baseline

Extracted from 13 design docs | 94 rows below (the original "102" was a miscount). Registered 2026-08-28 in docs/architecture/tr-registry.yaml (v2, 111 IDs: these 94 + 17 surfaced by the review — see traceability-index.md). The registry, not this table, is canonical.

System Layer Map

Approved 2026-08-27 (Phase 1).

┌──────────────────────────────────────────────────────────────────────────────┐
│ PRESENTATION   UI/HUD & Co-op Affordances · Tide-Tint (minimal, MVP) ·        │
│                Feedback Presenters (combat / harvest / build / craft VFX+SFX)  │
├──────────────────────────────────────────────────────────────────────────────┤
│ FEATURE        Crafting & Gear Identity · Base Building · Enemy AI            │
├──────────────────────────────────────────────────────────────────────────────┤
│ CORE           Player Movement · Combat · Harvesting · Inventory (Carry +     │
│                SharedStorage) · Land Content (LDU: layout + registries) ·     │
│                Camera                                                          │
├──────────────────────────────────────────────────────────────────────────────┤
│ FOUNDATION     Tide Scheduler (pure) · Netcode Session (rails, HostCommitQueue,│
│                session state) · Save & Persistence · Land Lifecycle (LDU:     │
│                Addressables half) · Input (action map) · Game Data (defs +     │
│                load validation)                                                │
├──────────────────────────────────────────────────────────────────────────────┤
│ PLATFORM       Unity 6.3 LTS · URP 2D (Render Graph) · NGO 2.x ⚠️ + transport │
│                · Input System · Addressables · Physics2D (Box2D) · UI Toolkit  │
└──────────────────────────────────────────────────────────────────────────────┘

Structural decisions (binding)

• LDU is two modules (the TD split-watch made concrete): LandLifecycle (Foundation — Addressables preload/activate/teardown on tide edges, memory budget) and LandContent (Core — pure layout(), KnownLandTemplates, socket authoring, the enemy spawn-contract call). Neither imports the other's concern.
• Netcode Session owns a HostCommitQueue — the single ordered channel every host-rail commit passes through, each executed as one non-yielding critical section on the host main thread (TR-net-006/007). Combat, Harvesting, Inventory, Crafting and Base Building submit command objects; none of them issue commit RPCs directly.
• GameData is a Foundation module: every Def and config table (items, recipes, structures, enemies, tide/harvest/combat/BB/inventory/movement/camera/save configs) is loaded once with the fail-loud validation tables the GDDs specify, then exposed read-only. Systems own their rules; GameData owns loading and validating* the data those rules read.
• Cinemachine is not used — one inert follow camera (camera quick-spec Rule 3) does not justify the package or its 3.x API risk.

Assembly layout

Why this matters: every GDD labels its formula/legality/state-machine criteria [UNIT] and several add a purity mandate (BB AC purity, combat/harvest "pure/DI-testable"). That is only achievable if the rules never reference UnityEngine. The assembly boundary makes the mandate a compile-time fact, not a discipline.

Engine-awareness flags

Module Ownership

Approved 2026-08-27 (Phase 2).

Foundation

Core

Feature

Presentation

Dependency diagram (arrows = depends on)

 UIHUD ──┐   TideTint    FeedbackPresenters
         │       │              │
         ▼       ▼              ▼
   Crafting ──► BaseBuilding    EnemyAI
      │  ▲         │  │           │
      │  └─────────┘  │           │            (Crafting ⇄ BB: peer — Crafting reads
      ▼               ▼           ▼             IStationPresenceProvider; BB reads
   Inventory ◄── Harvesting   Combat ◄──── PlayerMovement    IGameData.Items only)
      │               │          │                 │
      └───────┬───────┴──────────┴────────┬────────┘
              ▼                           ▼
      NetcodeSession (HostCommitQueue)   LandContent ◄── LandLifecycle
              │                           │                  │
              ▼                           ▼                  ▼
      SavePersistence ◄──────────── TideScheduler ◄──── (events)
              ▲
           GameData ── Input ── Camera (leaf; reads Movement aim only)

Every arrow points downward or sideways within a layer; the one lateral peer link (Crafting ⇄ BB) is interface-only, matching the GDDs' "peer both ways" contract. No Foundation module depends on anything above it.

Data Flow

Approved 2026-08-27 (Phase 3).

3.1 Frame update path

HOST frame                                        CLIENT frame
──────────                                        ────────────
Input System ─► PlayerMovement (owner rail)       Input System ─► PlayerMovement (owner rail)
   │ own transform written locally                    │ own transform written locally; NetworkTransform
   │ (host IS an owner for its own player)            │ sends state to host (one RTT stale on arrival)
   ▼                                                  ▼
Combat/Harvest/BB/Craft (owner half):             Combat/Harvest/BB/Craft (owner half):
   issue intents/commands ─► HostCommitQueue          issue intents/commands ─► RPC ⚠️ ─► host queue
   (local submit, same frame)                         predicted FX fire now (stance, whiff, ghost)
   ▼
HostTickOrchestrator (sole NetworkTickSystem.Tick subscriber — ADR-0015): tide Advance ─► CombatState.Tick (bleed-out, enemy phases, revive, home heal) ─► EnemyAI.Tick() (host only) ─► IEnemyCombat.EnterTelegraph → NetworkVariable<EnemyPhase>; EnemyAttackResolver → PendingEnemyDamage ─► Drain;
   │                             attacks whose resolution instant ≤ now → PendingEnemyDamage (ADR-0002)
   ▼
HostCommitQueue.Drain()  ── hooked to NetworkManager.NetworkTickSystem.Tick (ADR-0002; fires before
   │ NetworkVariable delta collection). ⚠️ The stage in which NGO applies incoming RPCs/NetworkTransform
   │ relative to Tick is undocumented — measured by ADR-0002 Verification 1–2, recorded in ADR-0008:
   │   1. SoftClose set (sockets closed since last drain); cancel enemy attacks on those lands
   │   1b. phase 0: apply PendingEnemyDamage (combat AC-32 — enemy first, then player)
   │   2. for each envelope in arrivalSeq order: drop if ResolveTick ≥ SoftCloseTick(socket), else
   │      cmd.Execute(ctx) → CommandResult  ← single synchronous non-yielding block; re-samples every gate
   │   3. release teardown for soft-closed lands (harvesting EC6)
   │   4. flush buffered Broadcast/QueueSpawn in command order; Save.Persist dirty-marks → I/O after Drain
   ▼
Replication out: NetworkVariables + host-confirmed broadcasts  ─────────►  clients apply:
                                                                  NetworkTransform.OnUpdate (interp),
                                                                  NodeView/HP/telegraph vars,
                                                                  confirmed FX (impact, thunk, burst)
   ▼                                                  ▼
TideScheduler.TintFloats ─► TideTint.SetGlobal       same, from replicated t (presentation-only)
Camera.LateUpdate (follow + aim bias)                 same
UIHUD reads views                                     same

Classification: owner-rail writes are local synchronous; intents are RPC (async, ordered channel); host commit execution is synchronous, single slot; replication is NGO shared state; tint/HUD are pull reads. No data flow crosses a thread boundary — Addressables loads are the only async work and they never touch gameplay state until LandActivated fires on the main thread.

3.2 Event / signal path

Rule: there is no global event bus. Each producer exposes typed C# events on its interface; presentation subscribes downward; nothing subscribes upward. The HostCommitQueue is the only fan-in point.

3.3 Save / load path

WRITE (host only, per confirmed command):
  cmd.Execute ─► owner table mutates ─► Save.Persist(table)  [dirty-mark only — ADR-0004]
  Drain returns ─► Save.EndOfDrain: serialise dirty tables (main thread, snapshot) ─► background flush:
                   write-temp → fsync / F_FULLFSYNC (macOS) → File.Replace → rotate 3 backups; lastDurableDrain ← N
  (durability is per-drain, broadcast-first; loss bound = wall-clock flushDeadlineMs — ADR-0004 §4)

LOAD (host, before NetworkManager.StartHost):
  Save.Load()
    1. version gate (saveFormatVersion, configVersion) → refuse loudly
    2. clock guard: TideScheduler.Restore(TideState{lastKnownGoodT, epochIndex, epochActivationT})  (future t wins)
    3. TideScheduler derives the cycle purely; the EPOCH is restored, not derived (tide EC14 — ADR-0001)
    4. union reconcile: IKnownLandTemplates, IKnownRecipes   (owners' predicates)
    5. droppable reconcile: HarvestDiffTable via ITideClock validity predicate
    6. permanent reconcile: IStructureRegistry (inert relics), IInstanceMetadata (orphans)
    7. inventories: CARRY per player, SharedStorage per container id (tag-without-row → mystery gear)
    8. player placement: saved position on Absent land → depositPoint; HP full; Downed cleared
  then StartHost → late-joiners receive the reconciled tables (TR-net-003)

Owners implement ISaveable (serialize/deserialize + Reconcile(ctx)); Save owns only ordering and I/O. Both instanceId counters are ISaveable singletons owned by Crafting and BaseBuilding respectively.

3.4 Initialisation order

1. GameData.LoadAndValidate()          — fail-loud; nothing else may start on failure
2. Input (action asset)                — no dependencies
3. Save.Load() [host]                  — needs GameData for reconcile predicates
4. TideScheduler.Restore(TideState)    — needs Save's lastKnownGoodT + epoch state; pure otherwise
5. NetcodeSession.StartHost / StartClient ⚠️  — needs tide t to replicate; HostCommitQueue armed
6. LandLifecycle.Subscribe(tide)       — needs tide + Addressables ready; first evaluation may Preload immediately
7. LandContent / Inventory / Crafting / BaseBuilding registries bound to Save tables
8. Player spawn (Movement, Combat actor, CarryInventory)  — needs session + reconciled CARRY
9. Camera, TideTint, UIHUD, FeedbackPresenters            — presentation last; all pull-only

Clients skip step 3 and receive the tables in the late-join snapshot between steps 5 and 7.

3.5 Key scenario walkthroughs

Strike at a node with a Rusher closing (harvesting Rule 2 / combat Rule 7):

client: Input.Strike ─► Rules.Referent.Choose(aim, nearbyHostiles, nearbyNodes) → targetKind, nodeId?
        Combat.IssueIntent(swingId, aim, targetKind, nodeId?) ─► predicted windup anim (phase constants by kind)
        ─► RPC ⚠️ ─► host queue (arrival-ordered)
host:   at completion tick: SoftClose? → discard/whiff
        targetKind == node  → HarvestResolveCommand: Docked ∧ swingsRemaining>0 ∧ CanAdd → decrement, Add, Persist(HarvestDiff)
        targetKind == enemy → StrikeResolveCommand: Rules.Combat.HitArc(current positions) → F1/F2, stagger, knockback, SwingLanded
        broadcast confirmed outcome ─► presenters (burst / impact) ; rejected → nothing (honest whiff)

Wall placement (BB Rule 6):

client: BuildMode (local) ─► Rules.BB.Snap → ghost; provisional F1 every frame (no alloc) ─► Confirm ─► PlaceStructureCommand RPC ⚠️
host:   queue slot: re-sample all 8 conjuncts via ITerrainQuery + registry + IHostPositions.All() (ADR-0009: raw last-received owner state, ≤ 1 RTT + 1 tick, snap-overridden)
        → IInventoryTx.Remove(cost, CARRY ∪ STORAGE-in-range-of-spot) → registry.Add → Persist → broadcast
clients: BaseNet.Structures list delta (ADR-0011) → ClientRegistry → StructureView (static BoxCollider2D on Structure + sprite, Physics2D.SyncTransforms) ; local player under footprint → Rules.Build.FindCorrectionCell → PlayerMotor.CorrectTo (EC21, interpolated write — ADR-0009)

Dock transition (tide Rule 8/9):

host: NextBoundary wake-up ─► PreloadDue ─► LandLifecycle.LoadAsync (Addressables) ─► cosmetic drift-in
      at φ: DockStarted ─► Layout.Build ─► Harvesting.SeedNodeState ─► spawn LandNet ─► colliders on ─► KnownLandTemplates.Append ─► LandActivated → node views, EnemySpawner (ADR-0005; clients activate on LandNet spawn)
      at φ+W: SoftClose ─► (same tick, first) combat discards ≥φ+W, harvest last-tick completes, SoftCloseDeposit → deposit at depositPoint (ADR-0009); drain step 3 → DrainReleased
      +EvictionGrace: GraceExpired ∧ DrainReleased ─► EvictionExpired (EC11 backstop) ─► despawn LandNet ─► LandTornDown ─► release slot; violet held until then

API Boundaries

Approved 2026-08-27 (Phase 4). C# — these are the contracts programmers implement against. Names are pinned at implementation; shapes are binding.

// ── Foundation ────────────────────────────────────────────────────────────────
public interface ITideClock {                      // Driftlands.Tide — pure; Runtime adapter supplies t
    (bool docked, double progress) Evaluate(int socket);   // pair: progress unreadable when !docked
    long   CycleIndex(int socket);   int  EpochIndex { get; }
    ulong  VariationSeed(int socket, long cycleIndex);
    TemplateId TemplateFor(int socket, long cycleIndex);
    long   NextBoundary();                          // strictly > t, ≤ t + C
    (float amber, float violet) TintFloats(int socket); // held (0,1) during EvictionGrace
    bool  IsDockingLive(int epochIndex, int socket, long cycleIndex); // the reconcile validity predicate the scheduler owns (ADR-0001, TD-ADR C3)
    event Action<int,TemplateId> PreloadDue; event Action<int> DockStarted; event Action<int> SoftClose;
}
// Invariants: no raw t/φ/W/C leaves this interface (tide AC-27); consumers never cache Evaluate() across ticks.

public interface ICommand { ulong OwnerClientId { get; } uint ClientSeq { get; } CommandResult Execute(HostContext ctx); }  // ADR-0002: returns CommandResult; ClientSeq owner-stamped
public readonly record struct QueuedCommand(ICommand Command, uint? ArrivalSeq);   // host-assigned arrival order (BB AC-20b's optional field lives here)
public interface IHostCommitQueue {                // NetcodeSession — the only fan-in (ADR-0002)
    void Enqueue(CommandEnvelope env, ulong ownerClientId);   // host only; wire entry is HostCommitChannel.SubmitRpc — ONE [Rpc(SendTo.Server)] on ONE NetworkObject
    void Drain(HostContext ctx);                    // once per NetworkTickSystem.Tick
    // Guarantee: Drain() runs once per host tick in the pinned phase (TR-net-008), executes commands in
    // arrival order (ArrivalSeq; lowest OwnerClientId only when seq is absent), each Execute() is one
    // synchronous non-yielding block, SoftClose is evaluated before any command on that tick.
    // Callers must: re-sample every gate inside Execute; never hold state across commands; never await.
}
public interface ISaveable { string TableId { get; } SaveClass Class { get; } /* Permanent | Droppable */
    void Serialize(ISaveWriter w); void Deserialize(ISaveReader r); void Reconcile(ReconcileContext ctx); }
public interface IGameData { IReadOnlyDictionary<ItemId,ItemDef> Items { get; } /* Recipes, Structures, Enemies, Templates, Configs */ }
public interface IPlayerInput { InputFrame Current { get; } }   // ADR-0007: one immutable per-frame snapshot (Driftlands.Rules.Input) — edges computed once; edge consumers run in Update only

// ── Core ──────────────────────────────────────────────────────────────────────
public readonly record struct StrikeIntent(uint SwingId, Vector2 Aim, TargetKind Kind, NodeId? Node);
// IStrikeResolver RETIRED by ADR-0015 — StrikeResolveCommand IS the resolver; node-kind intents are routed to HarvestResolveCommand at receipt. StrikeIntent above lives in Driftlands.Data (shared vocabulary, neither system owns it); IntentTick is host-stamped, never in the payload.
public interface ICombatState { /* ADR-0015: host-owned actor table keyed by PlayerKey/EnemyId — Player/Enemy views, HostSeesDashing, MirrorStep, ApplyHit, ApplyEnemyDamage, TryStartRevive/CancelRevive, RevokeSwing */ }
public interface IPlayerCombatView { int Hp { get; } int MaxHp { get; } PlayerState State { get; } float BleedOutRemaining { get; } }   // HUD/presenters — never enemy HP; SwingLanded/DamageAbsorbed are raised from the drain flush only (replaces ICombatActor — ADR-0015)  // two payload records (ADR-0003, TD-ADR C4)
public interface IEnemyCombat { void EnterTelegraph(AttackId id); bool Interruptible { get; } float Meter { get; } EnemyPhase Phase { get; } }   // ADR-0015: Meter is a float (F4 operates on floats); Phase exposed for enemy-ai Rule 6's cap check; EnterTelegraph is the ONLY AI→combat call
public interface IAimSource { Vector2 AimVector { get; } }               // Movement → Combat, BB ghost, Camera — RETAINED by ADR-0007 as a Movement pass-through (AimVector => input.Current.Aim); aim is computed in Rules.Input.AimResolver
public interface IHostPositions { Vector2 HostKnown(ulong clientId); }  // exact for host's own player, one-RTT stale for remotes (BB F1)
public readonly record struct ItemStack(ItemId Id, int Count, InstanceTag? Tag);
public interface ICarryInventory { bool CanAdd(ItemId id, int n); void Add(ItemStack s); bool CanRemove(ItemId id, int n); void Remove(ItemId id, int n); int Count(ItemId id); }
public interface ISharedStorage : ICarryInventory { ContainerId Id { get; } int ContentCount { get; } }
public interface IInventoryTx {                    // atomic over a CARRY ∪ STORAGE-set; host only, inside Execute
    bool CanRemove(IEnumerable<(ItemId, int)> cost, ICarryInventory carry, IReadOnlyList<ISharedStorage> inRange);
    void Remove(...);  bool CanAdd(ICarryInventory target, ItemStack s); }
public interface IKnownLandTemplates : ISaveable { bool Contains(TemplateId t); void Append(TemplateId t); }  // append-only, seeded
public interface ISocketLayout { IReadOnlyList<Socket> Sockets { get; } }  // Socket = (index, position, depositPoint, noBuildRadius)
public interface IEnemySpawner { void Spawn(TemplateId t, ulong variationSeed, IReadOnlyList<SpawnPoint> pts, ScalingContext ctx /* empty at MVP */); }

// ── Feature ───────────────────────────────────────────────────────────────────
public interface IStationPresenceProvider {        // BaseBuilding → Crafting; exactly these two, never a mode arg
    bool StationPresentExact(StationTier tier, Vector2 asker);
    bool StationPresentAtLeast(StationTier tier, Vector2 asker); }   // never cached host-side
public interface IGearHooks { float DamageModifier(InstanceId i); float DamageReduction(InstanceId i); float HarvestModifier(InstanceId i); } // dull → tier baseline
public interface ITerrainQuery { bool IsBuildable(Cell c); bool InPlaceableRegion(Cell c); }  // plain-data adapter; Rules never touch Tilemap
public interface IStructureRegistry : ISaveable { IReadOnlyList<StructureInstance> All { get; } bool AnyCovers(Cell c); }

Boundary invariants (binding):

• Driftlands.Rules functions take and return plain data only — every interface above that Rules consumes is a data snapshot passed in by Runtime.
• Anything ⚠️-marked (RPC shape, replication representation, NetworkTransform write mode) is an ADR input; the interface is fixed, the wire is not.
• Vector2/Cell inside Rules are Driftlands structs, not UnityEngine.Vector2 — the assembly has no Unity reference.
• Every host-rail mutation is reachable only through an ICommand executed by IHostCommitQueue; a direct setter on a host-authoritative table from outside a command is a boundary violation (review checklist + analyzer candidate) — with exactly one registered exception: the tide-edge carve-out (ADR-0005 §3: LandNet spawn/despawn and IKnownLandTemplates.Append, driven by Authority-clock tide events inside Advance).

ADR Audit

Phase 5, 2026-08-27: no ADRs existed. Superseded by /architecture-review 2026-08-28 (architecture-review-2026-08-28.md): 8 ADRs audited — 8/8 carry Engine Compatibility on 6000.3, 0 deprecated-API references, 3 cross-ADR conflicts (C1–C3, amended same day), 13 specialist findings (E1–E13).

Traceability Coverage

2026-08-28: 111 requirements — 64 covered, 28 partial, 19 gaps (Foundation layer: 0 gaps). Full matrix in traceability-index.md; stable IDs in tr-registry.yaml. Note TR-craft-003/004/006/008 (crafting runtime half) are assigned to no row below — see the review's Required ADRs (extend ADR-0010 or add row 16).

Required ADRs

Phase 6, 2026-08-27. ⏳ = the wire half is gated on the friend-group playtest (netcode-session Rule 7); the model half can be drafted as Proposed now. ⚠️ = HIGH-risk engine domain, verification step required before Accepted.

Foundation — must exist before any coding

Core — before the relevant system is built

Presentation — before the relevant screen/shader is built

Can defer to implementation

Camera follow implementation (TR-cam-002 — a script, not a decision); feedback-presenter timing (TR-combat-004, TR-harv-007 presentation halves); CI-gate test harness (TR-bb-008, TR-ldu-006 — test code).

Coverage: 102/102 requirements assigned. ADRs 1–7 and 13–14 (9 of 14) are writable now; ADRs 8–12 can be drafted Proposed today and finalised after the playtest.

Architecture Principles

• The world is a save file plus a pure function. No offline simulation, no schedule state; anything derivable from (seed, t, config) is never stored or replicated (concept, tide GDD, Forbidden Patterns).
• Two rails, one fan-in. Owner rail for what you own (movement, bag, predicted FX); host rail for what the world owns — and every host-rail mutation is an ICommand through the single HostCommitQueue, executed as one non-yielding synchronous block. No third rail, no side doors.
• Rules are engine-free. Formulas, legality predicates, state machines, and seeded content generation live in assemblies with no UnityEngine reference; Unity is an adapter. This is what makes every [UNIT] acceptance criterion honest.
• Re-sample at resolution, never cache. Docked, positions, gates, stationPresent — every host decision reads current state inside the command that acts on it. Client-side copies are for display only and may never gate a commit.
• Fail loudly at load, never silently at runtime. All game data passes its GDD validation table at boot; a config that violates an invariant stops the game with a named error. Schema-negatives (no MoveSpeedModifier, no builder field, no craft counts, no home nodes) are reflection tests, not conventions.
• HIGH-risk engine surfaces are ADR inputs, not assumptions. Every NGO 2.x and Render Graph touchpoint carries a verification step against the 6000.3 docs before its ADR moves to Accepted.

Open Questions