th08

東方永夜抄 ～ Imperishable Night

Our goal is an exact reconstruction of the original Japanese TH08 1.00d executable: recover C++ that, with the original Visual C++ .NET 2002 toolchain, reproduces its machine code, binary interfaces, and executable layout.

A reimplementation recreates a game's behavior with a new implementation. Here, the original binary guides both the behavior and the source structure. The playable ports build on that recovered source, adapting it to modern systems. Exact reconstruction and port compatibility have separate validation paths; whole-executable identity is still in progress.

[!IMPORTANT]

🌙 The authored reconstruction is complete, and the Linux port is playable.

Download TH08 Reconstruction v0.2.0 — Native Linux 64-bit;

active ELF64 source lives on

port/portable-64bit.

Windows and macOS ports remain in progress.

TL;DR

I want to... · Start here Understand the project and how the engine fits together · Project and engine guide Check reconstruction progress · Repository status Review replay validation results and reproduce them · Replay validation Understand how AI agents work on the project · AI agent workflow Read our accuracy and readability philosophy · What we mean by semantic reconstruction Contribute · Contributing Play or build a port · Platform guides Reproduce the native VC7 runtime gate · Windows i386 reconstruction runtime Reproduce the exact comparison · Exact reconstruction Find the production owner of a source symbol · Source and build ownership map Browse current subsystem semantics · Current semantic index Reuse the semantic/readability method in another title · Semantic and readability playbook Choose a human or agent reading route · Documentation index Browse the technical references · Project map Review upstream history and attribution · Credits and provenance

For a first read, start with the project guide. For an engineering session, use the agent session route. Both routes lead to the same authoritative evidence and project rules.

Repository status

This repository reconstructs the original Japanese 東方永夜抄 ～ Imperishable Night version 1.00d executable. Every one of the 1,107 authored functions now has source. Strict comparison currently accepts 1,106 of them, covering 459,396 of 459,757 authored bytes.

Area · Status · Current position Authored source · Complete · 1,107 / 1,107 functions are present in source Strict authored comparison · 99.92% by bytes · 1,106 / 1,107 functions are accepted as exact Whole executable · In progress · PE layout, linked runtime/library code, and one authored near match remain Web · Playable · Public WebAssembly/WebGL 2 build Linux · Playable · Native i386; x86_64/AArch64 work on port/portable-64bit Windows · In progress · VC7 i386 prerequisite complete; modern redistributable packaging remains macOS · In progress · Native backend and packaging are planned

Exact reconstruction and playable ports are separate milestones. The progress bar counts authored bytes accepted by strict comparison; the platform cards show where the reconstructed source is currently playable.

The VC7 Windows i386 build has completed its whole-program runtime validation. That pass caught source-ownership, linking, initialization, and lifetime defects beyond function-level matching. Exact checks use the normal build; playtesting uses bugfix, which accommodates the retail size/checksum check. See the native runtime procedure and issue ledger for the results. A redistributable modern Windows package remains a separate milestone.

The remaining exact-reconstruction work is the last authored near match, whole-image layout, and the compiler/runtime and D3DX code linked into the original game. The repository ledgers are the canonical source for live counts.

AI agent workflow

AI coding agents carry out the new engineering in this continuation: reverse engineering, matching, semantic recovery, tooling, documentation, and porting. The human maintainer sets direction, reviews releases and merges, and supplies the legally obtained target and game data. The imported GensokyoClub history retains its original authorship and contribution record.

Agents work on bounded tasks and check their conclusions against the verified target. The repository is the project's shared memory: source, ledgers, evidence notes, scripts, tests, and skills let the next session reproduce a result and continue from it.

