@dcl/protocol 1.0.0-2569677750.commit-6ce832a → 1.0.0-25751414897.commit-a9f7d81

package/proto/decentraland/sdk/components/avatar_modifier_area.proto

@@ -0,0 +1,53 @@
+syntax = "proto3";
+
+package decentraland.sdk.components;
+
+import "decentraland/common/vectors.proto";
+import "decentraland/sdk/components/common/id.proto";
+
+option (common.ecs_component_id) = 1070;
+
+// The AvatarModifierArea component can be attached to an Entity to define a region of space where 
+// avatar behavior changes.
+//
+// The Entity's Transform position determines the center-point of the region, while its size is 
+// given as a vector in the `area` property below. The Transform rotation is applied, but the scale 
+// is ignored.
+//
+// The modifier effect is only applied to avatars inside the region. It does not affect how players 
+// standing inside it see avatars on the other side of the boundary.
+//
+// Note that, while commonly used to delineate a 2D area in a scene (hence the name), the region
+// is actually a 3D volume.
+message PBAvatarModifierArea {
+  decentraland.common.Vector3 area = 1;      // the 3D size of the region
+  repeated string exclude_ids = 2;           // user IDs that can enter and remain unaffected
+  repeated AvatarModifierType modifiers = 3; // list of modifiers to apply
+  optional AvatarMovementSettings movement_settings = 4;
+  optional bool use_collider_range = 5;      // if true, the player will be considered inside the area when they are within 0.3m of the area. default true
+}
+
+// AvatarModifierType is an effect that should be applied to avatars inside the region.
+enum AvatarModifierType {
+  AMT_HIDE_AVATARS = 0;      // avatars are invisible
+  AMT_DISABLE_PASSPORTS = 1; // selecting (e.g. clicking) an avatar will not bring up their profile.
+}
+
+message AvatarMovementSettings {
+  optional AvatarControlType control_mode = 1;
+  // if not explicitly set, the following properties default to user's preference settings
+  optional float run_speed = 2;              // speed the player moves at, in m/s
+  optional float friction = 3;               // how fast the player gets up to speed or comes to rest. higher = more responsive
+  optional float gravity = 4;                // how fast the player accelerates vertically when not on a solid surface, in m/s. should normally be negative
+  optional float jump_height = 5;            // how high the player can jump, in meters. should normally be positive. gravity must have the same sign for jumping to be possible
+  optional float max_fall_speed = 6;         // max fall speed in m/s. should normally be negative
+  optional float turn_speed = 7;             // speed the player turns in tank mode, in radians/s
+  optional float walk_speed = 8;             // speed the player walks at, in m/s
+  optional bool allow_weighted_movement = 9; // whether to allow player to move at a slower speed (e.g. with a walk-key or when using a gamepad/joystick). defaults to true  
+}
+
+enum AvatarControlType {
+  CCT_NONE = 0;     // avatar cannot move
+  CCT_RELATIVE = 1; // avatar moves relative to the camera origin
+  CCT_TANK = 2;     // avatar moves like a tank: left/right rotate the player, forward/backward advance/retreat the player
+}

package/proto/decentraland/sdk/components/avatar_movement.proto

