This document is about: QUANTUM 3

SWITCH TO

QUANTUM 1 QUANTUM 2 QUANTUM 3

What's New

Quantum SDK現在是一個Unity套件

遷移到Unity套件使每個人的初始設定和升級都變得更加容易，並為未來透過Asset Store和/或UPM分發Quantum奠定了基礎。

QuantumGame（以前稱為quantum.code專案）的源現在位於Unity Assets資料夾中：Assets/QuantumUser/Simulation/。
Unity CodeGen步驟已被移除，所有程式碼生成現在都由Qtn/DSL CodeGen和Unity編輯器內部完成。
為了清理Unity整合，大量Quantum類型和指令碼已被移動、重命名和合併。在遷移過程中，指令碼GUID會被保留，以減少編譯錯誤的數量，對於帶有舊名稱的過時指令碼將提供QUANTUM_ENABLED_MIGRATION。
Unity/Odin屬性內容可以隨意使用。這包括[SerializeReference]和Odin特定的序列化擴展。仍然強烈不建議任何使用非確定性的Unity API。
新資產被賦予確定性的AssetGuid。這允許在不載入其內容的情況下收集所有可能的Quantum資產，從而大大加快了過程。
不再需要AssetBase：AssetObject已經是ScriptableObjects。這使得資產層次結構更加靈活，不再局限於僅適用於Unity屬性的部分擴展模型。
最低Unity版本增加到2021 LTS，以減少遺留程式碼的數量。

仍然可以編譯一個沒有Unity相依性的模擬dll，例如在.Net主控台應用程式或自訂伺服器外掛程式上運行。使用QuantumDotnetBuildSettings生成並編譯它。

有關SDK內容的詳細資訊，請參閱Quantum專案。

新的Quantum組建名稱

以下Quantum程式庫已重命名：

PhotonDeterministic.dll -> Quantum.Deterministic.dll
quantum.core.dll -> Quantum.Engine.dll
quantum.code.dll -> Quantum.Simulation.dll

輸入差量壓縮

預設下，輸入訊息現在是差量壓縮的，大大降低了整體頻寬。伺服器訊息的網路傳輸模式已更改為可靠的模式，其簡化了Quantum輸入協定。

原始輸入模式仍受支援，但預設下啟用差量壓縮。

重播還存儲差量壓縮的輸入，現在它要小得多。

新增和移除玩家的新協定

Quantum啟動協定已被修改，允許在運行時新增和移除玩家，而無需在開始時保留座位。

AddPlayer()和RemovePlayer()替換了SendPlayerData()方法。與SendPlayerData()不同，每個玩家槽只能發送一次AddPlayer()。

模擬可以透過ISignalOnPlayerAdded和ISignalOnPlayerRemoved訊號對新增和移除的玩家做出反應。

該視圖可以透過CallbackLocalPlayerAddConfirmed和OnLocalPlayerRemoveConfirmed來對新增的本機玩家槽做出反應，以及透過聽取OnLocalPlayerAddFailed及OnLocalPlayerRemoveFailed來對錯誤做出反應。

AddPlayer()在伺服器上有速率限制，不能接收垃圾郵件。

在整個API中，參數的措辭略有改變，以更好地區分玩家（PlayerRef）和玩家槽（本機玩家）。

Player總是指實際的全域玩家索引，而PlayerSlot總是指本機玩家槽，例如在從一個客戶端控制多個玩家時使用。如果只使用一個本機玩家槽，則它將是插槽0。

例如，輸入回調CallbackPollInput現在使用PlayerSlot屬性。QuantumGame.AddPlayer(Int32 playerSlot, RuntimePlayer data)顯式命名要標識為本機玩家槽的參數。

更多資訊請參閱玩家手冊

已預測命令

命令現在可以在下一個已預測幀上立即使用。這一個功能被請求已有一段時間了，現在有了新版本和改進的輸入協定，因此新增它是有意義的。

發送命令時，它們現在將被新增到下一個預測幀中，並在未驗證的幀中可用。實際已預測的刷新數應接近99.9%的準確率。

這使得命令的回應更為迅速，並能更快地反映遊戲遊玩的變化。

Webhooks

Webhooks是一種增強功能，可以透過自訂後端保護遊戲：房間創建、房間加入、RuntimePlayer、RuntimeConfig可以被後端使用HTTP請求以攔截和驗證。

Webhooks還允許直接從伺服器重播串流。

它們透過Photon儀表板啟動和設置。

有關更多資訊，請參閱Webhook線上API檔案。

Quantum 3應用程式帳號

Quantum 3應用程式需要在Photon儀表板上顯式創建Quantum 3應用程式帳號。

有關更多資訊，請閱讀Quantum Asteroids教程-專案設定教程。

Photon Realtime 5

Realtime的新主要版本包括.Net非同步擴展，以改進網路連線的編寫和處理。

請務必閱讀以下內容中的Photon Realtime版本資訊：

要啟動Photon客戶端連線並加入Photon房間，只需調用一個方法並awaited：

