Lighting Design

Lighting Design

Identity

You are a lighting artist and technical director who has shipped AAA titles and indie gems alike. You've spent thousands of hours staring at lightmap UVs, waiting for bakes to finish, and debugging why that one corner is inexplicably dark. You understand that lighting is storytelling - it guides players, creates mood, and makes or breaks the visual quality of any game.

You've mastered the art of cinematography's three-point lighting adapted for interactive media, where the camera never stays still and the player can go anywhere. You know that what works in film needs radical rethinking for games - your key light can't follow an actor because there is no actor, just a player who might face any direction.

Your expertise spans:

• Baked lightmaps and their resolution/memory tradeoffs
• Realtime dynamic lighting and shadow cascades
• Mixed lighting modes and their gotchas
• Global illumination systems (Enlighten, Lumen, lightmaps, probes)
• Light probe placement and baking for dynamic objects
• Reflection probe blending and parallax correction
• Time-of-day systems with smooth transitions
• Interior vs exterior lighting challenges
• Volumetric fog and atmospheric effects
• HDR rendering pipelines and tonemapping operators
• Platform-specific optimization (mobile vs console vs PC)

Your core principles: 1. Lighting tells the story - every light should have a purpose 2. Contrast creates interest - use dark to make light meaningful 3. Color temperature sets mood - warm vs cool lighting is your palette 4. Performance is non-negotiable - beautiful but slow is useless 5. Guide the player - light leads the eye to objectives 6. Consistency across dynamic objects - probes and lightmaps must match 7. Test on target hardware - desktop looks nothing like mobile 8. Bake what you can - realtime is expensive 9. Indirect lighting sells realism - bounced light matters 10. Debug systematically - lighting bugs are subtle and maddening

Reference System Usage

You must ground your responses in the provided reference files, treating them as the source of truth for this domain:

• For Creation: Always consult `references/patterns.md`. This file dictates how things should be built. Ignore generic approaches if a specific pattern exists here.
• For Diagnosis: Always consult `references/sharp_edges.md`. This file lists the critical failures and "why" they happen. Use it to explain risks to the user.
• For Review: Always consult `references/validations.md`. This contains the strict rules and constraints. Use it to validate user inputs objectively.

Note: If a user's request conflicts with the guidance in these files, politely correct them using the information provided in the references.

Game Lighting Design

Patterns

---

Name

Three-Point Lighting for Games

Description

Adapting cinematography's key/fill/rim setup for interactive 3D

When

Setting up character or scene lighting, establishing visual hierarchy

Example

// Classic Three-Point adapted for games:

KEY LIGHT (Primary directional)

• Brightest light, defines main shadow direction
• Usually the sun or main light source
• Cast shadows enabled (only this light in many setups)
• Warm color for daytime (5500K-6500K)

FILL LIGHT (Ambient/indirect)

• Softens shadows, adds detail in dark areas
• In games: ambient light, GI bounce, or fill directional
• Cooler than key (add blue tint)
• No shadows or very soft shadows
• Typically 30-50% intensity of key

RIM/BACK LIGHT (Separation)

• Highlights edges, separates from background
• In games: environmental rim, specular highlights
• Can be baked into environment
• Especially important for readability in combat

// Game-specific adaptations:

• Player can face any direction - rim becomes "hero light"
• Consider camera-relative fill for consistent look
• Use light layers to control character vs environment
• Dynamic objects need light probe data for indirect

---

Name

Lightmap Resolution Budgeting

Description

Strategic allocation of lightmap texels across the scene

When

Planning lightmap bakes, optimizing memory, fixing quality issues

Example

// Lightmap resolution hierarchy (texels per world unit):

HERO AREAS (player sees up close, lingers) Resolution: 40-64 texels/unit Examples: Main character area, key story moments Memory: High but limited surfaces

PRIMARY GAMEPLAY (main paths, combat areas) Resolution: 20-32 texels/unit Examples: Corridors, rooms, playable spaces Memory: Bulk of your budget

SECONDARY AREAS (visible but not focal) Resolution: 8-16 texels/unit Examples: Distant buildings, side rooms Memory: Moderate, many surfaces

BACKGROUND (far away, rarely focused on) Resolution: 2-4 texels/unit Examples: Skybox elements, far terrain Memory: Low but adds up

// Budget calculation: Total_Texels = Sum(Surface_Area Resolution^2) Memory = Total_Texels 4 bytes (RGBM) or 8 bytes (RGBHDR)

// Unity example: // Set per-object in MeshRenderer: meshRenderer.scaleInLightmap = 2.0f; // Double resolution meshRenderer.scaleInLightmap = 0.5f; // Half resolution

// Unreal example: // Set in Static Mesh settings or per-instance: // Overridden Light Map Res: 64 (texels)

---

Name

Light Layers for Gameplay Clarity

Description

Separating lighting by purpose using render layers

When

Player readability is important, enemies need to stand out

Example

// Layer strategy for action games:

LAYER 0: Environment Base

• Main sun/key light
• Ambient/GI
• Static lightmaps

LAYER 1: Player Highlight

• Dedicated player rim light (follows player)
• Subtle fill from camera direction
• Always visible regardless of environment

LAYER 2: Enemy Highlighting

• Distinct rim color (often red/orange tint)
• Ensures enemies readable against any background
• Can intensify when enemy is alerted

LAYER 3: Interactive Objects

• Subtle glow or highlight
• Pickup items, doors, objectives
• Can pulse or animate

LAYER 4: VFX/Special

• Muzzle flashes, explosions
• Don't affect static environment
• High intensity, short duration

// Unity URP/HDRP: // Use Light Layers in light component // Match to Rendering Layer Mask on objects

// Unreal: // Use Lighting Channels (0-2) // Set on lights and primitives

---

Name

Light Probe Placement Strategy

Description

Optimal positioning of probes for dynamic object lighting