@@ -0,0 +1,46 @@
+syntax = "proto3";
+
+package decentraland.sdk.components;
+
+import "decentraland/sdk/components/common/id.proto";
+import "decentraland/common/vectors.proto";
+
+option (common.ecs_component_id) = 1501;
+
+message PBAvatarMovement {
+  decentraland.common.Vector3 velocity = 1;
+  float orientation = 2;                                    // 0-360, we don't allow pitch/roll
+  optional decentraland.common.Vector3 ground_direction = 3;
+  optional bool walk_success = 4;                           // set for one frame when a walk_target ends: true = reached target, false = failed; absent = in progress or no walk
+}
+
+// engine behaviour (uses only capsule shapecasts and GJK closest point for portability):
+// 1: set avatar orientation from movement info -> P1
+// 2: record "ground collider" - nearest collider within threshold distance in ground_direction using avatar collider shapecast
+// 3: update all colliders, record previous transform and new transform.
+// 4: apply ground collider movement: take collider closest point, modify P1 translation and rotation by closest point translation and rotation change -> P2
+// 5: resolve collisions using position-based constraints
+//   initialize constraints to -inf, +inf
+//   repeat
+//       for each collider[i] that collides with the P3+N player:
+//           if closest point = capsule middle (i.e. collider collides with P3 collider but with radius 0), 
+//               ignore / continue
+//           else 
+//               update constraints based on minimum movement to escape collision
+//               e.g. if avatar is 1cm into the floor, constraint_min = max(constraint_min, vec3(0, 0.01, 0))
+//       reposition player to satisfy constraints for each axis:
+//           y: satsify floor before ceiling: new position = max(constraint_min, min(constraint_max, current position))
+//           x and z: if squashed, take average, else satisfy the required constraint
+//           if constraint_min > constraint_max then new position = average(constraint_min, constraint_max) 
+//           else new position = clamp(current position, constraint_min, constraint_max)
+//   while position !~= previous position
+// 6: apply velocity (collide and slide)
+//   disable anything we are initially colliding with
+//   shapecast avatar from position to position + velocity * timestep
+//   on impact:
+//       project velocity onto slide plane (standard "Collide & Slide")
+//       velocity = old velocity - (normal * dot(velocity, normal))
+//       repeat continue with residual velocity and residual time
+// 7: provide AvatarMovementInfo values
+//      actual velocity = (final - P3+N) / timestep
+//      external_velocity = (P3+N - P1) / timestep

package/proto/decentraland/sdk/components/avatar_movement_info.proto

@@ -0,0 +1,22 @@
+syntax = "proto3";
+
+package decentraland.sdk.components;
+
+import "decentraland/sdk/components/common/id.proto";
+import "decentraland/common/vectors.proto";
+import "decentraland/sdk/components/avatar_locomotion_settings.proto";
+import "decentraland/sdk/components/input_modifier.proto";
+
+option (common.ecs_component_id) = 1500;
+
+message PBAvatarMovementInfo {
+  float step_time = 1;                                      // the length of time the current step velocity will apply for
+  float previous_step_time = 2;                             // the length of time the previous step velocity applied for
+  decentraland.common.Vector3 requested_velocity = 3;       // the velocity requested for the previous frame
+  decentraland.common.Vector3 actual_velocity = 4;          // the resulting velocity taking collisions into account
+  decentraland.common.Vector3 external_velocity = 5;        // the velocity imparted by movement of the "ground" platform or pushing from other moving colliders
+  decentraland.sdk.components.PBAvatarLocomotionSettings active_avatar_locomotion_settings = 6;
+  decentraland.sdk.components.PBInputModifier active_input_modifier = 7;
+  optional decentraland.common.Vector3 walk_target = 8;    // if set, the movement scene should walk the player to this scene-relative position
+  optional float walk_threshold = 9;                        // stop distance for walk_target; considered reached when within this distance
+}

package/proto/decentraland/sdk/components/avatar_shape.proto

@@ -0,0 +1,45 @@
+syntax = "proto3";
+package decentraland.sdk.components;
+
+import "decentraland/sdk/components/common/id.proto";
+option (common.ecs_component_id) = 1080;
+import "decentraland/common/colors.proto";
+
+// The AvatarShape component contains the information required to draw and animate avatar, acting as
+// a simplified GLTF container for this specific case. 
+//
+// All fields (except ID) are optional have reasonable default values. In the case of `wearables`,
+// each slot on the Avatar's body that is not explicitly included in the list has its own default.
+//
+// Note that, while AvatarShape can be attached to any Entity, it's only actually used in the global 
+// Avatar Scene. Other requirements are usually better served by GLTFs.
+message PBAvatarShape {
+  string id = 1;                  // the user ID
+  optional string name = 2;       // visible name (default: "NPC")
+  optional string body_shape = 3; // shape URN (default "urn:decentraland:off-chain:base-avatars:BaseFemale")
+
+  optional decentraland.common.Color3 skin_color = 4; // RGB (default [0.6, 0.462, 0.356])
+  optional decentraland.common.Color3 hair_color = 5; // RGB (default [0.283, 0.142, 0])
+  optional decentraland.common.Color3 eye_color = 6;  // RGB (default [0.6, 0.462, 0.356])
+
+  optional string expression_trigger_id = 7;       // current emote animations
+  optional int64 expression_trigger_timestamp = 8; // start of emote animations (in the same order)
+
+  optional bool talking = 9; // whether to display the floating voice chat icon
+
+  // Wearable URNs, one for each body slot.
+  //   Default values for each unspecified slot:
+  //     Eyes    : "urn:decentraland:off-chain:base-avatars:f_eyes_00", 
+  //     Eyebrows: "urn:decentraland:off-chain:base-avatars:f_eyebrows_00",
+  //     Mouth   : "urn:decentraland:off-chain:base-avatars:f_mouth_00" 
+  //     Hair    : "urn:decentraland:off-chain:base-avatars:standard_hair", 
+  //     Shirt   : "urn:decentraland:off-chain:base-avatars:f_simple_yellow_tshirt", 
+  //     Trousers: "urn:decentraland:off-chain:base-avatars:f_brown_trousers", 
+  //     Shoes   : "urn:decentraland:off-chain:base-avatars:bun_shoes"]
+  repeated string wearables = 10; 
+  repeated string emotes = 11; // available emotes (default empty)
+
+  optional bool show_only_wearables = 12; // hides the skin + hair + facial features (default: false)
+  repeated string force_render = 13; // slots that will render even if hidden
+}
+

