Autopilot · write-up
Direct prediction use of C-owned tracks
Migration
ABI 20 adds fitted world velocity to XapTrack. The canonical update fits the
last eight retained samples in C with a simple two-pass least-squares calculation.
Fewer than three samples retain the instantaneous world velocity. The optional
XAP_TRACK_FIT_VELOCITY input flag makes this work independently selectable.
No additional Python-to-C calls or history input transfers are needed.
The existing _stable_world_velocity entry point now reuses that result for
native-backed objects. Its consumers include linear prediction, target leading,
pickup planning and projectile analysis. Exact direction-table projectile motion
still takes precedence over a fitted trend. Python tracking and the original
fitter remain available.
The Python compatibility object stores a derived velocity and a reference to the immutable history it describes. This does not copy history again. Replaced histories cannot reuse the result: identity is checked on lookup, and dataclass replacement does not carry the derived runtime attribute. Fits are attached only once enough samples exist. This preserves the reference's instantaneous fallback for young objects and synthetic/replaced diagnostic views.
The port deliberately uses ordinary double arithmetic; no fixed-point machinery or bit-identical float emulation is added. Geometry and gameplay comparisons remain the validation criterion. This migrates the first history consumer; it does not remove Python tactics, classification or raw game-field decoding yet.
Comparison and validation
compare_kernels.py --variants c-velocity-old,c-velocity-native compares the preceding native
tracker with fitting disabled against native fitting and direct reuse. Both use
the same tracker and raw-byte reuse. Native tracking tests cover irregular frame
intervals, world coordinates, replaced histories and exact directional overrides.
Results and default decision
Two sequential CPU-4-pinned Level 1 replay repeats over frames 2367–10059 measured
3.19926 ms per observation without native fits versus 3.21381 ms with them:
0.45% slower, with no demonstrated end-to-end benefit. The profile reduced
_stable_world_velocity cumulative time from 0.6691 to 0.3649 seconds, but attached
197,587 compatibility caches for only 72,208 estimator calls. The added work
elsewhere consumed that local saving.
The native fit therefore remains opt-in, not the default for the C backend.
The original experiment used c-velocity-old,c before that default decision;
repeat it now with c-velocity-old,c-velocity-native. The retained C implementation
is available for genuine fallback consumers during later migration.
Consumer instrumentation counted 40,596 shell estimator calls and 4,963 calls on objects with captured scripted motion. Exact shell/script paths already exist elsewhere, so many of these callers should consume those paths instead of a linear fitted estimate. Not every movement is a captured script: unknown routines, missing capture state and reactive motion still need explicit fallback handling. A fit is an approximation, not a replacement for known script execution.
All checked Level 1–5 replay verdicts match with fitting enabled. The final full suite passes 930 tests after the opt-in default change. Tests explicitly enable native fitting when verifying its result.
Artifacts under xenon_tools/run_logs/:
- tracked-velocity-timing-0908/comparison.json: two-repeat timing.
- tracked-velocity-profile-0908/comparison.json: separate profile.
- tracked-velocity-level{2,3,4,5}-0908/comparison.json: cross-level checks.
- tracked-velocity-consumers-0908.counts.json: classified estimator call counts.
- tracked-velocity-tests-0908.txt: full suite before the final default change.
- tracked-velocity-final-tests-0908.txt: final 930-test pass.
No Hatari/TCP integration or WASM profiling was performed. The next useful migration is exact trajectory consumption by targeting and related callers, with fitting limited to cases for which exact prediction is unavailable.