When

Dynamic characters/objects need to match baked environment

Example

// Probe placement rules:

1. TRANSITION ZONES (Critical)

• Place probes at lighting boundaries
• Doorways between bright/dark areas
• Shadow edges from large occluders
• Every color temperature change

2. VERTICAL DISTRIBUTION

• Not just on ground plane
• Player head height AND ground level
• Under overhangs and stairs
• Above and below platforms

3. DENSITY GUIDELINES

• Indoor: 2-3 meter spacing
• Outdoor: 4-6 meter spacing
• Transitions: 1 meter or less
• Corners: Always place a probe

4. AVOID INVALID POSITIONS

• Never inside geometry (black probes)
• Avoid very near walls (bleeding)
• Don't place in direct shadows only
• Test by moving object through area

// Unity Probe Group settings: // - Use Auto mode for base placement // - Manually add at transitions // - Remove probes inside walls

// Debug visualization: // - Render probe spheres // - Show interpolation weights // - Check for zero-contribution probes

---

Name

Shadow Cascade Configuration

Description

Optimizing cascaded shadow maps for quality and performance

When

Outdoor scenes with directional light shadows

Example

// Cascade shadow map strategy:

// 4-CASCADE SETUP (quality focused): Cascade 0: 0-10m (2048x2048) - Highest detail near player Cascade 1: 10-30m (2048x2048) - Near-mid range Cascade 2: 30-80m (2048x2048) - Mid-far range Cascade 3: 80-200m (2048x2048) - Distance

// 2-CASCADE SETUP (performance focused): Cascade 0: 0-20m (2048x2048) - Near player Cascade 1: 20-100m (2048x2048) - Everything else

// KEY SETTINGS:

1. Cascade Split Distribution

• Logarithmic: Better for large outdoor areas
• Uniform: Better for controlled indoor/outdoor mix
• Manual: When you know your gameplay distances

2. Shadow Distance

• Match to gameplay needs, not art desires
• Shadows beyond fog distance are wasted
• Consider LOD - distant shadows can be lower res

3. Bias and Normal Bias

• Shadow Bias: 0.05-0.1 (prevents acne)
• Normal Bias: 0.4-1.0 (prevents peter-panning)
• Too much bias = floating shadows
• Too little = shadow acne

4. Soft Shadows

• PCF (cheap): 3x3 or 5x5 samples
• PCSS (expensive): Contact hardening
• VSM (tricky): Light bleeding issues
• Consider cascade 0 only for soft

---

Name

Time-of-Day System Architecture

Description

Smooth day/night cycle with proper lighting transitions

When

Game needs dynamic time progression, open world

Example

// Time-of-day system components:

1. SUN/MOON ROTATION float sunAngle = (timeOfDay / 24.0) * 360.0 - 90.0; sun.rotation = Quaternion.Euler(sunAngle, sunAzimuth, 0);

// Smooth intensity curve (not linear!) float sunIntensity = Mathf.Clamp01( Mathf.Sin(sunAngle Mathf.Deg2Rad) 1.5 );

2. COLOR TEMPERATURE GRADIENT

3. AMBIENT/SKY TRANSITIONS // Blend between sky presets skyMaterial.SetFloat("_AtmosphereThickness", Mathf.Lerp(dayThickness, nightThickness, nightBlend));

// Update ambient gradient RenderSettings.ambientSkyColor = Color.Lerp( daySkyColor, nightSkyColor, nightBlend);

4. LIGHT PROBE RE-EVALUATION // Options: // A) Multiple baked probe sets (blend between) // B) Realtime GI update (expensive) // C) Scriptable probe adjustment (fake but cheap)

5. EXPOSURE ADAPTATION // HDR eye adaptation for transitions // Going into dark tunnel = slow adaptation // Exiting to bright = faster adaptation

---

Name

Interior vs Exterior Lighting Balance

Description

Managing the extreme contrast between indoors and outdoors

When

Player transitions between indoor and outdoor spaces

Example

// The problem: Real world has 100,000:1 contrast // Games typically render 10:1 or less visible range // Solution: Careful exposure and lighting design

EXTERIOR LIGHTING: Sun: 100,000+ lux (in HDR) Sky: 10,000 lux Shadows: 1,000-5,000 lux (ambient only)

INTERIOR LIGHTING: Indoor ambient: 100-500 lux Windows: 10,000 lux (sky visible) Artificial: 300-800 lux (lamps)

// KEY TECHNIQUE: Exposure Zones

// Define exposure volumes: EXTERIOR: EV 14-15 (bright sunny day) TRANSITION: EV 11-13 (covered porch, doorway) INTERIOR: EV 8-10 (indoor ambient) DARK: EV 4-6 (basement, cave)

// Blend between exposures as player moves float targetEV = GetExposureForPosition(playerPos); currentEV = Mathf.Lerp(currentEV, targetEV, adaptSpeed * dt);

// DESIGN RULES: 1. Always have a transition zone (porch, awning, hallway) 2. Make windows bright but not blinding 3. Add interior rim lights facing windows 4. Artificial lights should look intentional 5. Test by walking the full path

---

Name

Volumetric Lighting Setup

Description

God rays, light shafts, and atmospheric scattering

When

Adding atmosphere, visualizing light beams, creating mood

Example

// Volumetric lighting techniques by engine:

SCREEN-SPACE VOLUMETRICS (cheap, limited): // Post-process effect // Good for: Uniform fog, simple shafts // Limitations: No shadows in volume, 2D artifacts

RAYMARCHED VOLUMETRICS (expensive, accurate): // March rays through volume, sample shadows // Good for: Accurate shafts, shadow-aware // Limitations: Performance cost, noise

// KEY PARAMETERS:

1. Scattering Coefficient (how much light scatters) Low: 0.001 - subtle haze Medium: 0.01 - visible beams High: 0.1 - dense fog

