네트워크 속성(Networked Properties)

개요

네트워크 속성은 NetworkBehaviour를 상속받은 클래스의 속성으로, 관련된 네트워크 객체의 네트워크 상태를 정의합니다.

네트워크 속성을 정의하려면, NetworkBehaviour를 상속받은 클래스의 자동 속성(auto-property)에 [Networked] 속성을 추가하면 됩니다. 이 속성은 Fusion에게 해당 속성의 getter와 setter를 네트워크 객체의 상태 메모리 버퍼에 자동으로 연결하도록 IL 코드를 생성하라는 명령을 전달합니다.

중요: 직접 속성을 구현하지 마세요! 자동 속성(auto-property)으로 남겨두세요. 특수한 속성 처리가 필요한 경우, 별도의 속성으로 래핑 해야 합니다.

public class PlayerBehaviour : NetworkBehaviour
{
  [Networked] public float Health { get; set; }
}

네트워크 속성의 변경은 일반적으로 FixedUpdateNetwork()에서 이루어져야 하며, 이는 클라이언트 예측과의 호환성을 보장하며, 복제된 변경 사항이 틱(Tick) 단위로 정확하게 처리됩니다.

참고: 공유 모드에서는 Update()나 FixedUpdate() 같은 다른 타이밍 섹션에서도 네트워크 속성을 수정할 수 있는 경우가 있습니다.

public override void FixedUpdateNetwork()
{
    Health += Runner.DeltaTime * HealthRegen;
}

지원되는 타입

Fusion에서 지원되는 타입은 다음과 같습니다:

Blittable 기본 타입
byte	sbyte	short (Int16)	int (Int32)	long (Int64)
ushort (UInt16)	uint (UInt32)	ulong (UInt64)	float (Single)	double
Blittable 유니티 구조체 타입
Vector2	Vector3	Vector4	Quaternion	Matrix4x4
Vector2Int	Vector3Int	BoundingSphere	Bounds	Rect
BoundsInt	RectInt	Color	Color32
시스템 및 사용자 정의 Blittable 타입
열거형(Enums)	System.Types (예: System.Guid)	구조체(Structs)	기타 INetworkStructs
Fusion 정의된 INetworkStructs
NetworkString<IFixedStorage>	NetworkBool	Ptr	Angle	TickTimer
PlayerRef	PlayerRefSet	SceneRef	NetworkId	NetworkObjectGuid
NetworkObjectHeader	NetworkPrefabRef	NetworkPrefabId	NetworkRNG	NetworkButtons
BitSet64	BitSet128	BitSet192	BitSet256
IFixedStorage (_2, _4, _8, _16, _32, _64, _128, _256, _512)
네트워크 컬렉션(Network collections)
NetworkArray<T>: `[Capacity]` 속성으로 최대 `Length` 설정 (기본값: 1)	NetworkDictionary<K, V>: `[Capacity]`로 최대 `Count` 설정	NetworkLinkedList<T>: `Capacity` 속성으로 최대 `Count` 설정	NetworkString<_size>: 사전 정의된 `IFixedStorage` 타입 사용 (예: `_32`)
고정 크기 버퍼(Fixed-Size Buffers)
*unsafe*: 예) `fixed int MyArray[32]`

네트워크 Fusion 객체 타입

NetworkObject와 NetworkBehaviour 참조는 NetworkBehaviour의 네트워크 속성(Networked Properties)으로 사용할 수 있습니다.
(참고: 참조는 INetworkStruct에서 유효하지 않습니다.)

내부적으로, 이러한 네트워크 속성으로 사용된 NetworkObject와 NetworkBehaviour 참조는 각각 NetworkId와 NetworkBehaviourId 값으로 변환됩니다.

네트워크 Fusion 객체 타입을 참조하세요.

기본값 설정

[Networked] 속성에 대해 기본값을 설정할 수 있습니다.

일반 타입(Common Types)

대부분의 일반적인 타입은 간단한 할당으로 기본값을 설정할 수 있습니다.

