Godot 클라이언트

sync와 stateMachine 룸에서는 룸에 있는 오브젝트를 Godot의 노드로 표시할 수 있습니다. 이 페이지에서는 그 Godot 측의 설정과 API를 설명합니다. 대상은 Godot 4의 GDScript이며, 2D와 3D 모두에 대응합니다.

동기화의 구조(누가 무엇을 변경할 수 있는지, 전송 순서, 재접속 등)는 엔진에 공통이므로 오브젝트 동기화의 구조에 정리되어 있습니다. 이 페이지에서는 Godot에서의 작성 방법을 설명합니다. 룸의 룰도 GDScript로 작성할 수 있습니다. 작성 방법은 GDScript로 룰 작성하기를 참조해 주세요.

Unity 클라이언트와 Godot 클라이언트가 같은 룸에 참가하는 것은 상정하지 않습니다. 하나의 게임에서는 어느 한쪽만 사용해 주세요.

전체 구조

Godot에서는 다음 노드와 리소스를 사용합니다. 모두 GS2 SDK for Godot의 애드온(addons/gs2)에 포함되어 있습니다.

Unity에서는 컴포넌트를 GameObject에 추가하지만, Godot에서는 노드를 씬의 루트의 자식으로 추가합니다. Gs2NetworkEntity와 Transform 노드는 기본적으로 부모(target = "..")를 대상으로 합니다.

GDScript에는 예외가 없으므로, 실패는 반환값(false나 null)으로 돌아오고 사유는 각 노드의 last_error에 들어갑니다. 사용법의 오류는 push_error로도 보고합니다.

룸에 접속하기

1. 씬에 Gs2NetworkWorld와 Gs2NetworkSession을 배치합니다.
2. World의 catalog에 Prefab 카탈로그를, Session의 world에 World를 설정합니다.
3. GS2-Realtime에서 받은 룸의 주소(액세스 토큰, IP 주소, 포트, 암호화 키)로 connect_room을 호출합니다.

extends Node

const PLAYER_PREFAB := 1 # 카탈로그 엔트리의 ID

@onready var world: Gs2NetworkWorld = $World
@onready var session: Gs2NetworkSession = $Session


func _ready() -> void:
    # 한 번만 연결한다. 접속할 때마다 연결하면 재접속 시 중복됨
    session.room_ready.connect(_on_room_ready)
    world.spawned.connect(_on_spawned)
    session.disconnected.connect(func(reason: String) -> void: print("Disconnected: ", reason))


# 접속·재접속할 때마다
func join(access_token: String, ip_address: String, port: int, encryption_key: String) -> void:
    if not session.connect_room(access_token, ip_address, port, encryption_key):
        push_error(session.last_error)


func _on_room_ready() -> void:
    # 스냅샷 반영 후. 생성이나 전송을 할 수 있다
    world.instantiate(PLAYER_PREFAB, Vector3.ZERO)


func _on_spawned(entity: Gs2NetworkEntity) -> void:
    if entity.is_mine():
        print("My player is in the room: ", entity.get_parent().name)

Session은 노드가 비활성화되었을 때(process_mode = DISABLED)나 트리에서 제거되었을 때에도 접속을 종료합니다. Session과 World는 일시 정지의 영향을 받지 않으며(PROCESS_MODE_ALWAYS), 경과 시간은 실제 시간으로 측정합니다.

전송은 접속 후라면 언제 호출해도 됩니다(전송 순서).

Session을 사용하지 않고 독자적인 통신 경로를 연결하는 경우에는 world.attach(connection_id, send)로 연결하고, 받은 데이터를 world.receive_at(payload, server_milliseconds)에 전달하며, 접속이 끊기면 world.detach()를 호출합니다.

씬 등록하기

1. 표시용 씬을 만들고, 루트(CharacterBody3D, Node2D 등)의 자식으로 Gs2NetworkEntity를 추가합니다. 위치·회전도 동기화한다면 Gs2NetworkTransform3D(2D라면 Gs2NetworkTransform2D)도 자식으로 추가합니다.
2. 새 리소스로 Gs2NetworkPrefabCatalog를 만들고, prefabs에 Gs2NetworkPrefabEntry(Prefab ID와 PackedScene)를 추가합니다.
3. World의 catalog에 그 카탈로그를 지정합니다.

