@dcl/protocol 1.0.0-4408137944.commit-a67c796 → 1.0.0-4427886959.commit-6b9dcb5

package/out-ts/social.gen.ts

@@ -0,0 +1,3 @@
+/* eslint-disable */
+
+export const protobufPackage = "decentraland.social";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dcl/protocol",
-  "version": "1.0.0-4408137944.commit-a67c796",
+  "version": "1.0.0-4427886959.commit-6b9dcb5",
   "description": "",
   "main": "index.js",
   "scripts": {
@@ -26,5 +26,5 @@
     "out-js",
     "public"
   ],
-  "commit": "a67c79606bd8a34a25a0ce8c3278b72ec1dabd86"
+  "commit": "6b9dcb5fe3d5102f69ebe62a0f4f6b147c55ca04"
 }

package/proto/decentraland/sdk/components/animator.proto

@@ -4,16 +4,23 @@ package decentraland.sdk.components;
 import "decentraland/sdk/components/common/id.proto";
 option (common.ecs_component_id) = 1042;
 
+// The Animator component is a container for multiple potential animations an Entity can display,
+// separately or at the same time. It can be used to start, stop or blend animations; as well as
+// to inspect their playback state.
+//
+// Animations have a `weight` property, which determines how pronounced the animation will be. This
+// can be adjusted to blend animations together, or gracefully transition from one to the next.
 message PBAnimator {
-   repeated PBAnimationState states = 1;
+  repeated PBAnimationState states = 1; // a collection of animations and their current state
 }
 
+// AnimationState indicates the status and configuration of one available animation.
 message PBAnimationState {
-  string name = 1;
-  string clip = 2;
-  optional bool playing = 3;
-  optional float weight = 4; // default=1.0s
-  optional float speed = 5; // default=1.0
-  optional bool loop = 6; // default=true
-  optional bool should_reset = 7;
+  string name = 1;                // the identifier for this animation, to use in scene code
+  string clip = 2;                // the animation path in the `files` array of the scene manifest
+  optional bool playing = 3;      // whether this animation is currently playing
+  optional float weight = 4;      // the "weight" of this animation (see below, default: 1.0)
+  optional float speed = 5;       // the playback speed (default: 1.0)
+  optional bool loop = 6;         // whether the animation repeats until stopped (default: true)
+  optional bool should_reset = 7; // whether the Entity is restored to its prior state when done
 }

package/proto/decentraland/sdk/components/audio_source.proto

@@ -4,10 +4,20 @@ package decentraland.sdk.components;
 import "decentraland/sdk/components/common/id.proto";
 option (common.ecs_component_id) = 1020;
 