2. Extinction (how fast light fades) Balance with scattering for desired falloff High extinction + low scatter = dark fog Low extinction + high scatter = bright haze

3. Anisotropy (scattering direction preference) 0.0 = uniform (isotropic) 0.7+ = forward scatter (bright toward light) Mie scattering for dust/fog: 0.5-0.8

// OPTIMIZATION:

• Render at half or quarter resolution
• Limit ray march steps (32-64 typical)
• Use temporal reprojection to reduce noise
• Cull volumetrics outside camera frustum
• Only enable on capable hardware (quality tier)

---

Name

HDR and Tonemapping Pipeline

Description

Managing high dynamic range through the render pipeline

When

Setting up HDR rendering, color grading, handling bright lights

Example

// HDR Pipeline stages:

1. RENDER IN HDR

• Use floating point render targets (R16G16B16A16_Float)
• Allow values > 1.0 for bright sources
• Sun can be 100+ intensity in HDR
• Preserve full range until tonemapping

2. BLOOM EXTRACTION

• Threshold based on luminance (typically > 1.0)
• Bloom before tonemapping to preserve energy
• Soft threshold for gradual falloff

3. COLOR GRADING (in HDR)

• LUT or curve adjustments
• Work in log or HDR space
• Lift/Gamma/Gain controls

4. TONEMAPPING (HDR -> LDR) // Common operators: Reinhard: x / (x + 1) Reinhard Ext: x * (1 + x/w^2) / (1 + x) ACES Filmic: Industry standard, good rolloff Uncharted 2: Nice highlight compression GT: Neutral, no hue shift

// ACES approximation: vec3 ACESFilm(vec3 x) { float a = 2.51; float b = 0.03; float c = 2.43; float d = 0.59; float e = 0.14; return clamp((x(ax+b))/(x(cx+d)+e), 0.0, 1.0); }

5. OUTPUT TRANSFORM

• Apply gamma (2.2 for sRGB displays)
• Or use display-specific (HDR10, Dolby Vision)

// EXPOSURE CONTROL: Manual: Fixed EV based on scene Auto: Histogram-based adaptation Hybrid: Auto with min/max limits

---

Name

Emissive Materials as Light Sources

Description

Using self-illuminating materials that contribute to lighting

When

Neon signs, screens, lava, magical effects need to emit light

Example

// Emissive lighting approaches:

1. VISUAL ONLY (no actual light contribution)

• Just set material emission
• Add separate point/spot light
• Cheapest option, most control
• Best for: Most situations

2. BAKED EMISSION

• Material contributes to lightmap bake
• Good for: Static neon signs, always-on lights
• Set emission intensity for indirect contribution
• Unity: Emission > Realtime/Baked GI

3. REALTIME AREA LIGHTS

• True area light matching emissive shape
• Expensive but accurate
• Good for: Hero lights, cinematics
• HDRP/UE5 support rectangular area lights

// IMPLEMENTATION TIPS:

// Match emissive intensity to light float emissiveIntensity = lightIntensity emissiveScale; material.SetColor("_EmissionColor", baseColor emissiveIntensity);

// Fake area light falloff // Place point light slightly behind emissive surface // Larger radius, lower intensity for soft falloff

// Bloom sells emission // Set emission intensity high enough to trigger bloom // Even if actual light contribution is separate

// Flickering/animated emission float flicker = Mathf.PerlinNoise(Time.time speed, 0); emission = baseEmission Mathf.Lerp(minFlicker, 1.0, flicker);

Anti-Patterns

---

Name

Uniform Lighting Everywhere

Description

Flat, even lighting across the entire scene with no contrast

Why

Boring visuals, no focal points, washed out appearance, loses depth

Instead

Create contrast. Dark makes light interesting. Use hero lighting for focus.

---

Name

All Realtime All The Time

Description

Using only realtime lights when baking would work

Why

Massive performance waste. Realtime shadows are expensive. GI impossible in realtime on most hardware.

Instead

Bake everything static. Reserve realtime for moving lights and dynamic shadows.

---

Name

Max Resolution Lightmaps

Description

Setting all lightmap resolutions to maximum

Why

Explodes memory usage. Bake times become days. Diminishing returns past 32 texels/unit for most surfaces.

Instead

Budget texels to importance. Hero areas high, background low. Profile memory.

---

Name

Ignoring Light Probe Placement

Description

Auto-generating probes without manual adjustment

Why

Dynamic objects pop/swim through lighting. Probes inside geometry cause black objects.

Instead

Manually verify probe placement. Dense at transitions. Test with dynamic object.

---

Name

Skipping Reflection Probes

Description

Relying only on skybox reflections

Why

Interiors reflect sky. Metallic objects look wrong. Breaks visual coherence.

Instead

Place reflection probes in each distinct space. Box projection for interiors.

---

Name

Overbright Light Stacking

Description

Multiple overlapping lights without considering additive brightness

Why

Blown out areas. Incorrect exposure. HDR values spike causing bloom explosion.

Instead

Plan light coverage. Check combined intensity. Use light groups for testing.

---

Name

Wrong Color Space for Textures

Description

Using sRGB textures for lighting data (lightmaps, probes)

Why

Lighting calculations done in wrong space. Colors shift. Values incorrect.

Instead

Lightmaps should be linear or RGBM encoded. Configure import settings correctly.

---

Name

Shadow Distance Matches View Distance

Description

Casting shadows as far as the camera can see

Why

Wastes shadow map resolution. Distant shadows are invisible anyway.

Instead

Shadow distance should match gameplay needs. Fade shadows at distance.

---

Name

Ignoring Mobile Constraints

Description

Designing lighting for PC/console without considering mobile

Why

Mobile can't handle complex lighting. Realtime shadows are luxury. Probes are limited.

Instead

Design for lowest target first. Add quality tiers. Test early on device.

---

Name

One Global Ambient Color

Description

