From 389342749d61a223169cc5e844dc0aab6428abe4 Mon Sep 17 00:00:00 2001 From: nearnshaw Date: Wed, 13 Nov 2024 16:48:40 -0300 Subject: [PATCH 1/6] 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 2611142ec4754e28e805db4d40a0195e1ba00bf0 Mon Sep 17 00:00:00 2001 From: nearnshaw Date: Mon, 2 Dec 2024 14:54:07 -0300 Subject: [PATCH 2/6] texture tween --- content/ADR-255-texture-tweens.md | 62 +++++++++++++++++++++++++++++++ 1 file changed, 62 insertions(+) create mode 100644 content/ADR-255-texture-tweens.md diff --git a/content/ADR-255-texture-tweens.md b/content/ADR-255-texture-tweens.md new file mode 100644 index 00000000..929d0abb --- /dev/null +++ b/content/ADR-255-texture-tweens.md @@ -0,0 +1,62 @@ +--- +layout: adr +adr: 255 +title: Texture tweens +date: 2024-12-02 +status: Draft +type: RFC +spdx-license: CC0-1.0 +authors: + - nearnshaw +--- + +# Abstract + +This document describes an approach for making it possible for creators to slide textures. This can be used to simulate running liquids, as well as many other interesting texture effects. + +This new feature combines very well with ADR-254 (GLTF Nodes), as it enables to do the same effects on the textures of any .gltf model. + +## Offset and tiling + +Today the settings available on a texture are limited. We need to be able to also change the offset and the scale of a texture. As part of this ADR we're also adding two new fields to all textures: + +- `offset`: _Vector2_, shifts the image from starting on the 0,0 mark. Default value `0,0` +- `tiling`: _Vector2_, determines how many times the texture fits on the surface. Default value `1,1`. The behavior of the remaining space on the texture will depend on the value of `wrapMode`. + +A creator could theoretically write a system that changes the `offset` value on every frame, but that would be very bad for performance. If something will continually change their offset, it's recommended to instead use a Tween for that. + +## Texture tween + +We'll define a new type of tween that affects the Material rather than the Transform. This is enabled by using the already existing Tween and TweenSequence components, with a new `TextureMove` option to be added to the existing `Move`, `Rotate`, and `Scale`. + +The new `TextureMove` option on the `Tween` component will have the following fields: + +- `TextureMovementType`: _(optional)_, defines if the movement will be on the `offset` or the `tiling` field (see section above) +- `start`: _Vector2_ the initial value of the offset or tiling +- `end`: _Vector2_ the final value of the offset or tiling + +The scene can also use a `TweenSequence` to make continuos movements possible, just like with other kinds of tweens. + +## Texture layers + +Materials have several textures besides the albedo_texture, including bump_texture, alpha_texture, emissive_texture. Because of shader optimization reasons, the alignment of these fields is not independent from each other. The albedo_texture behaves as the base texture, any changes to this texture affect all other layers equally. Other layers are then able to set their own different alignment properties, but these are compounded with those of the base texture. + +For example, if the offset of the base texture is `(0.2, 0)` and the offset of the emissive texture is `(0.1, 0)`, the final position of the emissive texture will end up equivalent to `(0.3, 0)`. + +This applies to changing the `offset` and `tiling` fields manually, as well as using a texture tween. + +The `TextureMove` Tween affects the base texture, so all textures move together with it. + +## Serialization + +```yaml +parameters: +``` + +```protobuf + +``` + +## Semantics + +### Example From 6e3ae3cfe23464ba95f6407e0c54dabcf86b67af Mon Sep 17 00:00:00 2001 From: nearnshaw Date: Mon, 2 Dec 2024 16:06:52 -0300 Subject: [PATCH 3/6] examples --- content/ADR-255-texture-tweens.md | 90 +++++++++++++++++++++++++++++++ 1 file changed, 90 insertions(+) diff --git a/content/ADR-255-texture-tweens.md b/content/ADR-255-texture-tweens.md index 929d0abb..28e81aff 100644 --- a/content/ADR-255-texture-tweens.md +++ b/content/ADR-255-texture-tweens.md @@ -34,6 +34,8 @@ The new `TextureMove` option on the `Tween` component will have the following fi - `TextureMovementType`: _(optional)_, defines if the movement will be on the `offset` or the `tiling` field (see section above) - `start`: _Vector2_ the initial value of the offset or tiling - `end`: _Vector2_ the final value of the offset or tiling +- `duration`: _number_ how long the transition takes, in milliseconds +- `easingFunction`: How the curve of movement over time changes, the default value is `EasingFunction.EF_LINEAR` The scene can also use a `TweenSequence` to make continuos movements possible, just like with other kinds of tweens. @@ -60,3 +62,91 @@ parameters: ## Semantics ### Example + +Offset texture: + +```ts +Material.setPbrMaterial(myEntity, { + texture: Material.Texture.Common({ + src: 'assets/materials/wood.png', + wrapMode: TextureWrapMode.TWM_REPEAT, + offset: Vector2.create(0, 0.2), + tiling: Vector2.create(1, 1), + }), +}) +``` + +Simple continuos flow: + +```ts +const myEntity = engine.addEntity() + +MeshRenderer.setPlane(myEntity) + +Transform.create(myEntity, { + position: Vector3.create(4, 1, 4), +}) + +Material.setPbrMaterial(myEntity, { + texture: Material.Texture.Common({ + src: 'materials/water.png', + wrapMode: TextureWrapMode.TWM_REPEAT, + }), +}) + +Tween.create(myEntity, { + mode: Tween.Mode.TextureMove({ + start: Vector2.create(0, 0), + end: Vector2.create(0, 1), + }), + duration: 1000, + easingFunction: EasingFunction.EF_LINEAR, +}) + +TweenSequence.create(myEntity, { sequence: [], loop: TweenLoop.TL_RESTART }) +``` + +Square-moving tween sequence: + +```ts +//(...) + +Tween.create(myEntity, { + mode: Tween.Mode.TextureMove({ + start: Vector2.create(0, 0), + end: Vector2.create(0, 1), + }), + duration: 1000, + easingFunction: EasingFunction.EF_LINEAR, +}) + +TweenSequence.create(myEntity, { + sequence: [ + { + mode: Tween.Mode.TextureMove({ + start: Vector2.create(0, 1), + end: Vector2.create(1, 1), + }), + duration: 1000, + easingFunction: EasingFunction.EF_LINEAR, + }, + { + mode: Tween.Mode.TextureMove({ + start: Vector2.create(1, 1), + end: Vector2.create(1, 0), + }), + duration: 1000, + easingFunction: EasingFunction.EF_LINEAR, + }, + { + mode: Tween.Mode.TextureMove({ + start: Vector2.create(1, 0), + end: Vector2.create(0, 0), + }), + duration: 1000, + easingFunction: EasingFunction.EF_LINEAR, + }, + ], + loop: TweenLoop.TL_RESTART, +}) +``` From 3f1825cdd74e308617776c2130b65853d09c9201 Mon Sep 17 00:00:00 2001 From: Nicolas Earnshaw Date: Tue, 3 Dec 2024 16:15:41 -0300 Subject: [PATCH 4/6] Update content/ADR-255-texture-tweens.md Co-authored-by: Aga Signed-off-by: Nicolas Earnshaw --- content/ADR-255-texture-tweens.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/ADR-255-texture-tweens.md b/content/ADR-255-texture-tweens.md index 28e81aff..af7bd54d 100644 --- a/content/ADR-255-texture-tweens.md +++ b/content/ADR-255-texture-tweens.md @@ -12,7 +12,7 @@ authors: # Abstract -This document describes an approach for making it possible for creators to slide textures. This can be used to simulate running liquids, as well as many other interesting texture effects. +This document describes an approach for making it possible for creators to animate textures. This can be used to simulate running liquids, as well as many other interesting texture effects. This new feature combines very well with ADR-254 (GLTF Nodes), as it enables to do the same effects on the textures of any .gltf model. From 02a642f5a016d7f8366941748a63536f6f1acf1c Mon Sep 17 00:00:00 2001 From: nearnshaw Date: Tue, 3 Dec 2024 16:19:46 -0300 Subject: [PATCH 5/6] changes based on feedback --- content/ADR-253-light-sources.md | 116 ------------------------------ content/ADR-255-texture-tweens.md | 6 +- 2 files changed, 1 insertion(+), 121 deletions(-) delete mode 100644 content/ADR-253-light-sources.md diff --git a/content/ADR-253-light-sources.md b/content/ADR-253-light-sources.md deleted file mode 100644 index c0d39d5e..00000000 --- a/content/ADR-253-light-sources.md +++ /dev/null @@ -1,116 +0,0 @@ ---- -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 diff --git a/content/ADR-255-texture-tweens.md b/content/ADR-255-texture-tweens.md index af7bd54d..a192a636 100644 --- a/content/ADR-255-texture-tweens.md +++ b/content/ADR-255-texture-tweens.md @@ -41,14 +41,10 @@ The scene can also use a `TweenSequence` to make continuos movements possible, j ## Texture layers -Materials have several textures besides the albedo_texture, including bump_texture, alpha_texture, emissive_texture. Because of shader optimization reasons, the alignment of these fields is not independent from each other. The albedo_texture behaves as the base texture, any changes to this texture affect all other layers equally. Other layers are then able to set their own different alignment properties, but these are compounded with those of the base texture. - -For example, if the offset of the base texture is `(0.2, 0)` and the offset of the emissive texture is `(0.1, 0)`, the final position of the emissive texture will end up equivalent to `(0.3, 0)`. +Materials have several textures besides the albedo_texture, including bump_texture, alpha_texture, emissive_texture. The `TextureMove` Tween affects the base texture, so all textures move together with it. This applies to changing the `offset` and `tiling` fields manually, as well as using a texture tween. -The `TextureMove` Tween affects the base texture, so all textures move together with it. - ## Serialization ```yaml From 13d5e8385b9f9925ddc5b279209a97533b4534e0 Mon Sep 17 00:00:00 2001 From: Alejandro Alvarez Melucci <163010988+AlejandroAlvarezMelucciDCL@users.noreply.github.com> Date: Thu, 12 Dec 2024 11:11:41 -0300 Subject: [PATCH 6/6] Update ADR-255-texture-tweens.md Added serialization definitions for Tween and Texture Signed-off-by: Alejandro Alvarez Melucci <163010988+AlejandroAlvarezMelucciDCL@users.noreply.github.com> --- content/ADR-255-texture-tweens.md | 41 ++++++++++++++++++++++++++++++- 1 file changed, 40 insertions(+), 1 deletion(-) diff --git a/content/ADR-255-texture-tweens.md b/content/ADR-255-texture-tweens.md index a192a636..530840a0 100644 --- a/content/ADR-255-texture-tweens.md +++ b/content/ADR-255-texture-tweens.md @@ -49,10 +49,49 @@ This applies to changing the `offset` and `tiling` fields manually, as well as u ```yaml parameters: + COMPONENT_ID: 1102 + COMPONENT_NAME: core::Tween + CRDT_TYPE: LastWriteWin-Element-Set ``` ```protobuf - +message Texture { + string src = 1; + optional TextureWrapMode wrap_mode = 2; // default = TextureWrapMode.Clamp + optional TextureFilterMode filter_mode = 3; // default = FilterMode.Bilinear + + // Final uv = offset + (input_uv * tiling) + optional Vector2 offset = 4; // default = Vector2.Zero; Offset for texture positioning, only works for the texture property in PbrMaterial or UnlitMaterial. + optional Vector2 tiling = 5; // default = Vector2.One; Tiling multiplier for texture repetition, only works for the texture property in PbrMaterial or UnlitMaterial. +} + +message PBTween { + float duration = 1; // in milliseconds + EasingFunction easing_function = 2; + + oneof mode { + Move move = 3; + Rotate rotate = 4; + Scale scale = 5; + TextureMove texture_move = 8; + } + + optional bool playing = 6; // default true (pause or running) + optional float current_time = 7; // between 0 and 1 +} + +// This tween mode allows to move the texture of a PbrMaterial or UnlitMaterial. +// You can also specify the movement type (offset or tiling) +message TextureMove { + decentraland.common.Vector2 start = 1; + decentraland.common.Vector2 end = 2; + optional TextureMovementType movement_type = 3; // default = TextureMovementType.TMT_OFFSET +} + +enum TextureMovementType { + TMT_OFFSET = 0; // default = TextureMovementType.TMT_OFFSET + TMT_TILING = 1; +} ``` ## Semantics