Files

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.