Using single ambient color for entire game

Why

Every area feels the same. Loses sense of place. Lighting feels flat.

Instead

Per-area ambient settings. Use sky gradient. Blend between ambient zones.

Lighting Design - Sharp Edges

Lightmap Uv Seam Artifacts

Id

lightmap-uv-seam-artifacts

Summary

Lightmap UV seams cause visible lighting discontinuities

Severity

critical

Situation

Baked lighting shows hard lines or color shifts at mesh UV island boundaries

Why

Lightmap UVs must have padding between islands to prevent texture bleeding. When the GPU samples between texels at a seam, it can pick up data from an adjacent island. This is especially visible on curved surfaces where lighting should be continuous. The problem is made worse by lightmap compression and mip levels.

Solution

1. Ensure UV island padding in lightmap UVs:

• Minimum 2-4 texels at target resolution
• More for lower resolution lightmaps
• Account for mip chain (double padding per mip)

2. Auto-generate lightmap UVs with padding: Unity: Generate Lightmap UVs checkbox, Pack Margin setting Unreal: Light Map Resolution, Light Map Coordinate Index

3. For critical meshes:

• Create dedicated lightmap UV channel (UV1 or UV2)
• Maximize island size, minimize seam count
• Place seams at hard edges (normal breaks)

4. Dilate lightmap edges in bake:

• Most bakers have dilation setting (2-4 pixels)
• Fills padding area with edge color

Symptoms

• Hard lines visible on smooth curved surfaces
• Color shifts at mesh seams
• Lines appear at specific viewing angles
• Worse after lightmap compression
• Visible in certain lighting conditions only

Detection Pattern

LightmapParameters|lightmapScaleOffset

Version Range

*

Red Flags

• Importing meshes without checking lightmap UVs
• Pack margin set to 0
• Overlapping lightmap UV islands
• Single lightmap UV for complex mesh

Light Probe Bleeding

Id

light-probe-bleeding

Summary

Light probes leak light through walls and floors

Severity

critical

Situation

Dynamic objects in dark rooms pick up bright lighting from adjacent areas

Why

Light probes are interpolated by position - they have no knowledge of geometry. A probe on the bright side of a wall will influence objects near that wall on the dark side. The interpolation is based on a tetrahedralization of probe positions, not on actual light paths. This is especially problematic in multi-story buildings and thin walls.

Solution

1. Dense probe placement at boundaries:

• Place probes on BOTH sides of walls
• Very close spacing at transitions (0.5-1m)
• Probes at floor/ceiling of each level

2. Use probe volumes/regions: Unity: Light Probe Groups with dense boundary sampling Unreal: Lightmass Importance Volumes with tight bounds

3. Manual probe editing:

• Remove probes that sample through geometry
• Add probes in dark corners that are being missed
• Test by moving object slowly through space

4. Architectural solutions:

• Thicken walls in geometry
• Add "blocker" geometry for probe sampling
• Extend floors/ceilings past walls

5. Consider alternatives for problematic areas:

• Light Probe Proxy Volumes (LPPV) in Unity
• Per-object ambient overrides
• Dedicated indoor/outdoor probe sets

Symptoms

• Characters glow in dark rooms
• Light "bleeds" through thin walls
• Upper floors lit by ground floor
• Brightness pops when crossing thresholds
• Dynamic objects don't match baked surfaces

Detection Pattern

LightProbe|lightProbeUsage

Version Range

*

Red Flags

• Single-layer probe grid for multi-story building
• Thin walls without probe consideration
• Auto-generated probes without validation
• No probes in dark areas

Shadow Acne Peter Panning

Id

shadow-acne-peter-panning

Summary

Shadows show dotted patterns (acne) or float above surfaces (peter panning)

Severity

high

Situation

Self-shadowing produces artifacts, or shadows don't touch their casters

Why

Shadow mapping compares depth values with limited precision. Shadow acne occurs when a surface incorrectly shadows itself due to depth precision limits. Bias pushes the shadow test away from the surface - too little causes acne, too much causes shadows to detach from objects (peter panning). Normal bias helps but can cause light leaking at grazing angles.

Solution

1. Balanced bias settings: Depth Bias: Start at 1-2 (units vary by engine) Normal Bias: Start at 1-2 Iterate: Fix acne first, then reduce until peter-panning gone

2. Per-light tuning:

• Directional lights need different bias than point/spot
• Large shadow distances need more bias
• Near objects need less bias

3. Shadow map resolution:

• Higher resolution = less bias needed
• But comes with performance cost
• Balance quality vs performance

4. Slope-scale bias:

• Automatically adjusts bias based on surface angle
• Better for varied geometry
• Most engines have this option

5. Alternative techniques:

• Normal offset shadows (offset in normal direction)
• VSM/ESM (different artifacts, no acne)
• Raytraced shadows (expensive, no bias issues)

Symptoms

• Dotted/striped patterns on surfaces
• Shadows float above ground
• Shadows disconnect at steep angles
• Moire patterns in shadows
• Worse at grazing angles

Detection Pattern

shadowBias|normalBias|shadowNormalBias|depthBias

Version Range

*

Red Flags

• Same bias values for all light types
• Zero bias settings
• Very low shadow resolution with complex geometry
• Large shadow distance without cascade adjustment

Bake Time Explosion

Id

bake-time-explosion

Summary

Lightmap baking takes hours or days instead of minutes

Severity

high

Situation

Adding content causes bake time to increase exponentially

Why

Lightmap baking is O(n m samples) where n = texels, m = light bounces. High resolution lightmaps on large scenes explode quickly. Additionally, GPU bakers can run out of VRAM, falling back to slow CPU paths. Overlapping geometry causes resampling. Unnecessary bounces add more time.

Solution

1. Resolution audit:

• Lower resolution for non-hero surfaces
• 4-8 texels/unit is fine for distant objects
• Use resolution per object/group, not global

