decentraland / decentraland/sdk

SDK7 APIs: make a clearly definition

Open
#930 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
No language data
Stars
4
Forks
5
PR merge metrics
No merged PRs in 30d

Description

There is a misunderstanding about what APIs are usable and what aren't.

Glossary:
- **Foundation client**: refers to https://github.com/decentraland/unity-renderer/
- 🏷️ : inheritance from SDK6

# Current protocol status

## ✅ `~system/CommsApi`
- `async getActiveVideoStreams`

## ✅ `~system/PortableExperiences`
- `async spawn`
- `async kill`
- `async exit`
- `async getPortableExperiencesLoaded`

## ✅ `~system/RestrictedActions`
- `async movePlayerTo`
- `async teleportTo`
- `async triggerEmote`
- `async changeRealm`
- `async openExternalUrl`
- `async openNftDialog`
- `async setCommunicationsAdapter`
- `async triggerSceneEmote`

## ✅ `~system/Runtime`
- `async getRealm`
- `async getWorldTime`
- `async readFile`
- `async getSceneInformation`

## ✅ `~system/SignedFetch`
- `async signedFetch`
- `async getHeaders`

## ✅ `system/EngineApi` (SDK7 methods)
- `async crdtSendToRenderer` ✅
- `async crdtGetState` ✅
- `async crdtGetMessageFromRenderer` :x:
- [ ] remove

## ⚠️🏷️ `system/EngineApi` (SDK6 methods)
- `async sendBatch` @deprecated :warning: 🏷️
- [X] Only Foundation Client exposes it
- `async subscribe` @deprecated :warning: 🏷️
- [X] Only Foundation Client exposes it
- `async unsubscribe` @deprecated :warning: 🏷️
- [X] Only Foundation Client exposes it

## ⚠️🏷️ `~system/Players`
- `async getPlayerData`
- `async getPlayersInScene`
- `async getConnectedPlayers`

- [X] only Foundation client exposes this
- [ ] When the Foundation client implements the ECS approach, stop exposing it

## ⚠️🏷️ `~system/UserIdentity`
Same as `~system/Players`, probably getting the `PlayerIdentityData.get(engine.PlayerEntity)`
- `async getUserPublicKey`
- `async getUserData`
- [X] Only Foundation client exposes this
- [ ] When the Foundation client implements the ECS approach, stop exposing it

## :warning: `~system/EthereumController`
Marked as deprecated for SDK7 runtime:
- `async requirePayment` :x: 🏷️
- [ ] remove
- [ ] export a function in the SDK with a similar behavior
- `async signMessage` :x: 🏷️
- [ ] remove
- [ ] export a function in the SDK with a similar behavior
- `async convertMessageToObject` :x: 🏷️
- [ ] remove
- `async getUserAccount` :x: 🏷️
- [ ] remove

The only exposed to SDK7 should be:
- `async sendAsync` ✅

## :x: 🏷️ `~system/UserActionModule`
- `async requestTeleport`
- [ ] :x: remove

## :warning: 🏷️ `~system/CommunicationsController`
- `async send`: marked as deprecated in https://github.com/decentraland/protocol/blob/75f18e8094a0435594eecfbb6e020614b2a86c69/proto/decentraland/kernel/apis/communications_controller.proto#L11
- [ ] Foundation client implements it
- ⚠️ This is connected with `~system/EngineApi :: sendBatch` method (comms event)
- [ ] :warning: TBD official functionality for runtime 7

## :eyes: :x: `~system/Scene`
- [ ] Stop exposing it
- [ ] Maintain API to deployed scenes (wrap the ~system/Runtime)
- `async getSceneInfo` :warning:

## :x:🏷️ `~system/EnvironmentApi` (deprecated)
- [ ] remove the API
This API shouldn't be exposed to SDK7
- `async getBootstrapData`
- `async isPreviewMode`
- `async getPlatform`
- `async areUnsafeRequestAllowed`
- `async getCurrentRealm`
- `async getExplorerConfiguration`
- `async getDecentralandTime`

## (Optional to clients for now) `~system/Testing`
- `async logTestResult`
- `async plan`
- `async setCameraTransform`

