skate-3-rust-engine/docs/custom-map-lighting.md

Custom map lighting

Custom .skate maps use the existing StandardMaterial PBR path: albedo, normal, ORM, emissive, alpha mask/blend, and UV1 lightmaps remain intact. A scene-owned shadowed directional light and ambient light now illuminate those surfaces and PBR characters. Shadow cascades cover 100 metres; local authored point/spot lights retain their existing settings. Area lights remain unsupported.

The environment header supplies start hour and orbit azimuth; extended headers also supply sun/moon colour, intensity and day/night ambient. The adapter maps unit sun intensity to 10,000 lux and unit ambient to 1,000 brightness. These are portable rendering choices, not recovered retail constants. The start hour is fixed: there is no new day/night controller or per-frame light update. Existing baked diffuse on lightmapped custom surfaces is retained. The package horizon colour remains the background; native sky sidecars are only loaded for retail scenes. Zero authored light intensity is respected.

Provenance and ambiguity

Startup and in-process loading share RetailScene::for_map. It checks embedded retail material definitions, WMET retail-manifest metadata, RWCM collision, SKYB retail sky, native collision edges and native rails. It never classifies from a filename, map title or ordinary lightmap presence. The Blender exporter writes WMET only for its retained SKATE3_RETAIL_MANIFEST; the retail pipeline also writes WMET/RWCM. This conservatively protects imported Skate 2 scenes whose material definitions may be absent, and edited retail-derived maps. WCFG, BMAT and MOBJ are general authoring records, not retail evidence.

A legacy retail export stripped of all native evidence is indistinguishable from custom PBR geometry. A custom rebuild retaining native records is treated as retail. No unreliable name heuristic or new authoring UI is introduced. Retain provenance when re-exporting retail maps. This classification protects the existing rendering path; it does not add support for missing retail shader families or missing sky/irradiance sidecars.

Scene lifetime

Directional/local lights, sky and backdrop are MapEntity-owned and retire with their scene. Ambient/background are replaced on publication. The gameplay camera switches retail HDR/tone on and off; the GPU exposure meter resets on a new scene generation. Retail character conversion retains original material handles and layers, restores them on each transition, and binds fresh authored lighting only in a retail scene. Dedicated zero-illuminance retail shadow maps are removed/recreated, preserving the separate player-only baked-world map. Character conversion is restricted to PlayerRoot descendants; only the gameplay camera acquires shadow layer 28. Scoring layer 31 and session overlays keep their existing cameras/materials. Custom character PBR materials respond to the custom scene lights without a separate character light rig.

Manual visual checks

• Open an ordinary custom map: compare upward and vertical surfaces, moving player shadows, normal maps, transparent textures and emissive surfaces.
• Check a map with local lights and/or baked indirect lighting; confirm those remain visible. Check an authored night start and zero-intensity sun.
• Open vanilla Skate 3 and imported Skate 2 maps: verify baked scenery remains unchanged and the dedicated player shadow remains visible where supported.
• Switch vanilla -> custom -> vanilla several times without restarting. Check sky/background, exposure, character shading and shadows for stale state or increasing brightness. Repeat with a custom character and clothing changes.
• Open scoring HUD, session marker and customization overlays on both map types; verify no world/player silhouettes or lighting appear in overlays.
• Rename a custom package to a retail-like name: it must still get custom lighting. A retail-derived package retaining provenance must stay retail.

No game, recomp, Steam or gameplay automation was launched for this change.

Automated validation

cargo check -p skate-game --tests --no-default-features --release --offline passed with existing warnings. A static-CRT release test harness was linked directly into the worktree's ignored private output using the shared Cargo cache. All six focused CPU tests passed: map_render::tests (3), retail_character::tests (2), and camera::environment_tests (1). These checks do not validate GPU appearance; use the visual checklist above.

SKATE15 loading is also covered by ten data-reader tests (including legacy versions, both compression codecs, all storage transforms, texture references and malformed input). A user-supplied v15 custom map passed the ignored CPU supplied_custom_map_prepares_and_retires check: decoding, runtime validation, material/mesh preparation, publication, custom-light classification and scene retirement. Supply SKATE_TEST_CUSTOM_MAP and SKATE_TEST_CUSTOM_ASSETS to run that check on another local custom map; no user map bytes are committed.

A subsequent offboard-query exit was traced to validating the unused fourth SIMD lane as a position coordinate. Static swept-line queries now validate only XYZ and radius, matching their dot3/Vector3 collision math. The regression checks identical hits with infinite/NaN fourth lanes and rejection of invalid XYZ/radius. Six contact-toolkit tests pass. The existing embedded_static_rwcm_hits_distinct_actor_query_ids test fails its metadata expectation (matching_group == -1 && geometry == 0) before executing the changed query path; that unrelated fixture expectation remains unchanged.

Custom collision performance

Portable map collision previously occupied one query mesh, so nearby queries scanned the entire map. It now uses contiguous 64-triangle bounds in the existing static hierarchy, built once during loading. Triangle order, geometry IDs, filters, packed surfaces and adjacency remain unchanged. Native RWCM clusters retain their existing path.

A static query benchmark on the supplied custom map (89,613 triangles) sampled 257 local segments with identical candidate IDs/order before and after. Triangle checks fell from 23,030,541 to 4,198,157; measured candidate-query time fell from 16.51 ms to 3.82 ms total (about 4.3x). A 16-triangle partition was also tried, but had higher query time (4.69 ms) despite fewer triangle checks. These are CPU microbenchmark results, not gameplay FPS or GPU measurements. Ten map tests passed. The supplied-map benchmark is opt-in via SKATE_TEST_CUSTOM_MAP. Frame timing can be captured with the existing SKATE_PERF_REPORT environment setting (10-second warmup, report/exit after 25 seconds); no automated gameplay was run.

Frame capture: mesh binding preparation

The user-run capture after collision clustering measured 83.5 FPS / 11.98 ms mean frame time. Main schedule time was 2.80 ms, physics 1.55 ms/frame, and the render mesh-bind-group preparation section 9.75 ms. CPU query improvements therefore did not address the dominant measured render preparation cost.

The vendored renderer now caches complete per-phase model/skin/morph/lightmap binding sets, retaining at most four rotating allocation combinations per phase. Buffer contents can update without recreating descriptors. Keys include model allocation/offset/size, current/previous skin and morph buffer IDs, morph mesh/texture/skin-layout identities, lightmap revision and layout identity. Pipeline changes clear the cache; removed phases and replaced map resources retire their entries. The existing opt-in GPU cache test covers rotating allocations, reuse, size changes, skin/morph replacement and bounded retention. A new gameplay capture is required to quantify the resulting FPS change.

Validation: release build check passed, and the explicit Vulkan GPU cache regression test passed. No gameplay was launched for this change.

Remaining hitch investigation

The next user capture measured 525.1 FPS, 1.90 ms mean frame time and 0.126 ms mesh binding preparation. Two clusters of slow frames remained; the maximum was 26.71 ms, with only 4.01 ms in the main schedule and 2.71 ms in physics. Another 25.53 ms frame contained no physics tick. The aggregate render metrics cannot identify those individual stalls. No specific hitch cause is confirmed.

The opt-in profiler now retains timestamped main/render samples, pending pipeline counts, and bounded slow-section events (at least 2 ms, at most 256). Main/render sample buffers are preallocated. Reports still write only at the end of the capture; normal launches do not enable this instrumentation. The release compile check passed. Another user-run capture is required to locate the remaining stalls; no game or gameplay automation was launched.