ZEPETO Players

20min
﻿
ZepetoPlayers는 ZEPETO 플레이어와 ZEPETO 캐릭터를 제어하기 위해 설계된 매니저(싱글톤) 클래스입니다.
ZepetoPlayers를 장면에 추가하면 ZEPETO 플레이어를 생성, 삭제 및 조작할 수 있습니다.
ZepetoPlayer는 멀티플레이어 월드에서 직접 제어하는 플레이어와 다른 플레이어를 관리하는 데 사용되는 ZEPETO 캐릭터의 개별 인스턴스를 나타냅니다.
멀티플레이어 월드에서 생성된 모든 ZepetoPlayer는 고유한 세션 ID가 할당되며 이 세션 ID를 사용하여 관리됩니다.
ZepetoPlayer는 ZepetoCharacter의 속성을 가지고 있기 때문에 ZepetoCharacter와 관련된 기능을 사용하여 제어할 수 있습니다.
ZepetoPlayer의 유형은 세 가지입니다:
ZepetoPlayer
설명
로컬 플레이어
로컬 사용자가 직접 제어하는 ZEPETO 캐릭터 인스턴스입니다.

- 캐릭터 컨트롤러/Zepeto 카메라 컴포넌트가 부착되어 있습니다.
네트워크 플레이어 (원격 플레이어)
멀티플레이 콘텐츠에서 로드하고 활용할 수 있는 ZEPETO 캐릭터 인스턴스입니다.

- 캐릭터 컨트롤러/Zepeto 카메라 컴포넌트가 부착되어 있지 않습니다.
봇 플레이어
멀티플레이 콘텐츠를 위한 ZEPETO 캐릭터 인스턴스이지만, 실제 사용자가 아닌 봇에 의해 제어됩니다.

플레이어가 부족한 멀티플레이 월드를 시작할 때 또는 플레이 중 플레이어가 나갈 경우 대체로 사용됩니다.

- 캐릭터 컨트롤러/Zepeto 카메라 컴포넌트가 부착되어 있지 않습니다.
다음 가이드를 참조하십시오.
[ZEPETO Players﻿]
[Bot 플레이어 생성 가이드﻿]
ZepetoCharacter는 월드 씬에서 로드되고 제어될 수 있는 ZEPETO 캐릭터의 기본 인스턴스 단위입니다.
ZepetoCharacter는 ZEPETO 앱을 통해 생성된 아바타의 외형을 가지고 있습니다.
다음 가이드를 참조하십시오. [ZEPETO Character﻿]
ZepetoPlayers 추가하기
계층 창에서 ZEPETO → ZepetoPlayers 탭을 선택하십시오.
﻿
이제 장면에 추가할 수 있습니다.
﻿
ZepetoPlayers를 추가하는 것만으로는 Zepeto Player가 장면에 들어오지 않음을 유의하세요. ZepetoPlayers의 캐릭터 생성 API를 사용하여 스크립트를 구현해야 합니다.
장면에서 로컬 플레이어만 빠르게 생성하고 시도하고 싶다면, 가이드를 참조하세요:
다음 가이드를 참조하세요. [제페토 캐릭터 생성하기﻿]
﻿
Zepeto 플레이어의 이름과 프로필 사진을 표시하는 방법에 대한 샘플은 가이드를 확인하세요:
다음 가이드를 참조하세요. [유저 정보﻿]
﻿
ZEPETO 플레이어 API
ZepetoPlayers API에 관심이 있다면 문서를 참조하세요:
다음 가이드를 참조하세요. [ZEPETO.Character.Controller API]
﻿
이 가이드는 주로 멀티플레이어 시나리오에서 ZEPETO 플레이어를 사용하는 예제를 다룹니다.
﻿
ZEPETO 플레이어를 사용한 멀티플레이 위치 동기화 구현
싱글 플레이어 월드에서는 로컬 플레이어만 생성하면 되고, 로컬 플레이어만 화면에 나타나므로 동기화가 필요하지 않습니다.
그러나 멀티플레이어 월드에서는 직접 제어하는 로컬 플레이어뿐만 아니라 네트워크 플레이어라고 불리는 다른 플레이어도 화면에 표시되어야 합니다.
네트워크 플레이어의 모든 행동 - 이동, 점프 및 특정 제스처 수행 - 은 화면에 동일하게 나타나야 합니다.
이 과정을 동기화라고 합니다.
동기화 스크립트를 구현하지 않으면 네트워크 플레이어의 외형이나 움직임을 볼 수 없습니다.
동기화가 없는 멀티플레이 월드에서는 다른 클라이언트가 방에 들어왔는지 알 수 있는 유일한 방법은 홈 버튼을 통해서입니다.
캐릭터 생성 및 동기화 스크립트 없이 멀티플레이 설정만 적용했을 때의 외형
﻿
﻿
1단계 : 멀티플레이 환경 설정
멀티플레이 튜토리얼 비디오를 통해 멀티플레이의 기본 설정과 개념을 이해하는 것으로 시작하는 것이 좋습니다.
다음 가이드를 참조하십시오.
[멀티플레이 제작하기﻿ ]
[멀티플레이﻿]
﻿
2단계 : 화면에 다른 플레이어 표시하기
당신의 로컬 플레이어는 다른 사람의 장치에서 네트워크 플레이어로 취급됩니다.
이는 당신의 로컬 플레이어도 동기화를 위해 서버에 정보를 보내야 함을 의미합니다.
멀티플레이 월드에 연결된 모든 플레이어는 자신의 정보를 공유해야 합니다.
멀티플레이 방에 연결된 모든 클라이언트는 멀티플레이 방 상태 데이터를 공유합니다.
이 방 상태 데이터는 Schemas.json에 정의된 스키마를 따릅니다.
(스키마를 데이터 구조로 고려해 주세요)
이 가이드에서는 플레이어의 위치를 Room State 데이터를 통해 동기화합니다. 따라서 각 플레이어의 위치 데이터를 나타낼 수 있는 스키마를 Schemas.json에 정의하세요.
schema.json
{
"State" : {"players" : {"map" : "Player"}},
"Player" : {"sessionId" : "string","zepetoUserId" : "string","transform" : "Transform","state" : "number","subState" : "number"},
"Transform" : {"position" : "Vector3","rotation" : "Vector3"},
"Vector3" : {"x" : "number","y" : "number","z" : "number"}
}
{
"State" : {"players" : {"map" : "Player"}},
"Player" : {"sessionId" : "string","zepetoUserId" : "string","transform" : "Transform","state" : "number","subState" : "number"},
"Transform" : {"position" : "Vector3","rotation" : "Vector3"},
"Vector3" : {"x" : "number","y" : "number","z" : "number"}
}
﻿
다음 가이드를 참조하세요. [Multiplay Room State﻿ ]
﻿
👍 팁
서버와 모든 클라이언트가 공유해야 할 모든 정보를 멀티플레이 룸 상태에 저장하세요.
각 플레이어의 레벨, 경험치, 점수 등과 같은 개별 데이터를 데이터 저장소를 사용하여 저장하세요.
﻿
서버 스크립트는 다른 플레이어가 방에 들어왔을 때 이를 인식하고 해당 정보를 클라이언트에 전송하여 그 플레이어를 장면에 로드할 수 있습니다.
﻿
단계 2-1 : 기본 서버 스크립트
플레이어가 멀티플레이 월드의 방에 들어오면 onJoin()이 호출됩니다.
서버 스크립트에서 연결된 플레이어의 정보를 방 상태의 플레이어 목록에 추가합니다.
﻿
또한, 플레이어가 방을 나가면 onLeave()가 호출됩니다.
서버 스크립트는 방 상태의 플레이어 목록에서 나간 플레이어의 정보를 제거합니다.
TypeScript
import {Sandbox, SandboxOptions, SandboxPlayer} from "ZEPETO.Multiplay";
import {Player} from "ZEPETO.Multiplay.Schema";
 
