This document is about: QUANTUM 3

SWITCH TO

QUANTUM 1 QUANTUM 2 QUANTUM 3

Configuration Files

概述

建立並執行 Quantum 遊戲需要七種不同的設定檔案。

參數名稱	描述
`PhotonServerSettings`	儲存 Photon 雲端連線的詳細資訊。
`SessionConfig`	儲存確定性模擬和伺服器的設定。
`SimulationConfig`	儲存 Quantum ECS 層和核心系統（如物理系統）的設定。
`RuntimeConfig`	儲存實際遊戲/應用的資料。
`RuntimePlayer`	儲存個別玩家的資料。
`QuantumEditorSettings`	儲存 Unity 專案的設定。
`QuantumGameGizmoSettings`	儲存 Quantum 模擬期間顯示的 Unity gizmos 設定。

PhotonServerSettings, SessionConfig, SimulationConfig, QuantumEditorSettings及QuantumGameGizmoSettings儲存在 Unity 專案的ScriptableObjects中，而儲存在 Unity 專案的 RuntimeConfig及RuntimePlayer通常在執行期間組裝。

Quantum 選單 Quantum > Find Config > ..可協助定位 Unity 專案中設定資源的全域實例。

PhotonServerSettings

Quantum 3.0 使用 Photon Realtime 5 來連接並與 Photon 雲端通訊。此設定儲存建立連線所需的所有資訊。

Photon Realtime詳情請參閱Photon Realtime簡介。

最重要的設定是 AppId。請閱讀Quantum Asteroids教學 - 專案設定頁面，了解如何設定Photon AppId。

參數名稱	描述
`應用程式設定`	詳情請參閱內嵌程式碼摘要或 Photon Realtime 5 API 文件。
`以秒的玩家TTL`	玩家的預設存活時間，用於建立 Photon 房間時。詳情請參閱 Realtime 文件。
`以秒的空房間TTL`	房間的預設存活時間，在建立 Photon 房間時設定。詳情請參閱 Realtime 文件。
`最佳區域總結鍵`	當連接到最佳區域（`FixedRegion:null`）時，Photon 會針對`AppId`對每個可用區域進行 ping 測試。結果會使用此鍵儲存在 Unity PlayerPrefs 中，以便下次應用啟動時重複使用。
`管理App Id`	開啟 Photon AppId 儀表板 URL。
`最佳區域快取`	從 PlayerPrefs 讀取的最佳區域快取內容。
`重置最佳區域快取`	刪除 PlayerPrefs 的內容。
`開啟區域儀表板`	開啟 Photon 區域儀表板 URL。
`載入應用程式設定`	按鈕會設定 `AppSettings` 以連接到雲端或本地伺服器。

SessionConfig

SessionConfig的其他名稱包括DeterministicConfig或DeterministicSessionConfig。

透過 SessionConfig，開發者可以參數化確定性模擬和插件（Quantum 伺服器元件）的內部設定。

每個客戶端將其 SessionConfig 作為SessionRunner.Arguments的一部分發送到伺服器。伺服器會選擇接收到的第一個實例，或通過調用 webhook 或運行自訂插件來覆蓋它。SessionConfig 會在模擬開始前在所有客戶端之間同步。詳情請參閱線上設定序列圖部分。

此設定的內容包含在校驗和生成中。