-message PBAudioSource {  
-  optional bool playing = 1;
-  optional float volume = 2; // default=1.0f
-  optional bool loop = 3;
-  optional float pitch = 4; // default=1.0f
-  string audio_clip_url = 5;
+// The AudioSource component can play an audio clips bundled with the scene, controlling some
+// of the behavior.
+//
+// In each AudioSource instance, the sound is spatially located at the associated entity’s position,
+// given by its Transform.
+//
+// Note that the `audio_clip_url` is not actually a URL, but rather the path of a file bundled with
+// the scene and declared in its manifest. The name was chosen because the URL use-case will
+// eventually be supported.
+message PBAudioSource { 
+  optional bool playing = 1; // whether the clip is currently playing.
+  optional float volume = 2; // the audio volume (default: 1.0).
+  optional bool loop = 3;    // whether the clip should restart when finished.
+  optional float pitch = 4;  // the audio pitch (default: 1.0).
+  string audio_clip_url = 5; // the clip path as given in the `files` array of the scene's manifest.
 }
+

package/proto/decentraland/sdk/components/audio_stream.proto

@@ -4,8 +4,11 @@ package decentraland.sdk.components;
 import "decentraland/sdk/components/common/id.proto";
 option (common.ecs_component_id) = 1021;
 
+// The AudioStream component can play external audio clips given a URL, streaming it in real-time.
+//
+// Despite being attached to a particular entity, the sound is not affected by its position.
 message PBAudioStream {  
-  optional bool playing = 1;
-  optional float volume = 2; // default=1.0f
-  string url = 3;
+  optional bool playing = 1; // whether the clip is currently playing
+  optional float volume = 2; // the audio volume (default: 1.0)
+  string url = 3;            // the audio stream HTTP URL
 }

package/proto/decentraland/sdk/components/avatar_attach.proto

@@ -6,15 +6,23 @@ import "decentraland/sdk/components/common/id.proto";
 
 option (common.ecs_component_id) = 1073;
 
+// The AvatarAttach component automatically repositions an Entity to maintain the same position and 
+// rotation relative to some part of an avatar, called the "anchor point". The Entity 
+// will follow this anchor as it moves.
+//
+// The Entity's own Transform is overridden by this component. To offset position and adjust scale, 
+// add a child to the anchored Entity and set a Transform on it instead.
+//
+// AvatarAnchorPointType indicates which part of the avatar the Entity must follow.
+message PBAvatarAttach {
+  optional string avatar_id = 1;             // the user ID of the avatar (default: local user)
+  AvatarAnchorPointType anchor_point_id = 2; // the anchor point.
+}
+
+// AvatarAnchorPointType determines the part of the avatar's body that anchors the Entity.
 enum AvatarAnchorPointType {
   AAPT_POSITION = 0;
   AAPT_NAME_TAG = 1;
   AAPT_LEFT_HAND = 2;
   AAPT_RIGHT_HAND = 3;
 }
-
-message PBAvatarAttach {
-  // default's to current player avatar id if not provided
-  optional string avatar_id = 1;
-  AvatarAnchorPointType anchor_point_id = 2;
-}

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

@@ -7,13 +7,26 @@ import "decentraland/sdk/components/common/id.proto";
 
 option (common.ecs_component_id) = 1070;
 
-enum AvatarModifierType {
-  AMT_HIDE_AVATARS = 0;
-  AMT_DISABLE_PASSPORTS = 1;
+// 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
 }
 
-message PBAvatarModifierArea {
-  decentraland.common.Vector3 area = 1;
-  repeated string exclude_ids = 2;
-  repeated AvatarModifierType modifiers = 3;
+// 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.
 }

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

@@ -5,28 +5,38 @@ 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;
-  optional string name = 2; // default = NPC
-  optional string body_shape = 3; // default = urn:decentraland:off-chain:base-avatars:BaseFemale
-  optional decentraland.common.Color3 skin_color = 4; // default = decentraland.common.Color3(R = 0.6f, G = 0.462f, B = 0.356f)
-  optional decentraland.common.Color3 hair_color = 5; // default = decentraland.common.Color3(R = 0.283f, G = 0.142f, B = 0f)
-  optional decentraland.common.Color3 eye_color = 6; // default = decentraland.common.Color3(R = 0.6f, G = 0.462f, B = 0.356f)
-  optional string expression_trigger_id = 7;
-  optional int64 expression_trigger_timestamp = 8; // default = timestamp
-  optional bool talking = 9;
-  /**
-   * default = ["urn:decentraland:off-chain:base-avatars:f_eyes_00", 
-   *  "urn:decentraland:off-chain:base-avatars:f_eyebrows_00",
-   *  "urn:decentraland:off-chain:base-avatars:f_mouth_00" 
-   *  "urn:decentraland:off-chain:base-avatars:standard_hair", 
-   *  "urn:decentraland:off-chain:base-avatars:f_simple_yellow_tshirt", 
-   *  "urn:decentraland:off-chain:base-avatars:f_brown_trousers", 
-   *  "urn:decentraland:off-chain:base-avatars:bun_shoes"]
-   */
-  repeated string wearables = 10;
-  /**
-   * default = []
-   */
-  repeated string emotes = 11;
-}
+  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)
+}
+

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