export default class extends Sandbox {
 
 
    onCreate(options: SandboxOptions) {
 
    }
 
 
    async onJoin(client: SandboxPlayer) {
        const player = new Player();
        player.sessionId = client.sessionId;
 
        if (client.userId) {
            player.zepetoUserId = client.userId;
        }
 
 
 
        // 클라이언트 객체의 고유 키 값인 sessionId를 사용하여 Player 객체를 관리합니다.
        // 클라이언트는 players 객체에 add_OnAdd 이벤트를 추가하여 추가된 플레이어 객체에 대한 정보를 확인할 수 있습니다.
        this.state.players.set(client.sessionId, player);
    }
 
    async onLeave(client: SandboxPlayer, consented?: boolean) {
 
        this.state.players.delete(client.sessionId);
    }
}
import {Sandbox, SandboxOptions, SandboxPlayer} from "ZEPETO.Multiplay";
import {Player} from "ZEPETO.Multiplay.Schema";
 
export default class extends Sandbox {
 
 
    onCreate(options: SandboxOptions) {
 
    }
 
 
    async onJoin(client: SandboxPlayer) {
        const player = new Player();
        player.sessionId = client.sessionId;
 
        if (client.userId) {
            player.zepetoUserId = client.userId;
        }
 
 
 
        // 클라이언트 객체의 고유 키 값인 sessionId를 사용하여 Player 객체를 관리합니다.
        // 클라이언트는 players 객체에 add_OnAdd 이벤트를 추가하여 추가된 플레이어 객체에 대한 정보를 확인할 수 있습니다.
        this.state.players.set(client.sessionId, player);
    }
 
    async onLeave(client: SandboxPlayer, consented?: boolean) {
 
        this.state.players.delete(client.sessionId);
    }
}
﻿
﻿
단계 2-2 : 기본 클라이언트 스크립트
멀티플레이 월드를 생성할 때 서버와 통신하기 위해 클라이언트 스크립트가 필요합니다.
아래는 멀티플레이를 위한 기본 클라이언트 스크립트의 예입니다.
클라이언트 측에서는 currentPlayers 맵 데이터 구조를 사용하여 클라이언트에 표시할 플레이어 데이터를 관리합니다.
﻿
아래에 중요한 코드 줄이 설명되어 있습니다:
ZepetoPlayers.instance.CreatePlayerWithUserId(sessionId, player.zepetoUserId, spawnInfo, isLocal); 
클라이언트가 서버의 Room State에서 플레이어 정보를 수신하고 새로운 플레이어가 방에 참여하면 세션 ID가 할당됩니다. 생성 중인 플레이어의 세션 ID가 우리의 세션 ID와 일치하면 해당 플레이어는 로컬로 간주됩니다. 이 경우 플레이어는 isLocal = true, 로컬 플레이어임을 나타냅니다.
그 후, 지역 주민이 아닌 플레이어는 isLocal = false. 이는 모든 플레이어의 외관이 화면에 렌더링되도록 보장합니다. 지역 플레이어와 비지역 플레이어 모두 포함됩니다.
TypeScript
import {ZepetoScriptBehaviour} from 'ZEPETO.Script'
import {ZepetoWorldMultiplay} from 'ZEPETO.World'
import {Room, RoomData} from 'ZEPETO.Multiplay'
import {Player, State, Vector3} from 'ZEPETO.Multiplay.Schema'
import {CharacterState, SpawnInfo, ZepetoPlayers, ZepetoPlayer, CharacterJumpState} from 'ZEPETO.Character.Controller'
import * as UnityEngine from "UnityEngine";
 
 
export default class MultiplayClientCode extends ZepetoScriptBehaviour {
 
