Codebase Map

Navigation guide reviewed 2026-10-20 against main 2ed98fa. Source versions: protocol 34, AvatarBridge 4, WorldBridge 13, CaptureChannel 1. Tables list key components rather than every source file; use the build files for the complete target list and symbol searches for current locations. Setup covers building; the plan owns current status, player defaults and qualification limits.

Build targets

cmake --build build --config Release                    # everything
cmake --build build --target kh2coop_inject --config Release   # inject DLL only
cmake --build build --target kh2ctl --config Release           # CLI tool only
cmake --build build --target kh2coop_server --config Release   # server only
cmake --build build --target kh2coop_fake_sim --config Release # E2E test

Offline test suites (no KH2): kh2coop_fake_sim, kh2coop_avatar_test, kh2coop_world_test, kh2coop_bridge_test, kh2coop_recovery_test — each prints ALL CHECKS PASSED. The recovery target exercises the production monotonic scheduler plus actual ENet dropped-friend bootstrap and original-session pins. Windows-only kh2coop_spawntrace_test, kh2coop_lifecycletrace_test and kh2coop_hittrace_test exercise actual observer helpers with synthetic originals and test-owned memory. kh2coop_nativehit_test exercises the production claim consumer, incoming-hit context and production generation-guarded world/progress/ warp boundaries over owned memory and a headless transport. The Python saved-log auditor controls run via python -B -m unittest discover -s tests -p test_trace_audit.py.

Dependencies: ENet v1.3.17 (FetchContent), MinHook v1.3.3 (FetchContent, inject only).

Directory layout

kh2-multiplayer/
  inject/          ← DLL injected into KH2 process (friend control)
  runtime/         ← External process that reads KH2 memory + bridges to network
  server/          ← Host-authoritative multiplayer session server
  common/          ← Shared types, codec, protocol, networking, IPC mailbox
  tools/           ← kh2ctl CLI + MCP wrapper, avatarctl, headless Ghidra scripts
  scripts/         ← PowerShell helpers (restart-kh2, run MCP server, ghidra)
  tests/           ← E2E integration tests (no KH2 required)
  docs/            ← All documentation
  content/         ← Content/mod packaging notes

inject/ — In-process DLL (the friend control system)

Loaded into the KH2 process by kh2ctl launch/inject (Cheat Engine is a fallback). Hooks the entity update loop to replace friend AI with player input.

EntityHook.cpp also holds the VUH-1501 hit-ownership hooks (BuildHit 0x3D23C0 log, ApplyHitDamage 0x3D3BA0 drop filter + claims, host apply), driven through common/include/kh2coop/HitChannel.hpp. Those diagnostic claims/manual apply requests remain separate from protocol HitClaim transport. ApplyHitDamage now snapshots an ordinary canonical-player HP hit before client suppression and submits an immutable typed claim to EnemySync. The host checks current roster connection, sequence, epoch, binding and native combat metadata before one byte-verified TakeDamage attempt, then recaptures the census before HP/death publication. WorldBridge v13 carries atomic roster/delivery floors, explicit puppet authority, captured producer context, a separate bounded CAS operator mailbox, and (VUH-2640) the host's returning seats by connection ID, the writer's incarnation and a terminal-networking receipt bound to it in a 192-byte header. Protocol history: v9 retained v3 claims and v4 connection-tagged avatar relays; AvatarBridge v2 introduced pose provenance. Current bridge v4 retains DLL owner checks even for an unchanged cached pose. V5 also requires opaque world-incarnation identity and typed closure semantics. V6 adds separate authenticated diagnostic request/chunk/done packets on reliable channel 2. DesyncCollector copies actual local artifact bytes on one worker; DesyncUpload paces owner-thread transport; DesyncCapture persists the frozen all-peer aggregate and bounded suppression evidence. See DESYNC_REPORTS.md. V7 adds a DLL-produced nonzero 64-bit sequence to absolute enemy HP. Relay, network callbacks and the DLL reject older samples while retaining reliable cache replay; see HP_ORDERING.md. kh2coop_hp_order_test exercises real local ENet, reversed delivery, exact cache reconstruction and admission boundaries. V8 adds fresh-capture transaction fencing, bounded complete native staging and strict load/two-frame convergence ACKs; see FORCED_RESYNC.md. Dead bootstrap and full native/remote acceptance remain open. common/include/kh2coop/ClientRecovery.hpp owns bounded friend-only scheduling; RuntimeMain pumps it and heartbeats before attachment waits. Native combat now has scoped live evidence; broad populated reconnect and attack-specific/boss acceptance remain open.

Hook and feature navigation

EntityHook.cpp wires the native frame, input, ownership and feature hooks. Enemy mirroring/targeting, party construction, event hold and downed behavior have dedicated modules; historical line ranges no longer locate them reliably. Player-launch defaults come from tools/launcher/friend_package.py; direct DLL launches retain their own native defaults. Enabled behavior does not imply whole-route or every-family acceptance.

