이벤트 리스너

플레이어 행동 및 씬 변경과 관련되어 씬이 추적할 수 있는 이벤트.

씬이 구독할 수 있는 여러 이벤트가 있으며, 이를 통해 씬 안에 있거나 근처에 있는 동안 플레이어의 동작을 알 수 있습니다.

플레이어가 수행하는 버튼 및 클릭 이벤트는 다음을 참조하세요: 버튼 이벤트.

플레이어가 씬에 들어오거나 나갑니다

아바타가 씬을 구성하는 토지 구역 안팎으로 들어오거나 나가거나, 텔레포트로 들어오거나 나갈 때마다, 이를 수신할 수 있는 이벤트가 생성됩니다.

이 이벤트는 플레이어의 아바타를 포함한 모든 아바타에 의해 트리거됩니다.

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 이벤트에서 반환된 값과 플레이어의 값을 비교합니다.

씬의 모든 플레이어 조회

현재 씬에 있는 플레이어 전체 목록을, 다음을 가진 모든 엔티티를 순회하여 살펴보세요: 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 })
	}
}

플레이어가 카메라 모드를 변경합니다

카메라 모드를 알면 이 모드 사용 시 더 편안한 방식에 맞게 씬의 메커니즘을 미세 조정하는 데 매우 유용합니다. 예를 들어 3인칭에서는 작은 대상을 클릭하기가 더 어렵습니다.

다음 스니펫은 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인칭
		// 1 = 3인칭
	})
}

다음 플레이어의 카메라 모드 확인.

플레이어가 애니메이션을 재생합니다

다음을 사용하세요 onChange 다음의 함수 AvatarEmoteCommand 컴포넌트를 사용하여 플레이어가 이모트를 재생할 때마다 이벤트를 발생시킵니다. 여기에는 기본 이모트(댄스, 박수, 손 흔들기 등)와 토큰의 이모트가 모두 포함됩니다.

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

export function main() {
	AvatarEmoteCommand.onChange(engine.PlayerEntity, (emote) => {
		if (!emote) return
		console.log('이모트 재생됨: ', emote.emoteUrn)
	})
}

이 이벤트에는 다음 정보가 포함됩니다:

• emoteUrn: 수행된 이모트의 이름(예: wave, clap, kiss)

• loop: 이모트가 반복 재생되는지 또는 한 번 재생되는지

• 타임스탬프: 이모트가 트리거된 시점.

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

이벤트 on AvatarEquippedData 다음 정보가 포함됩니다:

• wearableUrns: 플레이어가 현재 장착 중인 착용 아이템 목록입니다.

• emoteUrns: 플레이어가 현재 빠른 액세스 휠에 장착한 이모트 목록입니다.

이벤트 on 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 컴포넌트를 사용하여 탐색기 패널이 열리거나 닫히는 시점을 감지합니다. 이는 다음에 있는 grow-only 컴포넌트입니다: 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 값).

• 타임스탬프: 이벤트가 발생한 시점을 나타내는 단조 증가 카운터입니다.

• event: 다음 중 하나입니다 { $case: 'opened' } 또는 { $case: 'closed' }.

💡 팁: 이모트 재생 이벤트의 동작 예시는 다음을 참조하세요: 4,23-emote-finish 테스트 씬으로, 다음의 모든 항목을 로그합니다: AvatarEmoteCommand 플레이어 엔티티에 추가된 각 항목을 다음과 같이 STARTED, FINISHED 또는 INTERRUPTED — 이모트를 끝까지 재생하여 다음을 확인하거나 FINISHED, 또는 재생 도중 자리를 떠나 다음을 확인하세요 INTERRUPTED.