    public multiplay: ZepetoWorldMultiplay;
 
    private room: Room;
    private currentPlayers: Map<string, Player> = new Map<string, Player>();
 
    private zepetoPlayer: ZepetoPlayer;
 
    private Start() {
 
        this.multiplay.RoomCreated += (room: Room) => {
            this.room = room;
        };
 
        this.multiplay.RoomJoined += (room: Room) => {
            room.OnStateChange += this.OnStateChange;
        };
 
    }
 
 
    private OnStateChange(state: State, isFirst: boolean) {
 
        // 첫 번째 OnStateChange 이벤트가 수신되면 전체 상태 스냅샷이 기록됩니다.
        if (isFirst) {
 
            // [CharacterController] (Local) 플레이어 인스턴스가 씬에 완전히 로드되었을 때 호출됩니다.
            ZepetoPlayers.instance.OnAddedLocalPlayer.AddListener(() => {
                const myPlayer = ZepetoPlayers.instance.LocalPlayer.zepetoPlayer;
                this.zepetoPlayer = myPlayer;
            });
 
            // [CharacterController] (Local) 플레이어 인스턴스가 씬에 완전히 로드되었을 때 호출됩니다.
            ZepetoPlayers.instance.OnAddedPlayer.AddListener((sessionId: string) => {
                const isLocal = this.room.SessionId === sessionId;
                if (!isLocal) {
                    const player: Player = this.currentPlayers.get(sessionId);
 
                }
            });
        }
 
        let join = new Map<string, Player>();
        let leave = new Map<string, Player>(this.currentPlayers);
 
        state.players.ForEach((sessionId: string, player: Player) => {
            if (!this.currentPlayers.has(sessionId)) {
                join.set(sessionId, player);
            }
            leave.delete(sessionId);
        });
 
        // [RoomState] 방에 들어오는 플레이어를 위한 플레이어 인스턴스 생성
        join.forEach((player: Player, sessionId: string) => this.OnJoinPlayer(sessionId, player));
 
        // [RoomState] 방을 나가는 플레이어를 위한 플레이어 인스턴스 제거
        leave.forEach((player: Player, sessionId: string) => this.OnLeavePlayer(sessionId, player));
    }
 
    private OnJoinPlayer(sessionId: string, player: Player) {
        console.log(`[OnJoinPlayer] players - sessionId : ${sessionId}`);
        this.currentPlayers.set(sessionId, player);
         
        // 플레이어 생성
        const isLocal = this.room.SessionId === player.sessionId;
        ZepetoPlayers.instance.CreatePlayerWithUserId(sessionId, player.zepetoUserId, new SpawnInfo(), isLocal);
    }
 
    private OnLeavePlayer(sessionId: string, player: Player) {
        console.log(`[OnRemove] players - sessionId : ${sessionId}`);
        this.currentPlayers.delete(sessionId);
 
        ZepetoPlayers.instance.RemovePlayer(sessionId);
    }
}

import {ZepetoScriptBehaviour} from 'ZEPETO.Script'
import {ZepetoWorldMultiplay} from 'ZEPETO.World'
import {Room, RoomData} from 'ZEPETO.Multiplay'
import {Player, State, Vector3} from 'ZEPETO.Multiplay.Schema'
import {CharacterState, SpawnInfo, ZepetoPlayers, ZepetoPlayer, CharacterJumpState} from 'ZEPETO.Character.Controller'
import * as UnityEngine from "UnityEngine";
 
 
export default class MultiplayClientCode extends ZepetoScriptBehaviour {
 
    public multiplay: ZepetoWorldMultiplay;
 
    private room: Room;
    private currentPlayers: Map<string, Player> = new Map<string, Player>();
 
    private zepetoPlayer: ZepetoPlayer;
 
