ADR 276: light sources

[nearnshaw]

No description provided.

[cloudflare-workers-and-pages]

Deploying adr with    Cloudflare Pages

Latest commit:	5e914b1
Status:	✅  Deploy successful!
Preview URL:	https://59372943.adr-cvq.pages.dev
Branch Preview URL:	https://light-sources.adr-cvq.pages.dev

View logs

[leanmendoza]

Thank you for putting this ADR for light sources! This is a crucial feature for Decentraland.
I want to take this place to debate this, given the previous work we've done in the protocol. Please take a look before reading the next part:

• https://github.com/decentraland/protocol/blob/protocol-squad/proto/decentraland/sdk/components/light.proto
• https://github.com/decentraland/protocol/blob/protocol-squad/proto/decentraland/sdk/components/spotlight.proto
• https://github.com/decentraland/protocol/blob/protocol-squad/proto/decentraland/sdk/components/global_light.proto

I had written a whole text to comment as a review, but then I split into different topics and comment each part of the ADR to keep the conversation cleaner :)

[leanmendoza]

I suggest reconsidering the use of arbitrary 0-1 values for light intensity in favor of physically-based units (lumens/m² or lux). This would provide several advantages:

1. Predictability: Artists and developers can reference real-world light measurements

   • A 100W household bulb (~1200 lumens) = ~100 lux at 1m
   • Sunlight varies from 400 lux (sunrise) to 10,000 lux (midday)

2. Consistency: Light behavior becomes more predictable across different implementations and scenes

3. Realism: Natural light falloff can be accurately modeled using the inverse square law

4. Interoperability: Better alignment with industry standards and other 3D tools

We have a working implementation of this approach in the protocol files that you might want to review: light.proto

The property could be renamed to illuminance to better reflect its physical meaning. The actual visual impact would still be subject to the renderer's exposure and tone mapping, but the relative relationships between lights would be preserved.

[aixaCode]

Good suggestion, how about we use Lumens instead, it measure the total amount of light emitted by a source. This makes it the ideal metric for describing the output of a light source, independent of where or how it is used. Lumens are inherently tied to the light source itself, while lux depends on the environment. Since we want to define properties of the light sources rather than the effect of light on a surface, lumens are a better fit, in my option.

[leanmendoza]

Regarding light range, I suggest following GLTF's KHR_lights_punctual approach:

1. The range should be optional (or even more not being added now). When unspecified, light naturally SHOULD attenuate following the inverse square law (1/d²)

2. When specified, GLTF uses this attenuation formula after following the inverse square law, then:

attenuation = max(min(1.0 - (distance/range)^4, 1), 0) / distance^2

Within the range of the light, attenuation should follow the inverse square law as closely as possible, although some non-quadratic falloff near the edge of the range may be used to avoid a hard cutoff

This provides:

• Natural physical falloff (1/d²)
• Smooth cutoff at the range distance
• Performance optimization opportunity (GPU can skip calculations beyond range)

Instead of having developers guess appropriate range values, we could:

• Make range optional
• Calculate a reasonable default cutoff based on illuminance
• Allow manual override when needed for performance tuning

This aligns with industry standards while maintaining physically-based behavior.

[leanmendoza]

Regarding the component structure, I'd like to discuss an alternative approach based on composition rather than a single component with type discrimination:

Instead of:

interface LightSource {
  type: 'point' | 'spot' | 'directional';
  intensity: number;
  // ... common properties ...
  // spot-specific properties when type === 'spot'
  angle?: number;
  innerAngle?: number;
}

Consider a composable approach:

interface Light {
  illuminance: number;
  color: Color3;
  shadows: boolean;
}

interface Spotlight {
  angle: number;
  innerAngle?: number;
}

interface GlobalLight {
  direction?: Vector3;
  ambientColor?: Color3;
  ambientBrightness?: number;
}

Benefits:

1. Cleaner Separation: Each component handles one specific aspect of lighting
2. Type Safety: No need for runtime type checking or optional properties
3. Extensibility: New light types can be added without modifying existing components
4. Flexibility: SDKs can provide their own abstractions while the protocol remains clean
5. Clarity: Entity behavior is determined by component composition:
   • Point Light = Entity + Light
   • Spot Light = Entity + Light + Spotlight
   • Directional Light = Root Entity + Light + GlobalLight

