Starter circuit specification — v0.4.0

One canonical course

The active prototype remains a single rectangular four-sector loop. This update does not invent a second layout or claim a new track selection UI.

World distances are Unreal centimetres. The drivable road centerlines are at Y = ±1800 on the east-west straights and X = ±2800 on the north-south straights. Road half-width is 800 cm. In order, checkpoints are east/south, east/north, west/north and west/south. Direction checks expect east, north, west and south travel respectively.

Source/Latebrake/Public/Track/CircuitLayout.h is the source of truth for those four gates, player/rival start positions and their recovery orientations. Both the Unreal game mode and the rival actor consume these common values. Player laps and recovery penalties have not been rebalanced.

Unreleased v0.5.2 ordered checkpoint plane validation

The previous sphere-overlap callback accepted the leading rim of a gate rather than crossing its center line, allowing premature sector credit. The runtime checkpoint actors now sample successive positions of the actual local player pawn and feed CircuitGateCrossing.h, which checks the canonical east, north, west, south directional normals.

A valid checkpoint requires: - The previous frame on the approach side of the gate plane and the current frame on the departure side, with >=150 cm/s forward velocity. - A maximum 1,200 cm total 3D movement between observations, without requiring either endpoint to be within the former 600 cm trigger sphere. This recognizes a legitimate fast/low-FPS sweep from outside that visual volume through the checkpoint plane. - An interpolated crossing point within 500 cm of the road centerline and within 380 cm vertically of the 38 cm gate-marker center. - The correct next checkpoint according to the existing RaceProgress rule, and a local player pawn rather than AI/rival actors.

The legacy 600 cm sphere is retained as an actor transform/marker root, but its gameplay overlap collision/handler is now disabled; it does not award an early sector. The per-frame test uses four cheap actor ticks instead of physics overlap notifications. Consecutive samples reset when the local player pawn changes or becomes unavailable.

This is source code with portable tests; there is no real UE 5.8 game playtest. The older rule also required both sample endpoints to lie within 600 cm of the plane; at low FPS, it could miss legitimate forward passes even if movement remained below the already allowed 1,200 cm displacement cap. The current code uses the entire bounded frame segment as a geometric sweep, interpolating its gate-plane intersection. The old sphere continues to display the gate but no longer controls timing eligibility.

The 1,200 cm displacement cap remains an intentional safeguard; a hitch that moves the car even farther may still miss the gate. Short and long explicit RecoverTo/restart movements are also rejected by CheckpointMotionTrace teleport generations, regardless of geometric appearance. Validate fast cornering, airborne vehicles, recover-to-track, restart and low-frame-rate phones before considering this qualified.

Unreleased v0.5.2 recovery/restart teleport fencing

Checking consecutive frame positions and a maximum movement size is not sufficient to distinguish a recovery from driving: an authorized RecoverTo can move the vehicle 200 cm across a checkpoint plane, well within the maximum 1,200 cm limit.

The player pawn now increments a 64-bit teleport revision on every RecoverTo(), including paid recovery and race restart. Each checkpoint actor retains its own CheckpointMotionTrace: - The first observation of a new pawn or teleport revision sets a fresh location baseline but cannot award a checkpoint. - Only movement between two frames of the same pawn and teleport revision can be passed to the ordered directional plane test. - Missing players and invalid/nonfinite positions discard the prior baseline. Racing on subsequent valid frames continues normally. - No new on-disk checkpoint state or extra physics/collision traces are required; this is event-local runtime bookkeeping.

The portable CheckpointMotionTrace tests simulate a short jump across each of the four gates and prove that no RaceProgress sector/lap is earned; actual physical crossings still complete the race. Installed UE 5.8 QA must check real teleports and tick order with physics, HUD sector timing, paid recovery, event replay and gamepad/Android input.

Visual course furnishings

TrackDecorations.h plans 28 white center dashes and 56 non-colliding decorative kerbs/curbs, alternating red and white, all on the existing asphalt. The runtime adds two primitive grandstands outside the drivable road and a visible overhead start/finish banner using only Unreal built-in cubes. Surface finish, materials, lighting, staging and camera angles remain engine-unverified.

The unreleased v0.5.1 source now uses a single scenery-holder actor with seven UInstancedStaticMeshComponent batches rather than 93 individual cosmetic actors. Batches cover 28 lane stripes, 28 red curbs, 28 white curbs, 2 grandstand bases, 4 light tiers, 2 dark tiers and 1 start/finish banner. All original scene positions, heights, scales and style assignments are generated by the portable deterministic DecorationBatchPlan.h. The nine physical ground/road/barrier blocks remain distinct, with unchanged physics and collision. Visual-only instances explicitly have collision, overlap events, navigation influence and cast shadows disabled.

The change reduces planned cosmetic actor/component overhead but does not establish a particular FPS improvement or draw-call count without a UE 5.8 Editor runtime profiling session. Stock Engine cube materials may not render the requested per-batch color parameter on every renderer; validate color contrast and readability on the actual target hardware. If required, author original project-owned, platform-cookable materials after the engine project builds.

The live GameMode emits LATEBRAKE_SCENERY_READY groups=7 instances=93 collision=off only when creation succeeds, otherwise LATEBRAKE_SCENERY_INCOMPLETE. This log reports component/instance construction, not correct rendering, cooking or playability.

Course overview map

The pure CircuitMap.h helper normalizes finite world locations to a north-up 0–1 coordinate space with clamping for out-of-track positions. In wide desktop HUD layouts, the racing HUD renders a small track loop, player's current position and the next required checkpoint. On compact and mobile viewports it is intentionally omitted to avoid clutter.

Validation requirements

Portable Windows/Linux/macOS CMake suites check this geometry and math, including fixed batch membership and unchanged legacy piece transforms. They cannot establish that a UE 5.8 game builds, materials/colors render correctly, that curbs never obstruct driving, or that the minimap avoids all HUD overlap. Real Unreal Editor tests and Win64/Android playtesting are required before a playable/stable release.