# Neural Radiance Cache Technical Artist Tuning Guide

The Maya renderer can replace later global-illumination bounces with a per-scene
Neural Radiance Cache (NRC). The cache learns indirect lighting from path-traced
samples during play, then answers GI queries through a small MLP.

Use this guide when tuning a playable level, cinematic capture map, or
performance preset that enables NRC.

## When to use NRC

Use NRC when the scene has expensive diffuse indirect lighting and enough frame
time for async training:

- Large spaces with many hidden bounce contributors.
- Dynamic time-of-day, doors, portals, or emissive materials that make static
  lightmaps stale.
- Lumen-class software ray tracing passes that spend too much time resolving
  unresolved rays.
- Probe-grid GI that meets frame budget but loses too much contact or color
  bleeding detail.

Avoid enabling NRC as the only GI path for scenes with very sparse training
samples, very low VRAM budgets, or lighting that changes every frame. Keep
probe-grid or Lumen fallback enabled until benchmark gates pass.

## Core controls

Tune these controls first:

| Control                    | Typical range | What it changes                                |
| -------------------------- | ------------: | ---------------------------------------------- |
| Hidden width               |         48-96 | Network capacity and weight memory.            |
| Hidden layers              |           2-4 | Detail capacity and inference cost.            |
| Training samples per frame |     1024-4096 | Convergence speed and async cost.              |
| Inference query count      |      60k-160k | Screen coverage and GI replacement cost.       |
| Temporal history frames    |           4-8 | Stability after training noise or camera cuts. |
| Fine NRC radius            |       24-48 m | Near-field GI detail in multi-resolution mode. |
| Coarse update interval     |    2-4 frames | Distant GI cost and temporal lag.              |

Increase network size only after checking debug error views. Many quality misses
come from missing training coverage or stale scene-change triggers rather than
from an undersized MLP.

## Recommended starting presets

### 60 fps exploration

- Target NRC frame cost: 0.8-1.5 ms.
- Hidden width: 64.
- Hidden layers: 3.
- Training samples per frame: 2048.
- Inference every frame for primary visible GI; coarse network every 3 frames.
- Require at least 16 optimizer steps before blending NRC into final GI.

### 30 fps cinematic capture

- Target NRC frame cost: 1.5-3.0 ms.
- Hidden width: 96.
- Hidden layers: 4.
- Training samples per frame: 4096.
- Fine radius: 48 m.
- Use Lumen surface-cache feedback when available.
- Require benchmark quality within 4 points of the path-traced reference.

### Low-memory fallback

- Target NRC memory: 48-64 MB.
- Hidden width: 48.
- Hidden layers: 2.
- Training samples per frame: 1024.
- Disable resident optimizer state when live refinement is idle.
- Keep probe-grid GI as the realtime renderer until memory gates pass.

## Warm-up workflow

For authored levels, ship baked NRC radiance data for important traversal areas.
The runtime should pre-train from this data during the level-load window and
then refine live:

1. Bake radiance samples with the current lighting revision.
2. Target at least 85 percent playable-area coverage.
3. Use probe spacing around 1.5-2.5 meters for gameplay spaces.
4. Reject baked data when the scene revision, area ID, or architecture checksum
   changes.
5. Allow live refinement before raising blend weight to 1.0.

If the warm-up plan reports low coverage, increase baked sample density before
raising network capacity. A larger network cannot learn missing parts of the
level without samples.

## Debug views

Technical artists should review NRC with these debug attachments:

- Predicted radiance: shows the lighting the network will inject.
- Ground-truth radiance: path-traced comparison for selected captures.
- Relative error heatmap: highlights underfit surfaces and lighting leaks.
- Confidence mask: shows where the runtime should trust or fade NRC output.
- Training sample overlay: verifies that moving props, emissive materials, and
  portal edges are represented in the replay queue.

Treat bright error heatmap bands near doorways, mirrors, emissive signs, and
thin geometry as content issues first. Add samples, adjust scene-change
thresholds, or reduce the NRC blend in those regions before globally increasing
quality.

## Scene-change triggers

Retraining should trigger when lighting or visibility changes enough to make
cached indirect radiance stale:

- Light moved, added, removed, or color/intensity changed.
- Time-of-day or sky luminance crossed the configured threshold.
- Door, portal, elevator, or large movable occluder changed state.
- Emissive material revision changed.
- Dynamic geometry revision changed in a way that affects bounce lighting.

