This document is about: FUSION 2
SWITCH TO

Network Collections

概要

Fusionは、ネットワークプロパティに使用できる、構造体ベースのコレクションタイプを提供します。

  • NetworkArray<T>
  • NetworkDictionary<K, V>
  • NetworkLinkedList<T>
  • NetworkString<Size>

これらのコレクションは構造体であり、リファレンス型ではないことに注意してください。これらのコレクションとC#コレクションの間には、C#での細かい使い方の違いがあります (Usage In INetworkStructsでの使い方を参照してください)。

使用できるT/K/Vタイプは以下の通りです。

  • プリミティブ
    • byte、sbyte
    • Int16、Int32、Int64
    • UInt16、UInt32、UInt64
    • float
    • double
  • Unity構造体タイプ (ILWeaver.csで定義)
    • Vector2、Vector3、Vector4
    • Quaternion
    • Matrix4x4
    • Vector2Int、Vector3Int
    • BoundingSphere
    • Bounds
    • Rect
    • BoundsInt
    • RectInt
    • Color、Color32
  • System.Guid
  • ユーザー定義によるINetworkStructs
  • Fusion定義によるINetworkStructs
    • NetworkString<IFixedStorage>
    • NetworkBool
    • Ptr
    • Angle
    • BitSet64, BitSet128, BitSet192, BitSet256
    • PlayerRefSet
    • NetworkId
    • NetworkButtons
    • NetworkRNG
    • NetworkObjectGuid
    • NetworkPrefabRef
    • NetworkObjectHeader
    • NetworkPrefabId
    • SceneRef
    • TickTimer
    • IFixedStorage (_2, _4, _8, _16, _32, _64, _128, _256, _512)

宣言

NetworkArrayNetworkDictionaryNetworkLinkedList[Networked] 属性を持つプロパティとして定義する必要があります。[Networked] 属性は ILWeaver にこれらのコレクションを関連付けられた NetworkRunnerSimultation インスタンスのバッキングメモリに接続するプロパティコードを生成するように指示します。

[Capacity] 属性は要素の最大数を指定します。使用量に関係なく、この数だけメモリが割り当てられるので、予想される最大数の要素をカバーするのに十分な最小の数を選択してください。値が変化しない限り、要素はネットワークトラフィックを生成しません。

C#

// A basic Network Collection declaration
[Networked, Capacity(4)]
NetworkArray<int> NetArray => default;

初期化

NetworkArrayNetworkDictionaryNetworkLinkedListNetworkBehaviour の Networked Property として宣言されている場合、 MakeInitializer() を使用して初期値を定義することができます。 .

C#

[Networked]
[Capacity(4)] // Sets the fixed capacity of the collection
NetworkArray<int> NetArray { get; }
  // Optional initialization
  = MakeInitializer(new int[] { 0, 1, 2, 3 });

[Networked, Capacity(4)]
NetworkLinkedList<int> NetLList { get; }
  // Optional initialization
  = MakeInitializer(new int[] { 0, 1, 2, 3 });

[Networked, Capacity(2)]
NetworkDictionary<int, int> NetDict { get; }
  // Optional initialization
  = MakeInitializer(new Dictionary<int, int> { { 0, 0 }, { 1, 1 } });

NetworkArray<T>

NetworkArrayは、C#の配列に代わる構造体で、Fusionのネットワークプロパティとして使用できます。C# の配列と完全に同じではありませんが、NetworkArrayIEnumerable コレクションで、値の取得や設定、他のコレクションへのコピーや他のコレクションからのコピーのメソッドを持っています。

主なメソッド:

  • Get(int index)
  • Set(int, T)

C#

public class CollectionTestsArray : NetworkBehaviour
{
  [Networked]
  [Capacity(4)] // Sets the fixed capacity of the collection
  NetworkArray<NetworkString<_32>> NetArray { get; } =
    MakeInitializer(new NetworkString<_32>[] { "#0", "#1", "#2", "#3" });

  public override void FixedUpdateNetwork()
  {
    NetArray.Set(0, "Zero");
    NetArray.Set(1, "One");
    NetArray.Set(2, "Two");

    // This is invalid with a NetworkDictionary property, use Set() instead.
    // NetArray[3] = "Three";

    NetArray.Set(0, NetArray[0].ToUpper());
    NetArray.Set(1, NetArray.Get(1).ToLower());
    NetArray.Set(2, default);

    for (int i = 0; i < NetArray.Length; ++i)
    {
      Debug.Log($"{i}: '{NetArray[i]}''");
    }
  }
}

NetworkDictionary<K, V>

NetworkDictionary は、C# の Dictionary に代わる構造体で、Fusion のNetworked Propertyとして使用することができます。 完全な IDictionary の実装ではありませんが、主要なメンバはすべて使用可能であり、Dictionary と類似しています。

主なメソッドとプロパティ:

  • Clear()
  • Add(K, V)
  • Remove(k)
  • ContainsKey(K)
  • ContainsValue(V)
  • Get(K)
  • Set(K, V)
  • this[K]
  • Capacity
  • Count

C#

public class NetworkDictionaryExample : NetworkBehaviour
{  
  [Networked]
  [Capacity(4)] // Sets the fixed capacity of the collection
  [UnitySerializeField] // Show this private property in the inspector.
  private NetworkDictionary<int, NetworkString<_32>> NetDict => default;