package/proto/decentraland/sdk/components/billboard.proto

@@ -0,0 +1,29 @@
+syntax = "proto3";
+
+package decentraland.sdk.components;
+
+import "decentraland/sdk/components/common/id.proto";
+
+// https://adr.decentraland.org/adr/ADR-198
+option (common.ecs_component_id) = 1090;
+
+// The Billboard component makes an Entity automatically reorient its rotation to face the camera. 
+// As the name indicates, it’s used to display in-game billboards and frequently combined with 
+// the TextShape component.
+//
+// Billboard only affects the Entity's rotation. Its scale and position are still determined by its
+// Transform.
+message PBBillboard {
+  optional BillboardMode billboard_mode = 1; // the BillboardMode (default: BM_ALL)
+}
+
+// BillboardMode indicates one or more axis for automatic rotation, in OR-able bit flag form.
+// Only the values below and the (BM_X | BM_Y) combination are valid.
+enum BillboardMode {
+  BM_NONE = 0;
+  BM_X = 1;
+  BM_Y = 2;
+  BM_Z = 4;
+  BM_ALL = 7; // bitwise combination BM_X | BM_Y | BM_Z
+}
+

package/proto/decentraland/sdk/components/camera_layer.proto

@@ -0,0 +1,30 @@
+syntax = "proto3";
+
+package decentraland.sdk.components;
+
+import "decentraland/sdk/components/common/id.proto";
+import "decentraland/common/colors.proto";
+
+option (common.ecs_component_id) = 1503;
+
+message PBCameraLayer {
+    // layer to which these settings apply. must be > 0
+    // Layer 0 is the default "real world" layer viewed by the player and cannot be modified.
+    uint32 layer = 1;
+
+    // should the sun light affect this layer? default false
+    optional bool directional_light = 2;
+
+    // should this layer show player avatars? default false
+    optional bool show_avatars = 3;
+
+    // should this layer show the sky? default false
+    optional bool show_skybox = 4;
+
+    // should this layer show distance fog? default false
+    optional bool show_fog = 5;
+
+    // ambient light overrides for this layer. default -> use same as main camera
+    optional decentraland.common.Color3 ambient_color_override = 6;
+    optional float ambient_brightness_override = 7;
+}

package/proto/decentraland/sdk/components/camera_layers.proto

@@ -0,0 +1,11 @@
+syntax = "proto3";
+
+package decentraland.sdk.components;
+
+import "decentraland/sdk/components/common/id.proto";
+
+option (common.ecs_component_id) = 1208;
+
+message PBCameraLayers {
+    repeated uint32 layers = 1;
+}

package/proto/decentraland/sdk/components/camera_mode.proto

@@ -0,0 +1,12 @@
+syntax = "proto3";
+package decentraland.sdk.components;
+
+import "decentraland/sdk/components/common/id.proto";
+option (common.ecs_component_id) = 1072;
+import "decentraland/sdk/components/common/camera_type.proto";
+
+// The CameraMode component can be used to determine whether the player is using a first-person o 
+// third-person view.
+message PBCameraMode {
+  common.CameraType mode = 1; // the camera type (1st-person or 3rd-person)
+}