    private Start() {
 
        this.multiplay.RoomCreated += (room: Room) => {
            this.room = room;
        };
 
        this.multiplay.RoomJoined += (room: Room) => {
            room.OnStateChange += this.OnStateChange;
        };
 
    }
 
 
    private OnStateChange(state: State, isFirst: boolean) {
 
        // 첫 번째 OnStateChange 이벤트가 수신되면 전체 상태 스냅샷이 기록됩니다.
        if (isFirst) {
 
            // [CharacterController] (Local) 플레이어 인스턴스가 씬에 완전히 로드되었을 때 호출됩니다.
            ZepetoPlayers.instance.OnAddedLocalPlayer.AddListener(() => {
                const myPlayer = ZepetoPlayers.instance.LocalPlayer.zepetoPlayer;
                this.zepetoPlayer = myPlayer;
            });
 
            // [CharacterController] (Local) 플레이어 인스턴스가 씬에 완전히 로드되었을 때 호출됩니다.
            ZepetoPlayers.instance.OnAddedPlayer.AddListener((sessionId: string) => {
                const isLocal = this.room.SessionId === sessionId;
                if (!isLocal) {
                    const player: Player = this.currentPlayers.get(sessionId);
 
                }
            });
        }
 
        let join = new Map<string, Player>();
        let leave = new Map<string, Player>(this.currentPlayers);
 
        state.players.ForEach((sessionId: string, player: Player) => {
            if (!this.currentPlayers.has(sessionId)) {
                join.set(sessionId, player);
            }
            leave.delete(sessionId);
        });
 
        // [RoomState] 방에 들어오는 플레이어를 위한 플레이어 인스턴스 생성
        join.forEach((player: Player, sessionId: string) => this.OnJoinPlayer(sessionId, player));
 
        // [RoomState] 방을 나가는 플레이어를 위한 플레이어 인스턴스 제거
        leave.forEach((player: Player, sessionId: string) => this.OnLeavePlayer(sessionId, player));
    }
 
    private OnJoinPlayer(sessionId: string, player: Player) {
        console.log(`[OnJoinPlayer] players - sessionId : ${sessionId}`);
        this.currentPlayers.set(sessionId, player);
         
        // 플레이어 생성
        const isLocal = this.room.SessionId === player.sessionId;
        ZepetoPlayers.instance.CreatePlayerWithUserId(sessionId, player.zepetoUserId, new SpawnInfo(), isLocal);
    }
 
    private OnLeavePlayer(sessionId: string, player: Player) {
        console.log(`[OnRemove] players - sessionId : ${sessionId}`);
        this.currentPlayers.delete(sessionId);
 
        ZepetoPlayers.instance.RemovePlayer(sessionId);
    }
}
﻿
﻿
이제 플레이어가 들어오면, ZEPETO 캐릭터가 화면에 생성되었음을 확인할 수 있습니다.
하지만 플레이어의 움직임은 아직 화면에 반영되지 않습니다.
내 화면에서는 내 로컬 플레이어만 움직이고, 다른 플레이어는 실제로 움직이고 있어도 정지해 있는 것처럼 보입니다.
﻿
﻿
다음으로 위치 동기화로 넘어갑니다.
﻿
3단계 : 다른 플레이어의 정보를 가져와 동기화하기
동기화를 위해, 플레이어가 움직이거나 어떤 행동을 할 때마다 그들은 자신의 상태 변화를 서버에 전송해야 합니다.
상태 변화를 포함한 메시지를 서버에 전송하는 것은 룸 메시지 통신을 통해 이루어집니다.
서버가 플레이어의 상태 변화에 대한 메시지를 받으면, 룸 상태를 업데이트합니다.
다음 가이드를 참조하십시오. [Multiplay Room Message﻿]
﻿
예를 들어, 내 로컬 플레이어의 이름이 B라고 가정해 보겠습니다.
네트워크 플레이어 A가 룸에 들어오면, 그들은 좌표 x:0, y:0, z:0에서 인스턴스화됩니다.
플레이어 A가 위치 x: -10, y: 0, z: 0으로 이동하면, B는 A가 이동하고 있다는 것을 실제로 알 방법이 없다.
이는 두 장치에서 각각 로컬로 운영되고 있기 때문에, 서로 다른 클라이언트에서 작동하고 있기 때문이다.
따라서 A를 조종하는 사람은 방 메시지를 통해 자신의 이동을 서버에 전달해야 한다.
서버가 이 정보를 수신하면, 방에 있는 모든 사람에게 A의 실시간 위치를 알린다. 이렇게 하면 B는 A가 이동하고 있다는 것을 알게 된다.
서버가 다른 플레이어에게 알리기 위해서는 두 가지 방법이 있다:
방 메시지 방송 사용하기.
방 상태 업데이트 후 클라이언트가 방 상태를 가져와 적용하기.
이 가이드는 방 상태를 업데이트하는 두 번째 방법을 사용한다.
﻿
﻿
Zepeto 플레이어가 장면에 로드되면 Zepeto 캐릭터 속성을 가지므로, Zepeto 캐릭터 기능을 사용하여 특정 위치로 이동하거나 점프를 시작할 수 있습니다.
B의 클라이언트가 A의 이동을 x:-10, y:0, z:0으로 시각화하기 위해 가장 직관적인 방법은 MoveToPosition()을 사용하는 것입니다. 이 함수는 서버에서 수신한 A의 가장 최근 위치로 플레이어를 이동시킵니다.
위치 변경뿐만 아니라 제스처, 스킬 사용, 아이템 수집 및 모든 상태 변경은 동기화를 위해 서버-클라이언트 통신이 필요합니다.
네트워크 전반에 걸쳐 모든 행동을 조화롭게 유지하기 위해 동기화를 구현해야 합니다.
👍 동기화 개념 요약
로컬 플레이어가 상태 변경을 할 때, 이를 방 메시지를 사용하여 서버에 전송합니다.
서버는 로컬 플레이어를 제외한 모든 다른 플레이어에게 상태 변경을 알립니다.
상태 변경 메시지를 수신하면, 클라이언트 코드는 메시지를 보낸 플레이어의 상태를 업데이트합니다.
﻿
3단계-1 : 완료된 위치 동기화가 있는 서버 스크립트
기본 서버 스크립트에서는 로컬 플레이어의 클라이언트에서 상태 변경에 대한 메시지를 받을 때마다 방 상태를 업데이트하기 위한 추가 구현이 필요합니다.
TypeScript
import {Sandbox, SandboxOptions, SandboxPlayer} from "ZEPETO.Multiplay";