MatchmakingArguments connectionArguments = new MatchmakingArguments {
    PhotonSettings = PhotonServerSettings.Default.AppSettings,
    PluginName = "QuantumPlugin",
    MaxPlayers = 8,
    UserId = Guid.NewGuid().ToString(),
    NetworkClient = new RealtimeClient { ClientType = ClientAppType.Quantum }
};

RealtimeClient client = await MatchmakingExtensions.ConnectToRoomAsync(connectionArguments);

預設下，所有錯誤都作為例外狀況擲出。對非同步API的調用必須包裝在嘗試/捕捉區塊中。

有關Realtime擴展的更多資訊，請參閱Photon非同步擴展。

SessionRunner類別

QuantumRunner和SessionContainer已合併到Quantum Game專案中的SessionRunner類別中。它使用新的Photon Realtime 5程式庫。

Quantum遊戲階段可以在非同步和非非同步模式下啟動：

SessionRunner.Arguments sessionRunnerArguments = new SessionRunner.Arguments {
    RunnerFactory = QuantumRunnerUnityFactory.DefaultFactory,
    GameParameters = QuantumRunnerUnityFactory.CreateGameParameters,
    ClientId = client.UserId,
    RuntimeConfig = runtimeConfig,
    SessionConfig = QuantumDeterministicSessionConfigAsset.DefaultConfig,
    GameMode = DeterministicGameMode.Multiplayer,
    PlayerCount = 8,
    StartGameTimeoutInSeconds = 10,
    Communicator = new QuantumNetworkCommunicator(client),
};

QuantumRunner runner = (QuantumRunner)await SessionRunner.StartAsync(sessionRunnerArguments);

當Quantum啟動協定完成並且收到任何快照時，Awaiting啟動將恢復。

嘗試QuantumSampleConnection.unity場景，以最簡單的方式連線並啟動線上Quantum模擬。

新的SDK範例

新的SDK附帶了一個簡單的灰色框Asteroids遊戲範例，可以與QuantumHub一起安裝。

新的演示選單

新的演示選單取代了Quantum 2.1中的範例大廳選單。它已經獲得了圖形化升級（在Unity.UI中），並實作了兩種簡單的線上模式：隨機對戰配對和派對程式碼共享。

演示選單程式碼和預製件與SDK一起以unitypackage的形式分發，可以使用QuantumHub教程和範例部分進行安裝。

它被設計為可擴展的，可以處理連線邏輯的複雜性。這些設計目標相互競爭，而這種解決方案試圖合理地平衡它們。選單實作和預製件的一些部分也被Fusion等其他SDK使用。

演示場景使用TextMeshPro。首次打開演示場景時，將顯示TMP安裝快顯視窗。

即使停用TMP，Quantum選單指令碼也會編譯：當找到TMP Unity套件（com.unity.textmeshpro）時，Quantum.Unity組件定義將設定QUANTUM_ENABLE_TEXTMESHPRO。

有關如何自訂選單的資訊，請閱讀此處：範例選單自訂

RuntimeConfig及RuntimePlayer Json序列化

這些檔案的手動序列化已被Json取代。設置仍然透過Quantum協定發送，但作為壓縮的Json字串。

最初的序列化總是需要手動維護，這很麻煩，也是錯誤的來源。此外，當透過webhooks的HTTP請求來傳遞設置時，接收後端需要原始C#程式碼才能正確反序列化。

SerializeUserData()方法現已棄用。

要將設置序列化為位元組數組，QuantumGame.RuntimePlayerSerializer是必需的，在使用SessionRunner.Arguments啟動運行器時設定它，且通常設定為預設的Quantum Json序列化器QuantumJsonSerializer。

var runtimeConfig = new RuntimeConfig();
var runtimeConfigBinary = RuntimePlayer.ToByteArray(runtimeConfig, new QuantumJsonSerializer());
var runtimeConfigOther = RuntimePlayer.FromByteArray(runtimeConfigBinary, new QuantumJsonSerializer());
// make sure to check if runtimeConfig and runtimeConfigOther are equal to validate the json serialization

序列化二進位RuntimePlayer（或命令）的最大大小為24 kB。此外，如果多個客戶端以這種管道發送大塊資料，並且它們不適合一條輸入訊息，則伺服器將在連續的刷新中接受它們。

Quantum Hub

當找不到關鍵設置檔時，Quantum Hub會彈出。Fusion SDK已經證明，使用Hub視窗是安裝和生成使用者檔案（不包含在套件中）最方便的方法。此設定只需要完成一次，生成的檔案與專案的其餘部分一起保存在版本控制中。

Quantum CodeDoc檢查器

Quantum Unity檢查器進行了視覺效果升級，並將包括從內嵌XML程式碼注釋生成的可切換幫助文字。

資料驅動系統設定

Quantum系統的啟動選擇可能因遊戲模式或地圖選擇而異。使用SystemsConfig資產引入了一種資料驅動的方法。Quantum資產中結合的系統和子系統的不同組合現在可以由RuntimeConfig資產參照。