flowchart LR
    H["Human<br/>scope & release"]:::human --> A["Fresh AI agent<br/>cold start"]:::agent
    K[("Repository memory<br/>rules · ledgers · handoff<br/>skills · evidence · guards")]:::memory --> A
    A --> E["Bounded task<br/>+ TH08 evidence"]:::evidence
    E --> I["Natural C++<br/>ABI / VC7 shape intact"]:::work
    I --> F{"Focused VC7<br/>exact?"}:::gate
    F -->|Mismatch| D["Diagnose<br/>and refine"]:::reject --> I
    F -->|Exact| O["Required aggregate<br/>+ portable Oracles"]:::oracle
    O --> G{"All gates<br/>pass?"}:::gate
    G -->|Refine| D
    G -->|Pass| R["Promote evidence, unknowns,<br/>guards & lessons into repo"]:::memory
    R --> Q["Commit & push<br/>auditable checkpoint"]:::done
    R -.->|reusable knowledge| K

    classDef human fill:#fff1c2,stroke:#b7791f,color:#3b2f0b,stroke-width:2px;
    classDef agent fill:#ede9fe,stroke:#7c3aed,color:#2e1065,stroke-width:2px;
    classDef memory fill:#dbeafe,stroke:#2563eb,color:#172554,stroke-width:2px;
    classDef evidence fill:#cffafe,stroke:#0891b2,color:#083344,stroke-width:2px;
    classDef work fill:#fef3c7,stroke:#d97706,color:#451a03,stroke-width:2px;
    classDef oracle fill:#dcfce7,stroke:#16a34a,color:#052e16,stroke-width:2px;
    classDef gate fill:#f3f4f6,stroke:#4b5563,color:#111827,stroke-width:2px;
    classDef reject fill:#fee2e2,stroke:#dc2626,color:#450a0a,stroke-width:2px;
    classDef done fill:#ccfbf1,stroke:#0f766e,color:#042f2e,stroke-width:2px;

An “oracle” is a reproducible check. We verify the target's size and SHA-256, compare the affected VC7 code and relocations, and cold-replay accepted units after shared changes. Native linking and playtesting, modern builds, layout checks, and CI test the source from complementary angles.

Each part of the working state has a home:

• AGENTS.md holds the target, ABI, safety, and acceptance rules.
• The CSV/TOML ledgers and status scripts hold live mappings and accepted

results; prose provides context for these canonical records.

• The current handoff says what is complete, what is

blocked, and what should happen next.

• Task-specific skills and

the knowledge map preserve tool recipes, VC7 source patterns, evidence boundaries, and lessons from failed experiments.

• Evidence notes explain accepted names, layouts, boundaries, and compiler

patterns; automated checks catch regressions.

A fresh session starts from the agent reading route, checks live state, and resumes one bounded task. Reconstruction uses one writer and serial Wine/VC7 builds. Results, failed experiments, and unresolved questions are recorded before handoff.

What we mean by semantic reconstruction

Matching the executable establishes the first requirement. Semantic reconstruction then recovers the game concepts hidden behind object offsets, anonymous fields, bare masks, and numbered interpreter cases and puts those meanings back into the C++.

Accuracy comes first. We add a type or name only when TH08 itself supports it through reads, writes, callers, or state transitions. TH06, TH07, and the inherited upstream names are useful corroboration; the Japanese TH08 1.00d target has final authority. Uncertain meanings remain explicitly documented as unknowns.

Equivalent-looking C++ expressions can produce different VC7 code. Under /Ob0, even a small helper or a reordered switch can change the output. The accepted formulation preserves the target-shaped expression or case order whenever exact emission depends on it.

Every semantic batch is checked in both directions. The VC7 comparison makes sure accepted target bytes stay exact; the modern builds make sure the same source still works as portable C++. Shared changes are rebuilt on Linux and checked against the fixed-layout verifier, with relevant runtime tests used when they are available.

To measure the semantic pass, we audited the repository against GensokyoClub/th06 and some100/th07. The first table compares protocols that recur across the three engines; the second looks at the residue a reader encounters in the target-side C++.

Protocol surface · This TH08 reconstruction · GensokyoClub/th06 · some100/th07 Primary ECL opcodes · 184 / 184 named · 136 / 136 named · 159 / 159 named ECL operand selectors · 101 / 101 named · 25 named values · 74 / 74 named Stage/background stream opcodes · 35 / 35 named · 6 named values · 31 / 31 named Named ECL timeline opcodes · 17 / 17 · 0 / 13 · 0 / 13 Stage interpolation modes · 8 · no separate selector · 7 Named replay event bits · 11 / 11 observed · no comparable domain · 0 / 7 observed Screen-effect modes · 8 · 3 · 5 Descriptive sound IDs · 46 / 46-value domain · 16 of 32 entries · 23 sparse entries Behavior-named effect IDs · 40 · 0 · 0 Audio command operations · 8 plus `NONE` · no separate enum · 7

Target-side source audit · This TH08 reconstruction · GensokyoClub/th06 · some100/th07 C/C++ files / lines · 98 / 61,315 · 95 / 31,361 · 75 / 42,979 Numeric case labels · 74 (12.1 per 10k lines) · 95 (30.3 per 10k) · 96 (22.3 per 10k) Decompiler-style local names · 0 · 581 · 389 Generic param_N names · 0 · 7 · 144 Anonymous identifiers found by the same debt scan · 0 · 284 · 78 LAB_... labels · 0 · 2 · 27 offsetof layout assertions · 700 · 0 · 0 Type-size assertions · 135 · 83 · 68 Automated semantic protocol guard · yes · no · no