import {Player, Transform, Vector3} from "ZEPETO.Multiplay.Schema";
 
export default class extends Sandbox {
 
     
    constructor() {
        super();
    }
 
    onCreate(options: SandboxOptions) {
        // 방 객체가 생성될 때 호출됩니다.
        // 방 객체의 상태 또는 데이터 초기화를 처리합니다.
 
        this.onMessage("onChangedTransform", (client, message) => {
            const player = this.state.players.get(client.sessionId);
 
            const transform = new Transform();
            transform.position = new Vector3();
            transform.position.x = message.position.x;
            transform.position.y = message.position.y;
            transform.position.z = message.position.z;
 
            transform.rotation = new Vector3();
            transform.rotation.x = message.rotation.x;
            transform.rotation.y = message.rotation.y;
            transform.rotation.z = message.rotation.z;
 
            if (player) {
                player.transform = transform;
            }
        });
 
        this.onMessage("onChangedState", (client, message) => {
            const player = this.state.players.get(client.sessionId);
            if (player) {
                player.state = message.state;
                player.subState = message.subState; // 캐릭터 컨트롤러 V2
            }
        });
    }
     
    
     
    async onJoin(client: SandboxPlayer) {
 
        // schemas.json에 정의된 플레이어 객체를 생성하고 초기 값을 설정합니다.
        console.log(`[OnJoin] sessionId : ${client.sessionId}, userId : ${client.userId}`)
 
        const player = new Player();
        player.sessionId = client.sessionId;
 
        if (client.userId) {
            player.zepetoUserId = client.userId;
        }
         // 클라이언트 객체의 고유 키 값인 sessionId를 사용하여 플레이어 객체를 관리합니다.
        // 클라이언트는 players 객체에 add_OnAdd 이벤트를 추가하여 추가된 플레이어 객체에 대한 정보를 확인할 수 있습니다.
        this.state.players.set(client.sessionId, player);
    }
 
    async onLeave(client: SandboxPlayer, consented?: boolean) {
 
        // allowReconnection을 설정하면 회로에 대한 연결을 유지할 수 있지만 기본 가이드에서는 즉시 정리합니다.
        // 클라이언트는 players 객체에 add_OnRemove 이벤트를 추가하여 삭제된 플레이어 객체에 대한 정보를 확인할 수 있습니다.
        this.state.players.delete(client.sessionId);
    }
}


import {Sandbox, SandboxOptions, SandboxPlayer} from "ZEPETO.Multiplay";

import {Player, Transform, Vector3} from "ZEPETO.Multiplay.Schema";
 
export default class extends Sandbox {
 
     
    constructor() {
        super();
    }
 
    onCreate(options: SandboxOptions) {
        // 방 객체가 생성될 때 호출됩니다.
        // 방 객체의 상태 또는 데이터 초기화를 처리합니다.
 
        this.onMessage("onChangedTransform", (client, message) => {
            const player = this.state.players.get(client.sessionId);
 
            const transform = new Transform();
            transform.position = new Vector3();
            transform.position.x = message.position.x;
            transform.position.y = message.position.y;
            transform.position.z = message.position.z;
 
            transform.rotation = new Vector3();
            transform.rotation.x = message.rotation.x;
            transform.rotation.y = message.rotation.y;
            transform.rotation.z = message.rotation.z;
 
            if (player) {
                player.transform = transform;
            }
        });
 
        this.onMessage("onChangedState", (client, message) => {
            const player = this.state.players.get(client.sessionId);
            if (player) {
                player.state = message.state;
                player.subState = message.subState; // 캐릭터 컨트롤러 V2
            }
        });
    }
     
    
     
    async onJoin(client: SandboxPlayer) {
 
        // schemas.json에 정의된 플레이어 객체를 생성하고 초기 값을 설정합니다.
        console.log(`[OnJoin] sessionId : ${client.sessionId}, userId : ${client.userId}`)
 
        const player = new Player();
        player.sessionId = client.sessionId;
 
        if (client.userId) {
            player.zepetoUserId = client.userId;
        }
         // 클라이언트 객체의 고유 키 값인 sessionId를 사용하여 플레이어 객체를 관리합니다.
        // 클라이언트는 players 객체에 add_OnAdd 이벤트를 추가하여 추가된 플레이어 객체에 대한 정보를 확인할 수 있습니다.
        this.state.players.set(client.sessionId, player);
    }
 
    async onLeave(client: SandboxPlayer, consented?: boolean) {
 
        // allowReconnection을 설정하면 회로에 대한 연결을 유지할 수 있지만 기본 가이드에서는 즉시 정리합니다.
        // 클라이언트는 players 객체에 add_OnRemove 이벤트를 추가하여 삭제된 플레이어 객체에 대한 정보를 확인할 수 있습니다.
        this.state.players.delete(client.sessionId);
    }
}

