This document is about: QUANTUM 3
SWITCH TO

Configuration Files

概述

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

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

PhotonServerSettings, SessionConfig, SimulationConfig, QuantumEditorSettingsQuantumGameGizmoSettings儲存在 Unity 專案的ScriptableObjects中,而儲存在 Unity 專案的 RuntimeConfigRuntimePlayer通常在執行期間組裝。

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

Find Quantum Configs Menu

PhotonServerSettings

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

Photon Realtime詳情請參閱Photon Realtime簡介

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

Photon Server Settings
參數名稱 描述
應用程式設定 詳情請參閱內嵌程式碼摘要或 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 會在模擬開始前在所有客戶端之間同步。詳情請參閱線上設定序列圖 部分。

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

Session Config
參數名稱 替代名稱 單位 描述
模擬率 更新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 等,作為子資源。
Default Configs
  • 檔案QuantumUser/Game/SimulationConfig.User.cs包含一個部分類別定義,可用於擴展 SimulationConfig 的內容。

C#

namespace Quantum {
  public partial class SimulationConfig : AssetObject {
    public int Foo;
  }
}
Simulation Config
參數名稱 描述
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

C#

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。

C#

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,例如測試序列化。

C#

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

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

C#

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。

C#

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 已經包含兩個欄位,可用於玩家視覺化和暱稱的起點。例如,演示選單使用它們。

C#

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創建一個預設編輯器設定資源。

Quantum Editor Settings
參數名稱 描述
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 Editor Settings

線上設定序列圖

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

Online Config Sequence Diagram
線上設定序列圖
Back to top