package/proto/decentraland/sdk/components/camera_mode_area.proto

@@ -0,0 +1,44 @@
+syntax = "proto3";
+
+package decentraland.sdk.components;
+
+import "decentraland/common/vectors.proto";
+import "decentraland/sdk/components/common/camera_type.proto";
+import "decentraland/sdk/components/common/id.proto";
+
+option (common.ecs_component_id) = 1071;
+
+// The CameraModeArea component can be attached to an Entity to define a region of space where 
+// the player's camera mode (1st-person, 3rd-person or cinematic) is overridden.
+//
+// The Entity's Transform position determines the center-point of the region, while its size is 
+// given as a vector in the `area` property below. The Transform rotation is applied, but the scale 
+// is ignored.
+//
+// When players leave the region, their previous setting is restored.
+//
+// Note that, while commonly used to delineate a 2D area in a scene (hence the name), the region
+// is actually a 3D volume.
+//
+// When mode is set to CtCinematic, the cinematic_settings field must also be provided.
+message PBCameraModeArea {
+  decentraland.common.Vector3 area = 1;                       // the 3D size of the region
+  common.CameraType mode = 2;                                 // the camera mode to enforce
+  optional CinematicSettings cinematic_settings = 3;
+  optional bool use_collider_range = 4;                       // if true, the player will be considered inside the area when they are within 0.3m of the area. default true
+}
+
+message CinematicSettings {
+  uint32 camera_entity = 1;           // Entity that defines the cinematic camera transform.
+                                      // Position -> camera's position
+                                      // Rotation -> camera's direction
+                                      // scale.z -> zoom level
+                                      // scale.x and scale.y -> unused
+  optional bool allow_manual_rotation = 2; // whether the user can move the camera's rotation. default false
+  optional float yaw_range = 3;       // how far the camera can rotate around the y-axis / look left/right, in radians. default unrestricted
+  optional float pitch_range = 4;     // how far the camera can rotate around the x-axis / look up-down, in radians. default unrestricted
+                                      // note: cameras can never look up/down further than Vec3::Y
+  optional float roll_range = 5;      // how far the camera can rotate around the z-axis / tilt, in radians. default unrestricted
+  optional float zoom_min = 6;        // minimum zoom level. must be greater than 0. defaults to the input zoom level
+  optional float zoom_max = 7;        // maximum zoom level. must be greater than 0. defaults to the input zoom level
+}

package/proto/decentraland/sdk/components/common/camera_transition.proto

@@ -0,0 +1,11 @@
+syntax = "proto3";
+package decentraland.sdk.components.common;
+
+// Defines the transition used towards the camera that contains the CameraTransition.
+// This structure may be updated in the future to specify from/to entities and to have easing functions.
+message CameraTransition {
+  oneof transition_mode {
+    float time = 1;
+    float speed = 2; // meters per second; e.g. speed 1 -> 1 meter per second
+  }
+}

package/proto/decentraland/sdk/components/common/camera_type.proto

@@ -0,0 +1,9 @@
+syntax = "proto3";
+
+package decentraland.sdk.components.common;
+
+enum CameraType {
+  CT_FIRST_PERSON = 0;
+  CT_THIRD_PERSON = 1;
+  CT_CINEMATIC = 2;    // controlled by the scene
+}

package/proto/decentraland/sdk/components/common/id.md

@@ -0,0 +1,2 @@
+# Why id as file option?
+Extending this option in the component definition allows having the data of its ID in the protocol buffer code generator. 

package/proto/decentraland/sdk/components/common/id.proto

@@ -0,0 +1,8 @@
+syntax = "proto3";
+package decentraland.sdk.components.common;
+
+import "google/protobuf/descriptor.proto";
+
+extend google.protobuf.FileOptions {
+  optional int32 ecs_component_id = 50000;
+}

package/proto/decentraland/sdk/components/common/input_action.proto