For art-directed events, prefer explicit scene revision bumps over relying only
on numeric thresholds. This keeps authored set-piece lighting predictable.

## Lumen-class GI integration

When the Lumen bridge is available, NRC should accelerate unresolved software
rays and feed confident radiance back into the surface cache. Keep these
constraints:

- Preserve screen traces for on-screen detail.
- Retain a non-zero probe or software-ray budget for fallback.
- Enable final-gather compositing so NRC is not presented as a separate lighting
  layer.
- Keep NRC lookup latency below the configured software trace budget.
- Disable surface-cache feedback if debug confidence is low or the scene is
  actively retraining after a major lighting change.

If the Lumen bridge falls back, do not force NRC into the final image. Fix the
bridge issue or ship the probe/Lumen fallback for that area.

## Benchmark gates

Before shipping NRC for a level, compare it against pure path tracing and
probe-based GI using the benchmark planner:

- NRC frame time must fit the target frame budget.
- NRC memory must fit the level VRAM budget.
- NRC quality must meet the level quality target.
- Quality loss against path tracing must stay within the accepted delta.
- NRC must be faster than probe-based GI by the configured speedup threshold.
- Training must be converged or past the minimum optimizer step gate.

Use pure path tracing as the offline reference, not as the realtime fallback.
Use probe-grid or Lumen GI as the player-facing fallback until the benchmark
recommends NRC as the realtime renderer.

## Benchmark report review

Attach the benchmark report to technical-art signoff. For the renderer-side
`NeuralRadianceCacheBenchmarkReport`, review these fields before approving NRC
for realtime GI:

| Report field                                                   | Approval read                                                    |
| -------------------------------------------------------------- | ---------------------------------------------------------------- |
| `path_tracing.average_relative_error`                          | Must remain zero because path tracing is the reference.          |
| `neural_radiance_cache.average_relative_error`                 | Primary learned-lighting quality gate.                           |
| `neural_radiance_cache.valid_samples`                          | Must cover the benchmark sample count except accepted fallbacks. |
| `neural_radiance_cache.average_confidence`                     | Should match the confidence mask in hero spaces.                 |
| `nrc_speedup_vs_path_tracing`                                  | Confirms path tracing is offline-only for this content.          |
| `probe_speedup_vs_path_tracing`                                | Establishes the fallback cost baseline.                          |
| `nrc_relative_error_delta_vs_probe`                            | Positive means NRC has lower error than probe GI.                |
| `probe_gi.average_relative_error` and `probe_gi.valid_samples` | Explains whether probe GI is a safe fallback.                    |

When the report recommends probe GI, do not compensate by raising global NRC
blend weight. Fix sample coverage, scene-change triggers, network size, or
inference density, then rerun the same benchmark so the comparison is stable
across reviews.

## Troubleshooting

| Symptom                                        | Likely cause                                             | Fix                                                            |
| ---------------------------------------------- | -------------------------------------------------------- | -------------------------------------------------------------- |
| Blotchy indirect light after load              | Warm-up samples are sparse or stale.                     | Re-bake radiance data and verify revision checks.              |
| Light leaks near doors                         | Portal state is not triggering retraining.               | Add explicit portal revision triggers and lower blend locally. |
| Shimmering on camera motion                    | Temporal confidence is too high for noisy output.        | Increase history frames or lower EMA alpha during convergence. |
| NRC slower than probe GI                       | Query count or network width is too high.                | Reduce inference density before reducing training samples.     |
| Quality below target but debug coverage is low | Missing samples, not model capacity.                     | Add path-traced sample coverage in the affected area.          |
| VRAM over budget                               | Optimizer state or replay buffers are resident too long. | Evict optimizer state when idle and resize training buffers.   |

## Signoff checklist

Before approving an NRC-enabled level:

1. Architecture plan is `ready` or only has accepted non-blocking warnings.
2. Warm-up uses matching area ID, scene revision, and architecture checksum.
3. Debug views show acceptable error and confidence in hero spaces.
4. Scene-change triggers cover authored lighting, door, portal, and emissive
   events.
5. Memory plan leaves enough VRAM headroom for platform texture streaming.
6. Lumen bridge keeps screen traces and fallback rays when enabled.
7. Benchmark comparison recommends NRC for realtime GI, or the level explicitly
   ships with probe/Lumen fallback.
