From 389342749d61a223169cc5e844dc0aab6428abe4 Mon Sep 17 00:00:00 2001 From: nearnshaw Date: Wed, 13 Nov 2024 16:48:40 -0300 Subject: [PATCH 1/4] light soruces --- content/ADR-253-light-sources.md | 116 +++++++++++++++++++++++++++++++ 1 file changed, 116 insertions(+) create mode 100644 content/ADR-253-light-sources.md diff --git a/content/ADR-253-light-sources.md b/content/ADR-253-light-sources.md new file mode 100644 index 00000000..c0d39d5e --- /dev/null +++ b/content/ADR-253-light-sources.md @@ -0,0 +1,116 @@ +--- +layout: adr +adr: 253 +title: Light Sources +date: 2024-11-13 +status: Review +type: RFC +spdx-license: CC0-1.0 +authors: + - nearnshaw +--- + +# Abstract + +This document explores a new feature that has been missing from Decentraland scenes: letting creators control light. We will allow creators to define a limited number of entities in their scenes that will behave as sources of light, and offer a number of parameters to control the kind of light-source, color, luminosity, etc. + +We also explore how we can make this work in an open world, and its implications. +We also discuss limitations that should be imposed, to prevent a degradation of the experience if this feature is misused. + +# Context + +Up until now, all light in Decentraland came from a single rigid source (the sun or moon). Enabling creators to create their own light sources enables a lot of creative possibilities. We see the control of light as important for the following: + +- Creating ambience and enhance the architecture of a scene +- Flashy effects for music festivals, fashion week, and other events of high visual impact +- Light as a visual cue: guide the player towards what’s important in a scene by shining a light on it. Signal a change in what’s going on in the scene by switching the lights to a different intensity or color. +- Darkness as a mechanic for spooky games +- Flashlights as a mechanic: the act of having to point a light to reveal what’s there can be a whole game mechanic. + +To be able to play with darkness, we'll also need to provide controls to be able to disable the global default light sources and play with that. + +Note: Some GLTF models come with lights packaged as nodes inside the structure of the model. We should ignore those completely. The only lights we will be rendering are the ones defined via code using the LightSource component. + +## Component description + +We should create a `LightSource` component that, when added to an entity, tells the engine to shine a light from that entity’s Transform position. + +A Type field will let you chose between _Spot_ and _Point_ light. We believe these two types of lights are enough for now, the component could be expanded in the future if we want to include other types. + +The following fields will be available on both types of light: + +- Color: _Color4_ +- Intensity: _number_ +- Range: _number_ +- Active: _boolean_ + +In lights of type _Spot_, we will also include: + +- Inner angle +- Outer angle + +These two fields define how wide to make both cones, the full intensity center and the lighter margins. +Caveats for these two: - max 180 - inner angle can’t be more than outer angle + +The `Active` flag lets creators easily turn a light source on or off. We could otherwise achieve the same by setting intensity to 0, but offering a switch makes it easier to retain the prior configuration. + +## Shadows + +Note: This feature will likely not ba a part of the initial implementation. It's included here to discuss the full vision, but field for this may not be present on the protocol or the SDK until later. + +By default lights won’t have shadows. Each light source can chose if they want shadows or not, and if to use hard shadows or soft shadows. + +We will add fields for this on the `LightSource` component: + +- Shadow type: No shadows / Hard Shadows / Soft shadows + +- The creator can chose the shadow resolution as a setting on each light source +- The shadow resolution is picked by the player in the user’s settings, as a global option. If they have low settings they’ll always use low res + +## Limitations + +Note: This aspect will likely not ba a part of the initial implementation. It's included here to discuss the full vision, but field for this may not be present on the protocol or the SDK until later. Although restrictions will be applied at an engine level, and each engine could theoretically have different values, it's ideal that we're all aligned on these values, so experiences don't differ accross engines. + +We will start with restrictive limitations, and raise them gradually if necessary. + +1 light source per parcel. We also need a maximum limit for large scenes. +What is a good number? TDB while developing and testing. + +We should also constrain the maximum brightness, otherwise we could completely blind the player. TDB while developing and testing. + +If a light is not being rendered because of going over the limits, the engine should print an error message to console, to make creators aware of the reasons. + +## Open world considerations + +We advise that each engine only renders the lights of the current scene you’re standing on. In this way: + +- Neighboring scenes don’t get affected in performance +- Neighboring scenes don’t mess with the esthetic of others, at least not when you’re standing on that other scene. + +Engines can add a default behavior of fading lights in/out over a period of a second whenever you switch scenes. This is to avoid abrupt light changes when you walk from one parcel to another. + +### Affect global ambient light + +Note: This point deserves its own ADR and will be addressed in the future, but it's good to start considering how it will interact. + +Creators might want to turn off the default light of the sun, to have better control over lighting conditions. This is essential for example to create a spooky ambiance. + +They could be done via a component on the root entity. Otherwise it could be a scene setting in the scene.json. TBD. + +It should ideally be possible to do both in worlds and in Genesis City, but perhaps we can start with enabling it just in worlds for now if that’s easier. + +To consider: Instead of turning on-off, can we also dim or tint the default light? + +## Serialization + +```yaml +parameters: +``` + +```protobuf + +``` + +## Semantics + +### Example From 5e914b18d9eff6f9bb609319fba5f294e8ab2828 Mon Sep 17 00:00:00 2001 From: nearnshaw Date: Thu, 14 Nov 2024 18:00:00 -0300 Subject: [PATCH 2/4] retouches based on feedback --- content/ADR-253-light-sources.md | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/content/ADR-253-light-sources.md b/content/ADR-253-light-sources.md index c0d39d5e..7003df0d 100644 --- a/content/ADR-253-light-sources.md +++ b/content/ADR-253-light-sources.md @@ -3,7 +3,7 @@ layout: adr adr: 253 title: Light Sources date: 2024-11-13 -status: Review +status: Draft type: RFC spdx-license: CC0-1.0 authors: @@ -37,20 +37,21 @@ We should create a `LightSource` component that, when added to an entity, tells A Type field will let you chose between _Spot_ and _Point_ light. We believe these two types of lights are enough for now, the component could be expanded in the future if we want to include other types. +A _Spot_ light projects a cone of concentrated light in a single direction, originating from a single point in the scene. It's ideal for shows and theatric effects, it can also be used to shine a light on something with a functional intention. + +A _Point_ light expands in all directions from a point in the scene, illuminating the space in a more subtle way. The point of origin is often not easy to pinpoint for the player. + The following fields will be available on both types of light: -- Color: _Color4_ -- Intensity: _number_ -- Range: _number_ -- Active: _boolean_ +- Color: _Color4_ The color of the light +- Intensity: _number_ The luminosity value of the light, from 0 to 1. +- Range: _number_ The maximum distance that can be affected by the light source. +- Active: _boolean_ Determines if the light is currently on or not. In lights of type _Spot_, we will also include: -- Inner angle -- Outer angle - -These two fields define how wide to make both cones, the full intensity center and the lighter margins. -Caveats for these two: - max 180 - inner angle can’t be more than outer angle +- Inner angle: _number_ This angle, measured from the direction vertex, defines a cone where the light has full intensity. Max 180, can’t be more than outer angle. +- Outer angle: _number_ This angle, measured from the direction vertex, defines a cone where the light has an effect, the intensity decreases farther away from the inner cone. Max 180. The `Active` flag lets creators easily turn a light source on or off. We could otherwise achieve the same by setting intensity to 0, but offering a switch makes it easier to retain the prior configuration. From 1cee77db139b4c18acac425e7adf90f042f870ee Mon Sep 17 00:00:00 2001 From: nearnshaw Date: Wed, 27 Nov 2024 15:39:31 -0300 Subject: [PATCH 3/4] modifications --- content/ADR-253-light-sources.md | 41 ++++++++++++++++++++++---------- 1 file changed, 29 insertions(+), 12 deletions(-) diff --git a/content/ADR-253-light-sources.md b/content/ADR-253-light-sources.md index 7003df0d..2652e2f2 100644 --- a/content/ADR-253-light-sources.md +++ b/content/ADR-253-light-sources.md @@ -35,38 +35,51 @@ Note: Some GLTF models come with lights packaged as nodes inside the structure o We should create a `LightSource` component that, when added to an entity, tells the engine to shine a light from that entity’s Transform position. -A Type field will let you chose between _Spot_ and _Point_ light. We believe these two types of lights are enough for now, the component could be expanded in the future if we want to include other types. +A Type field will let you chose between _Spot_, _Point_ and _Global_ light. We believe these types of lights are enough for now, the component could be expanded in the future if we want to include other types. A _Spot_ light projects a cone of concentrated light in a single direction, originating from a single point in the scene. It's ideal for shows and theatric effects, it can also be used to shine a light on something with a functional intention. A _Point_ light expands in all directions from a point in the scene, illuminating the space in a more subtle way. The point of origin is often not easy to pinpoint for the player. -The following fields will be available on both types of light: +A _Global_ light overrides the default ambient light from the sun or moon. It can only be added to the scene _root_ entity. + +The following fields will be available on all types of light: - Color: _Color4_ The color of the light -- Intensity: _number_ The luminosity value of the light, from 0 to 1. +- Brightness: _number_ The luminosity value of the light, expressed in Lumens. - Range: _number_ The maximum distance that can be affected by the light source. - Active: _boolean_ Determines if the light is currently on or not. +- Shadows: _boolean_. See [Shadows](#shadows) In lights of type _Spot_, we will also include: - Inner angle: _number_ This angle, measured from the direction vertex, defines a cone where the light has full intensity. Max 180, can’t be more than outer angle. - Outer angle: _number_ This angle, measured from the direction vertex, defines a cone where the light has an effect, the intensity decreases farther away from the inner cone. Max 180. -The `Active` flag lets creators easily turn a light source on or off. We could otherwise achieve the same by setting intensity to 0, but offering a switch makes it easier to retain the prior configuration. +In lights of type _Global_, we will also include: + +- direction: _Vector3_ Sunlight direction. +- ambientColor: _Color3_; // Sky/environment contribution +- ambientBrightness: _number_; // Overall scene brightness multiplier + +We will create helpers to make it easier for creators to create these components. For example: + +`LightSource.spotLight(myEntity, { brightness: 1000, angle: 10})` + +The `Active` flag lets creators easily turn a light source on or off. We could otherwise achieve the same by setting intensity to 0, but offering a switch makes it easier to retain the prior configuration. Another option debated was to use the `Visibility` component to turn off a light, but decided that we wanted to keep the visibility of any meshes as a separate independent consideration. ## Shadows Note: This feature will likely not ba a part of the initial implementation. It's included here to discuss the full vision, but field for this may not be present on the protocol or the SDK until later. -By default lights won’t have shadows. Each light source can chose if they want shadows or not, and if to use hard shadows or soft shadows. +All light sources will have a `shadows` property that determines if a light will cast shadows. -We will add fields for this on the `LightSource` component: +Default values should differ by light type: -- Shadow type: No shadows / Hard Shadows / Soft shadows +- Point/Spot lights: false (performance consideration) +- Global light: true (essential for scene depth) -- The creator can chose the shadow resolution as a setting on each light source -- The shadow resolution is picked by the player in the user’s settings, as a global option. If they have low settings they’ll always use low res +Each engine is free to determine considerations like shadow resolutions, or putting a limit on the number of shadows being computed and how to prioritize these. It's recommendable to make these variables dependent on user quality settings. ## Limitations @@ -96,11 +109,15 @@ Note: This point deserves its own ADR and will be addressed in the future, but i Creators might want to turn off the default light of the sun, to have better control over lighting conditions. This is essential for example to create a spooky ambiance. -They could be done via a component on the root entity. Otherwise it could be a scene setting in the scene.json. TBD. +This will be done by adding a `LightSource` component to the root entity, using the type `Global`. This will override the default directional light from the sun or moon. + +Default values: -It should ideally be possible to do both in worlds and in Genesis City, but perhaps we can start with enabling it just in worlds for now if that’s easier. +- Default directional light should match typical daylight +- Direction could vary with time-of-day (if implemented) +- Reasonable ambient light for scene visibility -To consider: Instead of turning on-off, can we also dim or tint the default light? +It should be possible to do both in worlds and in Genesis City. ## Serialization From c408d59f12aa24eb74621bbd0fdfc1f5fada6c8b Mon Sep 17 00:00:00 2001 From: nearnshaw Date: Thu, 28 Nov 2024 16:04:18 -0300 Subject: [PATCH 4/4] lux units --- content/ADR-253-light-sources.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/ADR-253-light-sources.md b/content/ADR-253-light-sources.md index 2652e2f2..737907f3 100644 --- a/content/ADR-253-light-sources.md +++ b/content/ADR-253-light-sources.md @@ -46,7 +46,7 @@ A _Global_ light overrides the default ambient light from the sun or moon. It ca The following fields will be available on all types of light: - Color: _Color4_ The color of the light -- Brightness: _number_ The luminosity value of the light, expressed in Lumens. +- Brightness: _number_ The luminosity value of the light. For _Spot_ and _Point_ light, this value is expressed in Lumens, for _Global_ light, it's expressed in Lux units (lumens per square metre). - Range: _number_ The maximum distance that can be affected by the light source. - Active: _boolean_ Determines if the light is currently on or not. - Shadows: _boolean_. See [Shadows](#shadows)