This document is about: FUSION 2

SWITCH TO

FUSION 1 FUSION 2

Data Sync Helpers

Fusion XR原型模組

資料同步協助工具原則

資料同步協助工具附加元件提供一些協助工具類別，其針對有特殊需要的使用案例來簡化同步資料。

一般舉例而言，目標使用案例是：

定期發送少量資料，延遲加入者也需要其完整清單：以3D筆來繪製點，並且也允許延遲加入者有完整的繪圖
定期發送少量資料，而不需要保存完整的清單，但是可以在下一次資料接收之前被發送幾次：舉例而言，可用於以魔杖在空中畫一個暫時的線，或是針對一支槍，確保所有子彈都已發射
同步一個大的單次拍攝資料：將應用程式中拍攝的照片發送到其他使用者

環緩衝錯過少量同步行為類別

概述

如同拋射物基礎中所見 - 拋射物資料緩衝，一個環緩衝是一個好的方法來儲存一系列小的資料，就算是接收到第一個資料之前也可以發送幾個資料：環緩衝邏輯將保存幾個這些資料，而不會錯過資料。

然而，對於延遲加入者也需要存取的資訊（繪圖點等等），單獨的環緩衝將逐漸錯過通過它的資料。

RingBufferLossLessSyncBehaviour<TEntry>類別解決這個問題：

在傳統的環緩衝之外，底層存儲持續追蹤被共享的資料的完整計數，
當延遲加入者抵達時，他們因此可以了解他們錯過的資料，
如果這發生，這個類別將透過RPC來發送一個訊息到其他使用者（該類別將負責找到能夠發送資料的使用者，就算原始作者已經離開房間），
擁有錯過資料的其他使用者將透過Runner.SendReliableDataToPlayer方法來共享它。

在後台，這個類別相依於NetworkArray<byte>來儲存環緩衝資料（開始索引，下一個寫入需要），資料計數總量，及實際資料：

Fusion Industries Addon Data Sync Helpers NetworkArray

錯過的資料可能發生在環緩衝填入過快的情況，也可能是延遲加入者的情況，這是發送請求錯過的資料範圍的訊息的情況：

Fusion Industries Addon Data Sync Helpers NetworkArray 2

RingBufferLosslessSyncBehaviour<TEntry>是一個泛型NetworkBehaviour子類別，其需要作為子類別以指定TEntry。
TEntry應該是一個架構，代表要共享的資料。其執行RingBuffer.IRingBufferEntry介面以定義它轉換為一個位元組陣列(AsByteArray)的方式以及從一個位元組陣列(FillFromBytes)載入其內容的方式。
為了幫助執行這些方法，SerializationTools含有靜態方法以協助。

用途

新增資料

作為狀態授權，使用AddEntry(TEntry)以在已同步資料中新增一個物件。

覆寫回調方法

舉例而言，可以覆寫某些回調，以在即時資料接收，或完全復原錯過的資料時做出回應。

    // newEntries will contain the new TEntry structs detected in the last data update.The received data at start might not be long enough to form an entry (for late joiners first ring reception, ...), those additional bytes are stored in newPaddingStartBytes
    public virtual void OnNewEntries(byte[] newPaddingStartBytes, TEntry[] newEntries) { }

    // OnDataLoss will warn of data loss: no need to handle the loss, the request are sent automatically
    public virtual void OnDataloss(RingBuffer.LossRange lossRange) { }

    // Called when one loss is restored
    protected virtual void OnLossRestored(LossRequest request, byte[] receivedData) { }

    // When all loss in the total data remains. SplitCompleteData() can be called to retrieve all the TEntry
    protected virtual void OnNoLossRemaining() { }

    // When a loss is permanent (no one having the data is still in the room
    public virtual void OnNoAnswerForALossRequest(LossRequest request) { }

執行I環緩衝輸入

SerializationTools類別簡化了執行IRingBufferEntry的預期的方法。

為了代表一個架構為一個位元組陣列(AsByteArray)，簡單地傳送所有其基礎已支援類型（浮點、向量3、位元組、四元數、整數）到SerializationTools.AsByteArray，並且它將傳回一個位元組陣列。
舉例而言，針對以下架構：

    [System.Serializable]
    public struct DrawPoint : RingBuffer.IRingBufferEntry
    {
        public Vector3 localPosition;
        public float drawPressure;
        /* ... */
    }

這個執行方式AsByteArray將是最佳的：

    public byte[] AsByteArray => SerializationTools.AsByteArray(localPosition, drawPressure);

