已弃用函数

旧版函数

以下函数均为旧版功能，应避免使用。它们目前仍可正常工作，但未来可能不再受支持。所有这些示例都附带了可获取相同信息或实现相同结果的替代方式链接。

玩家进入或离开场景

📔 注意：该 onEnterSceneObservable 和 onLeaveSceneObservable 事件已在 SDK 7.x 中弃用。请改用 onEnterScene ，详见玩家进入或离开场景.

每当一个头像进入或离开构成你场景的地块，或传送进出时，都会创建一个你可以监听的事件。该事件会被所有头像触发，包括玩家自己的头像。

import {
	onEnterSceneObservable,
	onLeaveSceneObservable,
} from '@dcl/sdk/observables'

onEnterSceneObservable.add((player) => {
	console.log('玩家进入场景：', player.userId)
})

onLeaveSceneObservable.add((player) => {
	console.log('玩家离开场景：', player.userId)
})

📔 注意：此事件只会响应当前在本地渲染的玩家。在大型场景中，如果场景尺寸超出可视范围，进入另一角的玩家可能不会被注册。如果该区域内的玩家数量超过 Decentraland 服务器上某个岛屿的承载能力，那么不在同一岛屿上的玩家也不可见，并且这些事件也不会跟踪他们。

这些 observables onEnterScene 和 onLeaveScene 从 '@dcl/sdk/observables' 导入的也已弃用。正确的函数名称相同，但应从 '@dcl/sdk/src/players' 导入。下面的示例中你可以看到两种写法，先是已弃用的版本，然后是正确的版本。

// 已弃用 - 从 observables 导入
import { onEnterScene, onLeaveScene } from '@dcl/sdk/observables'

onEnterScene.add((player) => {
	console.log('玩家进入场景：', player.userId)
})

onLeaveScene.add((player) => {
	console.log('玩家离开场景：', player.userId)
})

// 当前 - 作为玩家函数导入
import { onEnterScene, onLeaveScene } from '@dcl/sdk/src/players'

export function main() {
	onEnterScene((player) => {
		if (!player) return
		console.log('已进入场景', player)
	})

	onLeaveScene((userId) => {
		if (!userId) return
		console.log('已离开场景', userId)
	})
}

玩家连接或断开连接

📔 注意：该 getConnectedPlayers 函数和 onPlayerConnectedObservable 和 onPlayerDisconnectedObservable 事件已在 SDK 7.x 中弃用。请改用 onEnterScene ，详见玩家进入或离开场景。每个场景现在都是一个独立的通信岛，因此“已连接”和“在同一场景中”这两种状态现在是等价的。

通过以下方式获取当前所有已连接玩家的完整列表： getConnectedPlayers.

import { getConnectedPlayers } from '~system/Players'

executeTask(async () => {
	let connectedPlayers = await getConnectedPlayers({})
	connectedPlayers.players.forEach((player) => {
		console.log('玩家之前已经在这里：', player.userId)
	})
})

每当另一个玩家开始或停止被本地引擎渲染时，都会创建一个你可以监听的事件。玩家可能与你站在同一场景，也可能不是，但必须在可视范围内（不一定在视线内）。 onPlayerConnectedObservable onPlayerConnectedObservable 既能检测到玩家新近在附近连接，或进入足够近以处于可视范围，类似地， onPlayerDisconnectedObservable onPlayerDisconnectedObservable 能检测到玩家结束会话或走远。

import {
	onPlayerConnectedObservable,
	onPlayerDisconnectedObservable,
} from '@dcl/sdk/observables'

onPlayerConnectedObservable.add((player) => {
	console.log('玩家进入：', player.userId)
})

onPlayerDisconnectedObservable.add((player) => {
	console.log('玩家离开：', player.userId)
})

请记住，如果其他玩家在玩家加载你的场景之前就已经在周围被渲染，那么此事件不会通知新加载的场景这些已存在的玩家。如果你需要跟踪当前所有玩家，可以在场景加载时查询现有玩家，然后监听此事件以获取更新。

查询场景中的所有玩家

📔 注意：该 getPlayersInScene 函数在 SDK 7.x 中已弃用。请改为使用 PlayerIdentityData 组件遍历所有玩家。详见获取所有玩家.

你也可以通过调用 getPlayersInScene().

import { getPlayersInScene } from '~system/Players'

executeTask(async () => {
	let connectedPlayers = await getPlayersInScene({})
	connectedPlayers.players.forEach((player) => {
		console.log('玩家之前已经在这里：', player.userId)
	})
})

玩家播放动画

📔 注意：该 onPlayerExpressionObservable 事件在 SDK 7.x 中已弃用。请使用 AvatarEmoteCommand 组件代替，详见玩家播放动画.

每当玩家表演一个表情动作（舞蹈、鼓掌、挥手等）时，你都可以检测到此事件。

