[leite-matheus]

A follow-up to #57, merged with main at v1.0.15. Needs both owners' sign-off on the checkpoint change below (cross-play).

Track Lab: challenge, boss and hub levels from a .dkrmap

Until now a .dkrmap could only be a race track. All five other level kinds now play from one. Battle, bananas, eggs, boss and hub were each checked in game with a retail-clone header and with a track built from scratch.

• Boss. level_load swaps an unvisited boss level for its intro scene. It finds that scene by scanning ASSET_MISC_67 with no bound, so a custom level id read past the table and loaded junk (frozen camera). skip_custom_boss_intro in custom_tracks_hooks.cpp marks the course as visited first. After the race the game returns to the hub the player came from.
• Hub exits. A new manifest field, levelLinks ({slot, offset, track}), lets a hub EXIT lead to another installed .dkrmap. The hook sits after gzip_inflate in track_spawn_objects and patches the exit's destinationMapId. Hub → custom boss → hub was played through.
• Checkpoints 60 → 127. This is done with instructionPatches in both recomp policies (allocate_object_pools, checkpoint_update_all). The limit is 127 because nextCheckpoint is an s8. A 120-checkpoint oval races, and the AI completes laps on it.
• Shadow budgets. On dense custom floors the retail shadow clipping overflowed its fixed arrays (D_8011B120[32], D_8011C238[32], D_8011B330[120], which it uses as 128 entries). This crashed Paulista, an egg arena. Two hooks, dkr_shadow_clip_budget and dkr_shadow_polygon_budget, now keep it within those sizes. The fix rests on the crash dump: the crash later stopped reproducing even on the old build.
• Addon.
  • New Mode Checklist panel.
  • The AI Node Graph panel is enabled.
  • Mode validation.
  • A "Leads to" destination for hub exits, exported as levelLinks.
  • Adding an AI branch no longer fails on the wrong class.
• docs/CUSTOM_TRACKS.md documents the level kinds and levelLinks. Tests are in custom_tracks_tests.cpp.

Modern camera: hits and walls

• The Modern camera's hit shake is gone: the field, its ini key and its panel slider are removed. For about 1 s after a retail hit or explosion, boost and landing shake are off too. The retail camera is untouched.
• Wall fix. A wall behind the kart could put the eye inside the racer, filling the screen with one colour. The fix is in modern_cam:
  • collisionMinDist (1.6 m) keeps the eye at least that far from the pivot.
  • collisionLiftMax lets the boom rise over the kart instead.
  • Wall cuts slide in (collisionPullSharpness) instead of jumping 100+ units in one frame.
• Hits. During a hit the anchor is tied to the racer, the way the retail camera is, so the kart keeps its size on screen. On a climbing bank the camera no longer drops below the racer (riseLag, slopeMax).
• LoadCameraTuning kept the ini open, so the v1 → v2 migration from Modern camera keeps up through corners and hits; vehicle choice and a preview flight for custom tracks in Track Select #57 was never saved. It is now.
• New tests in modern_camera_dkr_tests.cpp: WallNeverPutsTheEyeInTheRacer, WallLiftReturns, ClimbingKeepsTheCameraAbove, WallCutSlides, HitKeepsTheBoomIn.

Enhanced water: caustics and low-pass spray

• Caustics. The two-sine caustics are replaced by a textured caustic layer: one texture sampled twice and panned in opposite directions. The texture is runtime-recomp/assets/water/WaterCaustics.png.
• Low-pass spray. Planes and hovercraft skimming low over water or lava now throw spray curtains and mist, and streak and whiten the liquid beneath them. The strength grows with speed and falls off with height. WaterDrawParams is already at the 2048-byte stride, so each craft's clearance lives in the last two shoreline vectors (WATER_CRAFT_AIR). Water draws never fill those vectors, and lava uses only 0..15; a static_assert guards this.
• No new patch layers. Both features ride on the existing baselined dkr-lava-glow.patch, and dkr-caustics.patch / dkr-lowpass.patch and their compose scripts are deleted. The folded patch applies with the same CMake flags and composes an RT64 tree byte-identical to the old chain.

Fixes

• Auto boot with a custom character crashed with Unadmitted custom presentation resource. This happens because auto boot skips character select, where the presentation is initialised. prepare_presentation now initialises it on demand. It allocates nothing in the guest, so the heap order is unchanged.
• Track Lab vertex paint. Paint on the baked layer now reaches the export; before, it was display-only and lost. A moved or shared .blend finds its base model beside itself.
• Plain runtime configure. A configure without the release overlay links again:
  • DKRCrashReports is now linked into DKRPortGame.
  • dkr_analogue_driving gets a retail pass-through: an MSVC /alternatename in runtime_code_mods.cpp, used only when the overlay does not define it.