@@ -0,0 +1,39 @@
+syntax = "proto3";
+
+package decentraland.sdk.components.common;
+
+enum InputAction {
+  IA_POINTER = 0;
+  IA_PRIMARY = 1;
+  IA_SECONDARY = 2;
+  IA_ANY = 3;
+  IA_FORWARD = 4;
+  IA_BACKWARD = 5;
+  IA_RIGHT = 6;
+  IA_LEFT = 7;
+  IA_JUMP = 8;
+  IA_WALK = 9;
+  IA_ACTION_3 = 10;
+  IA_ACTION_4 = 11;
+  IA_ACTION_5 = 12;
+  IA_ACTION_6 = 13;
+  IA_MODIFIER = 14;
+}
+
+// PointerEventType is a kind of interaction that can be detected.
+enum PointerEventType {
+  PET_UP = 0;
+  PET_DOWN = 1;
+  PET_HOVER_ENTER = 2;
+  PET_HOVER_LEAVE = 3;
+  PET_PROXIMITY_ENTER = 4;
+  PET_PROXIMITY_LEAVE = 5;
+  PET_DRAG_LOCKED = 6;
+  PET_DRAG = 7;
+  PET_DRAG_END = 8;
+}
+
+enum InteractionType {
+  CURSOR = 0;
+  PROXIMITY = 1;
+}

package/proto/decentraland/sdk/components/common/loading_state.proto

@@ -0,0 +1,10 @@
+syntax = "proto3";
+package decentraland.sdk.components.common;
+
+enum LoadingState {
+  UNKNOWN = 0;
+  LOADING = 1;
+  NOT_FOUND = 2;
+  FINISHED_WITH_ERROR = 3;
+  FINISHED = 4;
+}

package/proto/decentraland/sdk/components/common/media_state.proto

@@ -0,0 +1,13 @@
+syntax = "proto3";
+package decentraland.sdk.components.common;
+
+enum MediaState {
+  MS_NONE = 0;
+  MS_ERROR = 1;
+  MS_LOADING = 2;
+  MS_READY = 3;
+  MS_PLAYING = 4;
+  MS_BUFFERING = 5;
+  MS_SEEKING = 6;
+  MS_PAUSED = 7;
+}

package/proto/decentraland/sdk/components/common/raycast_hit.proto

@@ -0,0 +1,16 @@
+syntax = "proto3";
+
+package decentraland.sdk.components.common;
+import "decentraland/common/vectors.proto";
+
+// RaycastHit contains information about the intersection of a ray with a mesh.
+message RaycastHit {
+  // Position will be relative to the scene
+  decentraland.common.Vector3 position = 1;      // the intersection point in global coordinates
+  decentraland.common.Vector3 global_origin = 2; // the starting point of the ray in global coordinates
+  decentraland.common.Vector3 direction = 3;     // the direction vector of the ray in global coordinates
+  decentraland.common.Vector3 normal_hit = 4;    // normal of the hit surface in global coordinates
+  float length = 5;                              // the distance between the ray origin and the hit position
+  optional string mesh_name = 6;                 // mesh name, if collision happened inside a GltfContainer
+  optional uint32 entity_id = 7;                 // the ID of the Entity that has the impacted mesh attached
+}

package/proto/decentraland/sdk/components/common/texts.proto

@@ -0,0 +1,21 @@
+syntax = "proto3";
+
+package decentraland.sdk.components.common;
+
+enum TextAlignMode {
+  TAM_TOP_LEFT = 0;
+  TAM_TOP_CENTER = 1;
+  TAM_TOP_RIGHT = 2;
+  TAM_MIDDLE_LEFT = 3;
+  TAM_MIDDLE_CENTER = 4;
+  TAM_MIDDLE_RIGHT = 5;
+  TAM_BOTTOM_LEFT = 6;
+  TAM_BOTTOM_CENTER = 7;
+  TAM_BOTTOM_RIGHT = 8;
+}
+
+enum Font {
+  F_SANS_SERIF = 0;
+  F_SERIF = 1;
+  F_MONOSPACE = 2;
+}

package/proto/decentraland/sdk/components/engine_info.proto

@@ -0,0 +1,15 @@
+syntax = "proto3";
+package decentraland.sdk.components;
+
+import "decentraland/sdk/components/common/id.proto";
+option (common.ecs_component_id) = 1048;
+
+// EngineInfo provides information about the graphics engine running the scene.
+// The values of this component are written at the "physics" stage of the ADR-148. Meaning
+// the tick_number and frame_number of the same frame could be used as correlation numbers
+// for timestamps in other components.
+message PBEngineInfo {
+  uint32 frame_number = 1; // frame counter of the engine
+  float total_runtime = 2; // total runtime of this scene in seconds
+  uint32 tick_number  = 3; // tick counter of the scene as per ADR-148
+}

