Twin Saga Official Client Decompilation

Auditable reconstruction of the official Taiwanese Twin Saga / Astral Realm client. Generated code is a hypothesis until it is validated against the original program's behavior.

Artifact

The primary target is the X-Legend-signed game.bin version 7.0.1.11:

04716bc45c8eed719556c9c3163899452904da2a0497406d47c25fe24abef562  game.bin

It was recovered without running the installer from the official 2018-05-25 Traditional Chinese distribution preserved on client-twin-saga. See evidence/PROVENANCE.md for the complete custody chain and evidence/CLIENT-INVENTORY.json for the related native files. The current static network path is recorded in docs/NETWORK-CONNECTIONS.md. The autonomous reconstruction manifest uses evidence-gated phases: a bounded endpoint/login-connect milestone precedes configuration parsing, handshake/framing, and the final full network closure.

Original binaries are intentionally not committed here. The machine-local preservation.local.toml points to an authenticated extraction.

Workflow

From the MMO-Preservation tooling repository:

.\preserve.ps1 doctor --project ..\decomp-twin-saga-client
.\preserve.ps1 extract ..\decomp-twin-saga-client
.\preserve.ps1 index ..\decomp-twin-saga-client
.\preserve.ps1 grind ..\decomp-twin-saga-client --dry-run
.\preserve.ps1 grind ..\decomp-twin-saga-client --max-tasks 10
.\preserve.ps1 grade ..\decomp-twin-saga-client
.\preserve.ps1 differential-specs ..\decomp-twin-saga-client
.\preserve.ps1 differential ..\decomp-twin-saga-client
.\preserve.ps1 assemble ..\decomp-twin-saga-client --acceptance differential
.\preserve.ps1 integration-test ..\decomp-twin-saga-client
.\preserve.ps1 supervise ..\decomp-twin-saga-client --git-checkpoint --git-push
.\preserve.ps1 status ..\decomp-twin-saga-client
.\preserve.ps1 investigate ..\decomp-twin-saga-client --goal "Describe the login packet flow"

The pinned interactive model is qwen2.5-coder:7b through Ollama with a 16K context and 2K output cap. The 30B model is intentionally not used for this project because its weights, KV cache, and runtime workspace exhausted available GPU headroom. Ghidra performs the deterministic first pass; AI-refined functions keep both Ghidra and model provenance. The first controlled 7B refinement completed in 49 seconds while other GPU workloads remained active. Run explicitly selected functions in small batches and unload Ollama when the session is finished.

The unattended grind queue uses qwen2.5-coder:3b for small candidates, qwen2.5-coder:7b for default and escalation work, and codegemma:7b-instruct-v1.1-q4_0 for independent fidelity screening. It checkpoints after every function, recovers interrupted claims, and loads only one model at a time. Oversized and disassembly-only functions use resumable 4,000-character evidence slices instead of a workstation-stalling large context.

The shared evidence index covers all 87,387 records. Candidates pass through a Win32 x86 Clang syntax/object/ABI/structure gate, then safe leaf functions are compared with the signed original through Ghidra's concrete P-code emulator. Accepted source is separated into mechanical, differential, and integration trees with manifests. Automated model review alone is not accepted source.

Layout

• evidence/: hashes and, only when legally distributable, original immutable files
• analysis/ghidra/, analysis/ilspy/, analysis/cfr/: deterministic decompiler output
• analysis/ghidra-mcp/sessions/: read-only AI investigation reports and JSONL provenance
• analysis/ai/campaign-report.json: last unattended queue summary
• analysis/knowledge/report.json: call graph, symbol, type, and classifier summary
• analysis/grading/, analysis/differential/, analysis/assembly/: validation reports
• recovered/functions/: AI-refined function candidates
• recovered/metadata/: confidence, assumptions, risks, and provenance per function
• recovered/reviews/: independent automated fidelity screens
• recovered/grades/: per-function native compiler and structural results
• recovered/differential/: original-versus-rebuilt P-code evidence
• recovered/src/: acceptance-separated buildable source trees
• tests/protocol/: offline RSA/RC4 handshake and frame compatibility fixtures
• docs/STATUS.md: reconstruction and validation log
• work/: local Ghidra projects, caches, and other non-versioned state

Do not silently replace decompiler output or remove uncertainty markers. Bug fixes belong in the cohesive source tree with a test or a behavioral comparison whenever possible. Model confidence and reported risks are unverified model output; neither is a substitute for control-flow comparison, runtime traces, or maintainer review.