• Pinned bytes. Twelve first-party files touched above are bases of the v1.0.7 source capsule. They join DRIFTED_BASES in check_pinned_bytes.py, so they are checked against their pinned Git blob, which still matches.

Pattern checks

• python scripts/check.py --suite guard,tooling passes. The pattern guard reports 0 new findings: the low-pass layer is folded, and no new patches/<name>/ or compose scripts are added.
• No new guest hooks outside the existing hook files, and no hard-coded addresses: the new ones live in revision_addresses.hpp and the recomp policies.
• netplay/legacy_identity.hpp does not exist yet, so nothing was spliced anywhere else. See Risk.

Testing

• MSVC Release build of DKRPortGame (build/dkr-runtime-rt64) after the v1.0.15 merge: Egg Arena and Boss Circuit boot and race.
• In game before the merge:
  • All five level kinds and the 120-checkpoint oval.
  • Hub → custom boss → hub.
  • Paulista, a full egg match.
  • Auto boot with a custom AI character, a 45 s race with no fatal error.
  • Low-pass spray on a Whale Bay clone with a plane and a hovercraft.
• Not played yet:
  • The camera wall/hit changes, which were checked with an offline replay of DKR's wall bounce and the unit tests.
  • Low-pass spray since it moved into WATER_CRAFT_AIR.
  • Vertex paint in a race; it was checked in headless Blender only.
• Track Lab suites (tools/blender/run_tests.py) pass.

Risk

• Cross-play. The checkpoint instructionPatches change the guest's object-pool layout. Online already refuses mismatched builds, but this is a simulation-affecting change, and AGENTS.md asks for both owners' approval. If you'd rather not take it now, dropping the two checkpoint entries from the recomp policies brings back 60 checkpoints. Custom tracks with more than 60 checkpoints would then need re-exporting.
• /alternatename pass-through for dkr_analogue_driving is MSVC-only and only matters for configures without the online-performance overlay. Say if you'd prefer it handled differently.
• Rollback:
  • Water: revert the water commits; the pre-fold chain is in history.
  • Camera: only the Modern camera changes; the Retail camera is unaffected.

[swhitt]

The shadow budget hooks and the boss intro skip are pretty nicely reasoned against the decomp.

The camera commit override is the one I'm most nervous about, mostly because the wall changes haven't been played yet.

[swhitt]

This puts back modern_cam's eye after the retail clearance pass already decided it was in a wall. So while sliding (or under closest) the drawn eye sits wherever modern_cam had it, which can be behind the wall, and segment_at below then picks the segment for that spot. I think that trades "inside the racer" for "inside the wall" for the length of the slide.

Since the wall changes are still unplayed, it'd be good to try a tight wall on a retail track with this before merge.

[swhitt]

/alternatename is MSVC-only, so a plain configure on clang (macOS/Linux) still won't link. Maybe also mark the pass-through __attribute__((weak)) named dkr_analogue_driving under #else?

[swhitt]

lend_course_clear takes RACE_CLEARED back before the save, but this sets visited|cleared and never clears them. save_data.c packs those bits for every RACETYPE_BOSS level up to levelCount.

Does a custom boss level's flag end up in the EEPROM after a race?

[swhitt]

Nit: this trace is always on in release. Maybe gate it behind the water trace level like the camera ones?

[swhitt]

Not masked here, but mode_checklist.owner() does (playerID - 1) & 3. A chest with playerID 0 shows up as racer 3 in the checklist, but here it's -1 and destination_tags skips it - the Bank nodes row stays MISSING and blocks export. Maybe just use mode_checklist.owner(CHEST, ...) here.

[swhitt]

Checked this against the decomp. gTrackCheckpoints is the only thing sized by MAX_CHECKPOINTS, and the slti at checkpoint_update_all is the only bound on the load, so I think these two patches cover it. 127 also keeps everything inside the s8 fields.

Worth calling out: allocate_object_pools runs once at boot, so the extra ~3 KB is taken for every level, retail included, and every allocation after it moves. Online already refuses mismatched builds, so that's probably fine. It might be good to add a line to the CHANGELOG saying this build can't play online with older ones.