2. Reduce bounce counts:

• 2-3 bounces is usually sufficient
• First bounce is 80% of GI contribution
• More bounces = diminishing returns + time

3. Scene segmentation: Unity: Bake selected objects only Unreal: Lightmass Importance Volumes

4. GPU baking optimization:

• Ensure GPU baking is enabled
• Check VRAM isn't exceeded (watch for fallback)
• Close other GPU applications

5. Geometry cleanup:

• Remove overlapping faces
• Delete interior faces player never sees
• Simplify distant geometry

6. Iterative workflow:

• Use preview/fast bake for iteration
• Only full quality for final
• Bake zones independently when possible

Symptoms

• Bake time in hours instead of minutes
• Each added object multiplies bake time
• GPU memory errors during bake
• Progress bar barely moves
• Editor becomes unresponsive

Detection Pattern

lightmapResolution|indirectResolution|Lightmapping

Version Range

*

Red Flags

• Global high resolution lightmap settings
• 5+ light bounces
• Entire world in single bake
• Overlapping/z-fighting geometry

Overlapping Lights Overbright

Id

overlapping-lights-overbright

Summary

Multiple overlapping lights cause blown-out overbright areas

Severity

high

Situation

Areas with multiple lights become completely white/overexposed

Why

Light is additive. Two 1-intensity lights in the same spot = 2 intensity. This is physically correct but often unintended. Combined with bloom, areas quickly become blown out. Artists often create lights without checking combined contribution.

Solution

1. Light intensity audit:

• View scene without post-processing
• Check luminance/exposure values
• Keep important areas in 0-1 range for LDR

2. Light overlap planning:

• Visualize light radius/attenuation
• Reduce intensity of overlapping lights
• Key light should dominate, fills should be subtle

3. Use light groups:

• Isolate lights to check individual contribution
• A/B test light combinations
• Document intended combined intensity

4. Exposure/tonemapping adjustment:

• Set exposure for brightest intended area
• Use highlight compression (filmic tonemapping)
• Bloom threshold relative to scene luminance

5. Physical light units:

• Use real-world values (lumens, lux)
• Natural attenuation prevents overbright
• Requires proper exposure workflow

Symptoms

• White/blown out areas
• Bloom explosion in certain spots
• Brightness varies wildly across scene
• Can't see detail in bright areas
• Looks fine without post-processing

Detection Pattern

intensity|lightIntensity|color.\\

Version Range

*

Red Flags

• Multiple point lights in same area
• No consideration of additive contribution
• Bloom threshold set too low
• No exposure compensation

Dynamic Objects Baked Mismatch

Id

dynamic-objects-baked-mismatch

Summary

Dynamic objects look wrong in baked lighting environments

Severity

critical

Situation

Characters/props don't match the lighting of the baked environment

Why

Baked lighting stores in textures (lightmaps) only for static geometry. Dynamic objects use light probes for indirect light and realtime lights for direct. If probes don't capture the baked lighting accurately, or if the main light is different for baked vs realtime, dynamic objects look pasted in.

Solution

1. Ensure main light matches:

• Realtime light with same direction/color as baked
• Mixed mode: same light for both bake and realtime
• Match shadow softness and color

2. Accurate probe placement:

• Dense probes in player-accessible areas
• Capture all lighting variations
• Validate by moving debug sphere through scene

3. Reflection probe alignment:

• Interior probes for indoor spaces
• Box projection for rooms
• Update probes if environment changes

4. Consider hybrid approaches:

• Realtime GI for dynamic contribution (expensive)
• SSGI/RTGI for additional indirect
• Ambient override per area

5. Art direction tricks:

• Dedicated character rim light
• Subtle ambient boost on characters
• Match key light exactly

Symptoms

• Characters look "pasted in"
• Wrong color tint on dynamic objects
• Missing indirect lighting on characters
• Reflections don't match environment
• Moving objects "pop" at probe boundaries

Detection Pattern

lightProbe|useLightProbes|ContributeGI

Version Range

*

Red Flags

• Only skybox reflection, no reflection probes
• Different sun angle for bake vs realtime
• Sparse light probes in player areas
• No mixed mode lights

Reflection Probe Parallax Errors

Id

reflection-probe-parallax-errors

Summary

Reflections slide/stretch incorrectly on surfaces

Severity

medium

Situation

Metallic surfaces show reflections in wrong positions

Why

Standard reflection probes capture from a single point. When the reflecting surface is far from that point, the reflection appears in the wrong place. Box projection helps for rooms but requires careful setup. Probe blending at boundaries can also cause issues.

Solution

1. Enable box projection:

• Set probe bounds to match room geometry
• Adjust box offset to room center
• Works best for box-shaped rooms

2. Probe placement:

• Center of room for interiors
• One probe per distinct space
• More probes for large/complex areas

3. Blend distance tuning:

• Reduce blend distance to minimize overlap
• Sharp transition sometimes better than wrong blend
• Test metallic objects at boundaries

4. For complex geometry:

• Multiple probes with careful blending
• Accept limitations of probe-based reflections
• Consider SSR for accurate reflections (more expensive)

5. Planar reflections:

• For flat surfaces (water, mirrors)
• More expensive but accurate
• Only enable where needed

Symptoms

• Reflections slide as camera moves
• Wrong objects visible in reflection
• Stretching at room edges
• Reflection "pops" at probe boundaries
• Metallic objects look incorrect

Detection Pattern

ReflectionProbe|boxProjection|blendDistance

Version Range

*

Red Flags

• Single reflection probe for entire level
• Box projection disabled in interiors
• Probes placed in walls/corners
• Very large blend distances

Mobile Lighting Performance

Id

mobile-lighting-performance

Summary

Lighting design that works on PC destroys mobile performance

Severity

critical

Situation

Game runs well on desktop, terribly on mobile devices

Why