package/proto/decentraland/sdk/components/global_light.proto

@@ -0,0 +1,22 @@
+syntax = "proto3";
+package decentraland.sdk.components;
+
+import "decentraland/common/colors.proto";
+import "decentraland/common/vectors.proto";
+
+import "decentraland/sdk/components/common/id.proto";
+option (common.ecs_component_id) = 1206;
+
+// defines the global scene light settings. must be added to the scene root.
+// to control sunlight color, intensity, shadows etc, you can also add a PBLight to the scene root.
+message PBGlobalLight {
+  // the direction the directional light shines in.
+  // default depends on time of day and explorer implementation
+  optional decentraland.common.Vector3 direction = 1;
+  // ambient light color
+  // default: White
+  optional decentraland.common.Color3 ambient_color = 2;
+  // ambient light intensity. the explorer default ambient brightness is multiplied by this non-physical quantity.
+  // default 1
+  optional float ambient_brightness = 3; 
+}

package/proto/decentraland/sdk/components/gltf_container.proto

@@ -0,0 +1,19 @@
+syntax = "proto3";
+package decentraland.sdk.components;
+
+import "decentraland/sdk/components/common/id.proto";
+option (common.ecs_component_id) = 1041;
+
+// GltfContainer loads a GLTF file (and any additional files packaged inside) attached to an Entity.
+//
+// This allows the use of custom models, materials, collision boundaries and shapes that can't be 
+// achieved using MeshRenderer, MeshCollider and other standard components.
+message PBGltfContainer {
+  string src = 1; // the GLTF file path as listed in the scene's manifest.
+
+  reserved 2;
+  reserved 3;
+
+  optional uint32 visible_meshes_collision_mask = 4; // default: 0
+  optional uint32 invisible_meshes_collision_mask = 5; // default: CL_POINTER | CL_PHYSICS
+}

package/proto/decentraland/sdk/components/gltf_container_loading_state.proto

@@ -0,0 +1,26 @@
+syntax = "proto3";
+package decentraland.sdk.components;
+
+import "decentraland/sdk/components/common/id.proto";
+option (common.ecs_component_id) = 1049;
+
+import "decentraland/sdk/components/common/loading_state.proto";
+
+// GltfContainerLoadingState is set by the engine and provides information about
+// the current state of the GltfContainer of an entity.
+message PBGltfContainerLoadingState {
+  common.LoadingState current_state = 1;
+  repeated string node_paths = 2; // all node paths in the gltf, which can be used with a GltfNode to inspect and modify the gltf contents
+  repeated string mesh_names = 3; // all meshes in the gltf. unnamed meshes will be auto-assigned a name of the form `MeshX` or `MeshX/PrimitiveY`
+                                  // where X is the mesh index and Y is the primitive index (and there is more than 1 primitive). note this may 
+                                  // conflict with manually named meshes - to avoid any issues make sure all your meshes are explicitly named.
+  repeated string material_names = 4; // all materials in the gltf. unnamed materials will be auto-assigned a name of the form `MaterialX` where
+                                      // X is the material index. note this may conflict with manually named materials - to avoid any issues make
+                                      // sure all your materials are explicitly named.
+  repeated string skin_names = 5; // all mesh skins in the gltf. unnamed skins will be auto-assigned a name of the form `SkinX` where
+                                  // X is the skin index. note this may conflict with manually named skins - to avoid any issues make sure all 
+                                  // your skins are explicitly named.
+  repeated string animation_names = 6; // all animations in the gltf. unnamed animations will be auto-assigned a name of the form `AnimationX` where
+                                       // X is the animation index. note this may conflict with manually named anims - to avoid any issues make sure all 
+                                       // your animations are explicitly named.
+}

package/proto/decentraland/sdk/components/gltf_node.proto