인스펙터에는 ID 중복, 씬이나 Entity의 누락, 다른 Prefab용 스키마가 경고로 표시됩니다. 서버로부터 도착할 가능성이 있는 Prefab ID는 모두 등록해 주세요.

플레이어가 자신의 오브젝트를 만들 때는 PackedScene.instantiate()가 아니라 world.instantiate를 사용합니다.

위치·회전 동기화하기

위치·회전은 SDK에 표준 필드가 있어, 동기화 스키마가 없어도 동기화할 수 있습니다. 서버 측에서 동기화를 허가한 축(위치·회전)만 선택합니다.

2D에서는 Y축을 반전하지 않으므로, 룰에는 픽셀 좌표가 그대로 도착합니다. 표준 단위 간격(0.01)은 픽셀에는 너무 세밀하므로, 룰 측에서 거칠게 하는 것을 권장합니다(GDScript라면 ## @room_schema(..., standard=POSITION, position_precision=1.0)).

독자적인 값 표시하기

HP나 개폐 상태 등의 독자적인 값은 룰에서 동기화 스키마로 선언하고, 생성된 .realtimeschema를 사용합니다(독자적인 값).

1. 생성된 .realtimeschema를 프로젝트에 배치합니다. Gs2NetworkSchema 리소스로 가져와집니다.
2. 씬의 Gs2NetworkEntity.schema에 그 리소스를 지정합니다.
3. 값을 표시에 반영하려면 property_bindings(필드 이름, 대상 노드, 프로퍼티 또는 메서드)를 설정하거나 field_changed(field_name, value) 시그널을 사용합니다.

매번 전송 직전에 값을 쓰려면 _network_write(entity)를, 수신했을 때 읽으려면 _network_read(entity, changed)를 씬 안의 노드에 구현합니다(Unity의 INetworkObservable에 해당합니다).

GDScript로 룰을 작성한 경우에는 컴파일러가 형식 지정 접근자도 생성합니다(EnemyStateSchema.health(o) 등).

서버에 조작 전송하기

룰이 관리하는 오브젝트에는 씬에 Gs2SharedObject를 추가하여 조작을 전송합니다. 요청의 상태와 결과 코드의 의미는 서버에 조작 전송하기를 참조해 주세요.

모두 Gs2CommandRequest를 반환합니다. await request.wait()로 완료를 기다리거나 request.on_completed(callback)로 결과를 받습니다.

var request := door.interact(DoorAction.OPEN) # DoorAction은 룰에서 생성된 상수
await request.wait()
if request.status != Gs2SyncTypes.RequestStatus.SUCCEEDED:
    print("Refused: ", Gs2SyncTypes.result_name(request.result))

조작 권한을 사용하여 값 전송하기

조작 권한의 규칙은 조작 권한을 참조해 주세요.

Gs2SharedObject의 acquire() / renew() / release()는 조작 권한을 수동으로 관리하는 API이며, controlled_nodes의 전환이나 자동 갱신은 하지 않습니다.

플레이어 오브젝트 만들기

위치와 회전은 2D에서는 Vector2와 라디안, 3D에서는 Vector3와 Quaternion / Basis / 오일러 각(라디안)으로 전달할 수 있습니다. 소유자가 퇴장했을 때의 처리와 소유 기간의 규칙은 플레이어 오브젝트를 참조해 주세요.

RPC

RPC는 메서드 이름으로부터 자동으로 등록됩니다. 대상은 Entity의 부모 아래에 있는 노드(중첩된 다른 Entity 아래는 제외)의 메서드입니다.

# 소유자만 호출할 수 있는 RPC
func net_rpc_fire(direction: Vector3, damage: int, info: Gs2NetworkRpcInfo) -> void:
    print("fired by ", info.sender)

# 어느 참가자든 호출할 수 있는 RPC(오브젝트 카탈로그의 publicMethods)
func net_rpc_public_cheer(info: Gs2NetworkRpcInfo) -> void:
    pass

entity.send_rpc("fire", Gs2SyncTypes.RpcTarget.OTHERS, Vector3.FORWARD, 10)
entity.rpc_to("fire", connection_id, Vector3.FORWARD, 10)

• RPC의 ID는 접두사를 제외한 이름(fire)의 FNV-1a 해시입니다. 메서드 이름을 바꾸면 ID도 바뀌므로, 오브젝트 카탈로그와 클라이언트를 맞추어 갱신해 주세요.
• 전송 대상은 ALL·OTHERS·OWNER·ALL_BUFFERED·OTHERS_BUFFERED입니다. 의미는 RPC를 참조해 주세요.
• 인수에는 형식을 붙입니다. 사용할 수 있는 형식은 bool·int(enum 포함)·float·String·PackedByteArray·Vector2 / 3 / 4·Vector2i / 3i·Quaternion·Color입니다. 마지막 Gs2NetworkRpcInfo 인수에는 보낸 사람 등이 들어갑니다.
• Node.rpc()와 충돌하지 않도록, 전송 메서드의 이름은 send_rpc입니다.

인스펙터에서 Entity를 선택하면 등록된 RPC와 ID를 확인할 수 있습니다.

룸 이벤트·커스텀 프로퍼티·마스터 클라이언트·Interest Group

의미와 상한은 룸 이벤트·커스텀 프로퍼티·마스터 클라이언트·Interest Group을 참조해 주세요.

틱으로 움직이는 오브젝트 조작하기

틱을 사용하는 룸에서는 world.set_input(slot, value)로 입력을 전송합니다(틱과 예측). 슬롯에는 룰에서 생성된 상수(TickInput.MOVE_X 등)를 사용합니다.

룰에 예측 함수가 있는 경우, 컴파일러가 <룰 이름>Prediction을 생성합니다. 게임 시작 시 <룰 이름>Prediction.register(world)를 한 번 호출하면, 자신의 오브젝트를 룸과 같은 계산으로 먼저 움직입니다. 예측이 빗나갔을 경우에는 Transform이 차이를 약 correction_time(기본 0.1초)에 걸쳐 좁힙니다. 지연 보상을 위해 World의 view_delay는 Transform의 interpolation_delay와 같은 값(기본 0.1초)으로 하세요.

UDP로 상태 전송하기

룸이 UDP를 제공하고 Web 이외의 환경에서 동작할 때는 Session이 UDP를 사용합니다(UDP). 사용하지 않는 경우에는 Session의 use_udp를 false로 합니다.

Web 버전에서는 UDP를 사용할 수 없습니다. 또한 https로 배포하는 페이지에서는 ws://에 접속할 수 없는 경우가 있습니다.

오브젝트 카탈로그

인스펙터에서 Gs2NetworkPrefabCatalog를 선택하고 Project > Tools > GS2 > Copy Object Catalog JSON을 실행하면, 네임스페이스의 syncSetting.objectCatalog에 붙여 넣을 JSON이 클립보드에 복사됩니다. 룰이 정의하는 Prefab(Gs2SharedObject와, 룰이 정의하는 스키마의 것)은 제외됩니다. JSON의 형식과 항목은 오브젝트 카탈로그를 참조해 주세요.

오브젝트의 수명·룸 종료·전송량

접속이 끊기거나 재접속했을 때의 오브젝트 처리, 룸 종료 조건과의 관계, 전송량 기준은 오브젝트의 수명과 재접속·룸 종료 조건과의 관계·전송량 기준을 참조해 주세요. World의 전송 간격은 send_rate(기본값 20회/초)입니다.

잘 동작하지 않을 때

엔진에 공통인 확인 사항은 오브젝트 동기화의 구조를 참조해 주세요. Godot 고유의 확인 사항은 다음과 같습니다.

샘플

SDK의 samples/realtime/에 Unity 샘플을 이식한 2개의 샘플이 있습니다. 둘 다 룰을 GDScript로 작성했습니다.