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

參數名稱 | 描述 |
---|---|
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 連接協議的流程。