@@ -6,15 +6,22 @@ import "decentraland/sdk/components/common/id.proto";
 
 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.
 enum BillboardMode {
   BM_NONE = 0;
   BM_X = 1;
   BM_Y = 2;
   BM_Z = 4;
-  BM_ALL = 7;
+  BM_ALL = 7; // bitwise combination BM_X | BM_Y | BM_Z
 }
 
-message PBBillboard {
-  // default=BM_ALL
-  optional BillboardMode billboard_mode = 1; 
-}

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

@@ -5,6 +5,8 @@ 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;
+  common.CameraType mode = 1; // the camera type (1st-person or 3rd-person)
 }

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

@@ -8,7 +8,18 @@ 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 or 3rd-person) 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.
 message PBCameraModeArea {
-  decentraland.common.Vector3 area = 1;
-  common.CameraType mode = 2;
+  decentraland.common.Vector3 area = 1; // the 3D size of the region
+  common.CameraType mode = 2;           // the camera mode to enforce
 }

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

@@ -4,10 +4,10 @@ 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 {
-   // which file to load
-  string src = 1;
-  
-  // SDK7xx which node to load
-  // SDK7xx optional string scene_name = 2;
+  string src = 1; // the GLTF file path as listed in the scene's manifest.
 }

package/proto/decentraland/sdk/components/mesh_collider.proto

@@ -6,25 +6,31 @@ import "decentraland/sdk/components/common/id.proto";
 
 option (common.ecs_component_id) = 1019;
 
