事件监听器

场景可以跟踪的事件，与玩家操作和场景变化相关。

场景可以订阅多个事件，以了解玩家在场景内或附近时的行为。

关于玩家执行的按钮和点击事件，参见 按钮事件.

玩家进入或离开场景

当某个头像走进或走出构成你的场景的地块，或者传送进入或离开时，都会创建一个你可以监听的事件。

此事件会被所有头像触发，包括玩家自己的头像。

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)
	})
}

在 onEnterScene 事件中，函数可以访问 获取玩家数据 返回的所有数据，通过 player 属性。在 onLeaveScene 事件中，函数只能访问玩家的 ID。

仅当前玩家

你可以过滤触发的事件，只对玩家自己的头像作出反应，而不是对周围可能存在的其他头像。

import { getPlayer, onEnterScene, onLeaveScene } from '@dcl/sdk/src/players'

export function main() {
	let myPlayer = getPlayer()

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

		if (myPlayer && player.userId == myPlayer.userId) {
			console.log('我进来了')
		}
	})

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

		if (myPlayer && userId == myPlayer.userId) {
			console.log('我离开了')
		}
	})
}

此示例首先获取玩家的 ID，然后订阅事件并将事件返回的 userId 与该玩家的 ID 进行比较。

查询场景中的所有玩家

通过遍历所有带有 PlayerIdentityData 组件的实体，查看当前在你的场景中的完整玩家列表。

import { engine, PlayerIdentityData, Transform } from '@dcl/sdk/ecs'

export function main() {
	for (const [entity, data, transform] of engine.getEntitiesWith(
		PlayerIdentityData,
		Transform
	)) {
		console.log('玩家：', { entity, data, transform })
	}
}

玩家更改相机模式

了解相机模式非常有助于微调场景机制，以便更好地适配在此模式下更舒适的操作方式。例如，在第三人称视角下，小目标更难点击。

下面的代码片段使用 onChange 函数在相机每次变化时触发一个事件。它还会在场景加载时触发一个事件，并带有玩家的初始相机模式。

import { engine, CameraMode } from '@dcl/sdk/ecs'

export function main() {
	CameraMode.onChange(engine.CameraEntity, (cameraComponent) => {
		if (!cameraComponent) return
		console.log('相机模式已更改', cameraComponent?.mode)
		// 0 = 第一人称
		// 1 = 第三人称
	})
}

参见 检查玩家的相机模式.

玩家播放动画

使用 onChange 函数在 AvatarEmoteCommand 组件上在玩家每次播放表情时触发一个事件。这包括基础表情（跳舞、拍手、挥手等）以及代币表情。

import { AvatarEmoteCommand } from '@dcl/sdk/ecs'

export function main() {
	AvatarEmoteCommand.onChange(engine.PlayerEntity, (emote) => {
		if (!emote) return
		console.log('已播放表情：', emote.emoteUrn)
	})
}

该事件包含以下信息：

• emoteUrn：所执行表情的名称（即： 挥手, 拍手, 亲吻)

• loop：表情是循环播放还是只播放一次

• timestamp：表情被触发的时间。

• state： EmoteState 枚举中的一个值，描述生命周期事件： ES_STARTED （表情已开始；在旧客户端中，如果该字段缺失，这也是默认值）， ES_FINISHED （一个非循环表情已完整播放到结束），或者 ES_INTERRUPTED （表情因移动、传送、另一个表情、显式停止或离开场景而被中断）。参见 检测表情何时结束.

你也可以通过传入其他玩家的引用，而不是 engine.PlayerEntity.

玩家更改个人资料

使用 onChange 函数在 AvatarEquippedData 组件，在玩家更换穿戴物品或快捷访问轮盘上列出的表情时触发一个事件。同样，使用 onChange 函数在 AvatarBase 在玩家更改其基础头像属性（如发色、肤色、头像形状或名称）时触发一个事件。

import { AvatarEquippedData, AvatarBase } from '@dcl/sdk/ecs'

export function main() {
	AvatarEquippedData.onChange(engine.PlayerEntity, (equipped) => {
		if (!equipped) return
		console.log('新的穿戴物列表：', equipped.wearableUrns)
		console.log('新的表情列表：', equipped.emoteUrns)
	})

	AvatarBase.onChange(engine.PlayerEntity, (body) => {
		if (!body) return
		console.log('新的眼睛颜色：', body.eyesColor)
		console.log('新的肤色：', body.skinColor)
		console.log('新的发色：', body.hairColor)
		console.log('新的身体 URN：', body.bodyShapeUrn)
	})
}