import { onPlayerExpressionObservable } from '@dcl/sdk/observables'

onPlayerExpressionObservable.add(({ expressionId }) => {
	console.log('表情：', expressionId)
})

该事件包含以下信息：

expressionId：所执行表情动作的名称（即：挥手, 鼓掌, 亲吻)

📔 注意：当玩家做出表情且场景已加载时，都会触发此事件。此时玩家可能正站在附近的另一个场景中。

玩家更改资料

📔 注意：该 onProfileChanged 事件在 SDK 7.x 中已弃用。请使用 AvatarEquippedData 组件代替，详见玩家更改资料.

每当玩家对其个人资料进行更改时， onProfileChanged 都会调用该事件。这些更改可能包括穿戴不同的可穿戴物、更改名称、描述、激活便携体验等。

import { onProfileChanged } from '@dcl/sdk/observables'

onProfileChanged.add((profileData) => {
	console.log('自己的资料数据为：', profileData)
})

事件数据只包含玩家的 ID 以及该头像资料的版本号，依据 catalyst 服务器。每当传播一次更改，版本号就增加 1。

当此事件被触发时，你可以使用 getUserData() 函数来获取此信息的最新版本，包括玩家所穿戴的可穿戴物列表。你可能需要在调用 getUserData() 之前稍作延迟，以确保该函数返回的版本是最新的。

💡 提示：在使用旧版 web explorer 进行预览测试时，为避免使用随机头像，请在与你的 Metamask 钱包连接的浏览器中运行场景。

📔 注意：此事件只会由当前玩家的更改触发，而不会由附近其他玩家资料的更改触发。

场景完成加载

📔 注意：该 onSceneReadyObservable 事件在 SDK v7.x 中已弃用。这个函数已不再相关。你可以通过将其放在 Main() 函数中运行，确保在场景完成加载后执行某些操作。详见场景生命周期

当场景完成加载时， onSceneReadyObservable 会被调用。无论玩家是直接加载进场景，还是从其他地方走到场景中，这都适用。当场景中的所有内容完成初始加载后，包括大型模型等，此事件就会被调用。

import { onSceneReadyObservable } from '@dcl/sdk/observables'

onSceneReadyObservable.add(() => {
	console.log('场景已加载')
})

已弃用的玩家数据方法

📔 注意：该 getUserData() 和 getPlayerData() 函数在 SDK v7.4.x 中已弃用。请改用 getPlayer() 。详见用户数据.

要获取正在运行该场景的当前玩家信息，请使用 getUserData().

下面的示例导入 ~system/UserIdentity 命名空间并运行 getUserData().

import { getUserData } from '~system/UserIdentity'

executeTask(async () => {
	let userData = await getUserData({})
	console.log(userData.data)
})

你可以通过调用 getPlayerData()，传入一个 Decentraland 账户的 id，来获取附近其他玩家的数据。

import { getPlayerData } from '~system/Players'

executeTask(async () => {
	let userData = await getPlayerData({ userId: '0x….' })
	console.log(userData)
})

两者都满足 getUserData() 和 getPlayerData() 返回与内容 API 通过同样数据结构可用的数据。详见来自任意玩家的数据

getPlayerData() 只能获取当前附近玩家的数据。它们不一定必须站在同一场景中，但必须处于可视范围内，这是因为这些信息是从正在渲染这些头像的本地引擎中获取的。要在预览中试试这一点，请打开第二个标签页并使用另一个账号登录。

📔 注意：用户 ID 必须始终为小写。如果复制钱包地址，请确保所有字符都已转为小写。

该 getUserPublicKey() 和 getUserAccount() 函数也已弃用。请使用 getPlayer() 。详见用户数据.

获取天空盒时间

📔 注意：该 getDecentralandTime() 函数在 SDK v7.x.x 中已弃用。请使用 getWorldTime() 。详见获取 Decentraland 时间.

import { getDecentralandTime } from '~system/EnvironmentApi'

executeTask(async () => {
	let time = await getDecentralandTime({})
	console.log(time)
})

获取领域

📔 注意：该 getCurrentRealm() 函数在 SDK v7.x.x 中已弃用。请使用 getRealm() 。详见获取领域数据.

import { getCurrentRealm } from '~system/EnvironmentApi'

async function fetchPlayerData() {
	const playerRealm = await getCurrentRealm({})

	console.log(playerRealm.currentRealm?.domain)
}

fetchPlayerData()

是否为预览模式

📔 注意：该 isPreviewMode() 函数在 SDK v7.x.x 中已弃用。请使用 getRealm() 而是改用其中包含 preview 属性的对象。详见获取领域数据.

import { isPreviewMode } from '~system/EnvironmentApi'

executeTask(async () => {
	const { isPreview } = await isPreviewMode({})

	if (isPreview) {
		console.log('正在预览中运行')
	}
})

玩家点击另一名玩家

