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

package/proto/decentraland/quests/definitions.proto

@@ -0,0 +1,185 @@
+syntax = "proto3";
+package decentraland.quests;
+
+import "google/protobuf/empty.proto";
+
+// Errors 
+message InvalidQuest {}
+
+message NotUUID {}
+
+message InternalServerError {}
+
+message NotFoundQuestInstance {}
+
+message QuestAlreadyStarted {}
+
+message NotOwner {}
+
+message IgnoredEvent {}
+
+message StartQuestRequest {
+  string quest_id = 1;
+}
+
+message StartQuestResponse {
+  /* There are a few valid reasons to not be accepted:
+  *  - Quest is not found
+  *  - Quest is deactivated (the owner deleted it)
+  *  - User already started the quest
+  *  - Internal errors (DB connection failed or something like that) */
+  message Accepted {}
+  oneof response {
+    Accepted accepted = 1;
+    InvalidQuest invalid_quest = 2;
+    NotUUID not_uuid_error = 3;
+    InternalServerError internal_server_error = 4;
+    QuestAlreadyStarted quest_already_started = 5;
+  }
+}
+
+message AbortQuestRequest {
+  string quest_instance_id = 1;
+}
+
+message AbortQuestResponse {
+  /* There are a few valid reasons to not be accepted:
+  *  - Quest instance is not found
+  *  - Quest instance is from another user 
+  *  - Quest instance already aborted
+  *  - Internal errors (DB connection failed or something like that) */
+  message Accepted {}
+  oneof response {
+    Accepted accepted = 1;
+    NotFoundQuestInstance not_found_quest_instance = 2;
+    NotUUID not_uuid_error = 3;
+    NotOwner not_owner = 4;
+    InternalServerError internal_server_error = 5;
+  }
+}
+
+message Event {
+  string id = 1;
+  string address = 2;
+  Action action = 3;
+}
+
+message EventRequest {
+  Action action = 1;
+}
+
+message EventResponse {
+  oneof response {
+    string accepted_event_id = 1;
+    IgnoredEvent ignored_event = 2;
+    InternalServerError internal_server_error = 3;
+  }
+}
+
+message QuestDefinition {
+  repeated Step steps = 1;
+  repeated Connection connections = 2;
+}
+
+message Connection {
+  string step_from = 1;
+  string step_to = 2;
+}
+
+message Step {
+  string id = 1;
+  string description = 2;
+  repeated Task tasks = 3;
+}
+
+message Action {
+  string type = 1;
+  map<string, string> parameters = 2;
+}
+
+message Task {
+  string id = 1;
+  string description = 2;
+  repeated Action action_items = 3;
+}
+
+message StepContent {
+  repeated Task to_dos = 1;
+  repeated Task tasks_completed = 2;
+}
+
+message QuestState {
+  map<string, StepContent> current_steps = 2;
+  fixed32 steps_left = 3;
+  repeated string steps_completed = 4;
+  repeated string required_steps = 5;
+}
+
+message Quest {
+  string id = 1;
+  string name = 2;
+  string description = 3;
+  QuestDefinition definition = 4;
+  string creator_address = 5;
+  string image_url = 6;
+  bool active = 7;
+  fixed32 created_at = 8;
+}
+
+message QuestInstance {
+  string id = 1;
+  Quest quest = 2;
+  QuestState state = 3;
+}
+
+message QuestStateUpdate {
+  string instance_id = 1;
+  QuestState quest_state = 2;
+  string event_id = 3;
+}
+
+message UserUpdate {
+  oneof message {
+    bool subscribed = 1;
+    QuestStateUpdate quest_state_update = 2;
+    QuestInstance new_quest_started = 3;
+    string event_ignored = 4;
+  }
+  string user_address = 5;
+}
+
+message Quests {
+  repeated QuestInstance instances = 1;
+}
+
+message GetAllQuestsResponse {
+  oneof response {
+    Quests quests = 1;
+    InternalServerError internal_server_error = 2;
+  }
+}
+
+message GetQuestDefinitionRequest {
+  string quest_id = 1;
+}
+
+message GetQuestDefinitionResponse {
+  oneof response {
+    Quest quest = 1;
+    InternalServerError internal_server_error = 2;
+  }
+}
+
+service QuestsService {
+  // User actions
+  rpc StartQuest(StartQuestRequest) returns (StartQuestResponse) {}
+  rpc AbortQuest(AbortQuestRequest) returns (AbortQuestResponse) {}
+  rpc SendEvent(EventRequest) returns (EventResponse) {}
+
+  // Listen to changes in quest states and event processing updates
+  rpc Subscribe(google.protobuf.Empty) returns (stream UserUpdate) {}
+
+  // Query quest information
+  rpc GetAllQuests(google.protobuf.Empty) returns (GetAllQuestsResponse) {}
+  rpc GetQuestDefinition(GetQuestDefinitionRequest) returns (GetQuestDefinitionResponse) {}
+}

