Files
Neutron/docs/analysis/assets.md
T

145 lines
8.0 KiB
Markdown

# Asset recovery evidence
Verified against local originals on 2026-10-23. No original files were modified.
`Original/` is outside the modern local Git repository. Analysis/extraction uses
Python standard library only; nothing is uploaded.
## Verified corpus
`python3 tools/extractors/audit.py ../Original --report artifacts/extracted/audit.json`
successfully parsed all 100 `.omt` databases, 7,027 resource entries, with no
conversion failures:
| Resource | Count | Verification |
|---|---:|---|
| `3DSh` | 2,155 | Every shape v2 consumed exactly; positions finite; corner indices bounded |
| `3DMa` | 2,183 | Every material v1 consumed exactly; original texture links recovered |
| `Canv` | 1,614 | All RLE decoded to exact row lengths and all resource bytes consumed |
| `Wave` | 875 | RIFF/WAVE header and bounded RIFF lengths present |
| `mCTy` | 100 | Indexed metadata preserved; internal interpretation outstanding |
| `0HDR` | 100 | Indexed allocation metadata preserved; not runtime geometry |
Texture counts are 866 RGB555, 736 32-bit RGB, and 12 indexed 8-bit.
All 875 sound resources contain intact RIFF data: 874 PCM and one format-tag 85
(MP3 in WAVE). PCM rates/channels/sample widths vary; do not assume one audio
format. Loop and cue behavior in the surrounding OMT metadata remains unverified.
## Recovered scene outputs
Run from `GamePort/`:
```sh
python3 tools/extractors/prepare.py
python3 -m unittest discover -s tests -p test_extractors.py -v
```
Preparation produces ignored local files below `artifacts/extracted/`:
- `level1b/scene.json`: 8,607 expanded vertices, 2,869 triangles, 33 textures.
- `VR01/scene.json`: 240 expanded vertices, 80 triangles, 7 textures.
- Texture `.rgba` files plus PNG previews, preserving material ID links.
- `sounds/`, `musicjimmyshouse/`, `musicneighborhood/`: exact embedded WAV bytes.
- `animations/{jimstop,jimrun,jimjump,jimscratch}/`: original morph samples and manifests.
- `animations/jimycarl.rgba`: original normal Jimmy atlas, 256 x 256 indexed PNG decoded to RGBA.
Individual archive recovery:
```sh
python3 tools/extractors/omt.py ../Original/omt/level1b.omt --scene --output artifacts/extracted/level1b
python3 tools/extractors/omt.py ../Original/omt/sounds.omt --output artifacts/extracted/sounds --raw
python3 tools/extractors/ase.py ../Original/ASE/jimrun.ASE --base ../Original/ASE/jimstop.ase --output artifacts/extracted/animations/jimrun
```
The static OMT scene is geometry/material recovery, not a complete level state.
GAM entity transforms, object visibility, character meshes, lighting, camera,
gameplay collision masks, triggers and task progression must be applied separately.
All source scene polygons examined in these first scene exports are triangles;
the exporter supports polygon fans and warns for any larger polygons whose
concavity has not been validated.
## Executable evidence used
Preferred virtual addresses in the supplied `OMT2.dll` (image base `0x10000000`):
| Routine | Address | Supporting behavior |
|---|---|---|
| `OMedia3DShape::read_class` | `0x10007b60` | `3DSP` signature, version, vectors and polygon arrays |
| `OMedia3DPolygon::read_class` | `0x10003e20` | Version-dependent corners, UVs, normal indices, material links |
| `OMedia3DMaterial::read_class` | `0x10001490` | Compact v1 styles, color triplets and texture stream link |
| `OMediaCanvas::read_class` | `0x10025b80` | Dispatches OmCv through canvas converter |
| `OMediaOMTConverter::convert` | `0x10027df0` | OmGW dimensions, packing/key/palette header and row RLE |
| RLE unpack helper | `0x1006c230` | Byte/word/dword PackBits variants; LE signed controls |
| `OMediaOMTConverter::create_canvas` | `0x10028620` | Pixel RGB and alpha/color-key conversion |
| `OMediaOMTConverter::read_palette` | `0x10027b40` | OmPa/OPa2 palette with 4,096-byte accelerator |
| `OMediaDBObjectStreamLink::read_class` | `0x10030260` | BE16 present + fourcc + BE32 ID |
| Bool stream operator | `0x10073a80` | Booleans occupy two bytes on disk |
| `OMedia3DMorphAnim::render_draw_shape` | `0x10002df0` | Retains base shape while overriding per-index vectors |
RGB555 channels are expanded by `<< 3`, **not** normalized to 255. Instructions
at `0x10028815` onward verify this; maximum channels therefore remain 248.
The 32-bit path at `0x100288ab` selects RGB bits 16/8/0 and derives alpha from
color-key equality. Stored high-byte alpha is not copied by that converter.
Raw byte-exact resources remain available using `--raw`.
## ASE geometry and animation
The supplied ASE assets include standard ASCII mesh vertex/face tables, per-corner
texture indices, scene timing and vertex morph samples. `jimstop.ase` differs in
filename case from most other ASE files. Resolve filenames case-insensitively.
Two matching assets provide independent coordinate evidence, covered by tests:
- All eight `gate1.ASE` vertices and all eight `yokianpart.ASE` vertices match the
corresponding `objects.omt` resources after `(x,y,z) -> (x,z,y)`.
- Face index order remains identical; the reflection is not accompanied by an
index swap in the stored original.
- Every corner UV matches `(u,v) -> (u,-v)`.
- No additional `NODE_TM` is applied to these already exported vertex positions.
Source ASE normal fields are not assumed authoritative; exported preview normals
currently use flat triangle normals. Original smoothing must still be replicated.
Jimmy uses 426 source vertices and 814 faces. `jimstop.ase` has two samples,
`jimrun.ASE` five, and `jimjump.ASE` three, all with file scene speed 10 FPS and
480 ticks/frame. These establish asset sample timing, not state-specific playback
speed or loop policy in gameplay code.
The two jimstop vertex samples are identical: there is no idle motion to play.
The scratch file has three distinct samples at ticks0/960/1920. Preview clip keys
expose source motion explicitly instead of labeling the default idle as animated.
The EXE stores `jimyshock.png` at file offset `0xef0c8`, followed by `jimstop.ase`
at `0xef0d8`. **Primary integration corrected an early inference from string
proximity:** InitObject at `0x422C96..0x422CB0` binds `jimycarl.png` (VA
`0x4EEAC4`) to texture slot 0 and `jimyshock.png` to slot 1. The latter is the
shock/skeleton effect, not normal appearance. Prepared animation textures and
runtime defaults now use `jimycarl.png`; both have been visually inspected.
The ASE bitmap path `D:\\Jimmy\\jimmy\\jimmylast.bmp` is not a runtime dependency.
Run/jump filenames follow in the same initialization string cluster.
### Morph topology retention
Run/jump/scratch ASE files omit UV tables. Zero UVs would show a single texel and
are rejected by the animation exporter. The original morph renderer validates
the sample vector count against the base shape and interpolates per-index vectors
(`0x10002ed3`, `0x10002eee`, `0x10002f9a..0x10002fd9`), then submits the base
shape plus override vectors (`0x10003396..0x100033ab`). Its topology/UV remain
on the base shape. Therefore the prepared Jimmy animations explicitly use the
textured `jimstop.ase` base and original sample vertex indices. This also matters
because 23 face records in run/jump differ from the later dated stop asset even
though all sample vertex counts remain 426. `morphBase` provenance in each
animation manifest records the source and hash of the retained shape.
## Limits and next work
- Static asset decoding is verified, but visual fidelity needs comparison with an
isolated original game run.
- Legacy material booleans and polygon flags remain numerically preserved rather
than assigned unproven lighting/culling/collision meanings.
- Color triplet roles are conventional labels inferred from the legacy material
layout; exact renderer use should be cross-checked against recovered DX states.
- Animation exporter supports all supplied mesh records, but character bundles
prepared so far cover Jimmy stop/run/jump only. Original smooth normal and
state-driven playback behavior remain incomplete.
- Native runtime renderer/audio integration and package validation belong to the
primary/infrastructure work; successful extraction is not runtime verification.