Migration Guide

將Quantum 2.1專案遷移到Quantum 3.0的完整指南。

在開始Quantum 3遷移之前，請確保將專案升級到最新的Quantum 2.1版本和Unity 2021.3。

建議使用自動化流程。遇到問題時，請使用調試說明並與我們聯絡。

指令碼GUID已被保留，因此預製件和場景不會因缺少元件而受到影響。

為了減少遷移過程中可能出現的編譯錯誤，提供了具有舊名稱的過時指令碼。

以下外掛程式尚未與Quantum 3相容：

資產注入

Quantum 3.0遷移

確保專案有備份和/或處於源管理之下
將Quantum專案升級到最新的2.1 Quantum SDK
將Quantum專案升級到Unity Editor 2021.3或更高版本
下載最新的Photon-Quantum-3.0.0-Stable-Migration-XXXX.zip套件
將內容提取到Quantum 2.1專案的根資料夾中
Bot SDK規格：在Bot SDK v3套件中找到特定於外掛程式的遷移說明

開始前

由於Quantum資產的改變：
- 每個非抽象和非泛型資產都必須存在於一個名為此的單獨檔案中：<AssetName>.cs
- 必須重命名ScriptableObjects中常見的資產方法：Update()、Start()等等。
如果已新增GraphProfiler外掛程式，並且已將其從其預設位置Assets/Photon/Profiling移動，則必須在遷移前將其刪除。
必須重命名名為EntityRef的qtn檔案中定義的欄位。
建議在執行自動或手動遷移時，將中間步驟儲存為git認可。

A)自動流程

運行Quantum3Migration.ps1 Powershell指令碼
- 要排除故障，請檢查遷移日誌並啟用-PauseAfterEachStep，然後在每個步驟後將更改包裝成git認可。
開啟Unity編輯器
繼續執行Final Steps

Quantum3Migration.ps1 -UnityEditorPath <path> -Quantum2MigrationPreparationPackagePath <path> -Quantum3PackagePath <path> -Quantum3MigrationPackagePath <path> [..]

Usage:
  -UnityEditorPath <path>                 The path to the UnityEditor exe.
  -QuantumUnityPath <path>                The path to the Quantum Unity project folder. By default "quantum_unity".
  -QuantumCodePath <path>                 The path to the Quantum code project. By default "quantum_code/quantum.code".
  -AssetDBPath <path>                     The path to the temporary exported assets. By default "Quantum3MigrationAssets".
  -Quantum2MigrationPreparationPackagePath <path>
                                         The path to the Quantum 3 Migration Preparation unitypackage.
  -Quantum3PackagePath <path>            The path to the Quantum 3 SDK unitypackage.
  -Quantum3MigrationPackagePath <path>   The path to the Quantum 3 Migration unitypackage.
  -LogBasePath <path>                    The folder where the migration logs are stored. If not set logs are created inside the executing directory.
  -AssemblyDefinitionsDecision           Define the answer for the "remove assembly definition" prompt. "yes" or "no".
  -PauseAfterEachStep                    Pause and wait for user input after each step. Default is false.
  -SkipQuantum3PackageImports            Disable the package import steps.
  -SkipQuantumCodeCopy                   Disable importing the quantum code.
  -SkipInitialCodeGen                    Disable initial CodeGen steps.
  -SkipCompileErrorDetection             Disable waiting for compiler error fixes.
  -SkipAssetsUpgrade                     Disable upgrading the Quantum assets.

B)手動流程

匯入Quantum3MigrationPreparation.unitypackage
運行Quantum > Migration Preparation > Add Migration Defines
運行Quantum > Migration Preparation > Export Assets
運行Quantum > Migration Preparation > Delete Photon
匯入Photon-Quantum-3.0.0-XXXX.unitypackage（如果Unity編輯器崩潰，請重新啟動Unity）
匯入Photon-Quantum-3.0.0-Stable-Migration-XXXX.unitypackage
重新啟動Unity編輯器（在Enter Safemode對話方塊中按一下Ignore）
運行Tools > Quantum > Migration > Import Simulation Project
運行Tools > Quantum > Migration > Run Initial CodeGen
可選擇運行Tools > Quantum > Migration > Run Delete Assembly Definitions
重新啟動Unity編輯器（在Enter Safemode對話方塊中按一下Ignore）
修復編譯錯誤
- 如果Quantum AssetObjects具有現有的abstract void Update(Frame f)方法，Unity將會抱怨ScriptableObject必須具有無參數的Update()方法，請新增void Update() {}以修復編譯錯誤
運行Tools > Quantum > Migration > Check Asset Object Scripts
運行Tools > Quantum > Migration > Transfer AssetBase Guids To AssetObjects
運行Tools > Quantum > Migration > Upgrade AssetsObjects
運行Tools > Quantum > Migration > Enable AssetObject Postprocessor
運行Tools > Quantum > Migration > Reimport All AssetObjects
從QuantumHub運行Quantum使用者檔案安裝（Ctrl+H）

最後步驟