每当玩家点击另一名玩家时，你都可以检测到一个事件。

import { onPlayerClickedObservable } from '@dcl/sdk/observables'

onPlayerClickedObservable.add((clickEvent) => {
	console.log('点击了 ', clickEvent.userId, ' 详情：', clickEvent.ray)
})

📔 注意：该 onPlayerClickedObservable 事件在 SDK v7.x 中已弃用。未来版本将允许采用更以数据为中心的方法，基于定期查询数据而非事件。

作为替代，你可以给玩家附加一个不可见碰撞体，并检测对此碰撞体的点击。

📔 注意：执行点击的玩家和被点击的玩家都必须站在场景的地块内。此监听器只会检测当前玩家点击其他玩家的事件，不会检测其他玩家发起的点击。

该事件包含以下数据：

userId：被点击玩家的 id
ray：关于该点击射线的信息
- 方向: Vector3 一个归一化的 Vector3，表示从点击起点到点击命中点的方向。
- distance: 数值从起点到命中点的距离，单位为米。
- origin: Vector3 点击的起点，即执行点击的玩家位置，相对于场景而言。

💡 提示：点击另一名玩家的默认行为是打开玩家护照，你可以在那里查看该玩家的更多信息、将其添加为好友等。你可以通过添加一个头像修改区域.

玩家锁定/解锁光标

📔 注意：该 onPointerLockedStateChange 事件在 SDK v7.x 中已移除，不再可用。详见事件监听器以获取当前替代方案。

玩家可以在两种光标模式之间切换： 锁定光标 模式以控制相机，或 解锁光标 模式，以便在 UI 上自由移动光标。

玩家可通过点击以下按钮来解锁光标： 鼠标右键 或按下 Esc 键；并通过点击屏幕上的任意位置来重新锁定光标。

要在玩家在这两种模式之间切换时做出响应，请使用 onChange 在……上的函数 PointerLock 组件，参见事件监听器.

玩家更改 realm 或岛屿

Decentraland 中的玩家存在于彼此分离的领域和彼此分离的岛屿中。不同领域或岛屿中的玩家无法相互看见、互动或聊天，即使他们站在同一地块上也是如此。

每次玩家更改 realm 或岛屿时， onRealmChangedObservable 事件都会被调用。

import { onRealmChangedObservable } from '@dcl/sdk/observables'

onRealmChangedObservable.add((realmChange) => {
	console.log('玩家切换到岛屿：', realmChange.room)
})

📔 注意：该 onRealmChangedObservable 事件在 SDK v7.x 中已弃用。未来版本将允许采用更以数据为中心的方法，基于定期查询数据而非事件。

此事件包含以下字段：

serverName: 字符串；catalyst 服务器名称。
room: 字符串；岛屿名。
displayName: 字符串；catalyst 服务器名称后接一个 - 以及岛屿名。例如 unicorn-x011.
domain: 字符串；所使用的 catalyst 服务器的 URL。

随着玩家在地图中移动，他们可能会切换岛屿，以便与此刻离他们最近的玩家分组。岛屿的边界也会动态调整，以便每个岛屿容纳一个可管理规模的人群。因此，即使玩家站着不动，随着其他人进入或离开周围场景，他们也可能被切换到另一个岛屿。

如果你的场景依赖于第三方服务器来实时同步玩家之间的变化，那么你可能只想在被分组到同一 realm+岛屿中的玩家之间共享数据，因此当玩家更换岛屿时，在第三方服务器中切换房间是一个好习惯。

加密函数

📔 注意：函数 requirePayment(), signMessage(), convertMessageToObject() 已弃用。请使用 sendAsync() 函数代替。详见场景区块链操作。此外，还有一些库可以帮助简化这些函数的一些常见使用场景。

视频事件

📔 注意：该 onVideoEvent 事件在 SDK v7.x 中已弃用。详见事件监听器以获取非弃用替代方案。

当视频更改其播放状态时， onVideoEvent observable 会接收一个事件。

onVideoEvent.add((data) => {
	console.log('新的视频事件：', data)
})

视频事件的输入包含以下属性：

videoClipId ( 字符串）：更改状态的实体 ID。
componentId (字符串）：更改状态的组件 ID。
currentOffset (数值）：视频上 seek 属性的当前值。该值显示自视频原始起始点以来经过的秒数。 -1 。
totalVideoLength (数值）：整个视频的长度（秒）。 -1 如果长度未知。
videoStatus：新的视频状态值，对应于 VideoTexture，其值取自 VideoStatus 枚举。该枚举可包含以下可能值：
VideoStatus.NONE = 0,
VideoStatus.ERROR = 1,
VideoStatus.LOADING = 2,
VideoStatus.READY = 3,
VideoStatus.PLAYING = 4,
VideoStatus.BUFFERING = 5

上一页接近事件

下一页事件监听器

最后更新于 2天前