バージョン移行ガイド

Quantum 2.1から3.0への移行

これはQuantum 2.1プロジェクトをQuantum 3.0に移行するための完全ガイドです。

Quantum 3の移行を開始する前に、プロジェクトを最新のQuantum 2.1リリースおよびUnity 2021.3にアップグレードすることを確認してください。

自動化されたプロセスを使用することを推奨します。問題が発生した場合は、デバッグの手順を確認し、私たちに連絡してください。

スクリプトのGUIDは保持されているため、プレハブやシーンはコンポーネントの欠落による影響を受けません。

移行中の可能なコンパイルエラーを減らすために、レガシー名の古いスクリプトが提供されています。

次のアドオンはQuantum 3にまだ互換性がありません：

アセットインジェクション

移行ステップ

プロジェクトにバックアップがあることを確認し、またはソース管理下にあることを確認します。
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> [..]

使用方法：
- `-UnityEditorPath <path>`                  UnityEditorのexeへのパス。
- `-QuantumUnityPath <path>`                 Quantum Unityプロジェクトフォルダーへのパス。デフォルトは「quantum_unity」です。
- `-QuantumCodePath <path>`                  Quantumコードプロジェクトへのパス。デフォルトは「quantum_code/quantum.code」です。
- `-AssetDBPath <path>`                      一時的にエクスポートされたアセットへのパス。デフォルトは「Quantum3MigrationAssets」です。
- `-Quantum2MigrationPreparationPackagePath <path>`
                                              Quantum 3移行準備のunitypackageへのパス。
- `-Quantum3PackagePath <path>`              Quantum 3 SDKのunitypackageへのパス。
- `-Quantum3MigrationPackagePath <path>`     Quantum 3移行のunitypackageへのパス。
- `-LogBasePath <path>`                      移行ログが保存されるフォルダ。設定しない場合、ログは実行ディレクトリ内に作成されます。
- `-AssemblyDefinitionsDecision`              「アセンブリ定義を削除する」というプロンプトに対する回答を定義します。「yes」または「no」。
- `-PauseAfterEachStep`                       各ステップの後で一時停止し、ユーザー入力を待ちます。デフォルトはfalseです。
- `-SkipQuantum3PackageImports`               パッケージインポート手順を無効にします。
- `-SkipQuantumCodeCopy`                      Quantumコードのインポートを無効にします。
- `-SkipInitialCodeGen`                       初期CodeGen手順を無効にします。
- `-SkipCompileErrorDetection`                コンパイラーエラー修正の待機を無効にします。
- `-SkipAssetsUpgrade`                         Quantumアセットのアップグレードを無効にします。

B) 手動プロセス

Quantum3MigrationPreparation.unitypackageのインポート
Quantumの実行 > Migration Preparation > Add Migration Defines
Quantumの実行 > Migration Preparation > Delete Prefab Standalone Assets
Quantumの実行 > Migration Preparation > Export Assets
Quantumの実行 > Migration Preparation > Delete Photon
Photon-Quantum-3.0.0-XXXX.unitypackage のインポート(Unity Editorがクラッシュしたら、Unityを再起動します)
Photon-Quantum-3.0.0-Stable-Migration-XXXX.unitypackageをインポート
Unity Editorの再起動 (Enter Safemode ダイアログでIgnoreをクリックします)
Toolsを実行 > Quantum > Migration > Import Simulation Project
Toolsを実行 > Quantum > Migration > Run Initial CodeGen
Optionally Toolsを実行 > Quantum > Migration > Run Delete Assembly Definitions
Unity Editorの再起動 (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
Run the Quantum user file installation from the QuantumHub (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のAppIdを作成する必要があります。
QuantumEditorSettings.AssetSearchPathsを Assets に設定すると、プロジェクト全体を検索できます。今は十分に速いです。
たとえば、Resourcesフォルダ内のQuantumアセットを再インポートさせるために（右クリック > Reimport）、QuantumUnityDB.qunitydb アセットを再インポートします（これにより壊れたQuantumアセットのGUIDが修正されます）。
すべてのマップとナビメッシュを再ベイクします。
Quantum 3 APIの変更はすべて[Obsolete]属性でラップされており、正常に移行されたプロジェクトがコンパイルされるようになっています。その後、特にQuantumアセットとプロトタイプスクリプトに関する警告をチェックして修正し、新しい名前を優先してGameObject.AddComponent<QAssetEntityView>が機能するようにします。

Breaking Changes 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 でAppIdを設定し、ConnectUsingSettings() を使用してください。
RaiseEventOptions クラスは、RaiseEventArgs と呼ばれる構造体に変更されました。
EnterRoomParams が EnterRoomArgs に名前が変更されました。
OpJoinRandomRoomParams が JoinRandomRoomArgs に名前が変更されました。
RealtimeClient.ConnectionCallbackTargets は現在内部用です。AddCallbackTarget() と RemoveCallbackTarget() を使用してください。
列挙型 DebugLevel は LogLevel に名前が変更されました。列挙型名は現在パスカルケースです。

FAQ

"プロジェクトパスを設定できませんでした"

Quantum Unityプロジェクトフォルダーの名前を変更しました。QuantumUnityPathパラメータを正しいパスに設定してください。

Quantum Hub

移行中に、ユーザーエラーや他のバグによりQuantum Hubがユーザーにインストールプロセスの完了を許可しないことがあります。これを解決するには、プロジェクト内のPhotonServerSettingsスクリプタブルオブジェクトを削除して、Hubにファイルを再生成させることを試みてください。

パッケージのインポートに失敗しました

Quantum 3パッケージファイルパスが間違っています。Quantum3PackagePathパラメータを正しいパスに設定してください。

または

Quantum 3 Migrationパッケージファイルパスが間違っています。Quantum3MigrationPackagePathパラメータを正しいパスに設定してください。

Unity Editorのパス

Unity Editorのパスは、エディタの実行ファイルへのパスです。

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 という名前を付けることができます。これはコード生成でサポートされていますが、移行ではサポートされていません。エラーが発生する場合は、移行の前にこれらのフィールドの名前を変更することを推奨します。

Quantumバージョン

未定義のエラーが発生する場合、移行を試みる前に最新のQuantum 2.1リリースに更新されていることを確認してください。

最大コンポーネント数512

512コンポーネント数のライブラリを使用しているプロジェクトは、qtnファイルに新しいプラグマを追加する必要があります。

#pragma max_components 512

Quantum 2.1から3.0への移行

移行ステップ
Breaking Changes Realtime 5
FAQ