package/proto/decentraland/realm/about.proto

@@ -0,0 +1,138 @@
+syntax = "proto3";
+package decentraland.realm;
+
+import "decentraland/common/border_rect.proto";
+import "decentraland/common/vectors.proto";
+
+message AboutResponse {
+  bool healthy = 1;
+  AboutConfiguration configurations = 2;
+  ContentInfo content = 3;
+  CommsInfo comms = 4;
+  LambdasInfo lambdas = 5;
+  optional BffInfo bff = 6;
+  bool accepting_users = 7;
+
+  // @deprecated This message was never used but it's still here for compatibility reasons
+  // The reserved keyword is not working for all the toolset we have, so in the meanwhile it keeps commented
+  message MinimapConfiguration {
+    reserved 1;
+    // reserved "enabled";
+    reserved 2;
+    // reserved "data_image";
+    reserved 3;
+    // reserved "estate_image";
+  }
+
+  message MapConfiguration {
+    // whether the minimap should be rendered
+    bool minimap_enabled = 1;
+  
+    // the union of all rects here represents the places where that MAY have scenes
+    //  - all the other parcels are considered as empty, up to the explorer to decide if they're walkable or not
+    //  - the contained square is determined by points: 
+    //    - top-left      with  minX, maxY 
+    //    - bottom-left   with  minX, minY
+    //    - top-right     with  maxX, maxY 
+    //    - bottom-right  with  maxX, maxY 
+    //  Note: the coordinate system used is the Cartesian coordinate system, where the y-axis increases upwards, 
+    //    not the screen coordinate system, where the origin is at the top-left corner and the y-axis increases downwards.
+    repeated decentraland.common.BorderRect sizes = 2; 
+  
+    // ImageViewWithZoomLevel uses a description to render the minimap
+    //  using different images with different zoom levels.
+    // When `version='v1'`:
+    // - The description allows the explorer to form the URL:
+    //  url(x,y,zoom_level) = `{base_url}/{zoom_level}/{x},{y}{suffix_url}`
+    // - The given URL is for an image where the pixel `0,0` for the image `0,0` always
+    //    points to the top-left contained square.
+    // - The `zoom_level=1` is to a ratio of 3.2 pixel per parcel, this means in a 32x32 pixel square
+    //    you get 10x10 parcels. 
+    // - Each increase of zoom level, double the ratio pixel per parcels. 
+    message ImageViewWithZoomLevel {
+      // options: ['v1']
+      string version = 1; 
+      optional string base_url = 2;
+      optional string suffix_url = 3;
+      optional decentraland.common.Vector2 top_left_offset = 4;
+    }
+  
+    // ParcelView uses a description to render the minimap
+    //  using a image where each pixel is a parcel and each pixel
+    //  has the metadata to make a representation (using a shader or image-generation client-side)
+    // When `version='v1'`:
+    //  - The pixel `0,0` is the top-left contained square
+    //  - The image has to be at least of contained square pixels size
+    //  - The metadata inside each pixel follows the generated with the atlas server https://github.com/decentraland/atlas-server/blob/af371f2a59745a1f50b0b0b2382984288c4ae891/src/adapters/mini-map-renderer.ts#L27
+    message ParcelView {
+      // options: `v1`
+      string version = 1; 
+      optional string image_url = 2;
+    }
+  
+    optional ImageViewWithZoomLevel satellite_view = 5;
+    optional ParcelView parcel_view = 6;
+    optional ImageViewWithZoomLevel thumbnail_view = 7;
+  }
+
+  message SkyboxConfiguration {
+    // only one value at a time
+    optional float fixed_hour = 1;
+  }
+
+  message AboutConfiguration {
+    optional string realm_name = 1;
+    uint32 network_id = 2;
+    repeated string global_scenes_urn = 3;
+    repeated string scenes_urn = 4;
+
+    // The name "minimap" can't be used in this message
+    // The reserved keyword is not working for all the toolset we have, so in the meanwhile it keeps commented
+    reserved 5;
+    // reserved "minimap";
+
+    optional SkyboxConfiguration skybox = 6;
+
+    // A content server to be used to load the parcels around the user. Uses the POST /entities/active endpoint
+    // to continously fetch the parcels around the users. if null, then the default content server will be used
+    // if == "" then the city_loader will be disabled and the scenes_urn will be used to load the world
+    optional string city_loader_content_server = 7;
+    optional MapConfiguration map = 8;
+  }
+
+  message ContentInfo {
+    // common properties
+    bool healthy = 1;
+    optional string version = 2;
+    optional string commit_hash = 3;
+    string public_url = 4;
+  }
+  message LambdasInfo {
+    // common properties
+    bool healthy = 1;
+    optional string version = 2;
+    optional string commit_hash = 3;
+    string public_url = 4;
+  }
+  message CommsInfo {
+    // common properties
+    bool healthy = 1;
+    optional string version = 2;
+    optional string commit_hash = 3;
+    optional string public_url = 4;
+    // specific properties
+    string protocol = 50;
+    optional int32 users_count = 51;
+    optional string fixed_adapter = 52;
+  }
+  message BffInfo {
+    // common properties
+    bool healthy = 1;
+    optional string version = 2;
+    optional string commit_hash = 3;
+    string public_url = 4;
+    // specific properties
+    optional int32 user_count = 51;
+    optional string protocol_version = 52;
+  }
+}