為了載入一個位元組陣列到一個架構之中，SerializationTools.Unserialize方法處理基礎已支援類型的取消序列化（浮點、向量3、位元組、四元數、整數），同時追蹤在陣列中的位置。

所以針對某些範例架構，這個FillFromBytes的執行方式將載入以先前定義的AsByteArray序列化的資料：

    public void FillFromBytes(byte[] entryBytes)
    {
        int unserializePosition = 0;
        SerializationTools.Unserialize(entryBytes, ref unserializePosition, out localPosition);
        SerializationTools.Unserialize(entryBytes, ref unserializePosition, out drawPressure);
    }

環緩衝同步行為類別

RingBufferSyncBehaviour是RingBufferLossLessSyncBehaviour的上層類別，其處理環緩衝的方面，而不用訊息來復原沒有儲存在底層環緩衝的資料。

它可以用作為RingBufferLossLessSyncBehaviour，不需要任何與錯過復原相關的東西（仍然偵測錯過，但在這裡不是可復原的）。

這個類別可以用於傳統環緩衝的需要（槍拋射物等等）。

環緩衝索引追蹤本身是透過一個名為Ringbuffer的架構來完成的，該架構更新啟動索引及下一個寫入索引，並且可以在提供時新增資料／更新實際資料存儲。

串流同步行為類別

概述

StreamSynchedBehaviour允許發送任意的資料區塊到其他玩家。
這個協助工具使用Fusion SendReliableDataToPlayer API。
4個部分的金鑰用於以這個API來識別一個訊息，其第一個部分用於儲存物件ID，這樣在房間內的多個物件可以發送及接收資料，而不必擔心發送它們到錯誤的物件。

StreamSynchedBehaviour主要特定點用於處理延遲加入者案例：如何發送資料到錯過最初傳輸的使用者，特別是如果在共享模式中狀態授權已經離開房間的情況。

由延遲加入者發送的一個RPC訊息來完成這件事，其向狀態授權，或如果狀態授權已經離開房間則向另一個玩家請求接收完整快取。

用途

發送資料

以要發送的資料來調用Send(byte[] data)來發送資料。
以區塊的方式接收及儲存資料，如果需要的話子類別需要合併它們。

覆寫回調方法

舉例而言，有些回調可以被覆寫，以對即時資料接收或對錯過資料的復原作出回應。

    // Provides the 0-1 download progress of a currently received chunk of data
    protected virtual void OnDataProgress(float progress) { }
    // Called on complete reception of a chunk of data
    protected virtual void OnNewBytes(byte[] newData) { }
    // Called to know the client is a late joiner, waiting for data
    protected virtual void OnLateJoinersWaitingForData() { }
    // Called if missing data for a late joiner are unavailable anywhere
    protected virtual void OnMissingData() { }

示範

協助工具有一些範例類別，展示了如何將它們做成子類別：

TestStreamSynchedBehaviour針對StreamingSyncBehaviour
TestLosslessRingBufferSync針對RingBufferLossLessSyncBehaviour
TestRingBufferSync針對RingBufferSyncBehaviour

DemoStreaminghelpers場景含有StreamingSyncBehaviour的TestStreamSynchedBehaviour執行方式。
場景含有這些元件的2個元件，以展示資料被發送到正確的StreamSynchedBehaviour物件。
透過按下 發送隨機資料 按鈕，發送資料的區塊到已連線使用者，並且將顯示在 所有資料 屬性中。
延遲加入者也將可使用它。

DemoRingBuffer含有TestLosslessRingBufferSync及TestRingBufferSync，以展示沒有錯過的與常規的環緩衝。
在環物件上，透過按下 新增單一輸入項目（這將把檢查器 單一輸入項目以新增 欄位中說明的輸入項目新增到資料中）、新增隨機輸入項目 或 新增多個隨機輸入項目，將新增輸入項目到檢查器中的輸入項目欄位。
它們將顯示在已連線客戶端及延遲加入者客戶端上。
因為記錄水平包含 資料錯過復原，可以在主控台看見關於資料錯過復原的訊息。
延遲加入者將系統性地觸發該訊息，並且 新增多個隨機輸入項目 調用故意過快地填入環緩衝，這樣將顯示該訊息。
在結束時，所有使用者將有相同的輸入項目。

下載

這個附加元件的最新版本被包含在附加元件專案之中

已支援拓撲

共享模式

請注意，StreamingSyncBehaviour也可以用於主機端拓撲。

更改記錄

版本2.0.0：第一個版本

資料同步協助工具原則
環緩衝錯過少量同步行為類別

概述
用途

環緩衝同步行為類別
串流同步行為類別

概述
用途

示範
下載
已支援拓撲
更改記錄