상세 해설 - 프로토콜 토큰

Bolt에는 프로토콜 토큰이라고 하는 기능을 가지고 있는데 Bolt에서 발생할 수 있는 특정 액션으로 독단적인 데이터(C# 객체들)를 붙이기 위해서 사용되는 것은 아래와 같은 것 입니다:

  • 엔티티 인스턴스화
  • 서버에 접속
  • 씬 로딩

프로토콜 토큰이 존재하는 이유는 많은 경우에 특정 작업이 발생할 때 작은 데이터 조각을 사용하기를 원할 때가 있기 때문입니다. 네트워크의 특성상 데이터의 신뢰성이 보장되지 않기 때문에 액션 자체와같이 전송되어야 합니다. 프로토콜 토큰을 사용하여 이것을 수행할 수 있습니다.

특정 작업이 수행될 때 사용할 수 있는 데이터의 예는 다음과 같습니다:

  • 플레이어 캐릭터를 인스턴스화 할 때 플레이어가 선택한 커스터마이징된 옵션 전송을 원할 때.
  • 서버에 접속 시 플레이어가 사용자명과 비밀번호를 전송하기 원할 때.
  • 씬이 로딩을 시작할 때 계절(가을, 겨울 등)에 대한 올바른 텍스쳐를 로드하기를 원하는 경우

프로토콜 토큰은 일반적인 C# 클래스를 정의하여 생성되고 Bolt.IProtocolToken 인터페이스에서 상속 됩니다. 이 인터페이스는 두 개의 메소드를 정의합니다: Write 와 Read 입니다. 이 메소드들은 클래스 내에서 구현할 필요가 있습니다.

public class CharacterCustomization : Bolt.IProtocolToken {
  public int SkinId;
  public int HatId;

  public void Write(UdpKit.UdpPacket packet) {
    packet.WriteInt(SkinId);
    packet.WriteInt(HatId);
  }

  public void Read(UdpKit.UdpPacket packet) {
    SkinId = packet.ReadInt();
    HatId = packet.ReadInt();
  }
}

여기에서 엔티티 인스턴스를 생성할 때 일부 캐릭터 커스머마이징 데이터를 포함하고 있는 프로토콜을 정의 했습니다. 두 개의 간단한 정수형 필드가 있으며 캐릭터의 스킨 id 번호와 모자 id를 나타냅니다.

Write 메소드에서 전달할 패킷 객체에 WriteXXX() 메소드를 호출하여 패킷으로 데이터를 씁니다. 반대로 Read 에서는 전달된 패킷에 ReadXXX() 를 호출 합니다.

중요: WriteXXXReadXXX 는 상응되는 WriteRead 메소드에서 동일한 순서로 호출 해야 합니다.

프로토콜 토큰을 사용하기 위해서는 프로토콜 토큰을 Bolt에 등록 해야 합니다. Bolt.GlobalEventListener 에서 상속 받은 Unity 행위를 생성하여 구현할 수 있는BoltStarted콜백에서 수행되어야 합니다.Bolt.GlobalEventListener` 이 어떻게 동작하는 가에 대해서는 상세 해설 - 글로벌 콜백 섹션을 참고하시기 바랍니다.

BoltNetwork.RegisterTokenClass<T>() 을 호출하여 토큰 클래스를 등록하고 지네릭 파라미터 T 로써 클래스를 전달합니다. 아래 예제를 보세요.

[BoltGlobalBehaviour]
public class NetworkCallbacks : Bolt.GlobalEventListener {
  public override void BoltStartBegin() {
    BoltNetwork.RegisterTokenClass<CharacterCustomization>();
  }
}

이제 BoltNetwork.Instantiate 메소드를 호출할 때, CharacterCustomization 클래스의 인스턴스를 전달할 수 있습니다.

var token = new CharacterCustomization();
token.SkinId = 5;
token.HatId = 12;

BoltNetwork.Instantiate(BoltPrefabs.CharacterPrefab, token);

그리고 나서 Bolt.EntityBehaviourBolt.EntityBehaviour<T> 에서 상속된 C# 스크립트의 Attached 콜백에서 아래처럼 이 토큰에 접근할 수 있습니다.


public class MyEntityBehaviour : Bolt.EntityBehaviour<ICharacterState> {
  public override void Attached() {
    var customization = (CharacterCustomization)entity.attachToken;
    // ... use the customization data here
  }
}

기술문서 TOP으로 돌아가기