  public override void FixedUpdateNetwork()
  {
    NetDict.Clear();
    NetDict.Add(0, "Zero");
    NetDict.Add(2, "Two");
    NetDict.Add(5, "Five");

    // Setting values with the indexer are not valid, this is one of the cases
    // where the struct based NetworkDictionary differs in usage from Dictionary.
    // NetDict[0] = "Foo"; // this is not valid.

    if (NetDict.ContainsKey(0))
    {
      NetDict.Set(0, NetDict[0].ToUpper());
    }

    if (NetDict.TryGet(5, out var value))
    {
      NetDict.Set(5, value.ToLower());
    }

    NetDict.Remove(2);

    foreach(var kvp in NetDict)
    {
      Debug.Log($"{NetDict.Count}/{NetDict.Capacity} Key:{kvp.Key} Value:{kvp.Value}");
    }
  }
}

NetworkLinkedList<T>

NetworkLinkedListは、NetworkArray に代わる構造体で、容量のサブセットを使用することができます。追加されたアイテムは、バッキングデータの空きスロットに追加されます。アイテムが削除されると、バッキング配列データはメモリ内の他の要素を移動しません。代わりに、コレクションは構造体の一部として要素の順序に関するデータを格納し、列挙子とインデクサはバッキング配列に存在する順序ではなく、追加された順序で要素を返します。

C#

public class NetworkLinkedListExample : NetworkBehaviour
{
  [Networked]
  [Capacity(4)] // Sets the fixed capacity of the collection
  [UnitySerializeField] // Show this private property in the inspector.
  private NetworkLinkedList<NetworkString<_32>> NetList { get; }
    = MakeInitializer(new NetworkString<_32>[] { "Zero", "One", "Two", "Four"});

  public override void Spawned()
  {
    // Remove the second entry, leaving one open capacity.
    NetList.Remove("One");

    // Find an entry by value
    NetList.Set(NetList.IndexOf("Two"), "TWO");

    // Add a new entry. In memory it backfills the now open memory position.
    NetList.Add("Five");

    // The indexed order however remains in sequence,
    // so only the changed memory position is dirty and networked.
    Debug.Log($"List {NetList.Count}/{NetList.Capacity}" +
      $"0:'{NetList[0]}' 1:'{NetList[1]}' 2:'{NetList[2]} 3:'{NetList[3]}'");
  }
}

NetworkString<Size>

NetworkString は、文字列データ用の固定サイズのコレクションです。サイズは定義済みの IFixedStorage 型のいずれかを指定できます、 X はストレージ構造体のサイズです。例えば _32 であれば、 uint[32] でバックアップされ、32 文字までの文字列を格納できます。

C#

public class NetworkStringExample : NetworkBehaviour
{
  [Networked]
  public NetworkString<_16> NetString { get; set; }

  public override void FixedUpdateNetwork()
  {
    if (Runner.IsServer) {
      NetString = System.IO.Path.GetRandomFileName();
    }
  }
}

INetworkStructsでの使い方

INetworkStructである Networked Property の値を変更する場合は、次のいずれかを必ず実行してください。

  • INetworkStruct のコピーを操作し、変更したコピーを Networked Property に適用する、または、
  • Networked Property を ref として定義する。ネットワーク・プロパティが ref として宣言されている場合は、参照を直接変更できるため、値をコピーする必要はありません。

INetworkStruct型のネットワーク・プロパティは初期化することができま す(例として、以下のコードを参照してください)。

INetworkStructs のネットワーク化されたコレクションをネットワーク化されたプロパティとして使用:

C#

public class NetworkDictionaryTest : NetworkBehaviour
{
  [System.Serializable]
  struct NetworkStruct : INetworkStruct
  {
    [Networked, Capacity(16)]
    public NetworkDictionary<int, int> NestedDict => default;

    // NetworkString is a normal struct, so it doesn't require any Fusion attributes
    public NetworkString<_16> NestedString;

    // Define default initialization as a property if needed.
    public static NetworkStruct Defaults
    {
      get
      {
        var result = new NetworkStruct();
        result.NestedDict.Add(0, 0);
        result.NestedString = "Initialized";
        return result;
      }
    }
  }

  // Property declared normally as a value type
  [Networked]
  [UnitySerializeField]
  private NetworkStruct NestedStruct { get; set; } = NetworkStruct.Defaults;

  public void ModifyValues()
  {
    // NestedStruct is a value type, so modifications need to be performed on a copy,
    // and the modified result must be applied back to the property.
    var copy = NestedStruct;
    copy.NestedDict.Add(copy.NestedDict.Count, default);
    copy.NestedString = System.IO.Path.GetRandomFileName();
    NestedStruct = copy;
  }
}

これらのネットワーク化されたコレクションを INetworkStructリファレンス ネットワーク化されたプロパティとして使用します:

C#

public class NetworkDictionaryTest : NetworkBehaviour
{
  [System.Serializable]
  struct NetworkStruct : INetworkStruct
  {
    [Networked, Capacity(16)]
    public NetworkDictionary<int, int> NestedDict => default;

    // NetworkString is a normal struct, so it doesn't require any Fusion attributes
    public NetworkString<_16> NestedString;

    public static NetworkStruct Defaults
    {
      get
      {
        var result = new NetworkStruct();
        result.NestedDict.Add(0, 0);
        result.NestedString = "Initialized";
        return result;
      }
    }
  }

  // Property declared as ref type, allowing direct modification of values
  [Networked]
  [UnitySerializeField]
  private ref NetworkStruct NestedStruct => ref MakeRef(NetworkStruct.Defaults);

  public void ModifyValues()
  {
    // NestedStruct was declared as a ref above, so modifications
    // may be made directly to the reference, without need for copies.
    NestedStruct.NestedDict.Add(NestedStruct.NestedDict.Count, default);
    NestedStruct.NestedString = System.IO.Path.GetRandomFileName();
  }
}
Back to top