東方永夜抄 ～ Imperishable Night

<p align="center"> <img src="resources/title-screen.png" width="640" alt="Original Japanese TH08 1.00d title screen"> </p> <p align="center"> <img src="resources/progress.svg" alt="TH08 exact-source and playable-platform progress"> </p>

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

<p align="center"> <a href="https://th08-web.pages.dev/"> <img src="https://raw.githubusercontent.com/N0zoM1z0/th08-web/main/resources/th08-web-social-preview.jpg" width="800" alt="TH08 Web source-built browser port and Imperishable Night title screen"> </a> </p>

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.

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"

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.

<p align="center"> <img src="https://raw.githubusercontent.com/N0zoM1z0/th08/port/portable-64bit/resources/portable64-kaguya-lunatic.png" width="800" alt="Native x86_64 TH08 running Kaguya's Lunatic Princess spell under WSLg"> </p>

Maintainer bias, openly declared: Kaguya is my favorite, and 竹取飛翔 ～ Lunatic Princess is my favorite track. XD

<p align="center"> <img src="resources/kali-linux-port.gif" width="800" alt="TH08 native Linux reconstruction starting and running on Kali Linux"> </p>

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.

Earlier Linux renderer regression

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.

<p align="center"> <img src="resources/linux-stage5-texture-tiling.png" width="640" alt="Historical Linux Stage 5 dynamic text texture tiling regression"> </p>

Windows

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.

macOS

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.

Exact reconstruction

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.

Target executable

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.py

Build and compare

Initialize 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.py

The 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.

Analysis and live progress

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 --summary

Exact-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.

Project map

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

Credits and provenance

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.

License

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.