Files
Neutron/docs/analysis/level-resource-mapping.md

98 lines
5.0 KiB
Markdown

# Level3B / Level3E resource evidence
Static investigation, 2026-10-24. Source: unmodified `Original/Neutron.exe`, SHA-256
`f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8`.
Addresses are preferred-base EXE virtual addresses. File offsets for the addresses
below equal VA minus `0x400000` in this PE. No original code was executed.
## Findings and scope
The user is correct that **`gam/Level3B.gam` and `gam/Level3E.gam` exist**.
Both parse successfully as 1,777-byte entity files with four entities:
`3JIM`, `STRT`, `LOAD`, `3SBU`. Their bytes after the four-byte level header
are identical; headers are `LV3B` and `LV3E`. GAMs contain entity properties,
not replacement scene mesh/material/texture payloads.
The original executable also has explicit, separate archive-opening paths for
**`omt/level3B.omt` and `omt/level3E.omt`**. Those files are absent from the
supplied original tree. This is verified loader behavior, rather than an inferred
same-stem pairing or merely an unused string reference. No shared-map alias is
present on the traced initialization paths.
However, whether these scenes occur in normal shipped gameplay is **unverified**.
Small identical entity bodies suggest possible stubs/development leftovers; that
is an inference, not established intent. The primary's corpus check found no
serialized GAM string references to either scene name/code and no source TSK
starting in `LV3B`/`LV3E`. This does not exclude hardcoded transitions or other
entry routes. Do not describe the archives as confirmed required files for the
normal game, or tell the user their GAM files are missing.
## Class and archive dispatch
| Evidence | Level3B | Level3E |
|---|---|---|
| Complete class | `CLevel03BGame` | `CLevel03EGame` |
| Constructor | `0x451AF0` | `0x452690` |
| Constructor sets level code | `0x451BA8`: push `LV3B` | `0x452748`: push `LV3E` |
| Factory calls constructor for code | `0x45D635` | `0x45D78B` |
| Complete vtable | `0x4C7830` | `0x4C8A00` |
| Initialization slot `+0xB4` | `0x451C50` | `0x4527F0` |
| Literal archive string | `0x4F1F24`: `level3B.omt` | `0x4F1FFC`: `level3E.omt` |
| Archive string length/copy | `0x451C99` / `0x451CC5` | `0x452839` / `0x452865` |
| Dispatch archive loader slot `+0xE4` | `0x451CE8` | `0x452888` |
Both vtable `+0xE4` entries are `0x44E7B0`. This function copies the supplied
archive filename, invokes slot `+0x16C` with the directory string `omt` at
`0x4F1B1C` (`0x44E7FF..0x44E81E`), builds the string argument, calls the file
stream helper `0x476170` at `0x44E8B4`, then calls database helper `0x476000`
at `0x44E8CE`. It stores the file stream/database in globals
`0x5099D8` / `0x5099C0`. There is no fallback archive name in this routine.
File helper `0x476170` imports `OMediaFilePath` and `OMediaFileStream`
constructors (`0x48D188`, `0x48D184`). Database helper `0x476000` imports
`OMediaDataBase(OMediaStream*)` at `0x48D19C`. This confirms the archive string
goes to the real file/database path rather than to a debug label.
The level-code-to-GAM path is separate: the switch at `0x4607F1` selects
`level3b.gam` (`0x4F49C4`) at `0x46083E`; the `LV3E` branch selects
`level3e.gam` (`0x4F49A0`) at `0x46088E`. The level registry also contains
code/GAM records at `0x4F3BE0` and `0x4F3C4C`. Existence in the factory and
registries proves registration, not a normal-gameplay route.
## Missing-file handling
The traced archive-opening path does **not** directly abort, choose a shared map,
or produce procedural replacement geometry when the map archive cannot open:
- `0x476000` initializes its result to null, checks the stream pointer and its
open byte `+0x24` (`0x47602A..0x476033`), and returns null without constructing
a database when either condition fails.
- `0x44E7B0` retains the resulting null database and returns. It does not itself
throw or dispatch an explicit missing-map error in the examined path.
- Base geometry/entity-resource enumeration `0x44D4F0` checks `0x5099C0` at
`0x44D513`; null skips enumeration to `0x44D7F2`.
- The child initialization then continues and separately constructs `3SKY` through
the factory `0x459CB0`. Its sky resource is `omt\nightsky.omt` at `0x4F1DA4`,
passed at `0x451D35` / `0x4528D5`.
Thus these archives' absence means the port has no recovered scene geometry for
the registered entries. It does **not** prove an original startup crash, and this
static trace cannot establish whether the shipped game ever tries to enter them.
## Reproducible checks
Run from `GamePort`:
```sh
python3 tools/binary/level_resource_evidence.py
```
The read-only script passes **13 decisive instruction byte assertions**, resolves
both class vtables, verifies the archive directory/names, parses both GAMs, reports
their SHA-256 hashes, confirms their identical bodies and checks archive presence
case-insensitively. It reports normal-gameplay reachability as unverified.
Confidence: high for supplied-file presence, original loader mapping and null-map
enumeration handling; unverified for gameplay reachability, intended stub status,
and original runtime outcome.