# Earthsiege reverse engineering

Research on the supplied October 1994 CD of **Metaltech: Earthsiege 1.0**, supporting the ongoing native C++ reimplementation in `../earthsiege-cpp`.

Run the comparison installation with:

```sh
./run_earthsiege_dosbox.sh
```

The launcher lists the original 1.0 installation and separate CD, patched CD and floppy expansion installs. Use `--list` to list IDs or pass an ID directly. Each choice mounts its own C: drive and matching CD as D:. No system-wide DOSBox configuration is changed.

[The supplied-media audit](docs/INSTALL_MEDIA.md) covers the expansion and the archive labelled “Source”. The latter contains CD images and an expansion patch, not source code. Its 1996 base reissue repeats every original game file unchanged. The [editions and expansion browser](analysis/releases/index.html) adds mission briefings and resource comparisons. The [simulator comparison](docs/SIMULATOR_VERSIONS.md) now traces expansion weapon, resource, scanner, cleanup and radio changes with original-code probes. The [expansion catalogue and integration report](docs/EXPANSION_INTEGRATION.md) covers the expanded browsers and the C++ implementation, including original-code checks for careers, combat, deployment and rendering.

Open [the research browser](analysis/index.html) directly, or serve it locally with:

```sh
python3 -m http.server 8766 --bind 127.0.0.1
```

When serving, open **http://127.0.0.1:8766/analysis/** for models and animations, artwork and cockpits, digital audio, music auditions, missions, scenery, palettes, fonts and world settings. Browser previews identify remaining approximations; they are research tools, not the game reimplementation.

The [model browser](analysis/models/index.html) includes named HERCs in manual order, individual building variants, environment-coloured terrain thumbnails, editable loadouts and original day/dusk/night lighting presets with visibility and distance controls. [Model browser notes](docs/MODEL_BROWSER.md) explain the sources and preview boundaries.

The [mission browser](analysis/missions/index.html) opens in 3D with buildings, actors, routes and waypoints. Its list includes campaign/role and short mission summaries. **Game launch** uses the original launch setup, with explicit campaign context, equipment and repeatable random variations. Use **Focus** to inspect buildings, individual terrain variants or the “Jö” pattern in B0_C1_61; changing inspection options preserves the camera. [Scenery notes](docs/SCENERY_BROWSER.md) describe the sources and preview limits.

Original payloads are retained under `extracted/cd_1994_10`, with hashes and archive metadata in `analysis/volumes.json` and `analysis/media-manifest.json`. Extraction and independent original-code comparison tools are in `tools`. See [the analysis completion audit](docs/ANALYSIS_STATUS.md) for completed foundations and bounded unresolved endpoints and [the working research record](docs/WORKLOG.md) for evidence and history. The analysis-first pass is complete to that documented boundary. The native game now covers the original game loop; see [its current validation report](../earthsiege-cpp/docs/VALIDATION.md) for the completed comparisons and remaining fidelity limits.

[Pixel comparison results](docs/PIXEL_FIDELITY.md) explain the instruction-traced
rendering corrections and all remaining sampled differences. With presentation
timing isolated, 114 of 120 whole images match exactly; the other six are fully
explained by the bounded repair of invalid distant-radar model references.

[Mission fidelity findings](docs/MISSION_FIDELITY.md) document authored-world
comparisons, consecutive campaign journeys, gameplay corrections and explicit
handling of original formation and effect-queue memory defects.

[Build, language and library evidence](docs/BUILD_EVIDENCE.md) collects the C++ source paths, class/runtime findings, DOS extender and HMI SOS identification. [Audio research](docs/MUSIC.md) covers the original music and sound drivers in detail.

[Original command-line options](docs/COMMAND_LINE.md) explains the internal `-eggplant` handshake, movie-player buffer/timing options and simulator switches.

[Cheats and development controls](docs/CHEATS_AND_DEVELOPMENT.md) distinguishes verified ES1 handlers, public reports and unproven interpretations.

`analysis/` contains the curated browsers, findings and presentation assets.
Research generators, replay captures, mission fixtures, memory dumps and private
DOSBox runs live in the ignored `work/research/` tree. Run
`python3 tools/publish_analysis.py` to publish inspected outputs; the explicit
allowlist keeps later experiments out of the presentation directory.
[Research layout and publishing](docs/RESEARCH_LAYOUT.md) explains the workflow
and the relocation of existing evidence.

`./publish.sh --build-only` creates and verifies `web-stage/` for the full web
archive, including rendered Markdown reports. `./publish.sh --dry-run` previews
an rsync upload; `./publish.sh` publishes to `lostengines.com/earthsiege/`.
[Publisher instructions](tools/publish/README.md) cover the file selection,
verification and server destination.

This analysis tree is intentionally left uncommitted for manual inspection.


[Extended mission comparisons](docs/AUTONOMOUS_VALIDATION.md) cover authored
missions with player controls, longer runs and sanitizer checks. They document
the player-disable fix and the original aim-initialization and arithmetic bugs.

[Earthsiege 2 handoff](docs/EARTHSIEGE2_HANDOFF.md) collects the reusable analysis tools, validation methods and release-specific assumptions for the next investigation. The audio and documentation checkpoint is complete and Earthsiege 2 has forked. Earthsiege 1 work has resumed, starting with the omitted expansion media; further 1.0 gameplay validation remains on the work list.

[How Earthsiege draws a frame](https://lost-engines.github.io/earthsiege-exhumed/graphics/) explains the renderer with original-code captures and interactive illustrations. Article assets are retained in `analysis/graphics-engine/`; regenerate them in `work/research/graphics-engine/` with `tools/build_graphics_article.py`, then run `tools/publish_analysis.py`.