INetworkStruct

개요

INetworkStruct Fusion에서 사용될 수 있는 Networked 속성 및 RPC 메소드에 대한 구조체를 정의합니다.

사용자 정의 INetworkStruct 필수 사항:

• 구조체 타입이어야 합니다
• INetworkStruct 인터페이스를 구현해야 합니다
• blittable이어야 합니다

이 구조체들은 다른 INetworkStructs를 필드로 중첩할 수 있습니다.

Blittable 요건

INetworkStruct는 블릿 가능해야 합니다. 즉, 관리되는 컨텍스트와 관리되지 않는 컨텍스트 모두에서 절대적인 메모리 풋프린트를 가집니다. 따라서 field 멤버들은 다음이 아닐수 있습니다.

• ref 타입
• string 또는 char(대신 NetworkString을 사용하세요)
• bool(대신 NetworkBool 부울을 사용하세요)

.Net blittable 타입에 대한 상세 내용.

허용된 필드 타입

필드 멤버는 구조체의 메모리 공간 및 정렬에 직접적인 영향을 미치므로 반드시 블릿 가능한 유형이어야 합니다. 자동 구현되지 않는 속성 멤버와 메서드 멤버는 메모리 레이아웃에 영향을 주지 않으므로 이러한 타입으로 제한되지 않습니다.

안전한 필드 유형은 다음과 같습니다.

• Blittable 원시 타입
  • byte, sbyte
  • short, int, long
  • ushort, uint, ulong
  • float, double
• Blittable 유니티 구조체 타입
  • Vector2, Vector3, Vector4
  • Quaternion
  • Matrix4x4
  • Vector2Int, Vector3Int
  • BoundingSphere
  • Bounds
  • Rect
  • BoundsInt
  • RectInt
  • Color, Color32
• 열거형
• 시스템 Blittable 타입 (System.Guid 와 같은)
• 사용자 정의 INetworkStructs
• Fusion 정의 INetworkStructs
  • NetworkString<>
  • NetworkBool
  • Ptr
  • Angle
  • BitSet64, BitSet128, BitSet192, BitSet256
  • PlayerRefSet
  • NetworkId
  • NetworkButtons
  • NetworkRNG
  • NetworkObjectGuid
  • NetworkPrefabRef
  • NetworkObjectHeader
  • NetworkPrefabId
  • PlayerRef
  • SceneRef
  • TickTimer
  • IFixedStorage (_2, _4, _8, _16, _32, _64, _128, _256, _512)