package/proto/decentraland/sdk/components/README.md

@@ -0,0 +1,32 @@
+# How to add a new ECS Component with Protocol-Buffers
+
+In this directory, we have all the components with the schema `ComponentName.proto`. `ComponentName` has to be PascalCase, and the `.proto` is the extension that is recognized as protocol-buffer schema.
+
+Inside each proto, we need to have at least this template:
+```proto
+syntax = "proto3";
+
+import "decentraland/sdk/components/common/id.proto";
+option (common.ecs_component_id) = XXXX;
+
+message PBComponentName {
+    float one_parameter = 1;
+}
+
+```
+
+Some points that must be well-defined:
+- `XXXX` the component ID is a super important property of the component, and it has to be unique at least between proto, otherwise, the code generation will fail.
+- `PBComponentName` the root message has to be the same as the file name with the prefix `PB`
+- `one_parameter` each parameter name has to be snake_case.
+
+
+## Common directory
+The common directory only has to have unambiguous structures like decentraland.common.Vector3, decentraland.common.Color3, Quaternion, etc. These messages will never change.
+
+## About specific options with other languages
+The definition must be the minimal proto code, and it shouldn't have a specific option to compile on some platform. So if you have to add additional information to the proto, you will be able to run a post-process after the protocol schemas acquisition.
+For example, in the unity-renderer repo, it'll be necessary to add the `csharp_namespace` option but it's the responsibility of this particular implementation. This code option doesn't define how the component is.
+
+# Test component
+If you write a proto and then push, CI will fail because the tests will fail. All the components need to be tested. `@dcl/ecs/test/components` has some examples!

package/proto/decentraland/sdk/components/Transform.md

@@ -0,0 +1,25 @@
+
+# Transform
+
+Transform is not a protocol-buffer definition, because it uses the native byte-buffer to write directly on the wire. This allows the consumer to copy the message directly on memory and the component be serialized a little bit faster.
+
+```cpp
+// Transform length = 44 
+struct Transform {
+    float positionX;
+    float positionY;
+    float positionZ;
+
+    float rotationX;
+    float rotationY;
+    float rotationZ;
+    float rotationW;
+
+    float scaleX;
+    float scaleY;
+    float scaleZ;
+
+    uint32_t parentEntity;
+};
+```
+- Serialized in big-endian

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

