Files

121 lines
6.1 KiB
Markdown

# Source-backed static scene models
Implemented 2026-10-24 in `tools/extractors/models.py` and
`Application/StaticSceneVisuals.cs`. This adds the original model consumers for
OMT props, phone booths and explicit ASE/PNG entities. It does not establish
complete interaction, door collision, animation playback or visual fidelity.
## Evidence and prepared fixtures
LV1B has nine relevant model instances, sharing six source models:
| Source entities | Original model | Triangles per instance | Texture binding |
|---|---|---:|---|
| PHONE1 / PHONE2 | `phone.omt`, `3DSh:0` | 90 | Three original material/canvas links |
| bars | GAM `ASEFile=bars.ase` | 54 | GAM `PNGFile=chain.png` |
| Two `C3DBUTTON` records | GAM `Up.ase` / `Down.ase` | 16 each variant | GAM `UpDown.Png=switch.png` |
| dino | GAM `objects.omt`, `3DSh:27` | 256 | Original material27 -> canvas26 |
| plant1 / plant2 / plant3 | GAM `objects.omt`, `3DSh:28` | 168 | Original material28 -> canvas27 |
VR01 has two phone booths, using the same verified `phone.omt:3DSh:0` source
binding. Both booth instances remain separate even though their GAM tags match.
The phone class opens `phone.omt` at EXE `0x43579d` and selects shape0 at
`0x4357c9`. The similarly named `phone.ASE` and standalone `phone.png` are other
assets and are not substituted. Its three material links are `{0:Canv1,
1:Canv0,2:Canv2}`. The 90 triangles span **five** source material draw ranges,
with index counts `[120,6,12,6,126]`; retaining only a single final draw would omit
parts of the booth.
Button resource registrations are recovered at EXE `0x411695`, `0x4116c3`,
`0x411722`. InitObject at `0x411b93` selects literal `UP` (`0x4ed9bc`), so the
default static variant is source-backed. The consumer recognizes `UP` / `HIUP`
and `DOWN` / `HIDOWN`. It displays the first authored pose of the selected
variant; it does not imply that button morph transition timing is reconstructed.
Bars and other explicit ASEFile/PNGFile pairs retain the first authored sample
and the proven ASE-to-OMT axis/UV conversion. No additional node transform or
floor correction is introduced.
## Preparation interface
```python
prepare_models(original: Path, level_file: str, output: Path) -> dict
```
From `GamePort/`:
```sh
python3 tools/extractors/models.py --level level1b.gam --output artifacts/extracted/level1b/models
python3 tools/extractors/models.py --level VR01.gam --output artifacts/extracted/VR01/models
python3 -m unittest discover -s tests -p test_models.py -v
```
`models.json` schema1 contains:
- Source GAM path/hash and level code.
- `models`: unique keys, relative scene JSON paths, source hashes/resource
identities and geometry counts.
- `actors`: original ordinal/byte offset/tag/class, default variant, variant-to-
model-key references, and mapping evidence.
- `unresolved`: incomplete explicit mappings; no class default is invented.
Each OMT model exports only its selected `3DSh` and transitively referenced
`3DMa` / `Canv` resources. Source material/texture IDs remain local inside each
model scene file. No unrelated archive geometry is copied. Existing ASE and PNG
assets are decoded locally, without modifying originals.
The source corpus contains one Level3C button at GAM offset33909 whose explicit
`UpDown.Png` is `none`. It is recorded unresolved and omitted from model actors
until its actual constructor/fallback binding is recovered. LV1B/VR01 have no
unresolved entries in this subset. Other classes without explicit bindings are
outside this consumer and are not presumed invisible or complete.
## Runtime interface and invariants
```csharp
new StaticSceneVisuals(Mesh combined, SceneDirector director,
string assetsRoot, string preparedRoot);
Mesh Mesh { get; }
void Update(Mesh destination);
```
`preparedRoot` is the scene's `models` directory containing `models.json`.
All required geometry/texture bytes are prepared; no speculative runtime fallback
uses `assetsRoot`. Actor lookup uses original source GAM byte offsets rather than
tags, preserving duplicate tags. The integration can append later consumers and
pass the resulting combined mesh to `Update`.
All source model vertex/index/draw ranges are retained. Each instance/variant
gets distinct texture IDs starting at `int.MinValue+20000`; preexisting identity
collisions are rejected. The actual lab consumer adds19 original draw ranges
and15 texture identities. Every phone material draw follows actor visibility.
Button inactive variants keep allocated ranges but do not draw.
Director position/rotation updates transform original local vertices directly.
The current shared actor rotation convention is X, negative yaw Y, then Z,
followed by the director position. Exact general Euler composition still requires
original comparison; tests establish the implemented translation and yaw behavior.
No character grounding/floor correction is applied to these props. Bars movement
is visible only when a separate recovered gameplay consumer changes its actor
root; this visual consumer itself does not invent opening motion.
Null material handling matches the existing original DX rule: preserve geometry
but skip draws whose original material is null or unresolved. The original LV1B
invisible proxies reference absent material18; selective extraction preserves
those links and reports `nullMaterialIds` rather than fabricating a white material.
An explicit empty draw list stays empty on mesh integration.
## Verification
Eight Python test groups include a locally compiled .NET10 consumer harness.
They verify actual phone geometry and all five material ranges, explicit model
bindings, OMT subset export, duplicate tags, source hashes/output boundaries,
missing mapping reporting, distinct texture IDs, translation/yaw/no floor
correction, hide/show, independent button variants, retained combined buffers,
reserved-ID conflict rejection, and null-material geometry without invented draws.
The main C# project builds with zero warnings/errors after adding the consumer.
Prepared asset and managed harness checks are not GPU or original-runtime fidelity
verification. Primary integration must verify scene rendering, updating the final
combined buffers, source entity transitions, packaging, and native platform behavior.