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.
| I want to... | Start here |
|---|---|
| Understand the project and how the engine fits together | Project and engine guide |
| Check reconstruction progress | Repository status |
| 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.
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 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.
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.
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.
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.
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 |
Status: Playable
Play in the browser · source and documentation · latest release · engineering the Web port
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.
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"The native i386 ELF has been tested under WSLg and in a Kali Linux x86-64
virtual machine. It reads th08.dat and thbgm.dat directly and runs
independently of the original th08.exe. Settings, scores, replays, and
backups stay in the selected data directory.
The native-layout x86_64 PIE is the recommended Linux package. Its source is on
port/portable-64bit.
It has been played through a Lunatic Stage 1–6A route, including the ending,
results, and return to title, plus Stage 4A/6B Practice runs under WSLg. The
AArch64 build and loader have been verified, but it still needs a gameplay run
on real hardware.
Maintainer bias, openly declared: Kaguya is my favorite, and 竹取飛翔 ～ Lunatic Princess is my favorite track. XD
The portable window uses the project-owned
resources/modern-icon.png. On software-rendered
systems, a fresh configuration's fullscreen FPS/vsync calibration can be slow;
reusing an existing th08.cfg is optional.
An early Linux build sometimes tiled a dynamic text texture across the outer
frame and HUD during the Stage 4-to-5 transition, most visibly as repeated
Yakumo Yukari text. It also had missing enemy/boss art and incomplete effects.
The native-layout and renderer fixes produced clean final x86_64 full-route and
Practice runs. We keep the screenshot as a useful regression sample; reports
from additional drivers and desktops are welcome.
Status: In progress
See the native Windows guide for the current build and release requirements. The separate VC7 Windows i386 compile/link/play prerequisite is complete, including cold exact replay, native normal/bugfix links, final-link owner checks, and real Windows playtesting. Modern port work may now proceed; it still must replace the DirectX SDK debug DLL with redistributable components before publishing a supported Windows release.
The goal is a self-contained native build that accepts any legal TH08 data directory and ships with redistributable components.
Status: In progress
See the native macOS guide for the current plan. Native window, input, audio, rendering, packaging, and real-hardware validation are the remaining milestones.
The exact target is one binary: the original Japanese TH08 version 1.00d. A localized, patched, trial, or earlier executable is a different target.
This repository continues GensokyoClub/th08. Its complete Git history preserves the original authorship and contribution record.
Supply your own original executable as resources/th08.exe:
| Property | Required value |
|---|---|
| Version | Original Japanese 1.00d |
| Size | 840,704 bytes |
| SHA-256 | 330fbdbf58a710829d65277b4f312cfbb38d5448b3df523e79350b879213d924 |
| PE image base | 0x00400000 |
| Entry point | 0x004A619E |
The executable and game data remain copyrighted assets supplied privately by each contributor. Verify the private target before analysis or comparison:
python3 scripts/verify-target.pyInitialize the third-party submodules, then create the Visual Studio .NET 2002/DirectX 8 environment. On Linux or macOS:
git submodule update --init --recursive
./scripts/create_th08_prefix
python3 ./scripts/build.pyThe prefix helper uses Wine by default. Set WINE before invoking it when a
different compatible runner is required. On Windows, use the setup script
directly:
python scripts/create_devenv.py scripts/dls scripts/prefix
python scripts/build.py
See Build and exact matching for dependencies, build modes, reccmp, objdiff, and acceptance rules.
For whole-program validation, follow the
native Windows i386 runtime procedure.
It cold-replays accepted normal objects, verifies the normal image, and builds
bugfix last, leaving build/th08.exe ready for isolated Windows testing.
IDA MCP follows whichever database is active in the GUI, so TH08 analysis begins with the documented database attestation. Target-safe headless tools and the repository's target-pinned analysis scripts cover other analysis sessions.
Read current figures directly from the ledgers:
python3 scripts/analysis/report-reconstruction-status.py --summaryExact-match status comes from an accepted, reproducible comparison against the
verified target. Source mappings, generated progress artwork, successful
builds, and config/implemented.csv serve their own tracking and build roles.
Generated source-presence and strict-match figures are recorded in
docs/PROGRESS.md.
The documentation index provides reading routes and a reference catalog. Use the links below for a direct lookup.
| Need | Start here |
|---|---|
| Understand runtime relationships and terminology | Project and engine guide |
| Current state and next bounded work | Current handoff and generated progress |
| Repository/target structure | Architecture and binary inventory |
| Find the production TU, exact probe, shared include, or build selector | Source and build ownership map |
| Find current declarations and semantic evidence by subsystem | Current semantic index |
| Reverse engineering and acceptance | RE workflow, semantic reconstruction, cross-title semantic playbook, and build/matching |
| ANM/effect protocol references | ANM resource namespaces and Effect storage/callback roles |
| Analysis safety and commands | IDA safety, tool recipes, and agent rules |
| Reusable evidence and prior lessons | Knowledge map |
| Native VC7 runtime evidence | Windows i386 workflow, owner audit, and runtime issues |
| Playable ports | Port overview, Linux engineering, Linux play guide, Windows, macOS, and Web project |
This repository preserves the public
GensokyoClub/th08 history through
7ad3792,
the merge of upstream pull request #77 on August 10, 2026. The independent
continuation begins at its direct child,
001bf3e,
on August 13, 2026. The imported commits retain their original author and
committer metadata. The upstream project also credits @EstexNT for porting its
var_order pragma to MSVC7.
Work after that boundary has been developed from the imported public source, the legally obtained Japanese TH08 1.00d executable, and other public references.
The imported snapshot was published under the MIT License, and this continuation remains under the same license. LICENSE preserves the original copyright notice and records the continuation separately.
The upstream project's current public notice places its active reconstruction in private development in response to AI decompilations and ports. This project's engineering is predominantly agent-produced and is developed in the open, so the two projects now have different contribution models. Accordingly, this work is maintained as an independent continuation rather than as a stream of upstream pull requests, while preserving upstream history, credit, and license terms.
The N0zoM1z0/th07 reconstruction supplies this repository's workflow, structure, target gates, matching, and documentation model. GensokyoClub/th06 provides adjacent-engine corroboration, while TH08 target evidence retains final authority.
Repository code and documentation are provided under the included MIT License. Rights to the original game, executable, and game data remain with their respective owners.