@@ -0,0 +1,31 @@
+syntax = "proto3";
+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; // a collection of animations and their current state
+}
+
+// (*) initial state means what frame is set when the state is reset:
+// - if `speed` >= 0 the frame set is the first one
+// - if `speed` < 0 the frame set is the last one
+// (**) repeating means going back to the initial state at the moment the given animation is finished and keeps playing
+
+// AnimationState indicates the status and configuration of one available animation.
+message PBAnimationState {
+  reserved 1;                     // deprecated `name` prop
+  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;      // @experimental 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 is manually stopped (default: true)
+  optional bool should_reset = 7; // whether the animation is restored to the initial state (*) when it changes from stopped to playing (default: false)
+}

package/proto/decentraland/sdk/components/asset_load.proto

@@ -0,0 +1,10 @@
+syntax = "proto3";
+package decentraland.sdk.components;
+
+import "decentraland/sdk/components/common/id.proto";
+option (common.ecs_component_id) = 1213;
+
+// AssetLoad component allows an entity to request the pre-loading of one or more assets by the renderer.
+message PBAssetLoad {
+    repeated string assets = 1;
+}

package/proto/decentraland/sdk/components/asset_load_loading_state.proto

@@ -0,0 +1,16 @@
+syntax = "proto3";
+package decentraland.sdk.components;
+
+import "decentraland/sdk/components/common/id.proto";
+option (common.ecs_component_id) = 1214;
+
+import "decentraland/sdk/components/common/loading_state.proto";
+
+// AssetLoadLoadingState is set by the engine and provides information about
+// the current state of the AssetLoad of an entity.
+// The renderer appends a new object of this in each command, there can be many commands per frames
+message PBAssetLoadLoadingState {
+  common.LoadingState current_state = 1;   // current loading state
+  string asset = 2;                        // the asset being loaded (asset's scene path)
+  uint32 timestamp = 3;                    // monotonic counter
+}

package/proto/decentraland/sdk/components/audio_event.proto

@@ -0,0 +1,12 @@
+syntax = "proto3";
+
+package decentraland.sdk.components;
+
+import "decentraland/sdk/components/common/id.proto";
+import "decentraland/sdk/components/common/media_state.proto";
+option (common.ecs_component_id) = 1105;
+
+message PBAudioEvent {
+  common.MediaState state = 1;
+  uint32 timestamp = 2;     // monotonic counter
+}

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

@@ -0,0 +1,31 @@
+syntax = "proto3";
+package decentraland.sdk.components;
+
+import "decentraland/sdk/components/common/id.proto";
+option (common.ecs_component_id) = 1020;
+
+// 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.
+//
+// `playing=true` when it's previously `playing=true`
+//  a) if clip is playing and `current_time` is NOT SET, the clip remains in the current `current_time`
+//  b) if clip is stopped or `current_time` is set, the clip is played from the `current_time` (if set) or from the beginning
+//
+// If other property (volume, loop, pitch) is changed while playing, the clip is keep playing with the new properties
+// Changing `audio_clip_url` while playing stops the current clip and plays the new one (as a new instance)
+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.
+  optional float current_time = 6;  // specifies the current playback time of the clip in seconds (default: 0).
+  optional bool global = 7; // whether the audio plays at constant volume across the scene.
+}

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

@@ -0,0 +1,22 @@
+syntax = "proto3";
+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; // whether the clip is currently playing
+  optional float volume = 2; // the audio volume (default: 1.0)
+  string url = 3;            // the audio stream HTTP URL
+  // either the audio will be global or spatial (default: false)
+  // global: plays the same way for every listener. It is not affected by distance, direction, or position.
+  // spatial: changes depending on where the listener is relative to the sound source
+  optional bool spatial = 4;
+  // Within the min distance the audio will cease to grow louder in volume (default: 0)
+  optional float spatial_min_distance = 5;
+  // The distance where sound either becomes inaudible or stops attenuation (default: 60)
+  optional float spatial_max_distance = 6;
+}

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