该事件在 AvatarEquippedData 中包含以下信息：

• wearableUrns：玩家当前已装备的穿戴物列表。

• emoteUrns：玩家当前在快捷访问轮盘中装备的表情列表。

该事件在 AvatarBase 中包含以下信息：

• name：玩家的名称。

• bodyShapeUrn：对应男性或女性身体类型的 ID。

• skinColor：以 Color3

• eyesColor：以 Color3

• hairColor：以 Color3

你也可以检测场景中其他玩家的穿戴物或头像变化，只需传入其他玩家的引用，而不是 engine.PlayerEntity.

你也可以检测场景中其他玩家的个人资料变化，只需传入其他玩家的引用，而不是 engine.PlayerEntity.

玩家锁定或解锁光标

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

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

添加一个 PointerLock 组件到场景中的 engine.CameraEntity 实体，并使用 onChange 函数在 PointerLock 组件在玩家在两种光标模式之间切换时触发一个事件。

import {PointerLock} from '@dcl/sdk/ecs'

export function main() {
    PointerLock.onChange(engine.CameraEntity, (pointerLock) => {
		    if (!pointerLock) return
		    if(pointerLock.isPointerLocked){
			    // 显示关于光标模式的提示
		   }
	})
}

你可以利用这些信息轻轻提示玩家，例如弹出一个 UI，说明这款游戏在光标解锁状态下体验更佳。或者你也可以通过更改 isPointerLocked 组件上的该值来强制玩家的光标模式。下面的示例总是将光标模式设为解锁：

import {PointerLock} from '@dcl/sdk/ecs'

export function main() {
    PointerLock.createOrReplace(engine.CameraEntity, {isPointerLocked: false});
    PointerLock.onChange(engine.CameraEntity, (pointerLock) => {
		    if (!pointerLock) return
		    if(pointerLock.isPointerLocked){
			    PointerLock.getMutable(engine.CameraEntity).isPointerLocked = false
		   }
	})
}

打开探索器面板

你的场景可以使用 openExplorerUi 受限操作打开探索器内置的全屏面板（地图、设置、背包等）。这对于从场景 UI 引导玩家前往特定探索器功能很有用。

import { openExplorerUi } from '~system/RestrictedActions'
import { ExplorerUi } from '@dcl/sdk/ecs'

// 打开地图面板
await openExplorerUi({ ui: ExplorerUi.EU_MAP })

该 ExplorerUi 枚举包含以下值：

• EU_SETTINGS (0)

• EU_MAP (1)

• EU_BACKPACK (2)

• EU_CAMERA_REEL (3)

• EU_COMMUNITIES (4)

• EU_PLACES (5)

• EU_EVENTS (6)

注意： 与其他受限操作（movePlayerTo, triggerEmote), openExplorerUi 类似，它只在玩家站在场景地块内时有效。

观察面板何时打开或关闭

使用 ExplorerUiEventsResult 组件，用于检测探索器面板何时打开或关闭。这是 engine.RootEntity上的一个只增不减组件，类似于 PointerEventsResult。每当某个面板打开或关闭时，它都会流式传输事件。

import { engine, ExplorerUiEventsResult, ExplorerUi } from '@dcl/sdk/ecs'

engine.addSystem(() => {
	// 遍历自上一帧以来的新事件
	for (const event of ExplorerUiEventsResult.get(engine.RootEntity)) {
		if (event.event?.$case === 'opened') {
			console.log('面板已打开：', event.ui)
		}
		if (event.event?.$case === 'closed') {
			console.log('面板已关闭：', event.ui)
		}

		// 检查具体是哪个面板
		if (event.ui === ExplorerUi.EU_MAP && event.event?.$case === 'closed') {
			console.log('玩家关闭了地图')
		}
	}
})

每个事件包含：

• ui：事件对应的是哪个面板（一个 ExplorerUi 值）。

• timestamp：事件发生时的单调递增计数器。

• event：要么是 { $case: 'opened' } 要么是 { $case: 'closed' }.

💡 提示：有关表情播放事件的可运行示例，请参见 4,23-emote-finish 测试场景，其中会记录追加到玩家实体上的每个 AvatarEmoteCommand 条目，状态为 STARTED, FINISHED 要么是 INTERRUPTED — 完整播放一次表情可查看 FINISHED，或在播放中途走开以查看 INTERRUPTED.