121 lines
6.1 KiB
Markdown
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.
|