﻿
﻿
3단계-2 : 완료된 위치 동기화가 있는 클라이언트 스크립트
기본 클라이언트 스크립트의 주요 구현 사항은 다음과 같습니다:
서버의 방 상태가 변경될 때 OnStateChange를 자동으로 호출합니다.
다음의 SendMessageLoop(0.04) 함수를 사용하여, 로컬 플레이어의 위치와 캐릭터 점프 상태 정보를 서버에 0.04초마다 전송합니다.
TypeScript
import {ZepetoScriptBehaviour} from 'ZEPETO.Script'
import {ZepetoWorldMultiplay} from 'ZEPETO.World'
import {Room, RoomData} from 'ZEPETO.Multiplay'
import {Player, State, Vector3} from 'ZEPETO.Multiplay.Schema'
import {CharacterState, SpawnInfo, ZepetoPlayers, ZepetoPlayer, CharacterJumpState} from 'ZEPETO.Character.Controller'
import * as UnityEngine from "UnityEngine";
 
 
export default class ClientStarterV2 extends ZepetoScriptBehaviour {
 
    public multiplay: ZepetoWorldMultiplay;
 
    private room: Room;
    private currentPlayers: Map<string, Player> = new Map<string, Player>();
 
    private zepetoPlayer: ZepetoPlayer;
 
    private Start() {
      			this.multiplay.RoomCreated += (room: Room) => {
            this.room = room;
        };
 
        this.multiplay.RoomJoined += (room: Room) => {
            room.OnStateChange += this.OnStateChange;
        };
 
        this.StartCoroutine(this.SendMessageLoop(0.04));
    }
 
    // 로컬 캐릭터 변환을 서버에 예정된 간격으로 전송합니다.
    private* SendMessageLoop(tick: number) {
        while (true) {
            yield new UnityEngine.WaitForSeconds(tick);
 
            if (this.room != null && this.room.IsConnected) {
                const hasPlayer = ZepetoPlayers.instance.HasPlayer(this.room.SessionId);
                if (hasPlayer) {
                    const character = ZepetoPlayers.instance.GetPlayer(this.room.SessionId).character;                                 
                    this.SendTransform(character.transform);
                    this.SendState(character.CurrentState);
                }
            }
        }
    }
 
    private OnStateChange(state: State, isFirst: boolean) {
 
        // 첫 번째 OnStateChange 이벤트가 수신되면 전체 상태 스냅샷이 기록됩니다.
        if (isFirst) {
 
            // [CharacterController] (로컬) 플레이어 인스턴스가 씬에 완전히 로드될 때 호출됩니다.
            ZepetoPlayers.instance.OnAddedLocalPlayer.AddListener(() => {
                const myPlayer = ZepetoPlayers.instance.LocalPlayer.zepetoPlayer;
                this.zepetoPlayer = myPlayer;
            });
 
            // [CharacterController] (로컬) 플레이어 인스턴스가 씬에 완전히 로드될 때 호출됩니다.
            ZepetoPlayers.instance.OnAddedPlayer.AddListener((sessionId: string) => {
                const isLocal = this.room.SessionId === sessionId;
                if (!isLocal) {
                    const player: Player = this.currentPlayers.get(sessionId);
 
                    // [RoomState] 플레이어 인스턴스의 상태가 업데이트될 때마다 호출됩니다.
                    player.OnChange += (changeValues) => this.OnUpdatePlayer(sessionId, player);
                }
            });
        }
 
        let join = new Map<string, Player>();
        let leave = new Map<string, Player>(this.currentPlayers);
 
        state.players.ForEach((sessionId: string, player: Player) => {
            if (!this.currentPlayers.has(sessionId)) {
                join.set(sessionId, player);
            }
            leave.delete(sessionId);
        });
 
        // [RoomState] 방에 들어오는 플레이어를 위한 플레이어 인스턴스를 생성합니다.
        join.forEach((player: Player, sessionId: string) => this.OnJoinPlayer(sessionId, player));
 
        // [RoomState] 방을 나가는 플레이어를 위한 플레이어 인스턴스를 제거합니다.
        leave.forEach((player: Player, sessionId: string) => this.OnLeavePlayer(sessionId, player));
    }
 
    private OnJoinPlayer(sessionId: string, player: Player) {
        console.log(`[OnJoinPlayer] players - sessionId : ${sessionId}`);
        this.currentPlayers.set(sessionId, player);
 
        const spawnInfo = new SpawnInfo();
        const position = this.ParseVector3(player.transform.position);
        const rotation = this.ParseVector3(player.transform.rotation);
        spawnInfo.position = position;
        spawnInfo.rotation = UnityEngine.Quaternion.Euler(rotation);
 
        const isLocal = this.room.SessionId === player.sessionId;
        ZepetoPlayers.instance.CreatePlayerWithUserId(sessionId, player.zepetoUserId, spawnInfo, isLocal);
    }
 
    private OnLeavePlayer(sessionId: string, player: Player) {
        console.log(`[OnRemove] players - sessionId : ${sessionId}`);
        this.currentPlayers.delete(sessionId);
 
        ZepetoPlayers.instance.RemovePlayer(sessionId);
    }
 