# Current apis.d.ts exposed
```ts
/**
* CommsApi
*/
declare module "~system/CommsApi" {
export function getActiveVideoStreams(body: VideoTracksActiveStreamsRequest): Promise;
}

/**
* CommunicationsController
*/
declare module "~system/CommunicationsController" {
export function send(body: RealSendRequest): Promise;
}

/**
* EngineApi
*/
declare module "~system/EngineApi" {
export function sendBatch(body: ManyEntityAction): Promise;
export function subscribe(body: SubscribeRequest): Promise;
export function unsubscribe(body: UnsubscribeRequest): Promise;
export function crdtSendToRenderer(body: CrdtSendToRendererRequest): Promise;
export function crdtGetState(body: CrdtSendToRendererRequest): Promise;
export function crdtGetMessageFromRenderer(body: CrdtMessageFromRendererRequest): Promise;
}

/**
* EnvironmentApi
*/
declare module "~system/EnvironmentApi" {
export function getBootstrapData(body: GetBootstrapDataRequest): Promise;
export function isPreviewMode(body: IsPreviewModeRequest): Promise;
export function getPlatform(body: GetPlatformRequest): Promise;
export function areUnsafeRequestAllowed(body: AreUnsafeRequestAllowedRequest): Promise;
export function getCurrentRealm(body: GetCurrentRealmRequest): Promise;
export function getExplorerConfiguration(body: GetExplorerConfigurationRequest): Promise;
export function getDecentralandTime(body: GetDecentralandTimeRequest): Promise;
}

/**
* EthereumController
*/
declare module "~system/EthereumController" {
export function requirePayment(body: RequirePaymentRequest): Promise;
export function signMessage(body: SignMessageRequest): Promise;
export function convertMessageToObject(body: ConvertMessageToObjectRequest): Promise;
export function sendAsync(body: SendAsyncRequest): Promise;
export function getUserAccount(body: GetUserAccountRequest): Promise;
}

/**
* Players
*/
declare module "~system/Players" {
export function getPlayerData(body: GetPlayerDataRequest): Promise;
export function getPlayersInScene(body: GetPlayersInSceneRequest): Promise;
export function getConnectedPlayers(body: GetConnectedPlayersRequest): Promise;
}

/**
* PortableExperiences
*/
declare module "~system/PortableExperiences" {
export function spawn(body: SpawnRequest): Promise;
export function kill(body: KillRequest): Promise;
export function exit(body: ExitRequest): Promise;
export function getPortableExperiencesLoaded(body: GetPortableExperiencesLoadedRequest): Promise;
}

/**
* RestrictedActions
*/
declare module "~system/RestrictedActions" {
export function movePlayerTo(body: MovePlayerToRequest): Promise;
export function teleportTo(body: TeleportToRequest): Promise;
export function triggerEmote(body: TriggerEmoteRequest): Promise;
export function changeRealm(body: ChangeRealmRequest): Promise;
export function openExternalUrl(body: OpenExternalUrlRequest): Promise;
export function openNftDialog(body: OpenNftDialogRequest): Promise;
export function setCommunicationsAdapter(body: CommsAdapterRequest): Promise;
export function triggerSceneEmote(body: TriggerSceneEmoteRequest): Promise;
}

/**
* Runtime
*/
declare module "~system/Runtime" {
export function getRealm(body: GetRealmRequest): Promise;
export function getWorldTime(body: GetWorldTimeRequest): Promise;
export function readFile(body: ReadFileRequest): Promise;
export function getSceneInformation(body: CurrentSceneEntityRequest): Promise;
}

/**
* Scene
*/
declare module "~system/Scene" {
export function getSceneInfo(body: GetSceneRequest): Promise;
}

/**
* SignedFetch
*/
declare module "~system/SignedFetch" {
export function signedFetch(body: SignedFetchRequest): Promise;
export function getHeaders(body: SignedFetchRequest): Promise;

}

/**
* Testing
*/
declare module "~system/Testing" {
export function logTestResult(body: TestResult): Promise;
export function plan(body: TestPlan): Promise;
export function setCameraTransform(body: SetCameraTransformTestCommand): Promise;
}

/**
* UserActionModule
*/
declare module "~system/UserActionModule" {
export function requestTeleport(body: RequestTeleportRequest): Promise;
}

/**
* UserIdentity
*/
declare module "~system/UserIdentity" {
export function getUserPublicKey(body: GetUserPublicKeyRequest): Promise;
export function getUserData(body: GetUserDataRequest): Promise;
}
```

Contributor guide

Open the contributing guide

Research direction

Start by comparing the protocol-status list with the current apis.d.ts declarations included in the issue. Resolve which SDK7 APIs should remain exposed, which deprecated entries should be removed or replaced, and which Foundation Client exceptions still apply. Done means the documented and exposed API list agrees with the finalized SDK7 status.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
api
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.