Troubleshooting

Troubleshooting

Most faults in a lighting pipeline look the same from outside, in that nothing is lit. Four tools tell them apart, and the first one is the place to start.

The tools

Tool	What it answers
VRSL Diagnostics (select the manager in play mode, right-click the component header)	Did the shaders compile, did the decode produce fixture data, does the tile cull keep it, does the prepass feed the surfaces, and what did the beams take. One block in the Console.
VRSL → URP → Validate Shaders	Whether every package shader compiled. A full-screen shader that fails draws nothing rather than drawing wrong, so a compile error reads as a dark scene.
VRSL → URP → Validate Renderer Setup	Which renderer each camera uses, its depth-priming and MSAA modes, and whether the prepass covers the layers your fixtures sit on. Also what each camera renders at under the secondary-camera policy, and any opaque shader in the scene that lacks a depth pass. It reads and reports without changing anything.
VRSL → URP → DMX Config → DMX Monitor	Every channel live, which DMX route the fixtures read, and how long ago each universe was heard from. See DMX Monitor.

Symptoms

Symptom	Likely cause, and what to do
Nothing lit at all	Most often a full-screen shader that did not compile, which Validate Shaders will say. If the shaders are fine, VRSL Diagnostics says whether any fixture decoded a value, and none at all means the data is not arriving: check the DMX route, or that audio reaches AudioLink.
Everything lit a flat mid-grey	Either the manager's surfacePropertiesShader is empty, so no surface data is captured, or the surfaces sit on a layer left out of Lit surfaces.
The world's meshes light mid-grey while avatars keep their colour	The GPU Resident Drawer is on in the URP asset. VRSL cannot read the colour and gloss of the meshes it batches, so they light as plain mid-grey; VRSL Diagnostics and Validate Renderer Setup say so. To light a mesh in its own colour, add Unity's Disallow GPU Driven Rendering component to it (tick Apply To Children Recursively for a whole set piece), or turn the drawer off under Rendering on the URP asset. Avatars are unaffected because their shaders are not batched.
No beams	volumetricShader is empty, volumetricIntensity is 0, or quality is Off.
Beams show visible stepping	Set quality to High. Wide cones, long throws and dense haze show it before a narrow spot does. If the stepping is a regular pattern rather than fine grain, say so in an issue.
Fixture bodies dark while the light they cast works	On a fixture of your own, check its body renderers are in Fixture Shell Renderers; nothing drives a renderer left off the list. On a grid input the bodies read the grid textures the manager publishes, so check that its Grid Textures has a full set for the layout, strobe timer included.
DMX values plausible but wrong	Usually addressing. A fixture patched one channel off reads its neighbour's values and still looks deliberate. Open the DMX Monitor: a patch off by one shears diagonally. Check that use5ChannelMode matches the patch. A five-channel fixture read as thirteen picks up its neighbours.
A DMX fixture looks dimmer than expected	maxIntensity is on the same scale as a URP spot light's Intensity, so calibrate it against one. At curveMod 2 the light comes up late in the dimmer's travel; 1 is the gentlest curve.
Fixtures lit, but a source that should feed them is not	The source is only read when the manager's DMX Input is Stream data; under a grid it waits on standby. The DMX Monitor's header names the input and any source on standby.
Every light dark with DMX Input on Stream data	Nothing is sending stream data: no source in the scene, the source switched off, or a stream whose records were stripped on the way. With no source, or one switched off, the Console says so a few seconds in. VRSL Diagnostics and the DMX Monitor tell all three apart, including a Basis source that has decoded no record yet. Choose a grid if the stream carries no records.
Beams missing in a mirror	The secondary-camera policy on the manager. See Mirrors and Secondary Cameras.
A fixture body vanishes when depth priming is on	Under priming, URP draws only geometry whose depth pass matches its forward pass. Validate Renderer Setup names any opaque shader in the scene without one. Every shader the package ships has both, so this points at a custom shader.
Surfaces light as if flat under priming with MSAA on	A known limitation on renderers that prime with MSAA, which stock URP does not do but some hosts patch in. The surfaces still light, only without their own colour and gloss, and TESTING.md tracks it as S14.
Frame time worse than expected	In order: set quality to Standard or Off, set contact shadow strength to 0 if you do not need it, and check that lightCullShader is assigned, since without it both passes loop every fixture on every pixel. Then run Analyse This Scene, which says what costs what.
The manager's inspector says a reference is missing	Run VRSL → URP → Repair Manager Wiring. It fills every reference from the package's own assets. Three of the references are optional, and their tooltips say so.

Reporting a problem

Say which tools you ran and what they said, along with the Unity and URP versions, whether the renderer is Forward or Forward+, and the depth-priming and MSAA modes from Validate Renderer Setup. Mention whether it was desktop or a headset. The TESTING.md rows are the language the package is verified in, so naming a row that fails is the quickest report there is.