    private OnUpdatePlayer(sessionId: string, player: Player) {
 
        const position = this.ParseVector3(player.transform.position);
 
        const zepetoPlayer = ZepetoPlayers.instance.GetPlayer(sessionId);
 
        var moveDir = UnityEngine.Vector3.op_Subtraction(position, zepetoPlayer.character.transform.position);
        moveDir = new UnityEngine.Vector3(moveDir.x, 0, moveDir.z);
 
        if (moveDir.magnitude < 0.05) {
            if (player.state === CharacterState.MoveTurn)
                return;
            zepetoPlayer.character.StopMoving();
        } else {
            zepetoPlayer.character.MoveContinuously(moveDir);
        }
 
        if (player.state === CharacterState.Jump) {
            if (zepetoPlayer.character.CurrentState !== CharacterState.Jump) {
                zepetoPlayer.character.Jump();
            }
 
            if (player.subState === CharacterJumpState.JumpDouble) {
                zepetoPlayer.character.DoubleJump();
            }
        }
    }
 
    private SendTransform(transform: UnityEngine.Transform) {
        const data = new RoomData();
 
        const pos = new RoomData();
        pos.Add("x", transform.localPosition.x);
        pos.Add("y", transform.localPosition.y);
        pos.Add("z", transform.localPosition.z);
        data.Add("position", pos.GetObject());
 
        const rot = new RoomData();
        rot.Add("x", transform.localEulerAngles.x);
        rot.Add("y", transform.localEulerAngles.y);
        rot.Add("z", transform.localEulerAngles.z);
        data.Add("rotation", rot.GetObject());
        this.room.Send("onChangedTransform", data.GetObject());
    }
 
    private SendState(state: CharacterState) {
        const data = new RoomData();
        data.Add("state", state);
        if(state === CharacterState.Jump) {
            data.Add("subState", this.zepetoPlayer.character.MotionV2.CurrentJumpState);
        }
        this.room.Send("onChangedState", data.GetObject());
    }
 
    private ParseVector3(vector3: Vector3): UnityEngine.Vector3 {
        return new UnityEngine.Vector3
        (
            vector3.x,
            vector3.y,
            vector3.z
        );
    }
}
import {ZepetoScriptBehaviour} from 'ZEPETO.Script'
import {ZepetoWorldMultiplay} from 'ZEPETO.World'
import {Room, RoomData} from 'ZEPETO.Multiplay'
import {Player, State, Vector3} from 'ZEPETO.Multiplay.Schema'
import {CharacterState, SpawnInfo, ZepetoPlayers, ZepetoPlayer, CharacterJumpState} from 'ZEPETO.Character.Controller'
import * as UnityEngine from "UnityEngine";
 
 
export default class ClientStarterV2 extends ZepetoScriptBehaviour {
 
    public multiplay: ZepetoWorldMultiplay;
 
    private room: Room;
    private currentPlayers: Map<string, Player> = new Map<string, Player>();
 
    private zepetoPlayer: ZepetoPlayer;
 
    private Start() {
      			this.multiplay.RoomCreated += (room: Room) => {
            this.room = room;
        };
 
        this.multiplay.RoomJoined += (room: Room) => {
            room.OnStateChange += this.OnStateChange;
        };
 
        this.StartCoroutine(this.SendMessageLoop(0.04));
    }
 
    // 로컬 캐릭터 변환을 서버에 예정된 간격으로 전송합니다.
    private* SendMessageLoop(tick: number) {
        while (true) {
            yield new UnityEngine.WaitForSeconds(tick);
 
            if (this.room != null && this.room.IsConnected) {
                const hasPlayer = ZepetoPlayers.instance.HasPlayer(this.room.SessionId);
                if (hasPlayer) {
                    const character = ZepetoPlayers.instance.GetPlayer(this.room.SessionId).character;                                 
                    this.SendTransform(character.transform);
                    this.SendState(character.CurrentState);
                }
            }
        }
    }
 
    private OnStateChange(state: State, isFirst: boolean) {
 
        // 첫 번째 OnStateChange 이벤트가 수신되면 전체 상태 스냅샷이 기록됩니다.
        if (isFirst) {
 
            // [CharacterController] (로컬) 플레이어 인스턴스가 씬에 완전히 로드될 때 호출됩니다.
            ZepetoPlayers.instance.OnAddedLocalPlayer.AddListener(() => {
                const myPlayer = ZepetoPlayers.instance.LocalPlayer.zepetoPlayer;
                this.zepetoPlayer = myPlayer;
            });
 
            // [CharacterController] (로컬) 플레이어 인스턴스가 씬에 완전히 로드될 때 호출됩니다.
            ZepetoPlayers.instance.OnAddedPlayer.AddListener((sessionId: string) => {
                const isLocal = this.room.SessionId === sessionId;
                if (!isLocal) {
                    const player: Player = this.currentPlayers.get(sessionId);
 
                    // [RoomState] 플레이어 인스턴스의 상태가 업데이트될 때마다 호출됩니다.
                    player.OnChange += (changeValues) => this.OnUpdatePlayer(sessionId, player);
                }
            });
        }
 
        let join = new Map<string, Player>();
        let leave = new Map<string, Player>(this.currentPlayers);
 
        state.players.ForEach((sessionId: string, player: Player) => {
            if (!this.currentPlayers.has(sessionId)) {
                join.set(sessionId, player);
            }
            leave.delete(sessionId);
        });
 
        // [RoomState] 방에 들어오는 플레이어를 위한 플레이어 인스턴스를 생성합니다.
        join.forEach((player: Player, sessionId: string) => this.OnJoinPlayer(sessionId, player));
 
        // [RoomState] 방을 나가는 플레이어를 위한 플레이어 인스턴스를 제거합니다.
        leave.forEach((player: Player, sessionId: string) => this.OnLeavePlayer(sessionId, player));
    }
 