@@ -0,0 +1,51 @@
+syntax = "proto3";
+
+package decentraland.sdk.components;
+
+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 {
+  // @deprecated consider parenting to `engine.PlayerEntity`, this will attach to player position with an arbitrary offset
+  AAPT_POSITION = 0;
+  AAPT_NAME_TAG = 1;
+  AAPT_HEAD = 4;
+  AAPT_NECK = 5;
+  AAPT_SPINE = 6;
+  AAPT_SPINE1 = 7;
+  AAPT_SPINE2 = 8;
+  AAPT_HIP = 9;
+  AAPT_LEFT_SHOULDER = 10;
+  AAPT_LEFT_ARM = 11;
+  AAPT_LEFT_FOREARM = 12;
+  AAPT_LEFT_HAND = 2;
+  AAPT_LEFT_HAND_INDEX = 13;
+  AAPT_RIGHT_SHOULDER = 14;
+  AAPT_RIGHT_ARM = 15;
+  AAPT_RIGHT_FOREARM = 16;
+  AAPT_RIGHT_HAND = 3;
+  AAPT_RIGHT_HAND_INDEX = 17;
+  AAPT_LEFT_UP_LEG = 18;
+  AAPT_LEFT_LEG = 19;
+  AAPT_LEFT_FOOT = 20;
+  AAPT_LEFT_TOE_BASE = 21;
+  AAPT_RIGHT_UP_LEG = 22;
+  AAPT_RIGHT_LEG = 23;
+  AAPT_RIGHT_FOOT = 24;
+  AAPT_RIGHT_TOE_BASE = 25;
+}

package/proto/decentraland/sdk/components/avatar_base.proto

@@ -0,0 +1,15 @@
+
+syntax = "proto3";
+package decentraland.sdk.components;
+import "decentraland/common/colors.proto";
+import "decentraland/sdk/components/common/id.proto";
+option (common.ecs_component_id) = 1087;
+
+// AvatarBase sets all modifiers over the avatar's apparence.
+message PBAvatarBase {
+  decentraland.common.Color3 skin_color = 1;
+  decentraland.common.Color3 eyes_color = 2;
+  decentraland.common.Color3 hair_color = 3;
+  string body_shape_urn = 4;
+  string name = 5;
+}

package/proto/decentraland/sdk/components/avatar_emote_command.proto

@@ -0,0 +1,13 @@
+syntax = "proto3";
+package decentraland.sdk.components;
+
+import "decentraland/sdk/components/common/id.proto";
+option (common.ecs_component_id) = 1088;
+
+// AvatarEmoteCommand is a grow only value set, used to signal the renderer about
+// avatar emotes playback.
+message PBAvatarEmoteCommand {
+  string emote_urn = 1;
+  bool loop = 2;
+  uint32 timestamp = 3;          // monotonic counter
+}

package/proto/decentraland/sdk/components/avatar_equipped_data.proto

@@ -0,0 +1,14 @@
+syntax = "proto3";
+package decentraland.sdk.components;
+
+import "decentraland/sdk/components/common/id.proto";
+option (common.ecs_component_id) = 1091;
+
+// AvatarEquipData is used to read the information about the avatar's owneables.
+// this component is written by the engine using the communications transports'
+// data.
+message PBAvatarEquippedData {
+  repeated string wearable_urns = 1;
+  repeated string emote_urns = 2;
+  repeated string force_render = 3; // slots that will render even if hidden
+}

package/proto/decentraland/sdk/components/avatar_locomotion_settings.proto

@@ -0,0 +1,18 @@
+syntax = "proto3";
+
+package decentraland.sdk.components;
+
+import "decentraland/sdk/components/common/id.proto";
+
+option (common.ecs_component_id) = 1211;
+
+// The PBAvatarLocomotionSettings component allows scenes to modify locomotion settings defining things such
+// as the avatar movement speed, jump height etc.
+message PBAvatarLocomotionSettings {
+  optional float walk_speed = 1;            // Maximum speed when walking (in meters per second)
+  optional float jog_speed = 2;             // Maximum speed when jogging (in meters per second)
+  optional float run_speed = 3;             // Maximum speed when running (in meters per second)
+  optional float jump_height = 4;           // Height of a regular jump (in meters)
+  optional float run_jump_height = 5;       // Height of a jump while running (in meters)
+  optional float hard_landing_cooldown = 6; // Cooldown time after a hard landing before the avatar can move again (in seconds)
+}