> For the complete documentation index, see [llms.txt](https://docs.decentraland.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/jiao-hu-xing/deprecated-functions.md).

# 已弃用函数

旧版函数

以下函数均为旧版功能，应避免使用。它们目前仍可运行，但未来可能不再受支持。所有这些示例都包含链接，说明如何通过替代方式获取相同信息或实现相同结果。

## 玩家进入或离开场景

{% hint style="warning" %}
**📔 注意**： `onEnterSceneObservable` 和 `onLeaveSceneObservable` 事件在 SDK 7.x 中已弃用。请使用 `onEnterScene` 来替代，参见 [玩家进入或离开场景](/creator/content-creator-zh/chang-jing-sdk7/jiao-hu-xing/event-listeners.md#player-enters-or-leaves-scene).
{% endhint %}

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

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

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

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

{% hint style="warning" %}
**📔 注意**：此事件只响应当前在本地被渲染的玩家。在场景规模较大、超过可视范围时，处于对角区域的进入玩家可能不会被注册。如果某个区域中的玩家数量超过 Decentraland 服务器上某个岛屿所能承载的能力，那么那些不在同一岛屿上的玩家也不可见，并且不会被这些事件跟踪。
{% endhint %}

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

```ts
// 已弃用 - 从 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)
	})
}
```

## 玩家连接或断开连接

{% hint style="warning" %}
**📔 注意**： `getConnectedPlayers` 函数和 `onPlayerConnectedObservable` 和 `onPlayerDisconnectedObservable` 事件在 SDK 7.x 中已弃用。请使用 `onEnterScene` 来替代，参见 [玩家进入或离开场景](/creator/content-creator-zh/chang-jing-sdk7/jiao-hu-xing/event-listeners.md#player-enters-or-leaves-scene)。现在每个场景都是一个独立的通讯岛，因此连接状态和位于同一场景在效果上是一样的。
{% endhint %}

从 `getConnectedPlayers`.

```ts
import { getConnectedPlayers } from '~system/Players'

executeTask(async () => {
	let connectedPlayers = await getConnectedPlayers({})
	connectedPlayers.players.forEach((player) => {
		console.log('玩家早已在此：', player.userId)
	})
})
```

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

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

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

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

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

## 查询场景中的所有玩家

{% hint style="warning" %}
**📔 注意**： `getPlayersInScene` 函数在 SDK 7.x 中已弃用。请改为使用 `PlayerIdentityData` 组件遍历所有玩家。参见 [获取所有玩家](/creator/content-creator-zh/chang-jing-sdk7/jiao-hu-xing/user-data.md#fetch-all-players).
{% endhint %}

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

```ts
import { getPlayersInScene } from '~system/Players'

executeTask(async () => {
	let connectedPlayers = await getPlayersInScene({})
	connectedPlayers.players.forEach((player) => {
		console.log('玩家早已在此：', player.userId)
	})
})
```

## 玩家播放动画

{% hint style="warning" %}
**📔 注意**： `onPlayerExpressionObservable` 事件在 SDK 7.x 中已弃用。请使用 `AvatarEmoteCommand` 组件来替代，参见 [玩家播放动画](/creator/content-creator-zh/chang-jing-sdk7/jiao-hu-xing/event-listeners.md#player-plays-animation).
{% endhint %}

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

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

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

该事件包含以下信息：

* expressionId：所执行表情动作的名称（例如： *wave*, *clap*, *kiss*)

{% hint style="warning" %}
**📔 注意**：每当玩家做出表情且场景已加载时，都会触发此事件。发生时，玩家可能正站在附近的另一个场景中。
{% endhint %}

## 玩家更改个人资料

{% hint style="warning" %}
**📔 注意**： `onProfileChanged` 事件在 SDK 7.x 中已弃用。请使用 `AvatarEquippedData` 组件来替代，参见 [玩家更改个人资料](/creator/content-creator-zh/chang-jing-sdk7/jiao-hu-xing/event-listeners.md#player-changes-profile).
{% endhint %}

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

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

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

事件数据仅包含玩家的 ID 以及该头像个人资料的版本号，具体取决于催化器服务器。每当更改被传播，版本号都会增加 1。

当此事件被触发时，你就可以使用 [getUserData()](/creator/content-creator-zh/chang-jing-sdk7/jiao-hu-xing/user-data.md#get-player-data) 函数来获取此信息的最新版本，包括玩家穿戴的可穿戴物品列表。你可能需要在调用 `getUserData()` 之前稍作延迟，以确保该函数返回的版本是最新的。

{% hint style="info" %}
**💡 提示**：在使用旧版 Web Explorer 进行预览测试时，为避免使用随机头像，请在与你的 Metamask 钱包连接的浏览器中运行该场景。
{% endhint %}

{% hint style="warning" %}
**📔 注意**：此事件只会由当前玩家的更改触发，不会由附近其他玩家个人资料的更改触发。
{% endhint %}

## 场景加载完成

{% hint style="warning" %}
**📔 注意**： `onSceneReadyObservable` 事件在 SDK v7.x 中已弃用。此函数已不再相关。你可以通过将要执行的内容放在 `Main()` 函数中来确保场景加载完成后再执行。参见 [场景生命周期](/creator/content-creator-zh/chang-jing-sdk7/ru-men/coding-scenes.md#scene-lifecycle)
{% endhint %}

当场景完成加载时， `onSceneReadyObservable` 会被调用。无论玩家是直接载入该场景，还是从别处走到该场景，都会生效。当场景中的所有内容完成初始加载后，包括大型模型等，就会调用此事件。

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

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

## 已弃用的玩家数据方法

{% hint style="warning" %}
**📔 注意**： `getUserData()` 和 `getPlayerData()` 函数自 SDK v7.4.x 起已弃用。请使用 `getPlayer()` 来替代。参见 [用户数据](/creator/content-creator-zh/chang-jing-sdk7/jiao-hu-xing/user-data.md#get-user-data).
{% endhint %}

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

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

```ts
import { getUserData } from '~system/UserIdentity'

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

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

```ts
import { getPlayerData } from '~system/Players'

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

两者都 `getUserData()` 和 `getPlayerData()` 返回与内容 API 中可用的相同数据结构。参见 [来自任意玩家的数据](/creator/content-creator-zh/chang-jing-sdk7/jiao-hu-xing/user-data.md#data-from-any-player)

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

{% hint style="warning" %}
**📔 注意**：用户 ID 必须始终为小写。如果复制钱包地址，请确保所有字符都为小写。
{% endhint %}

该 `getUserPublicKey()` 和 `getUserAccount()` 函数也已弃用。请使用 `getPlayer()` 来替代。参见 [用户数据](/creator/content-creator-zh/chang-jing-sdk7/jiao-hu-xing/user-data.md#get-user-data).

## 获取天空盒时间

{% hint style="warning" %}
**📔 注意**： `getDecentralandTime()` 函数自 SDK v7.x.x 起已弃用。请使用 `getWorldTime()` 来替代。参见 [获取 Decentraland 时间](/creator/content-creator-zh/chang-jing-sdk7/jiao-hu-xing/runtime-data.md#get-decentraland-time).
{% endhint %}

```ts
import { getDecentralandTime } from '~system/EnvironmentApi'

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

## 获取领域

{% hint style="warning" %}
**📔 注意**： `getCurrentRealm()` 函数自 SDK v7.x.x 起已弃用。请使用 `getRealm()` 来替代。参见 [获取领域数据](/creator/content-creator-zh/chang-jing-sdk7/jiao-hu-xing/runtime-data.md#get-realm-data).
{% endhint %}

```ts
import { getCurrentRealm } from '~system/EnvironmentApi'

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

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

fetchPlayerData()
```

## 是否为预览模式

{% hint style="warning" %}
**📔 注意**： `isPreviewMode()` 函数自 SDK v7.x.x 起已弃用。请使用 `getRealm()` 来替代，其中包含一个 `preview` 属性。参见 [获取领域数据](/creator/content-creator-zh/chang-jing-sdk7/jiao-hu-xing/runtime-data.md#get-realm-data).
{% endhint %}

```ts
import { isPreviewMode } from '~system/EnvironmentApi'

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

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

## 玩家点击另一个玩家

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

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

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

{% hint style="warning" %}
**📔 注意**： `onPlayerClickedObservable` 事件在 SDK v7.x 中已弃用。未来版本将允许采用更 [数据驱动的方法](/creator/content-creator-zh/chang-jing-sdk7/jia-gou/data-oriented-programming.md)，基于定期查询数据而不是事件。

作为替代方案，你可以给玩家附加一个不可见的碰撞体，并检测对它的点击。
{% endhint %}

{% hint style="warning" %}
**📔 注意**：执行点击的玩家和被点击的玩家都必须站在该场景的地块内。此监听器只检测当前玩家点击其他玩家的事件，不会检测其他玩家执行的点击。
{% endhint %}

该事件包含以下数据：

* `userId`：被点击玩家的 ID
* `ray`：关于此次点击所射出的射线的数据
  * `方向`: *Vector3* 一个归一化的 Vector3，表示从点击起点到点击命中点的方向。
  * `distance`: *数字* 从起点到命中点的距离，单位为米。
  * `origin`: *Vector3* 点击的起点，即执行点击的玩家的位置，相对于场景。

{% hint style="info" %}
**💡 提示**：点击另一个玩家的默认行为是打开玩家证件，你可以在其中查看该玩家的更多信息、将其添加为好友等。你可以通过添加一个 [头像修改区域](/creator/content-creator-zh/chang-jing-sdk7/jiao-hu-xing/player-avatar.md#avatar-modifier-areas).
{% endhint %}

## 玩家锁定/解锁光标

{% hint style="warning" %}
**📔 注意**： `onPointerLockedStateChange` 事件已在 SDK v7.x 中移除，现已不可用。参见 [事件监听器](/creator/content-creator-zh/chang-jing-sdk7/jiao-hu-xing/event-listeners.md#player-locks-or-unlocks-cursor) 以了解当前可替代方案。
{% endhint %}

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

玩家可通过单击 *鼠标右键* 或按下 *Esc* 键来解锁光标，并通过单击屏幕任意位置重新锁定光标。

要在玩家在这两种模式之间切换时做出响应，请使用 `onChange` 函数在 `PointerLock` 组件，参见 [事件监听器](/creator/content-creator-zh/chang-jing-sdk7/jiao-hu-xing/event-listeners.md#player-locks-or-unlocks-cursor).

## 玩家更改领域或岛屿

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

每当玩家更改领域或岛屿时， `onRealmChangedObservable` 事件就会被调用。

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

onRealmChangedObservable.add((realmChange) => {
	console.log('玩家将岛屿更改为：', realmChange.room)
})
```

{% hint style="warning" %}
**📔 注意**： `onRealmChangedObservable` 事件在 SDK v7.x 中已弃用。未来版本将允许采用更 [数据驱动的方法](/creator/content-creator-zh/chang-jing-sdk7/jia-gou/data-oriented-programming.md)，基于定期查询数据而不是事件。
{% endhint %}

此事件包含以下字段：

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

随着玩家在地图中移动，他们可能会切换岛屿，以便与现在离他们最近的玩家分到一组。岛屿也会动态调整边界，以便容纳每个区域内可管理的人数。因此，即使玩家静止不动，随着其他人进入和离开周围场景，他们也可能会被更改到其他岛屿。

如果你的场景依赖于 [第三方服务器](/creator/content-creator-zh/chang-jing-sdk7/wang-luo/third-party-servers.md) 来实时同步玩家之间的更改，那么你可能只想在处于同一 realm+island 分组中的玩家之间共享数据，因此当玩家更改岛屿时，在第三方服务器中更改房间是一种良好做法。

## 加密函数

{% hint style="warning" %}
**📔 注意**：函数 `requirePayment()`, `signMessage()`, `convertMessageToObject()` 都已弃用。请改用 `sendAsync()` 函数。参见 [场景区块链操作](/creator/content-creator-zh/chang-jing-sdk7/qu-kuai-lian/scene-blockchain-operations.md)。另外也有一些库可以帮助简化这些函数的一些常见用例。
{% endhint %}

## 视频事件

{% hint style="warning" %}
**📔 注意**： `onVideoEvent` 事件在 SDK v7.x 中已弃用。参见 [事件监听器](/creator/content-creator-zh/chang-jing-sdk7/mei-ti/video-playing.md#video-events) 以获取非弃用替代方案。
{% endhint %}

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

```ts
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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/jiao-hu-xing/deprecated-functions.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.