더 이상 사용되지 않는 함수

레거시 함수

다음 함수들은 모두 레거시이며 사용을 피해야 합니다. 아직은 동작하지만, 앞으로는 지원이 중단될 수 있습니다. 이 모든 예시는 동일한 정보를 얻거나 같은 결과를 달성하는 다른 방법에 대한 링크를 포함합니다.

플레이어가 장면에 들어오거나 나감

📔 참고: onEnterSceneObservable 및 onLeaveSceneObservable 이벤트는 SDK 7.x에서 사용 중단되었습니다. 대신 onEnterScene 을 사용하세요. 다음을 참조하세요 플레이어가 장면에 들어오거나 나감.

아바타가 장면을 구성하는 토지 구획 안팎으로 들어오거나 나가거나, 텔레포트로 들어오거나 나갈 때마다 이를 감지할 수 있는 이벤트가 생성됩니다. 이 이벤트는 플레이어를 포함한 모든 아바타에 의해 트리거됩니다.

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

onEnterSceneObservable.add((player) => {
	console.log('player entered scene: ', player.userId)
})

onLeaveSceneObservable.add((player) => {
	console.log('player left scene: ', player.userId)
})

📔 참고: 이 이벤트는 현재 로컬에서 렌더링 중인 플레이어에만 반응합니다. 장면 크기가 시야 범위를 초과하는 큰 장면에서는 반대편 구석에서 들어오는 플레이어가 등록되지 않을 수 있습니다. 지역의 플레이어 수가 Decentraland 서버의 섬이 감당할 수 있는 수준을 넘으면, 같은 섬을 공유하지 않는 플레이어는 보이지 않으며 이 이벤트로도 추적되지 않습니다.

observable onEnterScene 및 onLeaveScene 는 '@dcl/sdk/observables' 에서 가져온 것도 사용 중단되었습니다. 올바른 함수는 이름은 같지만 '@dcl/sdk/src/players' 에서 가져와야 합니다. 아래 예제에서는 사용 중단된 버전과 올바른 버전 두 가지를 모두 볼 수 있습니다.

// 사용 중단됨 - observables에서 가져옴
import { onEnterScene, onLeaveScene } from '@dcl/sdk/observables'

onEnterScene.add((player) => {
	console.log('player entered scene: ', player.userId)
})

onLeaveScene.add((player) => {
	console.log('player left scene: ', 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 was already here: ', player.userId)
	})
})

다른 플레이어가 로컬 엔진에 의해 렌더링되기 시작하거나 중단될 때마다, 이를 감지할 수 있는 이벤트가 생성됩니다. 플레이어는 여러분과 같은 장면에 있을 수도 있고 아닐 수도 있지만, 시야 범위 안에는 있어야 합니다(반드시 보일 필요는 없음). onPlayerConnectedObservable 는 플레이어가 새로 근처에 연결되거나 시야 범위 안으로 충분히 가까워질 때를 감지하고, 마찬가지로 onPlayerDisconnectedObservable 는 플레이어가 세션을 종료하거나 멀리 걸어가 버릴 때를 감지합니다.

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

onPlayerConnectedObservable.add((player) => {
	console.log('player entered: ', player.userId)
})

onPlayerDisconnectedObservable.add((player) => {
	console.log('player left: ', 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 was already here: ', 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('Own profile data is ', profileData)
})

이벤트 데이터에는 캐털리스트 서버 기준으로 플레이어 ID와 해당 아바타 프로필의 버전 번호만 포함됩니다. 변경 사항이 전파될 때마다 버전 번호는 1씩 증가합니다.

이 이벤트가 트리거되면 다음을 사용하여 getUserData() 함수를 통해 플레이어가 착용 중인 착용 아이템 목록을 포함한 이 정보의 최신 버전을 가져올 수 있습니다. 호출하기 전에 약간의 지연을 추가해야 할 수도 있습니다 getUserData() 이 함수가 반환하는 버전이 최신인지 확인하기 위해.

💡 팁: 레거시 웹 익스플로러로 프리뷰 테스트를 할 때 무작위 아바타 사용을 피하려면, 여러분의 메타마스크 지갑과 연결된 브라우저에서 장면을 실행하세요.

📔 참고: 이 이벤트는 다른 근처 플레이어의 프로필 변경이 아니라 현재 플레이어의 변경에 의해서만 트리거됩니다.

장면 로딩 완료

📔 참고: 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('Clicked ', clickEvent.userId, ' details: ', clickEvent.ray)
})

📔 참고: onPlayerClickedObservable 이벤트는 SDK v7.x에서 사용 중단되었습니다. 향후 버전에서는 더 데이터 지향적 접근을 지원하게 되며, 이벤트 대신 정기적으로 데이터를 조회하는 방식에 기반하게 됩니다.

대안으로 플레이어에 보이지 않는 콜라이더를 추가하고 여기에 대한 클릭을 감지할 수 있습니다.

📔 참고: 클릭을 수행하는 플레이어와 클릭당하는 플레이어 모두 장면의 구획 안에 서 있어야 합니다. 이 리스너는 다른 플레이어가 수행한 클릭이 아니라 현재 플레이어가 다른 플레이어를 클릭하는 이벤트만 감지합니다.

이 이벤트에는 다음 데이터가 포함됩니다:

userId: 클릭된 플레이어의 ID
ray: 클릭으로 추적된 광선에 대한 데이터
- direction: Vector3 클릭의 시작점에서 클릭의 적중 지점까지의 방향을 나타내는 정규화된 Vector3입니다.
- distance: number 시작점에서 적중 지점까지의 거리(미터)입니다.
- origin: Vector3 클릭의 시작점, 즉 클릭을 한 플레이어의 위치이며 장면을 기준으로 합니다.