參數名稱	替代名稱	單位	描述
`模擬率`	`更新FPS`	Hz	Quantum每秒應執行的刷新數。
`Lockstep`	`Lockstep模擬`	布林值	以鎖步模式運行 Quantum 模擬，不執行回滾。建議將輸入 `InputDelayMin` 至少設為 `10`。
`Rollback Window`		刷新數	每個客戶端本地環形緩衝區中保留的幀數。控制 Quantum 可以預測未來的程度。鎖步模式中不使用。
`Checksum Interval`		刷新數	發送幀狀態的校驗和到伺服器進行驗證的頻率（開發時有用，發布時設為零）。以幀為單位。
`Checksum Cross Platform Determinism`		布林值	允許 Quantum 幀校驗和在跨平台時具有確定性，但會帶來較大成本，僅建議在除錯時使用。
`Input Delta Compression`		布林值	伺服器是否應對輸入進行增量壓縮（與前一刷新輸入集相比）。減少總體頻寬。
`Offset Min`	`Input Delay Min`	ms	玩家可以擁有的最小輸入延遲。
`Offset Max`	`Input Delay Max`	ms	玩家可以擁有的最大輸入延遲。
`Offset Ping Start`	`Input Delay Ping Start`	ms	Quantum開始應用輸入延遲的 ping 值。
`Send Redundancy`	`Input Redundancy`	刷新數	Quantum客戶端應對冗餘輸入重新發送施加的延遲量。`1` = 等待一幀，`2` = 等待兩幀，依此類推。
`Input Repeat Max Distance`		刷新數	Quantum 掃描可重複輸入的幀數。`5` = 向前和向後掃描五幀，`10` = 掃描十幀，依此類推。
`Hard Tolerance`		刷新數	伺服器在過期一幀並替換所有未接收到的輸入為重複輸入或 null 並發送給所有玩家之前等待的幀數。
`Offset Correction Limit`	`Min Time Correction Frames`	刷新數	當接收到時間校正包時，本地客戶端時間必須與伺服器時間相差多少，客戶端才會調整其本地時鐘。
`Correction Send Rate`	`Time Correction Rate`	Hz	伺服器每秒發送時間校正包的次數，以確保所有客戶端的時間同步。
`Correction Frames Limit`	`Min Offset Correction Diff`	刷新數	當前本地輸入延遲必須與當前請求的偏移量相差多少幀，Quantum 才會更新本地輸入偏移量。
`Room Wait Time`	`Session Start Timeout`	s	人工等待時間，控制伺服器在線上模擬請求啟動後等待其他玩家的時間。
`Time Scale Minimum`	`Time Scale Min`	%	伺服器可以應用的最小時間縮放。
`Time Scale Ping Start`	`Time Scale Ping Min`	ms	伺服器開始降低時間縮放至 `Time Scale Minimum` 的 ping 值。
`Time Scale Ping End`	`Time Scale Ping Max`	ms	伺服器達到 `Time Scale Minimum` 值的 ping 值，即達到最慢設定。
`Player Count`		int	模擬初始化時的玩家數量。可設為 0，因為此參數會在啟動 SessionRunner 時被 `SessionRunner.Arguments.PlayerCount`（當 > 0 時）覆蓋。
`Input Fixed Size`		int	輸入結構的大小。此值會在啟動 Session 後由內部設定。計算此值的方法是 `QuantumGame.GetInputSerializedFixedSize()`

SimulationConfig

SimulationConfig 包含 Quantum ECS 層和核心系統（如物理和導航）使用的參數。詳情請參閱手冊中相關系統的部分。

SimulationConfig 是 Quantum DB 的一部分，支援多個此設定的實例。通過 RuntimeConfig 引用 SimulationConfig 以選擇用於模擬的設定。

在 Quantum Hub 初始化 Quantum Unity 專案時，會創建以下檔案：

QuantumUser/Resources/QuantumDefaultConfigs.asset，其中包含一個 SimulationConfig 資源及其引用的預設設定資源，如 PhysicsMaterial、CharacterController2DConfig、NavMeshAgentConfig 等，作為子資源。

檔案QuantumUser/Game/SimulationConfig.User.cs包含一個部分類別定義，可用於擴展 SimulationConfig 的內容。

namespace Quantum {
  public partial class SimulationConfig : AssetObject {
    public int Foo;
  }
}

參數名稱	描述
`Entities`	請參閱 API 文件。
`Physics`	請參閱物理文件。
`Navigation`	請參閱導航文件。
`Auto Load Scene From Map`	此選項會在 Quantum 啟動序列期間觸發 Unity 場景載入。雖然一開始可能很方便，但一旦自訂啟動序列後應禁用並替換為自訂場景載入。"Previous Scene" 指的是 Quantum Map 中的場景名稱。例如，當 AutoLoadSceneFromMap 禁用時，演示選單有一個步驟可以在啟動 Quantum 模擬前載入場景。
`Thread Count`	覆蓋內部使用的執行緒數量。預設為 2。
`Checksum Snapshot History Length`	存已驗證幀校驗和的時間長度。用於在校驗和錯誤發生時生成幀轉儲。重播和本地模式中不使用。預設為 3。
`Checksum Error Dump Options`	校驗和轉儲的附加選項，如果預設設定無法提供清晰的畫面。
`Heap Tracking Mode`	在除錯模式下是否以及如何追蹤幀堆積中的分配。開發時推薦模式為 `DetectLeaks`。在主動除錯記憶體洩漏時，可以啟用 `TraceAllocations` 模式（警告：追蹤非常慢）。
`Heap Page Shift`	定義幀類別用於自訂分配（如 QList）的記憶體頁面最大大小。預設為 15。範例：2^15 = 32.768 位元組 `TotalHeapSizeInBytes = (1 << HeapPageShift) * HeapPageCount`
`Heap Page Count`	定義幀類別用於自訂分配（如 QList）的記憶體頁面最大數量。預設為 256。 `TotalHeapSizeInBytes = (1 << HeapPageShift) * HeapPageCount`
`Heap Extra Count`	設定為會話分配的額外堆積數量，以防需要創建比模擬本身實際需要的更多（輔助）幀。預設為 0。

