Implement source-backed Scooter vehicle in tutorial and outside

This commit is contained in:
UnixNight committed 2026-11-04 18:06:09 -05:00
1 parent 8df5e81070
commit 62c07a3d59
44 files changed
+3135 -174

No files matched your search

+156 -53
View File
@@ -1,100 +1,203 @@
#!/usr/bin/env python3
"""Export original Scooter resource data; do not assign attachments or playback.
"""Export exact Scooter OMT body/wheel and Jimmy rider resources.
The two Scooter ASE morphs have 195 indexed positions, whereas scooter.omt's
body has 98. Keep these samples unbound rather than inventing UVs or a base.
Mesh pivots, vertices, UVs, materials, texture pixels and morph samples are
unchanged. Runtime owns source vehicle/wheel transforms and action selection.
"""
from __future__ import annotations
import argparse
from collections import Counter
from dataclasses import asdict
import hashlib
import json
from pathlib import Path
from ase import export_ase, read_ase
from entities import resolve_asset
from models import export_omt_model
from omt import Database, FormatError, read_shape
from gam import parse
from omt import Database, FormatError, read_canvas, read_material, read_shape, write_png
from png import read_png
SOURCES = {
'Neutron.exe': 'f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8',
'omt/scooter.omt': '8d4ffdafee5fd819c5220ee4f608c901a5988fe6b8b13316e15618f5eec75e81',
'ASE/jimstop.ASE': 'b294d090ac5c4ec449d845db6d837f2cbedf5f7b812f5b6ed2bb70f85246f1d0',
'ASE/jimscooter.ASE': 'b27c8cb80811eb70e391fc061dab99c7d5f0b4d884c109b34c673a1815508299',
'ASE/jimscooterstop.ASE': 'edcdcc879a28757994525f815c88cd6dd46dc788b69ba2f902323d6de48cb873',
'ASE/jimstop.ASE': 'b294d090ac5c4ec449d845db6d837f2cbedf5f7b812f5b6ed2bb70f85246f1d0',
'ASE/godscooter.ASE': 'c18f1414ec2b397e0c8f8320f63830ab88630ea05a354bb99af34ce7fea79bd1',
'ASE/godscooter2.ASE': 'fcf9ca5e8298efa7b4d551d9d09878c04f1f2647b6a30edfa2297617a7d63189',
'png/jimycarl.png': '55ed165aaffe177cb62558a08d13fc3b2210da6e353065b108849d46df9dacb6',
'gam/VR05.gam': 'f8a14585116bbf0f339b22f634a3fa66b5e7c967bdd19a21e98a18aea2c73a02',
'gam/level1.gam': '40b809d007671e082c07c2766e487f30115a85ef3a067d5c15ff374b32cdb3f2',
}
CLIPS = ('jimscooter', 'jimscooterstop')
JIMMY_RGBA_SHA256 = '5e54ccb99e9e060843cd7f80fd93ff8bf47f8779666e41d4240398354a278a3f'
CANVASES = ((0, 'scooterwheel2', 22568, 3966, 32, 32,
'92dfef71def8079db70ba4eaa47e973d45a0b3987418e87dbf65cc3cf0bf823b'),
(1, 'goddard128', 26534, 65770, 128, 128,
'b22651171a7b9f2c99831a1ff4fd8d01d11ccabfc276d71dd91bacd710cd1cba'))
SHAPES = ((0, 'goddard01', 'body', 104, 19342, 98, 176),
(1, 'wheel', 'wheel', 92304, 5814, 32, 56))
# Mapped source spans: Init binds database0, Jimmy aliases, Goddard alias,
# wheel's inherited visual binder. Values are guarded below before output.
BINDINGS = (
(0x4214f0, 0x421515, 'body database entry0'),
(0x422c58, 0x422c80, 'Jimmy HISCOOT/HISCOOTSTOP'),
(0x41cdf0, 0x41ce04, 'Goddard HISCOOT'),
(0x468270, 0x46829a, 'wheel database visual binder'),
(0x477550, 0x4775e2, 'MakeShapeUnLit material consumer'),
)
def digest(data: bytes) -> str:
return hashlib.sha256(data).hexdigest()
def _json(path: Path, value):
path.write_text(json.dumps(value, separators=(',', ':'), allow_nan=False)+'\n', encoding='utf-8')
def _shape_scene(shape: dict, entry, materials: list, textures: list) -> dict:
"""Same source corner/triangle-fan expansion as omt.export_scene, one shape."""
scene = dict(source='scooter.omt', sha256=SOURCES['omt/scooter.omt'],
coordinates='Original OMT coordinates and pivot, unchanged', vertices=[], uvs=[], normals=[],
indices=[], meshes=[], materials=materials, textures=textures, collisionPolygons=[], warnings=[])
names = {m['id']: m['name'] for m in materials}
for polygon_index, poly in enumerate(shape['polygons']):
first = len(scene['vertices']); first_index = len(scene['indices'])
link = poly['material']; material = link['id'] if link else -1
for corner in poly['corners']:
scene['vertices'].append(shape['vertices'][corner['vertex']])
scene['uvs'].append(corner['uv'])
normal = corner['normal']
scene['normals'].append(shape['normals'][normal] if normal < len(shape['normals']) else poly['normal'])
for i in range(1, len(poly['corners'])-1):
scene['indices'].extend((first, first+i, first+i+1))
scene['collisionPolygons'].append(dict(shapeId=entry.id, polygonIndex=polygon_index,
normal=poly['normal'], materialName=names.get(material), materialId=material if link else None))
if scene['meshes'] and scene['meshes'][-1]['material'] == material:
scene['meshes'][-1]['indexCount'] += len(scene['indices'])-first_index
else:
scene['meshes'].append(dict(name=entry.name, shapeId=entry.id,
firstIndex=first_index, indexCount=len(scene['indices'])-first_index, material=material))
if len(poly['corners']) != 3:
raise FormatError('Scooter source topology unexpectedly needs fan triangulation')
return scene
def export_scooter(original: Path, output: Path) -> dict:
original, output = original.resolve(), output.resolve()
if output.is_relative_to(original) or original.is_relative_to(output):
raise ValueError('Output must be separate from the original installation')
# Existing descendants are checked before any helper writes into them.
if output.exists() and any(p.is_symlink() for p in output.rglob('*')):
raise ValueError('Generated Scooter paths must not contain symlinks')
paths = {name: resolve_asset(original, name) for name in SOURCES}
for name, path in paths.items():
if hashlib.sha256(path.read_bytes()).hexdigest() != SOURCES[name]:
if digest(path.read_bytes()) != SOURCES[name]:
raise FormatError(f'Unexpected original Scooter source identity: {name}')
clips = {name: read_ase(paths[f'ASE/{name}.ASE']) for name in (*CLIPS, 'jimstop')}
base = clips['jimstop']['objects'][0]['samples'][0]
if len(base['vertices']) != 426 or len(base['faces']) != 814 or not base['textureFaces']:
raise FormatError('Jimmy source base lacks exact compatible textured topology')
for stem in CLIPS:
clip = clips[stem]
if len(clip['objects']) != 1:
raise FormatError('Unexpected Scooter rider object count')
samples = clip['objects'][0]['samples']
if tuple(s['time'] for s in samples) != (0, 480) or any(
(len(s['vertices']), len(s['faces']), len(s['uvs']), len(s['textureFaces'])) != (426, 814, 0, 0) for s in samples):
raise FormatError('Unexpected Scooter rider source samples/topology')
jimmy = read_png(paths['png/jimycarl.png'])
if (jimmy['width'], jimmy['height'], digest(jimmy['rgba'])) != (256, 256, JIMMY_RGBA_SHA256):
raise FormatError('Unexpected Jimmy atlas pixels')
database = Database(paths['omt/scooter.omt'])
shapes = {}
for identity, expected in ((0, ('goddard01', 98, 176)), (1, ('wheel', 32, 56))):
entry = next(e for e in database.entries if e.type == '3DSh' and e.id == identity)
shape = read_shape(database.payload(entry))
if (entry.name, len(shape['vertices']), len(shape['polygons'])) != expected:
raise FormatError('Unexpected original Scooter shape metadata')
shapes[identity] = shape
animations = {name: read_ase(path) for name, path in paths.items() if name.startswith('ASE/')}
for name, animation in animations.items():
expected_count = 195 if 'godscooter' in name else 426
if len(animation['objects']) != 1 or len(animation['objects'][0]['samples']) != 2:
raise FormatError('Unexpected original Scooter animation objects/samples')
if any(len(s['vertices']) != expected_count for s in animation['objects'][0]['samples']):
raise FormatError('Unexpected original Scooter morph vertex count')
texture_path = resolve_asset(original, 'png/jimycarl.png')
texture = read_png(texture_path)
rgba = texture.pop('rgba')
texture.update(source=texture_path.name, sourceSha256=hashlib.sha256(texture_path.read_bytes()).hexdigest(),
rgbaSha256=hashlib.sha256(rgba).hexdigest(), path='../jimycarl.rgba')
manifest = dict(schema=1, sources=SOURCES.copy(), shapes=[], animations=[], unboundMorphs=[],
bindingPolicy='Resource-only export; caller owns original attachment, transforms and timing')
shapes, textures, materials, pixels = {}, [], [], {}
for entry in database.entries:
payload = database.payload(entry)
if entry.type == '3DSh':
shapes[entry.id] = (entry, read_shape(payload))
elif entry.type == '3DMa':
materials.append(dict(id=entry.id, name=entry.name, **read_material(payload)))
if set(shapes) != {0, 1} or len(materials) != 2:
raise FormatError('Unexpected Scooter shape/material count')
for id_, name, source_offset, source_bytes, width, height, rgba_sha in CANVASES:
entries = [e for e in database.entries if e.type == 'Canv' and e.id == id_]
if len(entries) != 1:
raise FormatError('Unexpected Scooter texture identity')
entry = entries[0]; canvas = read_canvas(database.payload(entry))
if (entry.name, entry.offset, entry.size, canvas['width'], canvas['height'], digest(canvas['rgba'])) != (
name, source_offset, source_bytes, width, height, rgba_sha):
raise FormatError('Unexpected Scooter canvas metadata/pixels')
pixels[id_] = canvas['rgba']
textures.append(dict(id=id_, name=name, path=f'../canvas_{id_}.rgba', png=f'../canvas_{id_}.png',
width=width, height=height, sourceOffset=source_offset, sourceBytes=source_bytes,
sourceSha256=digest(database.payload(entry)), rgbaSha256=rgba_sha))
if {m['id']: m['texture']['id'] for m in materials} != {0: 1, 1: 0}:
raise FormatError('Scooter material-to-canvas links changed')
scenes, shape_meta = {}, []
for id_, name, folder, offset, size, vertices, polygons in SHAPES:
entry, shape = shapes[id_]
if (entry.name, entry.offset, entry.size, len(shape['vertices']), len(shape['polygons'])) != (
name, offset, size, vertices, polygons):
raise FormatError('Unexpected Scooter source shape metadata')
counts = Counter(str(p['material']['id']) if p['material'] else 'null' for p in shape['polygons'])
if counts != ({'0': 176} if id_ == 0 else {'1': 28, 'null': 28}):
raise FormatError('Scooter source material assignment changed')
scenes[folder] = _shape_scene(shape, entry, materials, textures)
shape_meta.append(dict(shapeId=id_, name=name, path=f'{folder}/scene.json', sourceOffset=offset,
sourceBytes=size, sourceSha256=digest(database.payload(entry)), indexedVertices=vertices,
polygons=polygons, materialPolygons=dict(sorted(counts.items())),
storedSphere=dict(center=list(shape['bounds'][:3]), radius=shape['bounds'][3],
sourceCenterOffset=offset+8, sourceRadiusOffset=offset+20),
bounds=[[min(v[i] for v in shape['vertices']) for i in range(3)],
[max(v[i] for v in shape['vertices']) for i in range(3)]]))
levels = []
for name in ('gam/VR05.gam', 'gam/level1.gam'):
level = parse(paths[name].read_bytes())
levels.append(dict(source=paths[name].name, sha256=SOURCES[name],
entities=[dict(ordinal=i, **asdict(e)) for i, e in enumerate(level.entities)]))
# Import the established PE reader only after resource validation; no target execution.
import sys
sys.path.insert(0, str(Path(__file__).resolve().parents[1]/'binary'))
from pe_inspect import PE
from checkpoint_script_state import read_va
pe = PE(paths['Neutron.exe'])
spans = [dict(va=hex(start), fileOffset=hex(pe.offset(start-pe.base)), length=end-start,
purpose=purpose, sha256=digest(read_va(pe, start, end-start))) for start, end, purpose in BINDINGS]
manifest = dict(schema=1, sources=SOURCES.copy(), bodyMesh='body/scene.json', wheelMesh='wheel/scene.json',
scootAnimation='jimscooter/animation.json', stopAnimation='jimscooterstop/animation.json',
shapes=shape_meta, textures=textures, animations=[], levels=levels,
bindings=dict(bodyDatabaseShape=0, wheelDatabaseShape=1, scootAlias='HISCOOT', stopAlias='HISCOOTSTOP',
scootAction='SCOOT', stopAction='SCOOTSTOP', bodyUnlit=True, sourceSpans=spans),
goddardTransformation=dict(source='godscooter.ASE', alias='HISCOOT', indexedVertices=195, polygons=370,
sourceTimes=[0, 161], alternateSource='godscooter2.ASE',
status='Source binding/inventory only; no compatible textured195-vertex base supplied; not active vehicle body'),
bindingPolicy='Exact resources/source pivots. Runtime owns parent/child transforms, wheel spin/support, mounted root, action timing and lifecycle.')
output.mkdir(parents=True, exist_ok=True)
for identity in shapes:
folder = f'shape_{identity}'
details = export_omt_model(database, identity, output/folder)
manifest['shapes'].append(dict(id=identity, path=folder+'/scene.json', **details))
(output/'jimycarl.rgba').write_bytes(rgba)
for stem in ('jimscooter', 'jimscooterstop'):
(output/'jimycarl.rgba').write_bytes(jimmy['rgba'])
for id_, rgba in pixels.items():
(output/f'canvas_{id_}.rgba').write_bytes(rgba)
entry = next(e for e in textures if e['id'] == id_)
write_png(output/f'canvas_{id_}.png', entry['width'], entry['height'], rgba)
for folder, scene in scenes.items():
(output/folder).mkdir(parents=True, exist_ok=True)
_json(output/folder/'scene.json', scene)
for stem in CLIPS:
animation = export_ase(paths[f'ASE/{stem}.ASE'], output/stem, paths['ASE/jimstop.ASE'])
animation['texture'] = texture
animation['texture'] = dict(path='../jimycarl.rgba', width=256, height=256,
source=paths['png/jimycarl.png'].name, sourceSha256=SOURCES['png/jimycarl.png'], rgbaSha256=JIMMY_RGBA_SHA256)
_json(output/stem/'animation.json', animation)
manifest['animations'].append(dict(source=stem+'.ASE', path=stem+'/animation.json'))
for stem in ('godscooter', 'godscooter2'):
animation = animations[f'ASE/{stem}.ASE']
filename = stem+'-unbound.json'
_json(output/filename, animation)
manifest['unboundMorphs'].append(dict(source=stem+'.ASE', path=filename,
vertices=195, sourceTimes=[s['time'] for s in animation['objects'][0]['samples']],
reason='No matching textured base recovered; OMT body 98 and existing Goddard base 222 differ'))
manifest['animations'].append(dict(source=paths[f'ASE/{stem}.ASE'].name, path=f'{stem}/animation.json',
indexedVertices=426, polygons=814, sourceTimes=[0, 480]))
_json(output/'scooter.json', manifest)
return manifest
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument('original', type=Path)
parser.add_argument('--output', type=Path, required=True)
args = parser.parse_args()
if __name__ == '__main__':
cli = argparse.ArgumentParser(description=__doc__)
cli.add_argument('original', type=Path)
cli.add_argument('--output', type=Path, required=True)
args = cli.parse_args()
export_scooter(args.original, args.output)
print(f'Original Scooter resources exported: {args.output}/scooter.json')
if __name__ == '__main__':
main()