Fixing a Months-Long Lighting Bug - New Illumination System

With a little help from Claude Code, I finally tracked down a bug that had been haunting me for months. Sometimes the torches would cast shadows, sometimes not — and occasionally everything in the dungeon was bathed in a flat, boring gray. Completely non-deterministic, nearly impossible to reproduce reliably.

The culprit? An omni light casting shadows requires 6 shadow maps — one per cube face. A dungeon level with multiple torches quickly blows through SceneKit’s shadow map budget, causing it to silently drop lights, sometimes including the player’s own spotlight. The result: unpredictable lighting depending on how many torches were active at runtime.

A Completely New Illumination System

Once the root cause was clear, the fix was straightforward: rebuild the illumination from the ground up, dropping the shadow-casting omni lights in favour of a new approach that stays within the hardware budget. Here is what the dungeon looks like now compared to before:

Before	After

Shadow Priority for Torches

I still wanted to keep those moody, atmospheric shadows in at least a few spots per level. To make this possible without blowing the shadow map budget, I added a torch shadow priority feature to the Level Editor. You can now assign up to 3 torches per level a shadow priority — and at runtime, depending on the device’s hardware capabilities, 0 to 3 of those torches will actually cast shadows.

This gives level designers fine-grained control over where the atmospheric shadow effect appears, while keeping performance stable across all supported devices.

The fix will ship with R4.4 in April. There is plenty more in the pipeline — new features, gameplay improvements, and surprises I can not wait to show you. Stay tuned!

Download the Game

Download the Level Editor