RuntimeConfig

與 SimulationConfig 不同，RuntimeConfig 包含 可能因遊戲而異 的資訊。預設情況下，它定義了例如要載入的地圖和隨機種子。它沒有儲存設定的資源，而是在執行期間組裝，很可能是基於玩家的選擇（例如遊戲模式）。

要使用特定的 RuntimeConfig，請在啟動會話時將其分配給SessionRunner.Arguments。

var map              = new AssetRef<Map>(QuantumUnityDB.GetGlobalAssetGuid("Photon/Quantum/Samples/SampleScenes/Resources/SampleMap"));
var simulationConfig = new AssetRef<SimulationConfig>(QuantumUnityDB.GetGlobalAssetGuid("QuantumUser/Resources/QuantumDefaultConfigs|DefaultConfigSimulation"));
var systemsConfig    = new AssetRef<SystemsConfig>(QuantumUnityDB.GetGlobalAssetGuid("Photon/QuantumUser/Resources/DefaultSystemsConfig"));

var sessionRunnerArguments = new SessionRunner.Arguments {
    RuntimeConfig = new RuntimeConfig() {
        Map              = map,
        Seed             = DateTime.Now.Millisecond
        SimulationConfig = simulationConfig,
        SystemsConfig    = systemsConfig },
    // ..
};

與 SessionConfig 類似，RuntimeConfig 由每個客戶端發送到伺服器，可以通過 webhook 或自訂伺服器驗證，然後一個版本會在 Quantum 啟動序列期間分發給所有客戶端。

與 SessionConfig 不同，SessionConfig 在發送到伺服器時以二進位形式序列化，而 RuntimeConfig 預設使用 zip 壓縮的 Json 序列化 來上傳和下載設定。

在 Quantum Unity 專案安裝期間，會創建一個QuantumUser/Game/RuntimeConfig.User.cs腳本，允許擴展 RuntimeConfig。

namespace Quantum {
  public partial class RuntimeConfig {
    // Add your own fields (don't use properties).
    public int Foo;

    // Implement DumpUserData() to add information to a debug string that is returned when using Dump().
    partial void DumpUserData(ref String dump) {
    }
  }
}

複製 RuntimeConfig，例如測試序列化。

var copy = RuntimeConfig.Copy(runtimeConfig, new QuantumUnityJsonSerializer());

如果需要，設定也可以儲存在遊戲物件上，如QuantumRunnerLocalDebug腳本所做。

public class QuantumRunnerLocalDebug : QuantumMonoBehaviour {
    public RuntimeConfig RuntimeConfig;
    // ..
}

參數名稱	描述
`Seed`	用於初始化 `Frame.RNG` 下的隨機會話的種子。
`Map`	用於即將到來的遊戲會話的 Quantum Map 的資源引用。<
`SimulationConfig`	用於即將到來的遊戲會話的 SimulationConfig 的資源引用。
`SystemsConfig`	Quantum 系統設定的資源引用。如果未分配設定，則使用預設的內建系統選擇 `DeterministicSystemSetup.CreateSystems(RuntimeConfig, SimulationConfig, SystemsConfig)`。使用的系統可以通過代碼使用部分方法 `DeterministicSystemSetup.AddSystemsUser(System.Collections.Generic.ICollection{SystemBase}, RuntimeConfig, Quantum.SimulationConfig, Quantum.SystemsConfig)` 進行後處理。

RuntimePlayer

與 RuntimeConfig 類似，RuntimePlayer 描述單個玩家的執行時屬性。