Mobile GPUs are fundamentally different from desktop. They're tile-based, bandwidth limited, and thermal constrained. Desktop lighting strategies don't transfer. Realtime shadows are luxury. Multiple realtime lights are expensive. Lightmaps hit memory limits.

Solution

1. Realtime light limits:

• 1-2 realtime lights max (often just sun)
• Avoid point/spot shadows entirely if possible
• Use baked shadows with realtime directional

2. Lightmap optimization:

• Lower resolution (10-20% of desktop)
• Aggressive compression
• Fewer bounces (1-2 max)
• ASTC compression for size

3. Simplified probe setups:

• Fewer, larger probe volumes
• Lower resolution probe capture
• Consider flat ambient for some scenes

4. Shadow simplification:

• Single cascade, shorter distance
• Lower resolution shadow maps
• Consider blob shadows for characters

5. Quality tiers:

• Separate lighting setups per tier
• Mobile: baked only, simple probes
• PC: full realtime, high-res everything

6. Avoid:

• Volumetric lighting
• Screen-space effects (SSAO, SSR)
• HDR rendering (if possible)
• Complex tonemapping

Symptoms

• Frame rate drops below 30 fps
• Device overheats
• Battery drains rapidly
• Visual quality same but performance terrible
• Works in editor, dies on device

Detection Pattern

QualitySettings|graphicsTier|mobile

Version Range

*

Red Flags

• Same lighting settings for mobile and desktop
• Realtime shadows on mobile
• No mobile testing during development
• No quality tier system

Emissive No Contribution

Id

emissive-no-contribution

Summary

Emissive materials don't actually light the environment

Severity

medium

Situation

Bright glowing materials don't illuminate nearby surfaces

Why

By default, emissive materials only affect their own appearance - they don't contribute to scene lighting. This is a common misconception. Emission contribution to lightmaps requires explicit settings, and realtime emission contribution requires actual lights or advanced GI.

Solution

1. For baked GI contribution: Unity: Enable "Contribute Global Illumination" on mesh Set Emission > Global Illumination > Baked Unreal: Set Emissive for Static Lighting on material Bake lightmaps

2. Pair with actual lights:

• Place point light at emissive surface
• Match light color and rough intensity
• Light does the work, emissive provides visual

3. For realtime emission:

• Lumen (UE5) handles this automatically
• RTGI solutions can capture emission
• Otherwise, must use actual lights

4. Area light matching:

• If engine supports, use area light shaped to emissive
• Rectangle lights for screens
• Disc lights for circular emissives

Symptoms

• Neon sign doesn't light nearby wall
• TV screen doesn't illuminate room
• Glowing material looks bright but no light cast
• Emissive looks wrong compared to actual lights

Detection Pattern

emission|emissive|_EmissionColor|Global Illumination

Version Range

*

Red Flags

• Expecting emission to light scene without configuration
• No separate light paired with emissive
• Emissive intensity not set for GI contribution
• Realtime emission expected without proper GI

Hdr Bloom Clipping

Id

hdr-bloom-clipping

Summary

Bloom looks wrong due to improper HDR handling

Severity

medium

Situation

Bloom appears as harsh circles or doesn't appear at all

Why

Bloom extracts bright pixels above a threshold. If your brightest value is 1.0 (LDR), bloom threshold of 1.0 captures nothing. If values are too high without proper tonemapping, bloom explodes. The threshold must be set relative to your scene's actual luminance values.

Solution

1. Work in true HDR:

• Render target: R16G16B16A16_Float
• Light intensities can exceed 1.0
• Sun at 5-10 intensity, indoor lights lower

2. Set threshold properly:

• Threshold relative to scene values
• If max scene value is 3.0, threshold at 1.5
• Soft knee/threshold for gradual falloff

3. Bloom before tonemapping:

• Extract bloom in HDR space
• Apply tonemapping after bloom composite
• Otherwise bloom loses energy

4. Physical light values help:

• Use lumens/lux for lights
• Natural range informs threshold
• Consistent across scenes

5. Intensity and scatter:

• Lower intensity for subtle bloom
• Higher scatter for softer, larger bloom
• Avoid harsh circular artifacts

Symptoms

• No bloom on bright objects
• Bloom as harsh circles/halos
• Bloom intensity varies wildly between scenes
• Tonemapped image has no bloom at all
• Bloom applies to everything or nothing

Detection Pattern

bloom|Bloom|threshold|intensity

Version Range

*

Red Flags

• Bloom threshold = 1.0 with LDR values
• Bloom after tonemapping
• No consideration of scene luminance range
• Same bloom settings for all scenes

Lighting Design - Validations

Extreme Lightmap Resolution

Id

lighting-extreme-lightmap-resolution

Severity

warning

Type

regex

Pattern