    private OnJoinPlayer(sessionId: string, player: Player) {
        console.log(`[OnJoinPlayer] players - sessionId : ${sessionId}`);
        this.currentPlayers.set(sessionId, player);
 
        const spawnInfo = new SpawnInfo();
        const position = this.ParseVector3(player.transform.position);
        const rotation = this.ParseVector3(player.transform.rotation);
        spawnInfo.position = position;
        spawnInfo.rotation = UnityEngine.Quaternion.Euler(rotation);
 
        const isLocal = this.room.SessionId === player.sessionId;
        ZepetoPlayers.instance.CreatePlayerWithUserId(sessionId, player.zepetoUserId, spawnInfo, isLocal);
    }
 
    private OnLeavePlayer(sessionId: string, player: Player) {
        console.log(`[OnRemove] players - sessionId : ${sessionId}`);
        this.currentPlayers.delete(sessionId);
 
        ZepetoPlayers.instance.RemovePlayer(sessionId);
    }
 
    private OnUpdatePlayer(sessionId: string, player: Player) {
 
        const position = this.ParseVector3(player.transform.position);
 
        const zepetoPlayer = ZepetoPlayers.instance.GetPlayer(sessionId);
 
        var moveDir = UnityEngine.Vector3.op_Subtraction(position, zepetoPlayer.character.transform.position);
        moveDir = new UnityEngine.Vector3(moveDir.x, 0, moveDir.z);
 
        if (moveDir.magnitude < 0.05) {
            if (player.state === CharacterState.MoveTurn)
                return;
            zepetoPlayer.character.StopMoving();
        } else {
            zepetoPlayer.character.MoveContinuously(moveDir);
        }
 
        if (player.state === CharacterState.Jump) {
            if (zepetoPlayer.character.CurrentState !== CharacterState.Jump) {
                zepetoPlayer.character.Jump();
            }
 
            if (player.subState === CharacterJumpState.JumpDouble) {
                zepetoPlayer.character.DoubleJump();
            }
        }
    }
 
    private SendTransform(transform: UnityEngine.Transform) {
        const data = new RoomData();
 
        const pos = new RoomData();
        pos.Add("x", transform.localPosition.x);
        pos.Add("y", transform.localPosition.y);
        pos.Add("z", transform.localPosition.z);
        data.Add("position", pos.GetObject());
 
        const rot = new RoomData();
        rot.Add("x", transform.localEulerAngles.x);
        rot.Add("y", transform.localEulerAngles.y);
        rot.Add("z", transform.localEulerAngles.z);
        data.Add("rotation", rot.GetObject());
        this.room.Send("onChangedTransform", data.GetObject());
    }
 
    private SendState(state: CharacterState) {
        const data = new RoomData();
        data.Add("state", state);
        if(state === CharacterState.Jump) {
            data.Add("subState", this.zepetoPlayer.character.MotionV2.CurrentJumpState);
        }
        this.room.Send("onChangedState", data.GetObject());
    }
 
    private ParseVector3(vector3: Vector3): UnityEngine.Vector3 {
        return new UnityEngine.Vector3
        (
            vector3.x,
            vector3.y,
            vector3.z
        );
    }
}
﻿
﻿
위치 동기화 코드가 적용되어 내 로컬 플레이어뿐만 아니라 다른 플레이어의 움직임도 표시됩니다.
﻿
﻿
👍 팁
이 가이드는 위치 동기화만 구현합니다. 제스처 동기화, 객체 동기화 등은 구현되지 않았습니다.
원리는 모두 동일하지만, 필요한 순간마다 방 메시지를 보내고 받는 과정이 필요합니다.
동기화를 더 편리하게 구현하고 싶다면, 멀티플레이 동기화 모듈을 사용하는 것을 고려하세요.
﻿
ZepetoPlayer	설명
로컬 플레이어	로컬 사용자가 직접 제어하는 ZEPETO 캐릭터 인스턴스입니다. - 캐릭터 컨트롤러/Zepeto 카메라 컴포넌트가 부착되어 있습니다.
네트워크 플레이어 (원격 플레이어)	멀티플레이 콘텐츠에서 로드하고 활용할 수 있는 ZEPETO 캐릭터 인스턴스입니다. - 캐릭터 컨트롤러/Zepeto 카메라 컴포넌트가 부착되어 있지 않습니다.
봇 플레이어	멀티플레이 콘텐츠를 위한 ZEPETO 캐릭터 인스턴스이지만, 실제 사용자가 아닌 봇에 의해 제어됩니다. 플레이어가 부족한 멀티플레이 월드를 시작할 때 또는 플레이 중 플레이어가 나갈 경우 대체로 사용됩니다. - 캐릭터 컨트롤러/Zepeto 카메라 컴포넌트가 부착되어 있지 않습니다.
업데이트됨 11 Oct 2024
이 페이지가 도움이 되었습니까?
$ref & $unref
ZEPETO Player