• Network 컬렉션
  • NetworkArray<T>](~~~/manual/network-collections#networkarray_lt_t_) [Capacity] 속성을 사용한 (기본값 1) 최대 길이 Length 설정
  • NetworkDictionary<K, V> 최대 Count [Capacity]로 설정
  • NetworkLinkedList<T> [Capacity] 속성을 사용하여 최대 Count 설정.
  • NetworkString<_size>
• 고정 크기 버퍼 (unsafe: fixed int MyArray[32]와 같은)

사용

Networked 속성으로 INetworkStruct

구조체는 value 타입입니다. 편의를 위해 네트워크 속성은 ref 키워드를 사용할 수 있습니다. 이렇게 하면 복사본 작업 없이 속성 멤버들을 직접 수정할 수 있습니다.

C#

using Fusion;
using UnityEngine;

public class NetworkStructSampleCode : NetworkBehaviour
{
  public struct NetworkStructExample : INetworkStruct
  {
    public int IntField;
  }

  // For convenience, declared Networked INetworkStructs can use the ref keyword,
  // which allows direct modification of members without needing to work with copies.
  [Networked]
  public ref NetworkStructExample NetworkedStructRef => ref MakeRef<NetworkStructExample>();

  // You can also declare Networked structs normally,
  // but be aware the getter will return a copy and not a reference.
  [Networked]
  public NetworkStructExample NetworkedStruct { get; set; }

  public override void Spawned()
  {
    NetworkedStruct.IntField = 5;
    Debug.Log(NetworkedStruct.IntField); // prints default value (0) and not 5.

    NetworkedStructRef.IntField = 5;
    Debug.Log(NetworkedStructRef.IntField); // prints 5
  }
}

간단한 Blittable Value 타입

부동 소수점 이하 원시 타입은 기본 필드로 선언할 수 있습니다. 추가 코딩이나 속성이 필요하지 않습니다. 플로트 유형 또는 플로트 기반의 유니티 구조체(예: Vector3)에 대해서는 부동 소수점 타입 섹션을 참조하십시오.

C#

using Fusion;
using UnityEngine;


public class NetworkStructSampleCode : NetworkBehaviour
{
  public struct NetworkStructExample : INetworkStruct
  {
    // Non-float primitive structs and Enum types, can be used normally as a field.
    // Except bools, which are non-blittable and cannot be used as fields.
    public SnapAxis   EnumField;
    public int        IntField;
    public Color32    Color32Field;
    public Vector2Int VectorIntField;
  }

부동 소수점 타입

부동 소수점 타입(부동 소수점 기반 및 일반적인 유니티 부동 소수점 기반 유형)을 필드로 사용할 수 있습니다. 그러나 필드로 사용할 경우 Fusion ILWeever에서 압축 처리가 생성되지 않습니다.

이러한 부동 소수점 타입을 자동으로 압축하려면 기본 구현이 있는 속성에서 [Networked] 속성을 사용하십시오. Fusion의 ILWeaver는 압축 처리로 구현을 대체합니다.

C#

using Fusion;
using UnityEngine;
public class NetworkStructSampleCode : NetworkBehaviour
{
  public struct NetworkStructExample : INetworkStruct
  {
  // Recognized float-based Networked Properties will implement Fusion's compression.
  // Such as Float, Double, Vector2, Vector3, Color, Matrix etc.
  // Note: an auto-implemented property is allowed here.
  [Networked]
  public Vector3 CompressedVector { get; set; }

  [Networked]
  public float   CompressedFloat { get; set; }

  // Float types declared as fields will be uncompressed and will replicate bit for bit.
  // Typically you want compression, so this handling should not be used in most cases.
  public Vector3 UncompressedVector;
  public float   UncompressedFloat;
}

부울

부울은 블릿이 불가능하므로 필드에 bool 타입을 안전하게 사용할 수 없습니다. 퓨전은 bool 속성보다 구현 코드가 덜 필요한 bool과 상호 교환하여 사용할 수 있는 NetworkBool 타입을 제공합니다.

C#

using Fusion;
using UnityEngine;

public class NetworkStructSampleCode : NetworkBehaviour
{
  public struct NetworkStructExample : INetworkStruct
  {
    // The preferred way to network a boolean is to use the NetworkBool type.
    public NetworkBool NetworkBool;

    // [Networked] is required for the primitive bool in order to instruct
    // the ILWeaver to create the required backing int and implementation.
    // Note that we do NOT declare this as an auto-implemented property,
    // but instead with an empty getter/setter.
    [Networked]
    public bool PrimitiveBool { get => default; set { } }

 }

bool 타입은 자동 구현이 아닌 경우 속성으로 사용할 수도 있습니다.

문자열

문자열 및 문자 타입은 비트화할 수 없으므로 string 타입은 필드에 안전하게 사용할 수 없지만 자동 구현이 아닌 속성에 사용할 수 있습니다.

Fusion은 string과 상호 교환하여 사용할 수 있는 NetworkString<_size> 타입을 제공합니다. 이 유형은 string 속성보다 할당을 적게 생성하고 성능이 뛰어나며 구현하는 코드가 적습니다.

C#

using Fusion;
using UnityEngine;

public class NetworkStructSampleCode : NetworkBehaviour
{
  public struct NetworkStructExample : INetworkStruct
  {
    // The easiest and cleanest way to use a string in an INetworkStruct
    // is to use the Fusion NetworkString<> type as a field.
    // _16 here indicates that we are allocating a capacity of 16 characters.
    public NetworkString<_16> Name;

    // Optionally a regular string can be used as a Property (not a field)
    [Networked]       // Notifies the ILWeaver to extend this property
    [Capacity(16)]    // allocates memory for 16 characters
    [UnityMultiline]  // Optional attribute to force multi-line in inspector.
    public string StringProperty { get => default; set { } }
  }

  // For convenience, declared Networked INetworkStructs can use the ref keyword,
  // which allows direct modification of members without needing to deal with copies.
  [Networked]
  public ref NetworkStructExample NetworkedStructRef => ref MakeRef<NetworkStructExample>();

  public override void Spawned()
  {
    NetworkedStructRef.Name = "John Conner";
  }
}

네트워크 컬렉션

네트워크 컬렉션 사용 방법에 대한 상세 내용은 Network Collections 페이지를 참고하세요.

C#

using Fusion;
using UnityEngine;

public class NetworkStructSampleCode : NetworkBehaviour
{
  public struct  NetworkStructExample : INetworkStruct
  {
    // Network Collections must be NOT be declared as auto-implemented properties,
    // and with only a default getter (the IL Weaver will replace the getter).
    [Networked, Capacity(16)]
    public NetworkDictionary<int, NetworkString<_4>> DictOfStrings => default;
  }

  // For convenience, declared Networked INetworkStructs can use the ref keyword,
  // which allows direct modification of members without needing to work with copies.
  [Networked]
  public ref NetworkStructExample NetworkedStructRef => ref MakeRef<NetworkStructExample>();

  public override void Spawned()
  {
    NetworkedStructRef.DictOfStrings.Set(1, "One");
    NetworkedStructRef.DictOfStrings.Set(4, "Four");

    Debug.Log($"Values Set: " +
              $"1:{NetworkedStructRef.DictOfStrings.Get(1)} " +
              $"4:{NetworkedStructRef.DictOfStrings[4]}");
  }
}

Fusion 객체 및 ID 타입

INetworkStruct는 ID로 Fusion 객체를 확인할 수 없지만(관련 NetworkRunner를 인식하지 않음), 이러한 ID를 저장할 수 있습니다. 이러한 참조를 해결하려면 NetworkRunner 인스턴스가 필요하므로 NetworkBehavior에서 참조를 찾아야 합니다.

C#

using Fusion;
using UnityEngine;

public class NetworkStructSampleCode : NetworkBehaviour
{
  public struct NetworkStructExample : INetworkStruct
  {
    // Fusion Object and Ref ID types are backed by integers,
    // so they are blittable and can be used as basic fields.
    public NetworkId          NetworkIdField;
    public NetworkBehaviourId NetworkBehaviourIdField;
    public PlayerRef          PlayerRefField;
  }

  [Networked]
  public ref NetworkStructExample NetworkedStructRef => ref MakeRef<NetworkStructExample>();


  public override void Spawned()
  {
    // Capture this NetworkBehaviour's Id.
    NetworkedStructRef.NetworkBehaviourIdField = this;
  }

  public override unsafe void FixedUpdateNetwork()
  {
    // Look up the NetworkObject on the Runner using the networked ID.
    Runner.TryFindBehaviour(NetworkedStructRef.NetworkBehaviourIdField, out var nb);
    Debug.LogWarning($"NBID: {(nb == null ? "Null NB" : nb.Id)}");
  }
}

INetworkStruct 중첩

INetworkStruct를 구현하는 구조체들은 블릿 가능하므로, INetworkStruct 정의에서 필드로 사용할 수 있습니다.

C#

using Fusion;
using UnityEngine;

public class NetworkStructSampleCode : NetworkBehaviour
{
  public struct InnerStruct : INetworkStruct
  {
    public int IntField;
  }

  public struct OuterStruct: INetworkStruct
  {
    public InnerStruct Inner;
  }

  [Networked]
  public ref OuterStruct Outer => ref MakeRef<OuterStruct>();
}

중첩된 INetworkStructs가 있는 OnChanged

중첩된 INetworkStructs에 대한 OnChanged은 전체 구조체의 변화를 감지하며 개별 값은 변경 사항을 모니터링할 수 없습니다. 개별 필드/속성에 대한 콜백이 필요한 경우 NetworkBehaviour의 해당 변수를 고유한 네트워크 속성으로 유지하세요.

C#

using Fusion;
using UnityEngine;

public class NetworkStructSampleCode : NetworkBehaviour
{

  public struct NetworkStructExample : INetworkStruct
  {
    public NetworkBool NetworkBool;
  }

  [Networked(OnChanged = nameof(OnNetworkStructChanged))]
  public ref NetworkStructExample NetworkedStructRef => ref MakeRef<NetworkStructExample>();

  // Note that OnChanged monitors any changes to the ENTIRE INetworkStruct,
  // so this callback will be triggered by ANY changes to the struct.
  public static void OnNetworkStructChanged(Changed<NetworkStructSampleCode> changed)
  {
    Debug.LogWarning($"Bool changed {changed.Behaviour.NetworkedStructRef.NetworkBool}");
  }

  public override unsafe void FixedUpdateNetwork()
  {
    // Toggle the nested bool value every tick, to trigger the OnChanged callback.
    NetworkedStructRef.PrimitiveBool = !NetworkedStructRef.NetworkBool;
  }
}

고정 크기 버퍼 (Unsafe)

안전하지 않은 고정 크기 버퍼는 메모리 공간 및 정렬이 엄격하게 정의되어 있기 때문에 유효합니다.

C#

public struct NetworkStructExample : INetworkStruct
{
  // Fixed is allowed, and can be used for advanced custom unsafe handling.
  public unsafe fixed byte FixedArray[32];
}

Back to top