Entry 21
Ports on native types; the original's layout only in codecs
Filescrates/hwtr-game/src/car/mod.rslayout.rscrates/hwtr-game/src/body.rsram.rscrates/hwtr-hle/src/port.rs
Decision. Ported code is idiomatic Rust on native types. The original's
memory layout appears only in layout modules, whose read/write codecs
convert between RAM and those types for the tests and the shadow checks.
Before. The first ports (18-20) worked on the original's RAM
through offsets (ram.i32(car + MASS)). That made a ported function a
drop-in for the original and easy to diff, but it kept the PS1 layout inside
the port's logic, read like C, and would have to be unpicked later anyway.
Now. Car (with Wheel, Axle, Engine), Tuning and Body are
plain structs. The physics is methods on them (place_wheels, drivetrain,
aero, physics, spin_wheels, Body::integrate), and per-axle values
(grip, damping, downforce) are an Axle each rather than paired fields.
Checking is unchanged in strength. A test or shadow check reads the struct
out of a copy of RAM, runs the method, writes it back, and compares all of
RAM with what the original left. All tests pass, and the shadow run still
matches 9151 of 9151 calls over 2400 frames. hwtr-hle's port table pairs
each original address with an adapter that does that conversion.
Rules this sets for later ports:
- Byte flags whose values are not known to be only 0 and 1 stay as the
stored byte, with methods for their meaning (
Wheel::on_ground), so the codec round-trips them exactly. - Fields not yet understood are named by offset (
unknown_6b4) rather than guessed. - Fixed-point arithmetic stays exact (
fx, wrapping operations). Idiomatic means the structure: types, methods, iterators,Option. It does not mean floating point. - Bytes the original fills from uninitialised stack (the heading padding) are not modelled. The checks skip them.