玩家的資料行為與其他設定不同，因為它是在遊戲實際啟動後（AddPlayer）由每個玩家單獨發送的。詳情請參閱玩家和線上會話文件。

在 Quantum Unity 專案安裝期間，會創建一個QuantumUser/Game/RuntimePlayer.User.cs腳本，允許擴展 RuntimePlayer。

namespace Quantum {
  public partial class RuntimePlayer {
    // Add your own fields (don't use properties).
    public int Foo;

    // Implement DumpUserData() to add information to a debug string that is returned when using Dump().
    partial void DumpUserData(ref String dump) {
    }
  }
}

與 RuntimeConfig 類似，RuntimePlayer 資料在從Quantum發送和接收時使用 Json 序列化。

預設的 RuntimePlayer 已經包含兩個欄位，可用於玩家視覺化和暱稱的起點。例如，演示選單使用它們。

public partial class RuntimePlayer {
    // This is a proposal how to let players select an avatar prototype using RuntimePlayer. Can be ignored.
    public AssetRefEntityPrototype PlayerAvatar;
    // This is a proposal how to assign a nickname to players using RuntimePlayer. Can be ignored.
    public string PlayerNickname;
}

QuantumEditorSettings

Quantum 編輯器設定包含對 Unity 整合功能至關重要的資訊。

在 Quantum Hub 安裝 Quantum Unity 專案時，會在QuantumUser/Editor/QuantumEditorSettings.asset創建一個預設編輯器設定資源。

參數名稱	描述
`Asset Search Paths`	QuantumUnityDB 用於查找 Quantum 資源的位置。更改此設定需要手動重新導入所有 Unity（Quantum）資源。
`Default New Assets Location`	新 Quantum 資源創建的預設資料夾。
`Use Quantum Unit DB Asset Postprocessor`	後處理器允許複製 Quantum 資源和預製件，並確保設置新的 GUID 和正確的路徑。這可能會使批量處理變慢，可以在這裡切換。
`Use Quantum Toolbar Utilities`	如果啟用，會在播放按鈕旁邊顯示場景載入下拉選單。
`Quantum Toolbar Zone`	工具欄的顯示位置。更改後需要重新載入域。
`Use Photon App Versions Postprocessor`	如果啟用，會創建一個本地 PhotonPrivateAppVersion 可編程物件以支持演示選單場景。
`Entity Component Inspector Mode`	如果啟用，實體元件會在 EntityPrototype 檢查器中顯示
`FP Display Precision`	顯示 FP 時四捨五入的小數位數。預設為 5。
`Auto Build On Scene Save`	儲存場景時自動觸發烘焙。
`Auto Build On Playmode Changed`	如果設置，進入播放模式、儲存場景和構建玩家時會自動烘焙 MapData。
`Auto Build On Build`	如果設置，構建、儲存場景和構建玩家時會自動烘焙 MapData。
`Auto Run Qtn CodeGen`	如果啟用，quantum.code 中 .qtn 檔案的任何更改會立即運行代碼生成。
`Asset Guid Overrides`	啟用 GUID 覆蓋的 Quantum 資源列表。此列表會自動追蹤。
`Quantum Debug (All Platforms)`	為所有平台切換 QUANTUM_DEBUG 腳本定義以使用 Quantum 除錯 dll。
`Quantum Debug (Current Platform)`	為當前平台切換 QUANTUM_DEBUG 腳本定義以使用 Quantum 除錯 dll。

QuantumGameGizmoSettings

Gizmo 設定包含關於 Quantum 除錯和 Gizmo 渲染、顏色和切換的資訊。

在 Quantum Hub 安裝 Quantum Unity 專案時，會在QuantumUser/Editor/QuantumGameGizmosSettings.asset創建一個預設編輯器設定資源。

通常使用QuantumGameGizmosSettingsScriptableObject.Global.Settings檢索的全域設定。要在執行時使用不同的設定，請在執行時將其分配給QuantumRunner.GizmoSettings。

線上設定序列圖

客戶端控制的設定檔案通過 Quantum 連接協議的流程。

Online Config Sequence Diagram — 線上設定序列圖

概述
PhotonServerSettings
SessionConfig
SimulationConfig
RuntimeConfig
RuntimePlayer
QuantumEditorSettings
QuantumGameGizmoSettings
線上設定序列圖