runtime/ — External process (memory reader + network bridge)

Attaches to KH2 via ReadProcessMemory/WriteProcessMemory. Reads game state, manages camera (via fake actor allocation), and connects to the session server.

server/ — Multiplayer session server (relay)

Accepts client connections, version-gates them and assigns party slots. Relays owner-authoritative avatars (stamping the owner slot) and host-authored world sync (room transitions, cutscene holds, enemy manifest/HP/deaths, progress), which it accepts only from the host (slot Player). Routes authenticated, current-room hit claims to the host only. Caches world state so late joiners are caught up. Exact complete frames and current nonzero room epochs guard hold/manifest/HP/death cache writes; HP/death also require the current manifest. Old-room values cannot be replayed under a new epoch. Host resync now requests fresh checked native capture and stages an immutable transaction with delivery fencing; native recovery acceptance remains pending (FORCED_RESYNC.md). Co-op host departure/expiry closes old peer connections and clears those caches while the relay keeps listening. The older fake-physics SimulationState is a test double.

common/ — Shared library

Used by all components. Defines the wire protocol, domain types, serialization, and IPC.

tools/ — Developer tooling

tests/

Every kh2coop_*_test executable (plus each kh2coop_resourcetrace_test failure mode) is registered with CTest; after a Release build run ctest --test-dir build -C Release serially (several tests bind fixed loopback ports). None launches or attaches to KH2. Each Python tests/test_*.py is registered as well, as kh2coop_py_<name> with the label python. That adds about 2 minutes serially; -LE python skips them. The exception is the harness test_runtime_desync.py, which needs --bin-dir and --out-root.

scripts/

How the pieces connect

The diagram shows standalone ENet. In Steam mode SessionHost stays in the host runtime; the game brokers exchange authenticated relay-only traffic through Valve instead of starting kh2coop_server. The host's KH2 remains world authority in both modes. Steam transport records its two-PC technical qualification; native HUD and prologue encounters retain their separate loopback limits.

                    ┌──────────────────┐
                    │   KH2 Process    │
                    │                  │
                    │  ┌────────────┐  │     shared memory
                    │  │ inject DLL │◄─┼──── (InputMailbox) ◄── runtime process
                    │  └────────────┘  │                         │
                    │        │         │                         │ ENet
                    │   hooks entity   │                         │
                    │   update loop    │                    ┌────▼────┐
                    │                  │                    │ server  │
                    └──────────────────┘                    └─────────┘
                                                                │
                                                           ENet │
                                                                │
                                                        ┌───────▼───────┐
                                                        │ other clients │
                                                        └───────────────┘

• inject DLL runs inside KH2, hooks entity updates, reads input from mailbox or local gamepads
• runtime runs outside KH2, reads game state via ReadProcessMemory, writes input to the mailbox, connects to server
• server relays avatars and host-authored world sync between all connected clients
• kh2ctl is a developer tool that talks to the runtime's mailbox and KH2's memory

Avatar and world paths (plan D2/D9; the DLL sides of both bridges are live-lane work):

 KH2 + inject DLL                 runtime                       relay
 ----------------                 -------                       -----
 local avatar --AvatarBridge--> sendAvatar ---AvatarState----> stamp slot +
                                                               connection ID,
                                                                forward to
 puppet poses <-AvatarBridge--- AvatarSync <--AvatarRelay----- the others
                                (interpolate)
 world events --WorldBridge---> WorldPump ----world packets--> host-only check,
 (transition, enemies, claims)                                  cache, forward
 act on them  <-WorldBridge---- onWorldEnvelope <--------------- (claims -> host)

The opt-in two-player empty-AI layout adds inject/src/PartyEmptySeat.{hpp,cpp} for scoped native row/status and pause/history projections, and PartyEmptyPackage.{hpp,cpp} with pinned payload data for read-only selected-ARD qualification. GoA/Borough, pause, first Items selection and next-load restore passed live in run20261008-024646, fixture build/rig/party-empty2-20261007-01/rev6/live-fixture-10. See docs/PARTY_SETUP.md for flags and qualification limits.

• inject/src/PuppetCommandGuard.{hpp,cpp}: mandatory puppet-only Drive/Summon command admission, native exact-byte guards and retained callback/trampoline lifetime; no status or SAVE writes.

Host-chosen Donald/Goofy party layouts: build/rig/party-choice-20261007-01/rev5, code 3e3dcc6. Two-player Donald/Goofy passed live in runs 20261008-184452 / 20261008-185124; shared solo support remains UNQUALIFIED pending corrected fixtures. Policy/install/A2 controls and source/product pins are retained in rev5. See docs/PARTY_SETUP.md.