-enum ColliderLayer {
-  CL_NONE = 0;
-  CL_POINTER = 1;
-  CL_PHYSICS = 2;
-}
-
+// The MeshCollider component provides basic collision detection between Entities and Avatars. It 
+// can behave like a cube, a plane, a sphere or a cylinder. 
+//
+// The Entity's Transform affects the MeshCollider, scaling it and rotating it appropriately. If
+// the Transform for the collision mesh must be different than the Transform for rendering the Entity,
+// two different Entities must be used.
+//
+// More complex shapes require the use of a `GltfContainer` component.
 message PBMeshCollider {
+  // BoxMesh is a prism shape that contains the Entity.
   message BoxMesh {}
 
+  // CylinderMesh is a truncated cone shape that contains the Entity.
   message CylinderMesh {
-    optional float radius_top = 1; // default=1.0
-    optional float radius_bottom = 2; // default=1.0
+    optional float radius_top = 1;    // (default 1.0)
+    optional float radius_bottom = 2; // (default 1.0)
   }
 
+  // PlaneMesh is a 2D rectangle described by the Entity's Transform.
   message PlaneMesh {}
 
+  // SphereMesh is a sphere shape that contains the Entity.
   message SphereMesh {}
 
-  optional int32 collision_mask = 1; // default = ColliderLayer.Physics | ColliderLayer.Pointer
+  optional int32 collision_mask = 1; // enabled ColliderLayers (default CL_POINTER | CL_PHYSICS)
 
   oneof mesh {
     BoxMesh box = 2;
@@ -33,3 +39,10 @@ message PBMeshCollider {
     PlaneMesh plane = 5;
   }
 }
+
+// ColliderLayer determines the kind of collision to detect, in OR-able bit flag form.
+enum ColliderLayer {
+  CL_NONE = 0;    // no collisions
+  CL_POINTER = 1; // collisions with the player's pointer ray (e.g. mouse cursor hovering)
+  CL_PHYSICS = 2; // colission with Avatars
+}

package/proto/decentraland/sdk/components/mesh_renderer.proto

@@ -4,20 +4,33 @@ package decentraland.sdk.components;
 import "decentraland/sdk/components/common/id.proto";
 option (common.ecs_component_id) = 1018;
 
+// The MeshRenderer component renders a basic geometric shape for an Entity. It can be a cube, a 
+// plane, a sphere or a cylinder.
+//
+// The cube and plane variants can include a UV texture mapping, so specific areas of a material 
+// texture are rendered on different faces of the shape. They are serialized as a sequence of 2D
+// `float` coordinates, one for each corner of each side of each face.
+//
+// More complex shapes require the use of a `GltfContainer` component.
 message PBMeshRenderer {
+    
+    // BoxMesh renders a prism shape.
     message BoxMesh {
-        repeated float uvs = 1;
+        repeated float uvs = 1; // 96-value texture map (2D * 6 faces * 2 sides * 4 vertices)
     }
 
+    // CylinderMesh renders a truncated cone shape.
     message CylinderMesh {
-        optional float radius_top = 1; // default=1.0
-        optional float radius_bottom = 2; // default=1.0
+        optional float radius_top = 1;    // (default 1.0)
+        optional float radius_bottom = 2; // (default 1.0)
     }
 
+    // PlaneMesh renders a 2D rectangular shape.
     message PlaneMesh {
-        repeated float uvs = 1;
+        repeated float uvs = 1; // 16-value texture map (2D * 1 face * 2 sides * 4 vertices)
     }
 
+    // SphereMesh renders a spherical shape.
     message SphereMesh {
     }
 

package/proto/decentraland/sdk/components/nft_shape.proto

@@ -7,6 +7,20 @@ import "decentraland/sdk/components/common/id.proto";
 
 option (common.ecs_component_id) = 1040;
 
+// The NftShape component renders a framed picture from an NFT. It supports PNG, JPEG and GIF files.
+//
+// The `src` field is the URI of the NFT, which includes its parent contract and index, using
+// the `https:` or `ethereum:` schemes.
+//
+// The picture frame can have several different styles, plus a background color for images that have
+// transparent pixels.
+message PBNftShape {
+  string src = 1;                                // the URI of the NFT
+  optional NftFrameType style = 2;               // the frame style (default NFT_CLASSIC)
+  optional decentraland.common.Color3 color = 3; // RGB background (default [0.6404918, 0.611472, 0.8584906])
+}
+
+// NftFrameType is a predefined framing style for the image.
 enum NftFrameType {
   NFT_CLASSIC = 0;
   NFT_BAROQUE_ORNAMENT = 1;
@@ -31,10 +45,4 @@ enum NftFrameType {
   NFT_WOOD_TWIGS = 20;
   NFT_CANVAS = 21;
   NFT_NONE = 22;
-}
-
-message PBNftShape {
-  string src = 1;
-  optional NftFrameType style = 2; // default = PictureFrameStyle.Classic
-  optional decentraland.common.Color3 color = 3; // default = decentraland.common.Color3(0.6404918, 0.611472, 0.8584906)
-}
+}

package/proto/decentraland/sdk/components/pointer_events.proto

@@ -7,25 +7,39 @@ import "decentraland/sdk/components/common/input_action.proto";
 
 option (common.ecs_component_id) = 1062;
 
-enum PointerEventType {
-  PET_UP = 0;
-  PET_DOWN = 1;
-  PET_HOVER_ENTER = 2;
-  PET_HOVER_LEAVE = 3;
-}
-
+// PointerEvents adds configurable pointer-based interactions to the attached Entity.
+//
+// Events that match the criteria defined in the PointerEvents structure are reported back to the 
+// Entity via the PointerEventsResult component.
+//
+// Some examples of events that can be detected:
+// - Pointer hovering over the Entity.
+// - Held mouse button released over the Entity.
+// - Controller button pressed while targeting the Entity.
+// - Key pressed while targeting the Entity, but only in close range.
+//
+// It also supports simple visual feedback when interactions occur, by showing floating text.
+// More sophisticated feedback requires the use of other components.
 message PBPointerEvents {
   message Info {
-    optional common.InputAction button = 1; // default=InputAction.ANY
-    optional string hover_text = 2; // default='Interact'
-    optional float max_distance = 3; // default=10
-    optional bool show_feedback = 4; // default=true
+    optional common.InputAction button = 1; // key/button in use (default IA_ANY)
+    optional string hover_text = 2;         // feedback on hover (default 'Interact')
+    optional float max_distance = 3;        // range of interaction (default 10)
+    optional bool show_feedback = 4;        // enable or disable hover text (default true)
   }
 
   message Entry {
-    PointerEventType event_type = 1;
-    Info event_info = 2;
+    PointerEventType event_type = 1; // the kind of interaction to detect
+    Info event_info = 2;             // additional configuration for this detection
   }
 
-  repeated Entry pointer_events = 1;
+  repeated Entry pointer_events = 1; // the list of relevant events to detect
 }
+
+// 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;
+}

package/proto/decentraland/sdk/components/pointer_lock.proto

@@ -4,6 +4,8 @@ package decentraland.sdk.components;
 import "decentraland/sdk/components/common/id.proto";
 option (common.ecs_component_id) = 1074;
 
+// PointerLock indicates whether the mouse pointer is automatically following the camera’s point of
+// focus (locked), or can move freely on the screen (unlocked).
 message PBPointerLock {
-  bool is_pointer_locked = 1;
+  bool is_pointer_locked = 1; // whether the pointer is locked
 }

package/proto/decentraland/sdk/components/raycast.proto

@@ -7,14 +7,17 @@ import "decentraland/sdk/components/common/id.proto";
 
 option (common.ecs_component_id) = 1067;
 
+// The Raycast component allows scenes to request raycasting from the game engine. The results will
+// be available in a RaycastResult component set later on the same Entity.
+message PBRaycast {
+  decentraland.common.Vector3 origin = 2;    // the starting point of the ray in 3D space
+  decentraland.common.Vector3 direction = 3; // the direction of the ray in 3D space
+  float max_distance = 4;                    // the maximum length of the ray
+  RaycastQueryType query_type = 5;           // the RaycastQueryType behavior (see above)
+}
+
+// RaycastQueryType indicates whether the ray should stop on the first collition, or continue.
 enum RaycastQueryType {
   RQT_HIT_FIRST = 0;
   RQT_QUERY_ALL = 1;
 }
-
-message PBRaycast {
-  decentraland.common.Vector3 origin = 2;
-  decentraland.common.Vector3 direction = 3;
-  float max_distance = 4;
-  RaycastQueryType query_type = 5;
-}

package/proto/decentraland/sdk/components/raycast_result.proto

@@ -6,20 +6,25 @@ import "decentraland/common/vectors.proto";
 
 option (common.ecs_component_id) = 1068;
 
+// The RaycastResult component is added to an Entity when the results of a previously attached
+// Raycast component are available. It contains information about the ray and any objects it 
+// collided with.
 message PBRaycastResult {
-  int32 timestamp = 1;
-  decentraland.common.Vector3 origin = 2;
-  decentraland.common.Vector3 direction = 3;
-  repeated RaycastHit hits = 4;
+  int32 timestamp = 1;                       // the timestamp of the Raycast component addition
+  decentraland.common.Vector3 origin = 2;    // the starting point of the ray
+  decentraland.common.Vector3 direction = 3; // the direction vector of the ray
+  repeated RaycastHit hits = 4;              // zero or more hits
 }
 
-// Position will be relative to the scene  
+// RaycastHit contains information about the intersection of a ray with a mesh.
 message RaycastHit {
-  decentraland.common.Vector3 position = 1;
-  decentraland.common.Vector3 origin = 2;
-  decentraland.common.Vector3 direction = 3;
-  decentraland.common.Vector3 normal_hit = 4;
-  float length = 5;
-  optional string mesh_name = 6;
-  optional int64 entity_id = 7;
+  // Position will be relative to the scene  
+  decentraland.common.Vector3 position = 1;   // the intersection point
+  decentraland.common.Vector3 origin = 2;     // the starting point of the ray
+  decentraland.common.Vector3 direction = 3;  // the direction vector of the ray
+  decentraland.common.Vector3 normal_hit = 4; // the entry vector of the ray into the collision mesh
+  
+  float length = 5;              // the distance between the ray origin and the hit position
+  optional string mesh_name = 6; // (unused) mesh ID if collision happened inside a GltfContainer
+  optional int64 entity_id = 7;  // the ID of the Entity that has the impacted mesh attached
 }

package/proto/decentraland/sdk/components/text_shape.proto

@@ -8,29 +8,38 @@ import "decentraland/sdk/components/common/texts.proto";
 
 option (common.ecs_component_id) = 1030;
 
+// The TextShape component renders customizable floating text.
+//
+// The position and rotation of the text are defined by the Entity's Transform, while its size
+// can either scale with the Transform or be fixed by a font size.
+//
+// Several options can be configured, including color, padding, line spacing and drop shadows.
 message PBTextShape {
-  string text = 1;
-  optional common.Font font = 2; // default=F_SANS_SERIF
-  optional float font_size = 3; // default=10
-  optional bool font_auto_size = 4;
-  optional common.TextAlignMode text_align = 5; // default=TAM_CENTER_CENTER
-  optional float width = 6; // default=1
-  optional float height = 7; // default=1
-  optional float padding_top = 8;
-  optional float padding_right = 9;
-  optional float padding_bottom = 10;
-  optional float padding_left = 11;
-  // The amount of additional spacing to add between each lines of text.
-  optional float line_spacing = 12;
-  // Allows control over how many lines of text are displayed.
-  optional int32 line_count = 13;
-  // Enables text wrapping
-  optional bool text_wrapping = 14;
-  optional float shadow_blur = 15;
-  optional float shadow_offset_x = 16;
-  optional float shadow_offset_y = 17;
-  optional float outline_width = 18;
-  optional decentraland.common.Color3 shadow_color = 19; // default=(1.0,1.0,1.0)
-  optional decentraland.common.Color3 outline_color = 20; // default=(1.0,1.0,1.0)
-  optional decentraland.common.Color4 text_color = 21; // default=(1.0,1.0,1.0)
+  string text = 1; // the content
+
+  optional common.Font font = 2;    // the font (default F_SANS_SERIF)
+  optional float font_size = 3;     // the font size (default 10)
+  optional bool font_auto_size = 4; // override `font_size` to automatically fit in `width`/`height`
+  
+  optional common.TextAlignMode text_align = 5; // X and Y alignment (default TAM_CENTER_CENTER)
+
+  optional float width = 6;           // available horizontal space (default 1)
+  optional float height = 7;          // available vertical space (default 1)
+  optional float padding_top = 8;     // distance from text to top border (default 0)
+  optional float padding_right = 9;   // distance from text to right border (default 0)
+  optional float padding_bottom = 10; // distance from text to bottom border (default 0)
+  optional float padding_left = 11;   // distance from text to left border (default 0)
+  
+  optional float line_spacing = 12; // extra distance between lines (default 0)
+  optional int32 line_count = 13;   // maximum number of lines to display
+  optional bool text_wrapping = 14; // wrap text when the border is reached (default false)
+
+  optional float shadow_blur = 15;     // blurriness of the drop shadow (default 0)
+  optional float shadow_offset_x = 16; // horizontal length of the shadow (default 0)
+  optional float shadow_offset_y = 17; // vertical length of the shadow (default 0)
+  optional float outline_width = 18;   // width of the stroke outlining each letter (default 0)
+
+  optional decentraland.common.Color3 shadow_color = 19;  // drop shadow color (default [1.0, 1.0, 1.0])
+  optional decentraland.common.Color3 outline_color = 20; // outline stroke color (default [1.0, 1.0, 1.0])
+  optional decentraland.common.Color4 text_color = 21;    // text color (default [1.0, 1.0, 1.0])
 }