💡 팁: 다른 플레이어를 클릭할 때의 기본 동작은 플레이어 여권을 여는 것이며, 여기서 해당 플레이어에 대한 추가 정보를 보거나 친구로 추가하는 등의 작업을 할 수 있습니다. 원하는 경험을 방해하지 않도록 이 UI가 열리는 것을 비활성화하려면 다음을 추가하세요 Avatar Modifier Area.

플레이어가 커서를 잠그거나 잠금을 해제함

📔 참고: onPointerLockedStateChange 이벤트는 SDK v7.x에서 제거되어 더 이상 사용할 수 없습니다. 다음을 참조하세요 이벤트 리스너 에서 현재 대안을 확인하세요.

플레이어는 두 가지 커서 모드 사이를 전환할 수 있습니다: 잠긴 커서 모드로 카메라를 제어하거나 잠금 해제된 커서 모드로 UI 위에서 커서를 자유롭게 이동합니다.

플레이어는 다음을 클릭하여 커서를 잠금 해제합니다 마우스 오른쪽 버튼 또는 Esc 키를 누르고, 화면의 아무 곳이나 클릭하면 커서가 다시 잠깁니다.

플레이어가 이 두 모드 사이를 전환할 때마다 반응하려면 onChange 함수를 PointerLock 컴포넌트에 사용하세요. 다음을 참조하세요 이벤트 리스너.

플레이어가 렐름 또는 섬을 변경함

Decentraland의 플레이어는 서로 다른 렐름과 서로 다른 섬 안에 존재합니다. 서로 다른 렐름이나 섬에 있는 플레이어는 같은 구획에 서 있더라도 서로 볼 수도, 상호작용할 수도, 채팅할 수도 없습니다.

플레이어가 렐름이나 섬을 변경할 때마다 onRealmChangedObservable 이벤트가 호출됩니다.

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

onRealmChangedObservable.add((realmChange) => {
	console.log('PLAYER CHANGED ISLAND TO ', realmChange.room)
})

📔 참고: onRealmChangedObservable 이벤트는 SDK v7.x에서 사용 중단되었습니다. 향후 버전에서는 더 데이터 지향적 접근을 지원하게 되며, 이벤트 대신 정기적으로 데이터를 조회하는 방식에 기반하게 됩니다.

이 이벤트에는 다음 필드가 포함됩니다:

serverName: string; 캐털리스트 서버 이름입니다.
room: string; 섬 이름입니다.
displayName: string; 캐털리스트 서버 이름 뒤에 - 와 섬 이름이 이어진 것입니다. 예를 들면 unicorn-x011.
domain: string; 사용 중인 캐털리스트 서버의 URL입니다.

플레이어가 지도를 이동하면서, 이제 가장 가까운 플레이어들과 함께 묶이기 위해 섬을 바꿀 수 있습니다. 각 섬의 경계도 관리 가능한 인원 그룹에 맞게 동적으로 이동합니다. 따라서 플레이어가 가만히 서 있어도 주변 장면에 다른 플레이어가 들어오고 나가면서 섬이 변경될 수 있습니다.

여러분의 장면이 3rd party 서버 에 의존하여 플레이어 간 변경 사항을 실시간으로 동기화한다면, 같은 렐름+섬으로 묶인 플레이어들 사이에서만 데이터를 공유하는 것이 좋습니다. 따라서 플레이어가 섬을 바꿀 때마다 서드파티 서버의 룸도 변경하는 것이 좋은 습관입니다.

크립토 함수

📔 참고: 함수 requirePayment(), signMessage(), convertMessageToObject() 는 사용 중단되었습니다. 대신 sendAsync() 함수를 사용하세요. 다음을 참조하세요 장면 블록체인 작업. 이러한 함수의 일부 일반적인 사용 사례를 더 쉽게 처리할 수 있도록 도와주는 라이브러리도 있습니다.

비디오 이벤트

📔 참고: onVideoEvent 이벤트는 SDK v7.x에서 사용 중단되었습니다. 다음을 참조하세요 이벤트 리스너 사용 중단되지 않은 대안을 위해.

비디오의 재생 상태가 바뀌면 onVideoEvent observable이 이벤트를 수신합니다.

onVideoEvent.add((data) => {
	console.log('새 비디오 이벤트 ', data)
})

비디오 이벤트의 입력에는 다음 속성이 포함됩니다:

videoClipId ( string): 상태가 변경된 엔티티의 ID입니다.
componentId (string): 상태가 변경된 엔티티의 ID입니다.
currentOffset (number): 비디오의 seek 속성의 현재 값입니다. 이 값은 비디오의 원래 시작 시점 이후의 초를 보여줍니다. -1 기본값입니다.
totalVideoLength (number ): 전체 비디오 길이(초)입니다. -1 길이를 알 수 없으면
videoStatus: VideoTexture의 새로운 비디오 상태 값이며 VideoStatus 열거형의 값으로 표현됩니다. 이 열거형은 다음 가능한 값을 가질 수 있습니다:
VideoStatus.NONE = 0,
VideoStatus.ERROR = 1,
VideoStatus.LOADING = 2,
VideoStatus.READY = 3,
VideoStatus.PLAYING = 4,
VideoStatus.BUFFERING = 5

이전근접 이벤트

다음이벤트 리스너

마지막 업데이트 23일 전