[leanmendoza]

Regarding shadows, I suggest expanding this section to address several important aspects:

1. Shadow Control
   Instead of a simple boolean, consider these key properties:

• shadows: boolean - Whether the light casts shadows
• Default values should differ by light type:
  • Point/Spot lights: false (performance consideration)
  • Global/Directional light: true (essential for scene depth)

2. Implementation Considerations
   Add a note that shadow rendering may vary by platform:

// Even when shadows = true, the engine may:
// - Not display shadows at all
// - Show shadows for limited number of lights
// - Vary shadow quality
// Based on:
// - Platform capabilities
// - User settings
// - Performance requirements

3. Priority System
   Consider adding guidance for implementations about shadow priority:

• Global/Directional light shadows take precedence
• Point/Spot lights could use distance/illuminance for priority

This approach:

• Gives developers clear expectations
• Allows implementations to optimize performance
• Maintains flexibility for different platforms
• Provides predictable behavior across scenes

See our protocol implementation for a working example of these concepts.

[leanmendoza]

The Global Light section needs more detailed specification. Currently, there's a gap between point/spot lights and scene-wide lighting. Consider:

1. Global Light Components
   A scene's global lighting should be configurable through two complementary components:

// Core light properties (when attached to root)
interface Light {
  illuminance: number;  // 400 (sunrise) to 10,000 (midday)
  color: Color3;
  shadows: boolean;
}

// Global light specific properties
interface GlobalLight {
  direction?: Vector3;      // Sunlight direction
  ambientColor?: Color3;    // Sky/environment contribution
  ambientBrightness?: number; // Overall scene brightness multiplier
}

2. Root Entity Behavior

• Light on root = Override default directional (sun) light
• GlobalLight on root = Control direction and ambient settings
• Both components can work independently:
  • Light alone = Change sun color/intensity
  • GlobalLight alone = Change direction/ambient
  • Both = Full control

3. Default Behavior
   Add specification for default values:

• Default directional light should match typical daylight
• Direction could vary with time-of-day (if implemented)
• Reasonable ambient light for scene visibility

This matches our protocol implementation while providing clear guidance for scene creators and engine implementations.

[leanmendoza]

I suggest removing the "Limitations and Considerations" section from this ADR. Here's why:

1. Separation of Concerns

• This ADR should focus on defining the light component interfaces and their behavior
• Implementation details like performance limits should be handled separately:
  • Engine-specific optimizations
  • Platform-specific limitations
  • Scene-level restrictions

2. Flexibility for Implementations
   Let each explorer/renderer decide how to handle:

• Maximum number of lights
• Shadow map allocation
• Performance optimizations
• Mobile vs desktop capabilities
• Low-end vs high-end configurations

3. SDK's Role
   The SDK can provide:

• Platform-specific warnings
• Best practice guidelines
• Performance recommendations
• Scene validation tools

4. Better Documentation Structure
   These topics deserve their own documentation:

• Performance best practices ADR
• Scene optimization guide
• Platform compatibility matrix
• Implementation guidelines

This approach:

• Keeps the component specification clean and focused
• Allows for platform-specific optimizations
• Enables future improvements without spec changes
• Lets implementations evolve independently

[aixaCode]

I’m okay with removing the Limitations and Considerations section, but I’d like to challenge this approach slightly. These limitations guide how each client should behave, ensuring consistency across implementations. Without them, we risk significant divergence in how the feature works across clients, which might shift responsibility to creators to adapt to different behaviors.

Creating a separate ADR or RFC for these constraints could work, but we’d need to align on how the protocol should remain generic while still providing a baseline for consistent behavior. I also see the value in keeping this ADR abstract to allow for experimentation and flexibility, but it’s crucial we ensure creators aren’t left with unpredictable experiences due to discrepancies between clients.

Are we ok with having that differences between clients?
If we move this to another ADR, then we need to provide a clear guidelines, tools and documentation for creators to navigate that different clients.