INetworkStruct

INetworkStruct は、Fusion が Networked Properties と RPC のメソッドで使用できる構造体を定義しています。

ユーザー定義の INetworkStruct は以下のものでなければなりません。

struct 型であること。
INetworkStruct インターフェースを実装していること。
blittableであること。

これらの構造体は、他の INetworkStructs の中にフィールドとしてネストすることもできます。

Blittable 要件

INetworkStruct は Blittable でなければなりません。つまり、マネージコンテキストとアンマネージコンテキストの両方で絶対的なメモリフットプリントがあります。このため、field のメンバーは、以下であってはなりません：

任意の参照型
string または char (代わりに NetworkString を使用します)
bool (代わりに NetworkBool を使用)。

.Netのblittable型について詳しくはこちら

使用可能なフィールドタイプ

フィールドのメンバーは、構造体のメモリフットプリントとアライメントに直接影響するため、ブリタブル型でなければなりません。自動実装でないプロパティメンバーとメソッドメンバーは、メモリレイアウトに影響しないので、これらの型に制限されません。

安全なフィールドタイプには以下のものがあります：

Blittable primitives
- byte, sbyte
- short, int, long
- ushort, uint, ulong
- float, double
Blittable Unityの構造タイプ
- Vector2, Vector3, Vector4
- Quaternion
- Matrix4x4
- Vector2Int, Vector3Int
- BoundingSphere
- Bounds
- Rect
- BoundsInt
- RectInt
- Color, Color32
Enum
システム 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 Collections
最大長を [Capacity] 属性で指定する（デフォルトは1です）NetworkArray<T> 。
[Capacity] 属性を使用して最大 Count を設定することができる NetworkDictionary<K, V> 。
最大 Count を [Capacity] 属性を使用して設定するNetworkLinkedList<T>。
NetworkString<_size>
固定サイズのバッファ (unsafe: 例: fixed int MyArray[32])

使用法

ネットワークプロパティとしての INetworkStruct

構造体は値型であることに注意してください。利便性を高めるために、Networked Properties は ref キーワードを使用することができます。これは、コピーを操作することなく、プロパティのメンバを直接変更することができます。

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値タイプ

非フロートのBlittableプリミティブは、基本フィールドとして宣言するだけです。追加のコーディングやアトリビュートは必要ありません。float 型、または float ベースの Unity 構造体（Vector3 など）については、Float Types のセクションを参照してください。

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;
  }

フロート型

フロート型(プリミティブとフロートをラップするUnityの一般的なフロートベース型)はフィールドとして使用することができます。しかし、フィールドとして使用した場合、Fusion ILWeaverによる圧縮処理は行われません。

これらのフロート型を自動的に圧縮するには、デフォルトの実装を持つプロパティに [Networked] 属性を使用します。FusionのILWeaverは、圧縮処理で実装を置き換えます。

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はblittableではないので、bool型はフィールドに安全に使用することができません。Fusion は bool と互換性のある NetworkBool 型を提供しており、bool プロパティよりも少ないコードで実装でき、blittable なプロパティです。

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とCharの型はblittableではないので、string型をフィールドに安全に使用することはできませんが、自動実装でないプロパティには使用することができます。

Fusion では、[NetworkString<_size>] (~~~/manual/network-collections#networkstring_lt_size_) 型を提供しており、 string と同じように使用することができます。これにより、割り当てが少なくなり、パフォーマンスが向上し、string プロパティよりも実装に必要なコードが少なくて済みます。

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";
  }
}

ネットワークコレクション

ネットワークコレクションの使い方については、ネットワークコレクションのページを参照してください。

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 は Fusion オブジェクトの ID を解決できませんが（関連する NetworkRunner を認識しない）、ID を保存することはできます。NetworkRunner のインスタンスは、これらの検索を解決する必要があるため、参照の検索は NetworkBehaviour の中で行う必要があります。

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.ToString())}");
  }
}

INetworkStruct のネスト

INetworkStruct を実装した構造体は blittable なので、他の INetworkStruct 定義の内部でフィールドとして使用することができます。

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 コールバックは、構造体全体のあらゆる変更を検出し、個々の値の変更を監視することはできません。個々のフィールドやプロパティにコールバックが必要な場合は、その変数を独自のNetworked PropertyとしてNetworkBehaviourに保持してください。

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固定サイズバッファは、メモリフットプリントとアライメントが厳密に定義されているため、有効です。

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

使用可能なフィールドタイプ

使用法

ネットワークプロパティとしての INetworkStruct
シンプルなBlittable値タイプ
フロート型
ブール
文字列
ネットワークコレクション
Fusion オブジェクトと ID タイプ
INetworkStruct のネスト
ネストされた INetworkStructs の OnChanged
固定サイズバッファ（安全でないもの）