Document Forward+ measurements and Linux lighting evidence

docs/manual/editor/diagnostics.md

@@ -27,10 +27,16 @@ When GPU timestamps are available, the panel shows sun and local shadow pass
 durations. A zero duration after a disabled sun or sprite-only frame confirms
 that no sun shadow raster ran. The lighting path names the algorithm actually
 used, so compare it with a benchmark's requested mode before interpreting costs.
+For an explicitly tiled frame, the overlay also reports the 16×16 grid size,
+its compute GPU duration, the number of stored light candidates, and how many
+tiles overflowed their 64-index list and scanned all lights. Candidate and
+overflow counts require the diagnostics readback; **unavailable** is distinct
+from a measured zero. The diagnostic copy itself adds work, so close the panel
+before measuring performance.
 See [Lighting](lighting.md) for the 128-light and 16-tile limits.
 
 The Vulkan backend emits `VK_EXT_debug_utils` labels for `SunShadowAtlas`,
-`LocalShadowAtlas`, `ForwardAndUI`, `Readback`, and, when presenting,
+`LocalShadowAtlas`, `LightTileBuild` when tiled, `ForwardAndUI`, `Readback`, and, when presenting,
 `Presentation`. A fallback frame can have no shadow-raster label. A graphics
 capture tool that supports this extension can identify the command-buffer
 regions. Labels remain available without the Khronos validation layer when

docs/manual/editor/lighting.md

@@ -72,6 +72,25 @@ cleared and redrawn each frame; there is no persistent shadow cache yet.
 Sprite-only scenes, a missing sun, and a sun with `casts_shadow: false` skip sun
 shadow raster work.
 
+## Local-light rendering path
+
+The normal `Auto` setting uses the measured forward light scan. It is the
+current default for Editor and Player. A C++ renderer integration can explicitly
+set `RendererConfig::lighting_mode = LightingMode::Tiled` to build depth-free
+16×16 screen-tile lists on a capable Vulkan device. Each tile stores at most
+64 light indices in stable order. If more lights touch a tile, its fragment
+shader scans the complete submitted list, so an overflow never removes
+illumination. The path falls back to forward when no local lights are present
+or the compute/buffer requirements are unavailable. Sprites and UI stay unlit.
+
+This explicit path can help when light ranges occupy small parts of the screen;
+it costs extra work when nearly every light covers nearly every tile. The
+fixed dense benchmark was slower after including tile construction, so there
+is no automatic scene-dependent switch yet. The Player profile reports
+`effective_lighting_path`, tile GPU time and grid size; optional Editor
+diagnostics also report stored candidates and overflowing tiles. See
+[Profiling](profiling.md) and the [measured Forward+ study](https://github.com/emil28092005/Faset_Engine/blob/main/docs/studies/23-p3-forward-plus-2026-09-24.md).
+
 ## Add a point light through MCP
 
 MCP edits the **Editor document**, not entities in a running game. Use

docs/manual/editor/profiling.md

@@ -130,6 +130,15 @@ submitted-light count of zero is a different workload from 128 lights whose
 shadows are disabled. See [Lighting](lighting.md) for the capacity policy and
 [Diagnostics](diagnostics.md) for the Editor counters.
 
+The same sample includes `effective_lighting_path` (`forward` or `tiled`),
+`gpu_light_tiles_ms`, and `light_tile_count`. Stored candidate and overflow
+counts are present only when visibility diagnostics readback was enabled;
+`light_tile_counts_valid: false` means their `null` values are unavailable,
+not zero. The normal `Auto` setting currently resolves to `forward` after the
+fixed dense 1080p benchmark showed that tile construction cost outweighed its
+raster savings. A C++ renderer integration can explicitly request `Tiled` for
+a localized-light scene, then check the actual path before comparing timings.
+
 The fixed-scene benchmark compares 0, 4, 16, 32, 64, and 128 local lights under
 Direct, GPU frustum, and GPU occlusion visibility, with shadows on and off. Its
 wrapper runs three independent 1920×1080 repetitions per configuration, each
@@ -162,6 +171,18 @@ frame** at 32, 64, or 128 lights on the Linux physical reference GPU. The
 states the measured decision and scope. A software Vulkan run checks
 functionality, not physical GPU performance.
 
+For a direct comparison of the two algorithms on the same scene, invoke the
+Release executable twice with `--lighting forward` and `--lighting tiled`,
+using the same `--lights`, `--shadows`, `--visibility`, and output size. The
+default `--light-layout dense` preserves the fixed benchmark scene;
+`--light-layout localized` reduces point-light ranges to 1.75 units as a
+separately labelled workload. Compare `gpu_build_plus_raster_ms`, which includes
+`gpu_light_tiles_ms`, rather than raster time alone. One optional diagnostic
+frame with `--tile-diagnostics on` reports candidate and overflow counts but
+adds a GPU readback, so do not mix it into the timed runs. The
+[Forward+ measurement](https://github.com/emil28092005/Faset_Engine/blob/main/docs/studies/23-p3-forward-plus-2026-09-24.md) retains
+raw frames, shader hashes, and the decision.
+
 ## Current performance scope
 
 The accepted MVP path uses direct draws and CPU culling; P2 adds optional GPU