# Starting the Earthsiege 2 investigation

Earthsiege 1 is ready to serve as the reference project for a separate Earthsiege 2
analysis. There is no outstanding Earthsiege 1 prerequisite that needs to delay
the fork. The audio checkpoint is complete and the fork has taken place.
Earthsiege 1 work has resumed.

## Additional media found after the fork

The 1996 Earthsiege reissue includes an Earthsiege 2 demo under
`extracted/cd_1996_10/ES2DEMO`, with March/April 1996 file timestamps. It is
preserved here for the sequel investigation. CyberStorm and Hunter Hunted
demos are also present.

Earthsiege 1's expansion was omitted from the earlier scope. The
[media audit](INSTALL_MEDIA.md) now records its added HERCs, weapons, missions
and separate executables. Their behavior still needs tracing.

## Start with the media and consumers

Identify the sequel's exact media and executable revisions, retain hashes and
build a separate DOSBox installation before carrying over semantic names. Then
inventory its archives and make the model, mission and artwork browsers work on
its own resources before starting its C++ implementation. The Earthsiege 1
experience with terrain variants, generated buildings and equipment attachments
is a useful checklist for that first pass.

Shared names or similar layouts are leads to check. Earthsiege 1's addresses,
object offsets, rounding rules, palettes, campaign tables and HMI driver choices
are specific to this release and must be re-established for the sequel.

## Reusable work

| Area | Starting points |
|---|---|
| Resource inventory and original readers | [FORMATS.md](FORMATS.md), [RESOURCE_AUDIT.md](RESOURCE_AUDIT.md), `tools/audit_resource_consumers.py`. Preserve unknown bytes and distinguish inactive resources from undecoded formats. |
| Original execution | `tools/native_reference.py`, `tools/dosbox_session.py`, `tools/build_dosbox_reference.py`, [REFERENCE_CAPTURE.md](REFERENCE_CAPTURE.md). Reuse memory adapters and capture structure; replace executable layouts and routine addresses. |
| Models and assembly | [MODEL_BROWSER.md](MODEL_BROWSER.md), [ANIMATION.md](ANIMATION.md), [ARMAMENT.md](ARMAMENT.md), [LIGHTING.md](LIGHTING.md). Check hierarchy, LOD, cell variants, loadout attachments, movement and palette materials separately. |
| Missions and campaigns | [MISSION_LAUNCH.md](MISSION_LAUNCH.md), [CAMPAIGN.md](CAMPAIGN.md), [SCENERY_BROWSER.md](SCENERY_BROWSER.md). Capture the real launch state and RNG rather than presenting all source alternatives as a playable world. |
| Renderer | [RENDERING.md](RENDERING.md), [PIXEL_FIDELITY.md](PIXEL_FIDELITY.md), [ENVIRONMENT.md](ENVIRONMENT.md). Compare projection, ordering, scan conversion, clipping, palettes and masks before relying on screenshots alone. |
| Interface and fonts | [SHELL.md](SHELL.md), [INPUT.md](INPUT.md), [FONTS.md](FONTS.md). The browser scripts and font-outline exporter can be adapted once the sequel's formats are checked. |
| Audio | [MUSIC.md](MUSIC.md), `tools/native_music.py`, `tools/native_opl.py`, `tools/native_midi.py`, `tools/capture_midi_pipeline.py`. Reuse the original-driver capture method and the native Munt/Sound Canvas/SoundFont adapters. Firmware may be shared; song routing and instruments need a fresh audit. |
| Native regression structure | `../earthsiege-cpp/tests`, [native validation](../../earthsiege-cpp/docs/VALIDATION.md). Expected results come from the original; controlled clocks, external input and explicit driver completions help isolate deterministic behaviour. |

## Boundaries to carry forward

The [completion audit](ANALYSIS_STATUS.md) lists the few historical unknowns:
a 58-byte TEST.DAT, predecessor layouts and fields without an established live
consumer. Those remain preserved and labelled. A similar sequel structure could
provide new evidence, but they do not prevent using the Earthsiege 1 findings.

Four full original recordings match simulation, RNG, camera and return files.
Of 120 sampled images, 114 match directly; the six remaining cases match after
applying the same proved malformed-radar-model repair to the reference.
These are useful validation methods to carry over. They do not replace testing
new sequel rules or every campaign branch.

Further Earthsiege 1 gameplay testing can proceed independently after the fork.
Small audio interrupt/voice-completion timing differences remain a lower priority;
the original music routing and software-driver output are now independently
checked for both FM and physical-MIDI devices.

Checkpoint revisions: native `073d80a`; public overview `7d61021`. The analysis tree is intentionally uncommitted. `work/research/music/native-checkpoint.json` records the final audio validation and deployment.