啟用遷移定義QUANTUM_ENABLE_MIGRATION時，禁用是否必須運行CodeGen（qtn檔案已更改）的檢測，需要使用Unity選單手動運行：Tools > Quantum > CodeGen > Run Qtn CodeGen
指令碼經過了廣泛的重構：
- 元件原型後綴已從_Prototype更改為Prototype。
- 元件原型包裝器前綴從EntityComponent更改為QPrototype（例如EntityComponentTransform2D -> QPrototypeTransform2D）。
- 所有僅Unity的指令碼都被放在Quantum命名空間中，並被賦予了Quantum前綴（例如MapData -> QuantumMapData, EntityPrototype -> QuantumEntityPrototype）。
設置資產可能有不同的名稱和不同的位置，請在Quantum Setup部分瀏覽它們。
QuantumEditorSettings分為QuantumEditorSettings及QuantumGameGizmosSettings。
已生成一組新的預設設置（以前位於Resources/DB/Configs中），不再支援靜態GUID。
必須在Photon儀表板上創建Quantum3應用程式帳號。
QuantumEditorSettings.AssetSearchPaths可以設定為Assets來搜尋整個專案。現在已經夠快了。
例如，讓Unity重新匯入位於Resources資料夾中的Quantum資產（按右鍵>重新匯入），並重新匯入QuantumUnityDB.qunitydb資產（這將修復損壞的Quantum資產GUID）。
重新嵌入所有地圖和導航網格。
Quantum 3 API更改已全部包裝到[Obsolete]屬性中，以使成功遷移的項目能夠編譯。確保在那之後檢查並修復所有相關的警告，特別是Quantum資產和原型指令碼，並更偏好以它們的新名稱來使GameObject.AddComponent<QAssetEntityView>工作正常。

突破性變化Realtime 5

命名空間ExitGames.*已過時。改為使用Photon.Client和Photon.Realtime。
LoadBalancingClient已重命名為RealtimeClient。
LoadBalancingClient.LoadBalancingPeer已重命名為RealtimeClient.RealtimePeer。
移除了LoadBalancingPeer類別。操作現在位於RealtimeClient。
ExitGames.Client.Photon.Hashtable類別已重命名為Photon.Client.PhotonHashtable。客戶端現在只能發送PhotonHashtable。
移除了ConnectToRegionMaster()、ConnectToMasterServer()、ConnectToNameServer()。改為只使用ConnectUsingSettings()。
LoadBalancingClient.CloudRegion已過時。改為使用RealtimeClient.CurrentRegion。
LoadBalancingClient.AppVersion已過時。透過AppSettings及ConnectUsingSetting()來設定版本。
AppId設定器現在擲出一個NotImplementedException。在AppSettings中設定應用程式帳號，並改為使用ConnectUsingSettings()。
RaiseEventOptions類別已更改為名為RaiseEventArgs的結構體。
EnterRoomParams已更名為EnterRoomArgs。
OpJoinRandomRoomParams已更名為JoinRandomRoomArgs。
RealtimeClient.ConnectionCallbackTargets現在是內部的。請改用AddCallbackTarget()及RemoveCallbackTarget()。
列舉DebugLevel已更名為LogLevel。列舉名稱現在是Pascal大小寫。

問與答

「無法設定專案路徑」

您重命名了Quantum Unity項目資料夾。將QuantumUnityPath參數設定為正確的路徑。

Quantum Hub

在遷移過程中，由於使用者錯誤或其他錯誤，Quantum Hub可能不允許使用者完成安裝過程。為了解決這個問題，您可以嘗試刪除專案中的PhotonServerSettings可指令碼物件，以便Hub重新生成檔案。

匯入套件失敗

您的Quantum 3套件檔案路徑錯誤。將Quantum3PackagePath參數設置為正確的路徑。

或

您的Quantum 3遷移套件檔案路徑錯誤。將Quantum3MigrationPackagePath參數設置為正確的路徑。

Unity編輯器路徑

Unity編輯器路徑是編輯器可執行文件的路徑。

在Windows上，它通常位於C:\Program Files\Unity\Hub\Editor\UNITY_VERSION\Editor\Unity.exe。

Powershell指令碼僅適用於Windows。

Quantum.Code專案

如果您的Quantum程式碼csproj名稱與預設名稱不同，遷移可能會失敗。您需要將QuantumCodePath參數設置為正確的路徑。

Bot SDK

如果您在專案中使用Bot SDK，則也必須平行遷移它。

Bot SDK資料現在是單一的，而不是全域存儲的。

Powershell引數

Powershell引數必須使用單個「-」而不是「--」傳遞。

示例：-UnityEditorPath "C:\Program Files\Unity\Hub\Editor\2021.3.0f1\Editor\Unity.exe"
錯誤：--UnityEditorPath "C:\Program Files\Unity\Hub\Editor\2021.3.0f1\Editor\Unity.exe"

.Qtn欄位

可以將.qtn檔案中定義的欄位命名為EntityRef。Codegen支援這一點，但遷移不支援。如果有錯誤，建議在遷移之前重命名這些欄位。

Quantum版本

如果您遇到未定義的錯誤，請確保在嘗試遷移之前已更新到最新的Quantum 2.1版本。

最大元件數512

使用512個元件數程式庫的專案，需要向qtn檔案新增一個新的pragma。

#pragma max_components 512

Quantum 3.0遷移

開始前
A)自動流程
B)手動流程
最後步驟

突破性變化Realtime 5
問與答

「無法設定專案路徑」
Quantum Hub
匯入套件失敗
Unity編輯器路徑
Quantum.Code專案
Bot SDK
Powershell引數
.Qtn欄位
Quantum版本
最大元件數512