KH2 Multiplayer

Kingdom Hearts II Final Mix multiplayer mod. Player-controlled friend party members (Donald, Goofy) via in-process DLL injection with full animation, movement, and camera support.

Start here

What works today

Friend entity control (M3 — in progress)

• Press F5 in-game to take control of Donald (Friend1)
• Left stick moves Donald with proportional walk/run speed
• Camera follows Donald, right stick orbits
• Idle/walk/run animations match stick input (loops correctly at any distance from Sora)
• Sora frozen in place while controlling Donald
• Facing persists when stick is released

Networking layer (M0-M2 — complete)

• Binary codec for all domain types with little-endian framing
• Host-authoritative session server: version gating, slot assignment, snapshot broadcast
• ENet transport with heartbeat, 3-client integration tested
• Server-side fake physics for protocol testing without KH2

Runtime bridge (M1-M2 — complete)

• Attaches to live KH2 via ReadProcessMemory/WriteProcessMemory
• Entity discovery, room/actor/HP state reads, camera retargeting
• Shared-memory IPC (InputMailbox) between runtime and inject DLL

Architecture

Two runtime modes on shared infrastructure:

1. Campaign Co-op — up to 3 players share one host-authoritative session, each controlling a party slot (Sora, Donald, Goofy) with independent cameras.
2. Public Realm (planned) — persistent characters, public hubs, party-formed instances.

See docs/ARCHITECTURE_MODES.md for the full breakdown.

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

Quick start

# Build everything
cmake -B build -S . -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
cmake --build build --config Release

# Run E2E test (no KH2 needed)
.\build\tests\Release\kh2coop_fake_sim.exe

# Build just the inject DLL
cmake --build build --target kh2coop_inject --config Release

# Restart KH2 + rebuild DLL
.\scripts\restart-kh2.ps1

See docs/DEVELOPMENT_WORKFLOW.md for the full inject/test loop.

Documentation