- Shell 100%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
Mechanix RE
9caf3a308e
The behavioural specification recovered in passes 19-19w had never left staging.
START-HERE.md, added in the previous commit, referenced SPEC/VEHICLE-MODEL.md
throughout -- a file this repository did not contain. That is fixed here.
SPEC/VEHICLE-MODEL.md 20 sections: controls, performance, longitudinal,
steering, body dynamics, collision, respawn, path
nodes, race state, intra-frame ordering, how the AI
drives, and what is NOT covered
SPEC/ENTITY-OBJECT-MODEL.md field layout, with the measured meanings and an
explicit statement of where the accessor-derived
method stops seeing
SPEC/CONTROLS.md the key array as the authoritative input state
Two things were changed on the way across the clean-room wall:
- the one inline disassembly instruction is paraphrased. Disassembly does not
cross, and a single instruction is not an exception.
- a note explains that "pass N", tools/ and FINDINGS.md cite the analysis-side
record, which is not in this repository and is not needed to use the document.
Verified before commit: no disassembly anywhere in SPEC/, ORACLE/ or
START-HERE.md; all 19 code blocks are pseudocode; every section reference and
every file path cited by START-HERE resolves.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
|
||
| DATA | ||
| ORACLE | ||
| PROCESS | ||
| SPEC | ||
| tools | ||
| .gitignore | ||
| CONTRIBUTING.md | ||
| README.md | ||
| START-HERE.md | ||
Hot Wheels Mechanix — reimplementation specification
A behavioural and structural specification of Hot Wheels Mechanix (AWE Games, 2001), recovered from the shipped binaries and data files, published so it can be reimplemented cleanly.
This repository contains no game code and no game assets. It contains measurements, formats, and tables — see the clean-room note for why that boundary exists and what it means for contributors.
Start here
| If you want to… | Read |
|---|---|
| Understand what's known and how solid it is | SPEC/README.md |
| See a specific class | SPEC/classes/ — 47 sheets |
| Load the game's data files | SPEC/formats/ |
| Place level entities | SPEC/levels/ |
| Know which assets belong to which class | SPEC/assets/ |
| Consume the data programmatically | DATA/ — CSV/TSV |
| Know how any of this was established | PROCESS/FINDINGS.md |
| Understand validation | ORACLE/README.md |
| Compare against a real implementation | SPEC/IMPLEMENTATION-GAP.md |
What the engine is
Mechanix runs on Open Media Toolkit (OMT) by Yves Schmid / GarageCube — a cross-platform C++
2D/3D framework, released under LGPL as v2.5.0 in 2003. The game ships OMT2.dll, and that DLL
is byte-comparable across the AWE family: Mechanix, Jimmy Neutron: Boy Genius and JN vs JN each
export 1,358 functions across 110 OMedia* classes.
That matters more than anything else here: every class hierarchy in this spec terminates in
OMedia* classes whose real source is public. Those halves are cited, never guessed. Only the
game-specific classes above that boundary needed recovery.
Two binaries ship — MECHANIX.exe (Direct3D) and Mechanixsw.exe (software renderer). They share
~98.5 % identical code and import the same four DLLs; neither imports DirectDraw or Direct3D
directly. The renderer split lives entirely inside OMT2.dll, which the LGPL source documents.
Status, stated plainly
Structure and assets: complete and cross-checked.
- 47 classes with full inheritance DAG, object sizes, constructor addresses, vftables, and vtable slot counts split owned vs inherited
- 4,754 chunks indexed across all 36
.omtcontainers, matching independent prior measurements - 30 classes bound to their containers; all 19 vehicle→mesh bindings verified against shipped data
- 442 level entity markers positioned across all 7 levels (material-keyed)
Behaviour: not recovered. 588 methods are characterised by shape only — address, size, call count, FPU use, referenced constants. No method body is decompiled. Exactly one field is semantically resolved. Every sheet says so in its own Confidence block.
Nothing here is runtime-validated except two specific results, both marked as such.
The job is smaller than 47 classes suggests
24 of 47 classes override zero vtable slots. All 19 C3DCar subclasses are pure data variants
of a single base — they contain no behavioural code at all. Roughly ten classes carry behaviour,
and the densest single target is C3DCar slot 59 (~1,180 instructions, FPU-heavy) — the driving
routine.
Two traps to know about before you read the binary
Both will waste your time otherwise, and both are confirmed:
- The
.gamfilenames are dead references. The executables nameLevel1.gam…level7.gam, and no such file ships. They are never opened — verified by planting decoys in the working directory and watching a level load without touching one. They are leftovers from the shared AWE codebase, where Jimmy Neutron does use them.icons.omtis the same story. - There is no attract mode. The game does not self-start a demo. Two nine-minute idle runs never left the main menu.
Provenance
Every claim carries a tag: CONFIRMED (directly observed, with a citation you can check),
REPORTED (asserted by a prior source), INFERRED (reasoned, with what would falsify it), or
ASSUMED. Tags are never promoted. Where evidence is absent this says so, along with what was
searched.
PROCESS/FINDINGS.md is the full working log, including
the mistakes — several confident conclusions here were wrong and were
caught by experiment. They are documented rather than quietly corrected, because knowing which
kinds of reasoning failed is useful to anyone continuing the work.
Contributing
Read PROCESS/CLEAN-ROOM.md first — it is short, and it governs what may
be submitted here.
Corrections to measurements are especially welcome. If a number here disagrees with what you observe, that is a bug in the spec and worth an issue.