skate-3-rust-engine/docs/GRIND_INTEGRATION.md

# Grinding integration

## Current milestone: authored geometry, not playable grinding

The test course now owns seven named paths in `grind_world.rs`: two flat bars,
both half-pipe lips, and the three exposed platform edges. The downhill entrance
is not an edge, and triangle diagonals/transition tessellation are not splines.
Bar top centres and coping paths share the collision/render dimensions.
Climbing geometry from the other task is preserved.

`GrindGeometry` retains a relocatable Pegasus tSplineData blob. Its layout matches
the existing recomp's `owned/world/src/grind_spline.cpp`: 16-byte header,
32-byte rail records, 144-byte segments, signature `2C7017070007004A`, straight
segment delta at +0, origin at +48, inverse length at +64, bounds +80/+96,
length +112, cumulative length +116, and owner/previous/next +120/+124/+128.
IDs are stable host-authored integers, not guessed retail asset IDs.

This registry is not yet connected to contact acquisition or state selection.
Startup explicitly logs `native_acquisition=not_connected`. The game therefore
still treats the bars as ordinary collision geometry. Do not call this playable
grinding or replace the existing empty-edge providers with a proximity snap.

## Native integration audit

Evidence image: TU3 `default_82000000_011B0000.bin`, base `82000000`, SHA-256
`f4aa113eb541bfba03dbc108cf5ab43f58c965b20fa3b82f9c40938a0ad841c4`.
Community symbols plus generated PPC instruction comments were consulted.
The disposable IDA database's decompiler misdecodes some VMX128 operations;
its truncated pseudocode is not sufficient to port the nonempty branches.

- `82D8A828` GrindManager input update: constructs an AABB around processed
  position112 with half-extent1.2 (`821659F4`), unless byte2476 bit0 disables it.
- `82C1EAD8`: static asset/segment bounds collection, source order, maximum40;
  entries are48 bytes with endpoints and retained owner/flags. The final16
  bytes must not be invented as a surface normal.
- `82D875A8`: candidate acquisition/scoring. Dispatches truck/deck contact
  queries (`82C1FDC0`, `82C20130`, `82C1FB98`, `82C1F968`) before scoring. For
  example `82D89150` handles a two-truck candidate; it is not a nearest-rail
  angle classifier. Selection output has candidate byte384 in a416-byte record.
- `82C1E2C8` is now ported in core `physics/grind_contact.rs`: the exact
  segment/triangle leaf used by those truck/deck queries. It retains the
  zero-denominator rejection and closed0..1 bounds, unlike wheel probes with
  their endpoint tolerance. It does not itself accept a grind.
- `82D8AB08`: post-input manager publication precedes state selection.
- Native selector maps actual candidate grind type0..5 to states401,400,402,
  403,404,405. `player_state/selection.rs` currently publishes no candidate.
- Boardslide Enter `82D41100` calls shared grind entry `82D3F318`, then clears
  bytes240/241. Shared entry resets board controller settings, skeleton state
  and the grind manager; merely allowing state400 in transition.rs is unsafe.
- The active force/contact owner, output conditioner and graph attributes
  still need wiring. `player_state/publication.rs` currently uses default grind
  output; camera output has the same inactive assumption.
- Air acquisition also needs the nonempty trajectory path: `82D69F80`,
  `82D6A168`, `82D6A398`, `82D6A840` and GrindAirAdjust `82D712E0` onward.
  The clone's GRIND_CONTACT_SPEC explicitly leaves parts of this arbitration
  unresolved, so it cannot serve as a complete implementation.

Next implementation boundary: native endpoint/contact queries and candidate
record/scorer, then lifecycle/constraint/output integration as one coherent
vertical slice. Do not enable selector candidates before those owners exist.

Validation: build only; no gameplay or automated tests, per user instruction.

## 2026-09-07 collision and contact follow-up

The rail boxes were emitted with only ONE_SIDED. Native contact fixup82AD3130
rejects an edge-region contact when its convex bit is absent. Authored rail
faces now set the two perimeter-edge bits on each triangle and leave the
coplanar diagonal non-convex (0x60 /0xC0 for the existing triangle winding).
This change applies to rail/coping/support boxes only. Gameplay confirmation
is outstanding; a build does not establish that this explains every missed hit.

Core truck_contacts ports82C1FDC0's two local-board probe rectangles, using
TruckToWheel and DeckCenterToTruck, the -.02 start offset and -.20 depth,
first-triangle priority, strict squared-distance comparison and first-entry
tie retention. It remains a contact query, not an engagement decision.

Checked the task Research readable game recreation and its referenced
Skate3CustomEngineLayer/src/skate3_native_grind.cpp. That integration registers
splines in the original guest GrindData owner; it does not contain replacement
grind forces. Expand Skate 3 replay toolkit likewise supplies research and
capture infrastructure rather than a standalone grind controller.

The remaining native state/force and graph-attribute contracts are unresolved.
Do not advertise this build as grind-ready. Build log:
logs/grind-collision-build.log (successful,35 warnings); no tests executed.

## Additional static recovery

The reference process was closed at the user's request. Continue using static
analysis; do not relaunch it. IDA database
`research/reverse-engineering/XexDump/Skate3TU3_dump.i64` was copied into local
ignored `logs/grind-research-copy.i64`. The original was not modified. The
database has sparse function boundaries; bounded definitions are needed even
where the community symbol map supplies a name. VMX128 decompilation remains
unreliable; cross-check vector operations against generated instruction text.

New core routines (not yet called by the game's active state):

- `fifty_fifty_candidate`:82D89150 same-primitive two-truck branch. Rejects
  balance magnitude >=.9 and local-up contact depth >=.13. Adjacent-segment
  arbitration is deliberately outside this routine.
- `upright_normal`:82D370F8; the vertical-line fallback is the actual constant
  X axis at82139A10. `within_approach_angle`:82D88518's plane projection and
  strict cosine comparison.
- `grind_forces::lateral_pin`:82D3FA18. Native50-50 caller82D41D70 supplies
  strength800, forward offset0, up offset.07, damping scalar.133.
- `grind_forces::friction`:82D3FD88 after material selection. Receives actual
  support, material and engagement inputs; does not invent them. Native50-50
  caller supplies strength50 for engagement0,40 otherwise.
- `animation::grind_control::Fade`:82BB0D40; Begin82BB0A30 evaluates attribute
  bounds. First Update only clears the Begin latch. Later updates apply the
  native target, response, acceleration and step bounds.
- `grind_control::crouch`:82BB10F8. Begin82BB1078 seeds from physical crouching
  output. Runtime collection names for owner312 offsets1640..1652 and owner340
  offsets1760/1792/1816 still need resolving before host integration.

Vtable823283D0 identifies50-50: Enter82D3F318, Exit82D3F430,
PreUpdate82D3F4E8, Update82D41D70, Fill82D41FF8. Its angular target path
82D41E38 ->82D40890 uses existing matrix interpolation82BD3150 with weight.1,
then hook target82BD4318 and angular-only hook drive82C05658. It does not
teleport the deck to a spline. This should use the existing core interpolation
and hook implementation when connected.

The playable-state integration is still incomplete. In particular no selector
candidate is published, the active state adapter is absent, and MotionHost
still rejects the unbound stock grind behaviors. These ports alone are not a
grind-ready game build.