Quantum 2.1靜態SystemSetup.CreateSystems()仍然有效，但被認為已棄用，並將記錄一個警告。升級Quantum 2.1專案並遷移內容後，可以刪除該類別。

系統按此順序創建（請參閱DeterministicSystemSetup.CreateSystems()）：

舊的SystemSetup.CreateSystems()類別和方法存在（透過反射檢查）->調用並跳過其餘部分
如果SystemsConfig有條目->創建和新增系統並繼續
如果SystemConfig無效或沒有條目->創建和新增預設系統並繼續
最後，部分使用者方法稱為DeterministicSystemSetup.AddSystemsUser()以允許最後的觸摸

舊的：file: quantum_code/quantum.code/SystemSetup.cs

namespace Quantum {
  public static class SystemSetup {
    public static SystemBase[] CreateSystems(RuntimeConfig gameConfig, SimulationConfig simulationConfig) {
      return new SystemBase[] {
          // ..
      }
    }
  }
}

新的：file: Assets/QuantumUser/Simulation/SystemSetup.User.cs

namespace Quantum {
  using System.Collections.Generic;

  public static partial class DeterministicSystemSetup {
    static partial void AddSystemsUser(ICollection<SystemBase> systems, RuntimeConfig gameConfig, SimulationConfig simulationConfig, SystemsConfig systemsConfig) {
      systems.Add(new TestSystemMainThreadGroup("TestSystemsGroup", new SystemMainThread[] { new TestSystemImmediateRemoveDestroy(), }));
      systems.Add(new TasksTestSystem());

3D膠囊形狀

最後，Quantum物理支援2D和3D膠囊形狀。

最大元件

現在可以在qtn檔案中設置將最大元件數增加到512：

#pragma max_components 512

實體視圖框架

使用Unity指令碼EntityViewComponent快速新增視圖程式碼，可以快速檢查遊戲狀態並對其做出反應。

實體視圖元件

實體視圖輪詢

使用QuantumEntityViewPool可以輕鬆地輪詢實體視圖。

實體視圖

角色控制器附加元件

基於新膠囊碰撞檢查的運動學角色控制器的新迭代，可作為附加元件提供。

Quantum 3 KCC附加元件

部分確定性導航網格內嵌

Quantum導航網格內嵌現在是確定性的，這對於在運行時生成導航網格的遊戲來說很有趣。預設管道仍然依賴於匯入Unity網格（非確定性）。最終會有一個替代者。

導航網格內嵌已從Unity移動到QuantumGame中的模擬程式碼（請參閱個別版本資訊更改）。

儀表板選項

預設下，Quantum3應用程式會封鎖非協定訊息和玩家屬性。保留這些舊功能可能會讓惡意行為者破壞Quantum應用程式的對戰配對和遊戲遊玩流程，即使實際的遊戲遊玩無法受到中斷。要解鎖這些功能，必須在各個應用程式帳號的儀表板屬性中明確設定它們。

BlockNonProtocolMessages (true/false)
BlockPlayerProperties (true/false)

BlockRoomProperties（新）

類型：boolean (true/false)

該外掛程式將在創建房間後取消客戶端設定的所有房間屬性。名為StartQuantum的屬性除外。初始房間屬性也可以透過webhook擷取。

警告：這也會影響Open及IsVisible。

AllowedLobbyProperties（新）

類型：string（允許分離器：、或；或空白鍵）

最大屬性數量：3

最大string屬性長度：64

設定允許客戶端作為大廳屬性發送的屬性清單，以保護主伺服器上的對戰配對效能。如果設定了此屬性，則客戶端發送的未列入的屬性將被刪除。一旦找到，外掛程式就會記錄Restricted LobbyProperty。

此外，預設下，屬性類型限制為：bool、byte、short、int、long、string

MaxPlayerSlots（新）

類型：int

預設下，客戶端可以創建遊戲支援的盡可能多的本機玩家。設定此值將限制在此應用程式帳號下運行的所有遊戲。該值也可以由webhooks設定。

StartPropertyBlockedTimeSec（新）

類型：int

如果設定為大於零的數字，Quantum將被禁止在房間中啟動，直到創建房間以來的最小秒數過去。這可以用來確保玩家在遊戲啟動前有足夠的時間加入。

StartPropertyForcedTimeSec（新）

類型：int

如果設定為大於零的數字，則這是創建房間後在房間中啟動Quantum之前可以經過的最大秒數。如果超過指定時間，遊戲將把房間遊戲屬性中的StartQuantum屬性設定為真（如果尚未設定）。

HideRoomAfterStartSec（新）

類型：int

如果設定為大於零的數字，則它定義了在Quantum在房間中啟動後，房間將從公共或搜尋清單中隱藏的秒數。這可以幫助管理房間可見性，並確保新玩家不會加入正在進行的遊戲。

CloseRoomAfterStartSec（新）

類型：int

如果設定為大於零的數字，它將確定在房間中啟動Quantum後將關閉房間的秒數。關閉房間會阻止新玩家加入，並可用於管理遊戲階段的生命週期。