@dcl/protocol 1.0.0-3482040729.commit-4f0f6b5 → 1.0.0-34875307214.commit-1ca8fa7

package/proto/decentraland/kernel/apis/engine_api.proto

@@ -2,118 +2,10 @@ syntax = "proto3";
 
 package decentraland.kernel.apis;
 
-message OpenExternalUrlBody {
-  string url = 1;
-}
-
-message OpenNFTDialogBody {
-  string asset_contract_address = 1;
-  string token_id = 2;
-  optional string comment = 3;
-}
-
-message CreateEntityBody {
-  string id = 1;
-}
-
-message RemoveEntityBody {
-  string id = 1;
-}
-
-message UpdateEntityComponentBody {
-  string entity_id = 1;
-  int32 class_id = 2;
-  string name = 3;
-  string json = 4;
-}
-
-message AttachEntityComponentBody {
-  string entity_id = 1;
-  string name = 2;
-  string id = 3;
-}
-
-message ComponentRemovedBody {
-  string entity_id = 1;
-  string name = 2;
-}
-
-message SetEntityParentBody {
-  string entity_id = 1;
-  string parent_id = 2;
-}
-
-enum QueryType {
-  QT_INVALID_QUERY_TYPE = 0;
-  QT_HIT_FIRST = 1;
-  QT_HIT_ALL = 2;
-  QT_HIT_FIRST_AVATAR = 3;
-  QT_HIT_ALL_AVATARS = 4;
-}
-
-message QueryBody {
-  QueryType query_id = 1;
-  string payload = 2;
-}
-
-message ComponentCreatedBody {
-  string id = 1;
-  int32 class_id = 2;
-  string name = 3;
-}
-
-message ComponentDisposedBody {
-  string id = 1;
-}
-
-message ComponentUpdatedBody {
-  string id = 1;
-  string json = 2;
-}
-
-message InitMessagesFinishedBody {}
-
-message Payload {
-  optional OpenExternalUrlBody open_external_url = 1;
-  optional OpenNFTDialogBody open_nft_dialog = 2;
-  optional CreateEntityBody create_entity = 3;
-  optional RemoveEntityBody remove_entity = 4;
-  optional UpdateEntityComponentBody update_entity_component = 5;
-  optional AttachEntityComponentBody attach_entity_component = 6;
-  optional ComponentRemovedBody component_removed = 7;
-  optional SetEntityParentBody set_entity_parent = 8;
-  optional QueryBody query = 9;
-  optional ComponentCreatedBody component_created = 10;
-  optional ComponentDisposedBody component_disposed = 11;
-  optional ComponentUpdatedBody component_updated = 12;
-  optional InitMessagesFinishedBody init_messages_finished = 13;
-}
-
-enum EAType {
-  EAT_INVALID_EA_TYPE = 0;
-  EAT_OPEN_EXTERNAL_URL = 1;
-  EAT_OPEN_NFT_DIALOG = 2;
-  EAT_CREATE_ENTITY = 3;
-  EAT_REMOVE_ENTITY = 4;
-  EAT_UPDATE_ENTITY_COMPONENT = 5;
-  EAT_ATTACH_ENTITY_COMPONENT = 6;
-  EAT_COMPONENT_REMOVED = 7;
-  EAT_SET_ENTITY_PARENT = 8;
-  EAT_QUERY = 9;
-  EAT_COMPONENT_CREATED = 10;
-  EAT_COMPONENT_DISPOSED = 11;
-  EAT_COMPONENT_UPDATED = 12;
-  EAT_INIT_MESSAGES_FINISHED = 13;
-}
-
-message EntityAction {
-  EAType type = 1;
-  optional string tag = 2;
-  Payload payload = 3;
-}
+import "decentraland/sdk/ecs6/engine_interface_ecs6.proto";
 
 message ManyEntityAction {
-  repeated EntityAction actions = 1;
+  repeated decentraland.sdk.ecs6.EntityAction actions = 1;
 }
 
 message SendBatchResponse {
@@ -175,18 +67,52 @@ message EventData {
 message CrdtSendToRendererRequest {
   bytes data = 1;
 }
-message CrdtSendToResponse {}
 
+message CrdtSendToResponse {
+  // list of CRDT messages coming back from the renderer
+  repeated bytes data = 1;
+}
+
+message CrdtGetStateRequest {}
+message CrdtGetStateResponse {
+  // returns true if the returned state has scene-created entities
+  bool has_entities = 1;
+  // static entities data (root entity, camera, etc) and scene-created entities
+  repeated bytes data = 2;
+}
+
+// deprecated
 message CrdtMessageFromRendererRequest {}
+// deprecated
 message CrdtMessageFromRendererResponse {
   repeated bytes data = 1;
 }
 
+message IsServerRequest {}
+message IsServerResponse {
+  bool is_server = 1;
+}
+
 service EngineApiService {
+  // support for legacy SDK events.
+
+  // @deprecated
   rpc SendBatch(ManyEntityAction) returns (SendBatchResponse) {}
+  // @deprecated
   rpc Subscribe(SubscribeRequest) returns (SubscribeResponse) {}
+  // @deprecated
   rpc Unsubscribe(UnsubscribeRequest) returns (UnsubscribeResponse) {}
 
+  // send information of the CRDT messages to the renderer. It returns the CRDT changes back from the renderer
+  // like raycast responses or the player's position
   rpc CrdtSendToRenderer(CrdtSendToRendererRequest) returns (CrdtSendToResponse) {}
+
+  // retrieves the current _full_ state of the entities from the renderer. This function is used to hidrate
+  // the state of the scenes when the code of the worker is stopped/resumed
+  rpc CrdtGetState(CrdtSendToRendererRequest) returns (CrdtGetStateResponse) {}
+
+  // @deprecated, this response was merged into CrdtSendToResponse
   rpc CrdtGetMessageFromRenderer(CrdtMessageFromRendererRequest) returns (CrdtMessageFromRendererResponse) {}
+
+  rpc IsServer(IsServerRequest) returns (IsServerResponse) {}
 }

package/proto/decentraland/kernel/apis/environment_api.proto

@@ -59,11 +59,18 @@ message GetExplorerConfigurationRequest {}
 message GetDecentralandTimeRequest {}
 
 service EnvironmentApiService {
+  // @deprecated, only available for SDK6 compatibility. Use runtime_api instead
   rpc GetBootstrapData(GetBootstrapDataRequest) returns (BootstrapDataResponse) {}
+  // @deprecated, only available for SDK6 compatibility. Needs migration
   rpc IsPreviewMode(IsPreviewModeRequest) returns (PreviewModeResponse) {}
+  // @deprecated, only available for SDK6 compatibility
   rpc GetPlatform(GetPlatformRequest) returns (GetPlatformResponse) {}
+  // @deprecated, only available for SDK6 compatibility
   rpc AreUnsafeRequestAllowed(AreUnsafeRequestAllowedRequest) returns (AreUnsafeRequestAllowedResponse) {}
+  // @deprecated, use GetCurrentRealm from runtime_api instead
   rpc GetCurrentRealm(GetCurrentRealmRequest) returns (GetCurrentRealmResponse) {}
+  // @deprecated, only available for SDK6 compatibility
   rpc GetExplorerConfiguration(GetExplorerConfigurationRequest) returns (GetExplorerConfigurationResponse) {}
+  // @deprecated, use GetTime from runtime_api instead
   rpc GetDecentralandTime(GetDecentralandTimeRequest) returns (GetDecentralandTimeResponse) {}
 }

package/proto/decentraland/kernel/apis/ethereum_controller.proto

@@ -46,9 +46,19 @@ message GetUserAccountResponse {
 }
 
 service EthereumControllerService {
+    // @deprecated, only available for SDK6 compatibility. This was a low level API that can
+    // be replaced by any ethereum library on top of the provider
     rpc RequirePayment(RequirePaymentRequest) returns (RequirePaymentResponse) {}
+    // @deprecated, only available for SDK6 compatibility. This was a low level API that can
+    // be replaced by any ethereum library on top of the provider
     rpc SignMessage(SignMessageRequest) returns (SignMessageResponse) {}
+    // @deprecated, only available for SDK6 compatibility. This was a low level API that can
+    // be replaced by any ethereum library on top of the provider
     rpc ConvertMessageToObject(ConvertMessageToObjectRequest) returns (ConvertMessageToObjectResponse) {}
+
     rpc SendAsync(SendAsyncRequest) returns (SendAsyncResponse) {}
+
+    // @deprecated, only available for SDK6 compatibility. This was a low level API that can
+    // be replaced by any ethereum library on top of the provider
     rpc GetUserAccount(GetUserAccountRequest) returns (GetUserAccountResponse) {}
 }

package/proto/decentraland/kernel/apis/parcel_identity.proto

@@ -34,7 +34,10 @@ message GetIsEmptyResponse {
 }
 
 service ParcelIdentityService {
+    // @deprecated, only available for SDK6 compatibility
     rpc GetParcel(GetParcelRequest) returns (GetParcelResponse) {}
+    // @deprecated, only available for SDK6 compatibility
     rpc GetSceneId(GetSceneIdRequest) returns (GetSceneIdResponse) {}
+    // @deprecated, only available for SDK6 compatibility
     rpc GetIsEmpty(GetIsEmptyRequest) returns (GetIsEmptyResponse) {}
 }

package/proto/decentraland/kernel/apis/permissions.proto

@@ -8,6 +8,8 @@ enum PermissionItem {
   PI_USE_WEB3_API = 2;
   PI_USE_WEBSOCKET = 3;
   PI_USE_FETCH = 4;
+  PI_ALLOW_MEDIA_HOSTNAMES = 5;
+  PI_OPEN_EXTERNAL_LINK = 6;
 }
 
 message PermissionResponse {
@@ -27,6 +29,8 @@ message HasManyPermissionResponse {
 }
 
 service PermissionsService {
+  // @deprecated, only available for SDK6 compatibility
   rpc HasPermission(HasPermissionRequest) returns (PermissionResponse) {}
+  // @deprecated, only available for SDK6 compatibility
   rpc HasManyPermissions(HasManyPermissionRequest) returns (HasManyPermissionResponse) {}
 }

package/proto/decentraland/kernel/apis/players.proto

@@ -23,7 +23,13 @@ message GetPlayersInSceneRequest {}
 message GetConnectedPlayersRequest {}
 
 service PlayersService {
+    // Returns data about a specific player, by id
+    // NOTE: To be deprecated after implementing foreign-entities and once the avatar scene uses SDK7
     rpc GetPlayerData(GetPlayerDataRequest) returns (PlayersGetUserDataResponse) {}
+    // Returns a list of all the ids of players who are currently standing within the parcels of the scene
+    // NOTE: To be deprecated after implementing foreign-entities and once the avatar scene uses SDK7
     rpc GetPlayersInScene(GetPlayersInSceneRequest) returns (PlayerListResponse) {}
+    // Returns a list of all the ids of players who are currently connected to the same server and grouped together
+    // NOTE: To be deprecated after implementing foreign-entities and once the avatar scene uses SDK7
     rpc GetConnectedPlayers(GetConnectedPlayersRequest)  returns (PlayerListResponse) {}
 }

package/proto/decentraland/kernel/apis/portable_experiences.proto

@@ -10,12 +10,15 @@ message KillResponse {
 }
 
 message SpawnRequest {
-    string pid = 1;
+    optional string pid = 1;
+    optional string ens = 2;
 }
 
 message SpawnResponse {
     string pid = 1;
     string parent_cid = 2;
+    string name = 3;
+    optional string ens = 4;
 }
 
 message PxRequest {
@@ -34,8 +37,19 @@ message ExitResponse {
 }
 
 service PortableExperiencesService {
+    // Spawns a new portable experience that is detached from the current scene.
+    // Spawned portable experiences can only be controlled by 1) the user (from the UI)
+    // and 2) from the parent scene. If the parent scene gets unloaded i.e. by distance,
+    // once the player re-loads the parent it will inherit the children portable experiences
+    // to gain control over them.
     rpc Spawn(SpawnRequest) returns (SpawnResponse) {}
+    // Kill a child portable experience, this method only works if the child was
+    // spawned by the same process trying to kill it.
     rpc Kill(KillRequest) returns (KillResponse) {}
+    // Kill the current scene if the current scene is a portable experience. Other
+    // kind of scenes are not allowed to finish their programs like portable experiences.
     rpc Exit(ExitRequest) returns (ExitResponse) {}
+    // Gets a list of running portable experiences for the current user. Be mindful
+    // about the performance penalty of calling this function all frames.
     rpc GetPortableExperiencesLoaded(GetPortableExperiencesLoadedRequest) returns (GetPortableExperiencesLoadedResponse) {}
 }

package/proto/decentraland/kernel/apis/restricted_actions.proto

@@ -1,26 +1,173 @@
 syntax = "proto3";
 package decentraland.kernel.apis;
 
-message Vector3 {
-    float x = 1;
-    float y = 2;
-    float z = 3;
+import "decentraland/common/vectors.proto";
+import "decentraland/sdk/components/common/avatar_mask.proto";
+import "decentraland/sdk/components/common/explorer_ui.proto";
+
+message MovePlayerToRequest {
+  decentraland.common.Vector3 new_relative_position = 1;
+  optional decentraland.common.Vector3 camera_target = 2;
+  optional decentraland.common.Vector3 avatar_target = 3;
+  optional float duration = 4; // by default (no duration param) the player is instantly moved and not interpolated
 }
 
-message MovePlayerToResponse { }
+message TeleportToRequest {
+  // The parcel to land on. Omitted: the realm's default spawn (only meaningful with `realm`).
+  optional decentraland.common.Vector2 world_coordinates = 1;
+  // The realm the parcel belongs to: a world name (`foo.dcl.eth`) or a realm url. When set, the
+  // client changes realm (a full reconnect, even to the realm the player is in) and lands on the
+  // parcel there. Omitted: the parcel is in the player's current realm.
+  optional string realm = 2;
+}
 
-message MovePlayerToRequest {
-    Vector3 new_relative_position = 1;
-    optional Vector3 camera_target = 2;
+message TriggerEmoteRequest {
+  string predefined_emote = 1;
+  optional decentraland.sdk.components.common.AvatarMask mask = 2;
+}
+
+message ChangeRealmRequest {
+  string realm = 1;
+  optional string message = 2;
+}
+
+message OpenExternalUrlRequest {
+  string url = 1;
+}
+
+message OpenNftDialogRequest {
+  string urn = 1;
+}
+
+message UnblockPointerRequest {}
+
+message CommsAdapterRequest {
+  string connection_string = 1;
+}
+
+message TriggerSceneEmoteRequest {
+  string src = 1;
+  optional bool loop = 2;
+  optional decentraland.sdk.components.common.AvatarMask mask = 3;
+}
+
+message SuccessResponse {
+  bool success = 1;
 }
 
 message TriggerEmoteResponse { }
 
-message TriggerEmoteRequest {
-    string predefined_emote = 1;
+message MovePlayerToResponse { 
+  bool success = 1;
+}
+
+message WalkPlayerToRequest {
+  decentraland.common.Vector3 new_relative_position = 1;
+  float stop_threshold = 2;
+  optional float timeout = 3; // max seconds before the request is failed; not passed to the movement scene
+}
+
+message WalkPlayerToResponse {
+  bool success = 1;
+}
+
+message TeleportToResponse { }
+
+message SetUiFocusRequest {
+  string element_id = 1;
+}
+
+message ClearUiFocusRequest { }
+
+message GetUiFocusRequest { }
+
+message UiFocusResponse {
+  // the element that is/was focussed
+  optional string element_id = 1;
+}
+
+message CopyToClipboardRequest {
+  string text = 1;
+}
+
+message EmptyResponse { }
+
+message StopEmoteRequest { }
+
+// Verdict of an OpenExplorerUi request (enum rather than a bool so new outcomes stay expressible).
+enum OpenExplorerUiResult {
+  UNSPECIFIED = 0;
+  OPENED = 1;
+  WAS_ALREADY_OPEN = 2;             // a fullscreen panel is already open
+  REJECTED_NOT_CURRENT_SCENE = 3;   // the standard restricted-actions current-scene gate rejected the call
+  REJECTED_FEATURE_DISABLED = 4;    // the requested section is hidden by feature flags or client doesn't have that feature
+  REJECTED_NO_USER_GESTURE = 5;     // rejected: the call did not originate from a user gesture
+}
+
+message OpenExplorerUiRequest {
+  decentraland.sdk.components.common.ExplorerUi ui = 1;
+
+  // Extension point for future per-panel parameters, as a oneof so each panel gets its
+  // own optional param message without touching existing fields. 
+  //   message MapParams { int32 focus_x = 1; int32 focus_y = 2; }
+  //   oneof params { MapParams map = 10; }
+}
+
+message OpenExplorerUiResponse {
+  // Carries only the verdict of the open action. 
+  OpenExplorerUiResult open_result = 1;
 }
 
 service RestrictedActionsService {
-    rpc MovePlayerTo(MovePlayerToRequest) returns (MovePlayerToResponse) {}
-    rpc TriggerEmote(TriggerEmoteRequest) returns (TriggerEmoteResponse) {}
+  // MovePlayerTo will move the player to a position relative to the current scene.
+  // If 'duration' field is used in the request, the success response depends on the
+  // whole interpolation being completed or interrupted (e.g: by input movement)
+  rpc MovePlayerTo(MovePlayerToRequest) returns (MovePlayerToResponse) {}
+
+  // TeleportTo will move the user to the specified world LAND parcel coordinates
+  // WalkPlayerTo will walk the player to a position relative to the current scene,
+  // managed by the movement controller scene. Returns success when the player reaches
+  // within stop_threshold distance, or false if the path is blocked, the player gets
+  // stuck, the player interrupts the walk with manual input, or the optional timeout expires.
+  rpc WalkPlayerTo(WalkPlayerToRequest) returns (WalkPlayerToResponse) {}
+
+  rpc TeleportTo(TeleportToRequest) returns (TeleportToResponse) {}
+
+  // TriggerEmote will trigger an emote in this current user
+  rpc TriggerEmote(TriggerEmoteRequest) returns (TriggerEmoteResponse) {}
+
+  // @deprecated, use TeleportTo with `realm` (and no `world_coordinates` for the realm's default spawn)
+  // ChangeRealm prompts the user to change to a specific realm
+  rpc ChangeRealm(ChangeRealmRequest) returns (SuccessResponse) {}
+
+  // OpenExternalUrl prompts the user to open an external link
+  rpc OpenExternalUrl(OpenExternalUrlRequest) returns (SuccessResponse) {}
+
+  // OpenNftDialog opens an NFT dialog.
+  rpc OpenNftDialog(OpenNftDialogRequest) returns (SuccessResponse) {}
+
+  // Asks the explorer to connect to other communications adapter, this feature
+  // can be used to join private game servers
+  rpc SetCommunicationsAdapter(CommsAdapterRequest) returns (SuccessResponse) {}
+
+  // TriggerSceneEmote will trigger an scene emote file in this current user
+  rpc TriggerSceneEmote(TriggerSceneEmoteRequest) returns (SuccessResponse) {}
+
+  // CopyToClipboard copies the provided text into the clipboard
+  // Sets the focus to a specific UI element
+  rpc SetUiFocus(SetUiFocusRequest) returns (UiFocusResponse) {}
+
+  // Clears the focus from any currently focused textentry or dropdown
+  rpc ClearUiFocus(ClearUiFocusRequest) returns (UiFocusResponse) {}
+
+  // Returns the element_id of any currently focused textentry or dropdown
+  rpc GetUiFocus(GetUiFocusRequest) returns (UiFocusResponse) {}
+
+  rpc CopyToClipboard(CopyToClipboardRequest) returns (EmptyResponse) {}
+
+  // StopEmote will stop the current emote
+  rpc StopEmote(StopEmoteRequest) returns (SuccessResponse) {}
+
+  // OpenExplorerUi opens a specific fullscreen explorer panel and returns the open verdict.
+  rpc OpenExplorerUi(OpenExplorerUiRequest) returns (OpenExplorerUiResponse) {}
 }

package/proto/decentraland/kernel/apis/runtime.proto

@@ -0,0 +1,71 @@
+syntax = "proto3";
+package decentraland.kernel.apis;
+
+import "decentraland/common/content_mapping.proto";
+import "decentraland/sdk/components/realm_info.proto";
+
+// This API will contain all the information related to the world runtime.
+// Things related to the user, players or the scene itself has they own api, and
+// won't live here. (UserIdentity, Players, ParcelIdentity)
+
+message GetRealmResponse {
+  optional decentraland.sdk.components.PBRealmInfo realm_info = 1;
+}
+
+message GetWorldTimeResponse {
+  int32 seconds = 1;
+}
+
+message GetRealmRequest {}
+message GetWorldTimeRequest {}
+
+message ReadFileRequest {
+  // name of the deployed file
+  string file_name = 1;
+}
+message ReadFileResponse {
+  // contents of the file
+  bytes content = 1;
+  // deployed hash/CID
+  string hash = 2;
+}
+
+message CurrentSceneEntityRequest {}
+message CurrentSceneEntityResponse {
+  // this is either the entityId or the full URN of the scene that is running
+  string urn = 1;
+  // contents of the deployed entities
+  repeated decentraland.common.ContentMapping content = 2;
+  // JSON serialization of the entity.metadata field
+  string metadata_json = 3;
+  // baseUrl used to resolve all content files
+  string base_url = 4;
+}
+
+message GetExplorerInformationRequest {}
+message GetExplorerInformationResponse {
+  // the agent that current explorer is identified as
+  string agent = 1;
+  // options: "desktop", "mobile", "vr", "web"
+  string platform = 2;
+  // custom configurations set in the explorer
+  map<string, string> configurations = 3;
+}
+
+service RuntimeService {
+  // Provides information about the current realm
+  rpc GetRealm(GetRealmRequest) returns (GetRealmResponse) {}
+  // Provides information about the Decentraland Time, which is coordinated
+  // across players.
+  rpc GetWorldTime(GetWorldTimeRequest) returns (GetWorldTimeResponse) {}
+  // Returns the file content of a deployed asset. If the file doesn't
+  // exist or cannot be retrieved, the RPC call throws an error.
+  // This method is called to load any assets deployed among the scene,
+  // runtime may cache this response much more than the provided "fetch" function.
+  rpc ReadFile(ReadFileRequest) returns (ReadFileResponse) {}
+  // Returns information about the current scene. This is the replacement of GetBootstrapData
+  rpc GetSceneInformation(CurrentSceneEntityRequest) returns (CurrentSceneEntityResponse) {}
+
+  // Provides information about the explorer
+  rpc GetExplorerInformation(GetExplorerInformationRequest) returns (GetExplorerInformationResponse) {}
+}

package/proto/decentraland/kernel/apis/scene.proto

@@ -0,0 +1,16 @@
+syntax = "proto3";
+package decentraland.kernel.apis;
+
+import "decentraland/common/content_mapping.proto";
+
+message GetSceneRequest {}
+message GetSceneResponse {
+    string cid = 1;
+    string metadata = 2;
+    string base_url = 3;
+    repeated decentraland.common.ContentMapping contents = 4;
+}
+
+service SceneService {
+    rpc GetSceneInfo(GetSceneRequest) returns (GetSceneResponse) {}
+}

package/proto/decentraland/kernel/apis/signed_fetch.proto

@@ -20,6 +20,14 @@ message SignedFetchRequest {
     optional FlatFetchInit init = 2;
 }
 
+message GetHeadersResponse {
+    map<string, string> headers = 1;
+}
+
 service SignedFetchService {
+    // SignedFetch is used to authenticate JSON requests in name of the users,
+    // a special scoped signature is generated following the https://adr.decentraland.org/adr/ADR-44
     rpc SignedFetch(SignedFetchRequest) returns (FlatFetchResponse) {}
+
+    rpc GetHeaders(SignedFetchRequest) returns (GetHeadersResponse) {}
 }

package/proto/decentraland/kernel/apis/social_controller.proto

@@ -3,14 +3,17 @@ package decentraland.kernel.apis;
 
 message InitRequest {}
 message SocialEvent {
-  string event = 1;
-  string payload = 2;
+    string event = 1;
+    string payload = 2;
 }
 
 message GetAvatarEventsResponse {
-  repeated SocialEvent events = 1;
+    repeated SocialEvent events = 1;
 }
 
 service SocialControllerService {
+    // @deprecated, only available for SDK6 compatibility. This was a low level
+    // API used for the AvatarScene, it will be replaced by Foreign Entities in
+    // SDK7
     rpc PullAvatarEvents(InitRequest) returns (GetAvatarEventsResponse) {}
 }