This audit shows broad naming coverage in TH08's script protocols, objects, and layouts. The reference projects also offer useful directions: TH07 has names for shared ANM opcodes 25 and 31 and a broader resource catalogue; TH06 has 26 typed ECL packet structures against six target-backed families in TH08. Further work can adopt those ideas as TH08 evidence and VC7 comparison support them.

The remaining 74 numeric case labels are option-array indices, damage or life quantities, or per-file animation IDs whose visual meaning remains ambiguous. The audit used target-side C/C++ only (excluding TH08's modern port), with TH06 at cc475a0b and TH07 at 84963b2e. These are fixed review baselines and do not move with the current heads of either reference. The semantic reconstruction history gives the counting rules, full commit IDs, exceptions, and Oracle results.

The final pass cold-built all 75 configured comparison objects and reproduced all 1,106 / 1,106 accepted exact functions. The normal VC7 image linked, and the full Linux i386 build and fixed-layout check passed. The semantic reconstruction history has the full evidence trail, the exact-safe source-shape rules, the unknowns we kept, and the results for each batch.

Contributing

Contributions are welcome. We are especially interested in:

• evidence-backed exact reconstruction and whole-image layout work;
• a supported modern Windows package with a redistributable replacement for

the remaining D3DX debug dependency;

• a native macOS window, input, audio, renderer, and packaging backend;
• Linux renderer fixes, MIDI support, and testing on additional hardware;
• browser correctness, performance, and compatibility work in

N0zoM1z0/th08-web.

Before changing reconstruction state, read AGENTS.md, the reverse-engineering workflow, and the current handoff. Exact-match contributions must be supported by reproducible comparison against the specified target. Keep the original executable, DAT archives, extracted retail assets, private analysis databases, and credentials outside the repository.

Reporting bugs

TH08 has many teams, difficulties, and branching stage routes to test. Gameplay and port bug reports are welcome. Please open an issue with:

• Build and platform: release version, or branch and commit for a source

build; operating system and architecture. Include GPU/driver details for rendering problems.

• Game context: mode (Story, Practice, or Spell Practice), difficulty,

team or solo character, exact stage and route (for example, Stage 4A or 6B), and spell name/number when relevant.

• Reproduction: steps from the menu to the failure, expected behavior,

actual behavior, and whether it happens consistently.

• Evidence: screenshots or a short video showing the problem, plus logs

or a crash trace for an unexpected exit. A replay can help reproduce a gameplay issue; note the point where it occurs.

For browser bugs, use the Web project's issues. The Linux troubleshooting guide lists diagnostic files. Keep original game data and executables private.

Platform guides

The ports compile the reconstructed game code for modern systems. Players provide the original game data from a legally obtained copy of TH08.

Development location · Scope main · Exact reconstruction and modern i386 builds port/portable-64bit · Native x86_64 and AArch64 ports th08-web · Browser port in a separate repository

Web

Status: Playable

Play in the browser · source and documentation · latest release ·

TH08 Web compiles the reconstructed C++ directly to WebAssembly and runs it in a browser worker. It uses WebGL 2, Web Audio, browser-local files, and IndexedDB-backed saves.

Select th08.dat and thbgm.dat from a legal TH08 installation in the launcher. th08.dat remains in volatile session memory; thbgm.dat is range-read from its browser File object. Both files stay on the player's machine and outside persistent browser storage. Chrome has the best observed frame pacing; Firefox is also supported and is usually slower.

Linux

Status: Playable

• Download the latest native Linux release
• Download, installation, and player guide
• Native Linux porting architecture and validation
• Native 64-bit branch, build, and validation
• Portable Linux build workflow

The source commands below build the i386 product from main. For x86_64 or AArch64 source builds, follow the linked 64-bit branch guide. Release packages have their own architecture-specific runtime requirements in the player guide.

On Debian or Ubuntu, build and run against the original game-data directory:

scripts/setup-modern-linux.sh "/path/to/the/original/TH08 directory"

For later runs, use the incremental launcher:

scripts/play-modern-linux.sh "/path/to/the/original/TH08 directory"

The latest release includes x86_64, i386, and experimental AArch64 portable packages. Extract the package for your architecture and pass the original data directory:

./run-th08.sh "/path/to/the/original/TH08 directory"