From 2ad993f55631a2c1bb5df39fb4bcc478626ef2c2 Mon Sep 17 00:00:00 2001 From: gamer147 Date: Sun, 2 Aug 2026 15:31:28 -0400 Subject: [PATCH] Add repository front door --- README.md | 47 +++++++++++++++++++++++++ docs/PROJECT-STRUCTURE.md | 1 + docs/remake-architecture-and-roadmap.md | 13 +++---- 3 files changed, 55 insertions(+), 6 deletions(-) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..c3ca823 --- /dev/null +++ b/README.md @@ -0,0 +1,47 @@ +# AGE engine reimplementation + +Open reimplementation of Eushully's AGE engine with first-class modding. The first target is +*Himegari Dungeon Meister* (SYS4, 2009); the runtime is Godot 4.7 .NET plus a platform-neutral C# VM. + +This repository contains only authored engine, tooling, native-boundary, test, and documentation files. +It does not contain the original game. Supply a legally obtained AGE installation separately; never copy +original game data into this repository. + +## Start here + +Prerequisites for the current Windows development workflow are Python 3.11, the .NET 8 SDK, Godot 4.7 +.NET, and a Himegari install containing `SYS4INI.BIN`. Pass paths explicitly or configure +`AGE_GODOT_CONSOLE` and `AGE_GAME_ROOT`. + +```powershell +# Verify and display the resolved development environment without launching. +.\run-godot.ps1 -Doctor -GodotConsole -GameRoot + +# Run source-only/core validation. The default validation level is the complete workspace/runtime suite. +py -3.11 -X utf8 tools\validate.py --level core + +# Build and launch the natural SYSTEM4 → title → game route. +.\run-godot.ps1 -GodotConsole -GameRoot +``` + +`workspace` and `full` validation additionally require the extracted script corpus and disposable derived +inputs described by the tools reference. `runtime` and `full` require Godot plus a valid game root. A +selected requirement that is unavailable is an error, not a silent skip. + +## Canonical references + +- [Architecture and roadmap](docs/remake-architecture-and-roadmap.md) — direction, phases, and the current + codebase-consolidation effort. +- [Project structure](docs/PROJECT-STRUCTURE.md) — source/original/derived ownership and directory layout. +- [Tools reference](docs/tools-reference.md) — exact commands, prerequisites, inputs, and outputs. +- [Phase B framework](docs/phase-b-framework.md) — boot, menu, session, and gameplay execution order. +- [Engine reverse engineering](docs/engine-re.md) — native AGE findings and provenance. + +Follow the repository's canonical-document map when recording new knowledge: extend the existing owner and +cross-link it instead of duplicating facts here. + +## Generated data + +`build/` is disposable and ignored. Generated references identify their canonical source in their header; +edit that source and run its owning generator rather than patching generated output. The original game +install and extracted archives remain sibling directories outside this Git repository. diff --git a/docs/PROJECT-STRUCTURE.md b/docs/PROJECT-STRUCTURE.md index 1a37125..fa1f05c 100644 --- a/docs/PROJECT-STRUCTURE.md +++ b/docs/PROJECT-STRUCTURE.md @@ -28,6 +28,7 @@ S:\Game Hacking\Eushully\Himegari\ ← workspace root (three siblings) │ └── age-reimpl/ ← OUR WORK (everything we made lives here) │ + ├── README.md navigation-only repository front door; canonical facts stay in docs/ ├── run-godot.ps1 / run-godot.cmd tracked development launcher + Windows wrapper; │ resolves Godot/game-root from parameters, environment, │ PATH, and the conventional sibling install diff --git a/docs/remake-architecture-and-roadmap.md b/docs/remake-architecture-and-roadmap.md index db8663f..4bcc49c 100644 --- a/docs/remake-architecture-and-roadmap.md +++ b/docs/remake-architecture-and-roadmap.md @@ -524,8 +524,8 @@ requirements. #### Planned maintenance slice — codebase consolidation -**Status (2026-08-02): planned; step 1 is next.** The runtime and tooling now have enough independent -regression coverage to support behavior-preserving cleanup: 590 engine tests, ten directly runnable Python +**Status (2026-08-02): step 1 complete; step 2 is next.** The runtime and tooling now have enough independent +regression coverage to support behavior-preserving cleanup: 590 engine tests, eleven directly runnable Python tool suites, the Godot build/self-test, and the installed-corpus gates. The project layout itself is sound, but a few files have become navigation and ownership bottlenecks: `VirtualMachine.cs`, `GfxState.cs`, `Main.cs`, `GodotAdvHost.cs`, and `extract_init.py`. Repository entry points are also partly machine-local, @@ -536,7 +536,8 @@ compatibility, current command paths, generated-file ownership, and the one-engi Each step should land in bounded commits with the full validation level appropriate to the touched boundary; do not mix mechanical moves with semantic changes. -1. **Create a reproducible project front door.** Replace the locally excluded, machine-path-specific +1. **Create a reproducible project front door — completed 2026-08-02.** Replace the locally excluded, + machine-path-specific `run-godot.ps1`/`.cmd` workflow with a tracked launcher whose explicit parameters and documented environment fallbacks select Godot and the game root. Implement the already-listed one-command validation driver from `docs/tools-reference.md`, with named levels that distinguish hermetic/core, @@ -927,8 +928,8 @@ layer's rendering diverges from ADV; save layout. --- ## 8. Immediate next step -Begin step 1 of the **codebase consolidation** maintenance slice: land the tracked parameterized Godot -launcher, then the layered one-command validation driver, then the navigation-only repository README. -The launcher and validator establish the reproducible safety boundary needed before physical file splits. +Begin step 2 of the **codebase consolidation** maintenance slice: behavior-neutral physical splits backed +by the tracked launcher and layered validation driver. Start with the embedded `Main` self-test surface, +then move one existing domain at a time while preserving public types, commands, and generated output. Concrete playthrough blockers may still preempt this bounded maintenance work; the consolidation effort does not replace Phase B gameplay validation or the open cross-platform gates.