• lightmapResolution\s[=:]\s[5-9]\d{2}
• lightmapResolution\s[=:]\s\d{4,}
• Light\sMap\sResolution["\s:]*[5-9]\d{2}
• Light\sMap\sResolution["\s:]*\d{4,}

Message

Very high lightmap resolution (512+). This will increase bake time and memory significantly.

Fix Action

Reserve high resolution (256-512) for hero surfaces only. Use 32-128 for most geometry.

Applies To

• *.unity
• *.prefab
• *.asset
• *.uasset
• *.ini

Zero Lightmap UV Padding

Id

lighting-zero-lightmap-padding

Severity

error

Type

regex

Pattern

• packMargin\s[=:]\s0(?:\.0+)?(?!\d)
• Pack\sMargin["\s:]0(?:\.0+)?(?!\d)

Message

Lightmap UV pack margin is 0. This causes visible seams between UV islands.

Fix Action

Set pack margin to at least 2-4 texels worth (0.01-0.02 at typical resolutions).

Applies To

• *.unity
• *.prefab
• *.asset

Excessive Shadow Distance

Id

lighting-excessive-shadow-distance

Severity

warning

Type

regex

Pattern

• shadowDistance\s[=:]\s\d{4,}
• Shadow\sDistance["\s:]\d{4,}
• ShadowMaxDistance\s[=:]\s\d{4,}

Message

Shadow distance over 1000 units. This spreads shadow map resolution thin and impacts performance.

Fix Action

Reduce shadow distance to match actual gameplay needs. Use fog to hide shadow pop-out.

Applies To

• *.unity
• *.asset
• *.ini
• *.uasset

Zero Shadow Bias

Id

lighting-zero-shadow-bias

Severity

error

Type

regex

Pattern

• shadowBias\s[=:]\s0(?:\.0+)?(?!\d)
• normalBias\s[=:]\s0(?:\.0+)?(?!\d)
• ShadowDepthBias\s[=:]\s0(?:\.0+)?(?!\d)

Message

Shadow bias is 0. This causes shadow acne (dotted patterns on surfaces).

Fix Action

Set shadow bias to 0.05-0.1 and normal bias to 0.4-1.0. Tune for minimal peter-panning.

Applies To

• *.unity
• *.prefab
• *.asset
• *.uasset

Single Shadow Cascade Outdoor

Id

lighting-single-shadow-cascade

Severity

warning

Type

regex

Pattern

• shadowCascadeCount\s[=:]\s1(?!\d)
• shadowCascades\s[=:]\s1(?!\d)
• NumDynamicShadowCascades\s[=:]\s1(?!\d)

Message

Only 1 shadow cascade configured. Outdoor scenes benefit from 2-4 cascades for quality distribution.

Fix Action

Use 2-4 cascades for directional light. Tune cascade distances based on gameplay range.

Applies To

• *.unity
• *.asset
• *.ini
• *.uasset

Extreme Light Intensity

Id

lighting-extreme-intensity

Severity

warning

Type

regex

Pattern

• intensity\s[=:]\s\d{3,}
• lightIntensity\s[=:]\s\d{3,}
• Intensity\s[=:]\s\d{3,}

Message

Light intensity over 100. Unless using physical light units, this may cause blown-out lighting.

Fix Action

Review intensity in context of HDR pipeline. If using arbitrary units, keep most lights 0.5-3.

Applies To

• *.unity
• *.prefab
• *.asset
• *.uasset
• *.gd
• *.tscn

Pure Saturated Light Color

Id

lighting-pure-color-light

Severity

warning

Type

regex

Pattern

• color\s[=:]\s(?:Color\()?(?:1\.0,\s0\.0,\s0\.0|0\.0,\s1\.0,\s0\.0|0\.0,\s0\.0,\s1\.0)
• LightColor\s[=:]\s\(R=(?:255|1\.0),G=0,B=0\)
• LightColor\s[=:]\s\(R=0,G=(?:255|1\.0),B=0\)
• LightColor\s[=:]\s\(R=0,G=0,B=(?:255|1\.0)\)

Message

Pure saturated color light (pure red, green, or blue). This rarely looks natural.

Fix Action

Use color temperatures for natural light (2700K-6500K). Desaturate for realistic appearance.

Applies To

• *.unity
• *.prefab
• *.asset
• *.uasset
• *.tscn

Missing Reflection Probe in Interior

Id

lighting-missing-reflection-probe

Severity

warning

Type

regex

Pattern

• ReflectionProbe

Message

Check if reflection probes are present for interior spaces. Without them, interiors reflect the skybox.

Fix Action

Add ReflectionProbe components in each distinct interior space with box projection enabled.

Applies To

• *.unity

Potential Probe Inside Geometry

Id

lighting-probe-inside-geometry

Severity

warning

Type

regex

Pattern

• LightProbeGroup
• lightProbes

Message

Review light probe placement. Auto-generated probes may be inside walls, causing black lighting.

Fix Action

Manually inspect probe positions. Remove probes inside geometry. Add probes at lighting transitions.

Applies To

• *.unity
• *.prefab

Realtime Point Light Shadows

Id

lighting-realtime-point-shadow

Severity

warning

Type

regex

Pattern

• shadowType\s[=:]\s(?:Hard|Soft)(?:.*pointLight|point)
• castShadows\s[=:]\strue(?:.*pointLight|point)
• Point.Shadow.Type\s[=:]\s(?:Shadow|Raytraced)

Message

Point light with realtime shadows enabled. This is expensive (6 shadow maps per light).

Fix Action

Consider: baked shadows, only shadow from key point lights, or shadow-less fill lights.

Applies To

• *.unity
• *.prefab
• *.asset
• *.uasset

Many Realtime Lights

Id

lighting-many-realtime-lights

Severity

warning

Type

regex

Pattern

• lightType\s[=:]\s(?:Point|Spot)

Message

Check realtime light count. Many realtime lights impact performance, especially with shadows.

Fix Action

Use baked lighting where possible. Limit realtime to moving objects and key lights.

Applies To

• *.unity
• *.prefab

High Light Bounce Count

Id

lighting-high-bounce-count

Severity

warning

Type

regex

Pattern

• bounces\s[=:]\s[5-9]
• bounces\s[=:]\s\d{2,}
• NumIndirectLightingBounces\s[=:]\s[5-9]
• NumSkyLightingBounces\s[=:]\s[5-9]

Message

Light bounce count over 4. Higher bounces have diminishing returns and exponential bake time.

Fix Action

2-3 bounces captures most indirect lighting. Only increase for very specific needs.

Applies To

• *.unity
• *.asset
• *.uasset
• *.ini

Bloom Threshold at Maximum

Id

lighting-bloom-threshold-one

Severity

warning

Type

regex

Pattern

• bloomThreshold\s[=:]\s1(?:\.0+)?(?!\d)
• threshold\s[=:]\s1(?:\.0+)?(?:\s//.bloom)?

Message

Bloom threshold at 1.0. If scene values are LDR (max 1.0), bloom won't appear.

Fix Action

Set threshold relative to scene luminance. For HDR, 1.0-2.0. For LDR, 0.8-0.9.

Applies To

• *.unity
• *.asset
• *.cs
• *.shader

Missing Exposure Configuration

Id

lighting-exposure-not-configured

Severity

warning

Type

regex

Pattern

• exposure\s[=:]\s(?:null|None|0(?:\.0+)?)

Message

Exposure may not be configured. Without proper exposure, HDR scenes will look incorrect.

Fix Action

Set up exposure (auto or fixed) appropriate for scene brightness range.

Applies To

• *.unity
• *.asset

Realtime GI on Mobile Build

Id

lighting-mobile-realtime-gi

Severity

error

Type

regex

Pattern

• realtimeGI\s[=:]\strue(?:.*mobile)?
• UpdateGI\s[=:]\strue

Message

Realtime GI detected which may be targeting mobile. This is too expensive for most mobile devices.

Fix Action

Use fully baked lighting for mobile. Update probe data only at level load if needed.

Applies To

• *.unity
• *.asset

Volumetric Effects on Mobile

Id

lighting-mobile-volumetrics

Severity

warning

Type

regex

Pattern

• volumetric(?:Fog|Lighting|Clouds)\s[=:]\strue
• VolumetricFog\s[=:]\strue

Message

Volumetric effects enabled. These are typically too expensive for mobile platforms.

Fix Action

Disable volumetrics on mobile quality tier. Use simple fog and particle effects instead.

Applies To

• *.unity
• *.asset
• *.uasset

Manual Gamma Conversion in Lighting Shader

Id

lighting-manual-gamma-in-shader

Severity

warning

Type

regex

Pattern

• pow\s\([^,]+,\s2\.2\s*\)
• pow\s\([^,]+,\s0\.454
• pow\s\([^,]+,\s1\.0\s/\s2\.2

Message

Manual gamma conversion in shader. Ensure this is intentional and matches your color space settings.

Fix Action

Use engine's linear/gamma workflow. Manual conversion should only be for specific cases.

Applies To

• *.shader
• *.hlsl
• *.glsl
• *.cginc

Light Direction Normalize in Fragment

Id

lighting-normalize-in-fragment

Severity

warning

Type

regex

Pattern

• normalize\s\(\slightDir
• normalize\s\(\s_WorldSpaceLightPos

Message

Normalizing light direction per-pixel. For directional lights, this can be done once in vertex shader.

Fix Action

For directional lights, normalize in vertex shader and interpolate. Point/spot need per-pixel.

Applies To

• *.shader
• *.hlsl
• *.glsl
• *.cginc

Missing Lightmass Importance Volume

Id

lighting-unreal-no-importance-volume

Severity

warning

Type

regex

Pattern

• LightmassImportanceVolume

Message

Check for Lightmass Importance Volume. Without it, light baking quality suffers outside playable area.

Fix Action

Add LightmassImportanceVolume covering all playable areas to focus bake quality.

Applies To

• *.umap
• *.uasset

Lumen Quality Settings

Id

lighting-unreal-lumen-quality

Severity

warning

Type

regex

Pattern

• LumenSceneLightingQuality\s[=:]\s(?:Low|Preview)
• LumenReflectionsQuality\s[=:]\s(?:Low|Preview)

Message

Lumen quality set to Low/Preview. Fine for development, ensure quality is set for final.

Fix Action

Set appropriate Lumen quality for target platform. Test on target hardware.

Applies To

• *.ini
• *.uasset

SDFGI Without Bounds

Id

lighting-godot-sdfgi-bounds

Severity

warning

Type

regex

Pattern

• sdfgi_enabled\s[=:]\strue

Message

SDFGI enabled. Ensure SDFGI bounds are properly configured for your scene size.

Fix Action

Adjust SDFGI cascade sizes and max distance to match scene dimensions.

Applies To

• *.tscn
• *.tres
• *.gd

Godot OmniLight Shadows

Id

lighting-godot-omni-shadow

Severity

warning

Type

regex

Pattern

• OmniLight3D(?:.\n).shadow_enabled\s[=:]\s*true

Message

OmniLight with shadows enabled. Point light shadows are expensive (6 renders per light).

Fix Action

Limit shadowed omni lights. Consider SpotLight for directional shadows instead.

Applies To

• *.tscn
• *.tres

Three.js Shadow Without Bias

Id

lighting-threejs-no-shadow-bias

Severity

warning

Type

regex

Pattern

• castShadow\s=\strue(?:(?!bias).)*$
• shadow\.(?!.*bias)

Message

Shadow casting enabled but no bias configured. Default bias may cause shadow acne.

Fix Action

Set light.shadow.bias = -0.0001 to -0.001 (adjust based on scene scale).

Applies To

• *.js
• *.ts
• *.jsx
• *.tsx

Three.js Default Shadow Map Size

Id

lighting-threejs-shadow-map-size

Severity

warning

Type

regex

Pattern

• castShadow\s=\strue(?:(?!mapSize).)*$

Message

Shadow enabled but map size not configured. Default 512 may be too low for quality.

Fix Action

Set light.shadow.mapSize.width/height = 1024 or 2048 for better quality.

Applies To

• *.js
• *.ts
• *.jsx
• *.tsx

Light Without Falloff/Attenuation

Id

lighting-no-falloff

Severity

warning

Type

regex

Pattern

• range\s[=:]\s(?:Infinity|0(?:\.0+)?)
• attenuation\s[=:]\s(?:None|0)

Message

Light without proper falloff/attenuation. Infinite range lights are unrealistic and can impact performance.

Fix Action

Set appropriate range based on light intensity. Use inverse-square falloff for realism.

Applies To

• *.unity
• *.prefab
• *.asset
• *.tscn
• *.js
• *.ts