public class PlayerBehaviour : NetworkBehaviour
{
  [Networked] public float Health { get; set; } = 100;
  [Networked] public NetworkObject DefaultNetworkObject { get; set; } = GameObject.FindGameObjectWithTag("Foo").GetComponent<NetworkObject>();
}

컬렉션

네트워크 컬렉션(Network Collections)인 NetworkArray<T>, NetworkDictionary<K, V>, NetworkLinkedList<T>, NetworkString<_size> 등은 특별한 구문이 필요합니다. 자세한 내용은 해당 페이지를 참조하세요.

용량

[Capacity] 속성은 NetworkArray, NetworkDictionary, NetworkLinkedList, NetworkString, 문자열 등의 최대 크기를 정의하는 데 사용됩니다.

public class MyNetworkBehaviour : NetworkBehaviour
{
  [Networked, Capacity(14)]
  string MyString { get; set; }

  [Networked, Capacity(8)]
  NetworkArray<byte> MyArray { get; }
}

Ref 및 Ptr

적절한 생성자를 사용하여 참조 및 포인터의 기본값을 설정할 수 있습니다.

[Networked] public ref Byte Prop => ref MakeRef<Byte>(123);
[Networked] public Byte* Prop => MakePtr<Byte>(123);

변경 감지

변경 감지에 대한 자세한 내용은 변경 감지을 참조하세요.

고급 불리언 처리

게임 네트워킹에서는 값의 변화가 감지되지 않을 수 있는 경우(예: 연속화 전에 값이 참으로 뒤집혔다가 다시 거짓으로 바뀌거나, 토글이 도태, 데이터 손실, 공유 모드 스퀴싱, 플레이어 늦게 합류하는 등)를 위해 종종 불 대신 인트를 사용하는 것이 권장됩니다.

이를 위한 한 가지 전략은 int 부호 값을 사용하여 불 상태를 인코딩하고, 절댓값을 사용하여 값이 몇 번이나 변경되었는지 또는 마지막으로 변경된 시점과 같은 추가 정보를 저장하는 것입니다.

public class MyNetworkBehaviour : NetworkBehaviour
{
  // This is the backing value for our virtual bool.
  [Networked] int _intToggle { get; set; }
  
    
  // This property will automatically encode the change count into the backing value,
  // while still acting like a normal bool.
  private bool CountToggle 
  {
    // This assumes 0 to mean false, <= can be used to make 0 indicate true.
    get => _intToggle > 0;
    // Every call to set increments the absolute value
    // and sets the sign to negative for false, positive for true.
    set =>
      _intToggle = _intToggle >= 0 ? 
        value ?   _intToggle + 1 : -(_intToggle + 1) :
        value ? -(_intToggle - 1):   _intToggle - 1;
  }

  private int toggleCount => _intToggle >= 0 ? _intToggle : -_intToggle;
}

public class MyNetworkBehaviour : NetworkBehaviour
{
  // This is the backing value for our virtual bool.
  [Networked] int _intToggle { get; set; }

  // This property will automatically encode the current tick into the backing value,
  // while still acting like a normal bool.
  private bool TickToggle 
  {
    get => _intToggle > 0;
    set => _intToggle = value ? Runner.Tick : -Runner.Tick;
  }

  private Tick toggleLastChangedTick => _intToggle >= 0 ? _intToggle : -_intToggle;

}

보간

스냅샷과 보간을 참조하세요.

제네릭

NetworkBehaviour를 상속받는 템플릿 클래스를 생성할 수 있습니다. 이러한 클래스는 [Networked] 속성을 포함할 수도 있습니다.

// This is VALID
class ValidGenericClass_With_NonGenericProperty<T> : NetworkBehaviour {
    [Networked] public int Prop { get; set; }
}

그러나 <T> 타입의 제네릭 [Networked] 속성을 가지는 것은 불가능합니다.

// This is INVALID
class InValidGenericClass_With_GenericProperty<T> : NetworkBehaviour {
    [Networked] public T Prop { get; set; }
}

개요
지원되는 타입
네트워크 Fusion 객체 타입
기본값 설정
용량
Ref 및 Ptr
변경 감지
고급 불리언 처리
보간
제네릭