6.1 KiB
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
prepare_models(original: Path, level_file: str, output: Path) -> dict
From GamePort/:
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
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.