@@ -0,0 +1,42 @@
+syntax = "proto3";
+package decentraland.sdk.components;
+
+import "decentraland/sdk/components/common/id.proto";
+option (common.ecs_component_id) = 1200;
+
+// a GltfNode links a scene entity with a node from within a gltf, allowing the scene to inspect it or modify it.
+// This component must be added to a direct child of an entity with a PBGltfContainer component, or
+// to a direct child of another entity with a GltfNode component, and the referenced gltf node must be a descendent of the gltf node
+// in the parent.
+// The name must match the path of one of the nodes within the Gltf. These are available on the GltfContainerLoadingState component.
+// 
+// The renderer will attach a PBGltfNodeState to the entity describing the state. Once the state is `GNS_READY`, 
+// - the `Transform` will be updated to match the position of the node within the gltf (relative to the gltf root, or the parent node),
+// - a `MeshRenderer` with a GltfMesh mesh type will be added (if the gltf node has a mesh).
+// - a `MeshCollider` with a GltfMesh mesh type will be added (if the gltf node has a collider).
+// - a `Material` component including a GltfMaterial reference will be added (if the gltf node has a material).
+//
+// After creation, if an animation moves the node, the `Transform` will be updated.
+//
+// From the scene, you can modify various components to alter the gltf node:
+// - modifying the `Transform` position/rotation/scale will move the node. The position is interpreted relative to the gltf root (or parent node), 
+//   regardless of any intermediate gltf node hierarchy.
+//   If an animation is playing, the animation takes priority and the scene entity's position will be updated to match the animation.
+// - `Visibility` can be added to hide or show the node and it's children in the gltf hierarchy.
+// - `MeshRenderer` can be added/modified/removed to create/modify/remove a mesh on the node.
+// - `MeshCollider` can be added/modified/removed to create/modify/remove a collider on the node.
+// - `Material` can be added or modified to change the material properties. If the gltf node has a material, the original material will be
+//   used as a base, and any gltf features (e.g. occlusion maps) from the gtlf spec that the renderer supports but that are not exposed in the 
+//   PBMaterial will be maintained.
+//
+// The scene can add additional entities as children to the gltf node, but structural modifications of the gltf are not possible: 
+// - changing the scene hierarchy will not change the gltf node hierarchy. Moving the entity out of the gltf will sever the link and
+//   change the state to `GNS_FAILED`.
+// - deleting the scene entity will not delete the gltf node.
+//
+// Removing the GltfNode will revert any changes to the original gltf. If the GltfNode component is removed and the mesh/collider/material 
+// are not removed, this will result in a duplication of these components as the previously-linked entity will retain it's components and 
+// the gltf node will also be displayed.
+message PBGltfNode {
+  string path = 1; // the path of the target node in the Gltf.
+}

package/proto/decentraland/sdk/components/gltf_node_modifiers.proto

@@ -0,0 +1,25 @@
+syntax = "proto3";
+
+package decentraland.sdk.components;
+
+import "decentraland/sdk/components/common/id.proto";
+import "decentraland/sdk/components/material.proto";
+
+option (common.ecs_component_id) = 1099;
+
+// GltfNodeModifiers component is to be used attached to entities that have the GltfContainer component.
+//
+// This allows to override either the Material or the Casting Shadows behaviour of the target GLTF Node.
+// 
+// * If the 'path' of the first modifier in the collection is an empty string: the configuration will
+// affect all of the GLTF Nodes (as a global modifier).
+// * Otherwise, for the modifiers whose 'path' is found in the GLTF hierarchy, the modifier will affect only
+// the target Nodes.
+message PBGltfNodeModifiers {
+  message GltfNodeModifier {
+    string path = 1; // The GLTF hierarchy path of the target Node to be affected
+    optional bool cast_shadows = 2; // The casting shadows enabled override
+    optional PBMaterial material = 3; // The Material that will be overridden on the target Node
+  }
+  repeated GltfNodeModifier modifiers  = 1;
+}

package/proto/decentraland/sdk/components/gltf_node_state.proto

@@ -0,0 +1,20 @@
+syntax = "proto3";
+package decentraland.sdk.components;
+
+import "decentraland/sdk/components/common/id.proto";
+option (common.ecs_component_id) = 1201;
+
+// See the details of the GltfNode component for more information.
+
+// The state of a linked gltf node.
+// If the state is GNSV_FAILED, the renderer may describe the failure in the error string.
+message PBGltfNodeState {
+    GltfNodeStateValue state = 1;
+    optional string error = 2;
+}
+
+enum GltfNodeStateValue {
+    GNSV_PENDING = 0;
+    GNSV_FAILED = 1;
+    GNSV_READY = 2;
+}