This document is about: QUANTUM 3

SWITCH TO

QUANTUM 1 QUANTUM 2 QUANTUM 3

Quantumプロジェクト

Unitypackageの内容

Quantum 3 SDKは、unitypackageファイルで配布されています。これは大きくAssets/PhotonとAssets/QuantumUserの2つに分かれていて、前者はQuantum SDK、後者はユーザーが変更可能なコードになります。

Quantumをインストールすると、以下のフォルダー構造が確認できます。

Assets
├───Photon
│   ├───PhotonLibs
│   ├───PhotonRealtime
│   ├───Quantum
│   ├───QuantumAsteroids
│   └───QuantumMenu
└───QuantumUser
    ├───Editor
    │   ├───CodeGen
    |   └───Generated
    ├───Resources
    ├───Scenes
    ├───Simulation
    │   └───Generated
    └───View
        └───Generated

アップグレードによって、Photon以下のすべてのファイルは置き換えられますが、QuantumUserは置き換えられません。

すべての決定論的なシミュレーションコードは必ず、QuantumUser/Simulation以下か、Quantum.Simulationアセンブリ参照に含まれている必要があります。

Quantumビュースクリプトを拡張するコード（例：部分メソッド）は、Quantum.Unity/Quantum.Unity.Editorのアセンブリ参照に含めることができます。

Assets/Photon

Assets/Photon：このフォルダーには、Photon Quantumやその他のパッケージが含まれます。ここにあるファイルの変更は、アップグレード時に上書きされます。
Assets/Photon/PhotonLibs (and PhotonRealtime)：QuantumがCloudに接続/通信するために使用する、依存のPhotonライブラリが含まれます。
Assets/Photon/Quantum/Assemblies：Unity用のQuantumライブラリと、そのデバッグ版が含まれます。
Assets/Photon/Quantum/Editor：QuantumのUnityエディタースクリプトです。Quantum.Unity.Editor.dllにコンパイルされます。
Assets/Photon/Quantum/Editor/Assemblies：QuantumのCodeGenライブラリが含まれます。
Assets/Photon/Quantum/Editor/CodeGen：QuantumのCodeGenスクリプトが含まれます。Quantum.CodeGen.Qtn.dllにコンパイルされます。
Assets/Photon/Quantum/Runtime：QuantumのUnityランタイムスクリプトです。Quantum.Unity.dllにコンパイルされます。
Assets/Photon/Quantum/Simulation：Quantumシミュレーションのコアスクリプトです。Quantum.Simulation.dllにコンパイルされます。
Assets/Photon/Quantum/Samples：デモメニューシーンとGraphProfilerが含まれます。

Assets/QuantumUser

Assets/QuantumUser：このフォルダー内のファイルは、アップグレードで上書きされることはなく、開発者の管理下にあります。Quantumやシミュレーションライブラリへコードを追加するには、アセンブリ定義参照を使用します。
Assets/QuantumUser/Editor/CodeGen：Qtn CodeGenを拡張するファイルが含まれます。
Assets/QuantumUser/Editor/Generated：生成されたUnityエディタースクリプトです。
Assets/QuantumUser/Simulation：実際のシミュレーションコードです。
Assets/QuantumUser/Simulation/Generated：生成されたQuantum C#コードです。
Assets/QuantumUser/Resources：ランタイムの設定ファイルです。
Assets/QuantumUser/Scenes：新しいQuantumシーン用のデフォルトフォルダーです。
Assets/QuantumUser/View：ビュースクリプトを置くデフォルトの場所です。
Assets/QuantumUser/View/Generated：生成されたQuantumプロトタイプスクリプトです。このフォルダー内のスクリプトは、Quantum.Unity.dllを拡張します。

Quantumは以下4つのアセンブリに分割されています。

Quantum.Simulation：シミュレーションコードが含まれます。ユーザーのシミュレーションコードは、AssemblyDefinitionReferencesを使用してこのアセンブリに追加する必要があります。Unity/Odinのプロパティ属性は自由に使用できますが、非決定論的なUnity APIの使用は全く推奨できません。このアセンブリのコードは、スタンドアロンの.csprojとして簡単に動作させることができます。
Quantum.Unity：Qunatumとの統合に特化したUnityのコードが含まれます。さらに、コンポーネントプロトタイプをラップするMonoBehaviourがCodegenによって生成されます。
Quantum.Unity.Editor：Quantum.SimulationとQuantum.Unityのエディターコードが含まれます。
Quantum.Unity.Editor.CodeGen：Codegenとの統合コードが含まれます。これは他のQuantumアセンブリとは完全に独立しているため、コンパイルエラー時でも実行できます（セーフモードは終了する必要があります）。

Quantumの依存関係

Quantum Hub

Ctrl+Hを押すか、Quantumメニューから、Quantum Hubを開きます。

重要なQuantum設定ファイル（例：PhotonServerSettings）が欠けている場合も、Hubウィンドウがポップアップするので、インストールボタンを押しましょう。

インストールプロセスでは、unitypackageに含まれない（Quantumバージョンのアップグレードによって上書きされない）ファイルが、ローカルにインストールされます。

Quantumメニューのインストール

Quantumメニューはアドオンで、Hubを使用してSDKと一緒にインストールできます。unitypackageはAsset/Photon/QuantumMenu/Quantum-Menu.unitypackageにあります。

このインゲームメニューから、ランダムなオンラインマッチを開始したり、パーティーを作成したりすることができます。

カスタマイズ要素の詳細については、サンプルメニューのカスタマイズをご覧ください。

リリース/デバッグビルド

Quantumライブラリ（Quantum.Deterministic.dll・Quantum.Engine.dll・Quantum.Corium.dll）は、リリース版/デバッグ版の両方があります。QUANTUM_DEBUGグローバルスクリプト定義を使用して、Unityが正しいライブラリを認識できるようにしています。

デバッグとリリースの切り替えには、メニューを使用します。

注意点：定義はプラットフォームごとに設定する必要があるため、リリースビルド作成時にデバッグ版が無効になっていないプラットフォームがある可能性に気を付けてください。

デバッグビルドはリリースビルドに比べて著しくパフォーマンスが低下します。パフォーマンステストは、必ずQuantumリリースビルド（とUnity IL2CPP）を使用してください。詳細はプロファイリングセクションをご覧ください。

開発ビルドには、アサーション・例外・チェック・デバッグ出力など、開発に役立つものが含まれていますが、リリース設定では無効になります。以下がその例です。

Quantumプロジェクトコードから呼び出されるLog.Debug()/Log.Trace()は、ログを出力しません。
Draw.Shape()メソッドなどもすべて同様です。
NavMeshAgentConfig.ShowDebugAvoidance/ShowDebugSteeringは、ギズモを描画しません。
物理などの低水準システム内のアサーションや例外は無効になります。

ロギング

Quantumが提供するQunatum.Log静的クラスは、シミュレーションコードのログと、そのログの出力を生成します。

namespace Quantum {
  public unsafe class MyQuantumSystem : SystemMainThread
    public override void Update(Frame frame) {
      Log.Debug($"Updating MyQuantumSystem tick {frame.Number}");
    }
  }
}

Unity SDKにはQuantumUnityLoggerというラッパーがあり、RuntimeInitializeOnLoadMethod/InitializeOnLoadMethod時に静的に初期化されます（QuantumUnityLogger.Initialize()参照）。

部分メソッドInitializePartial()を使用して、この初期化をカスタマイズできます。

QuantumUnityLoggerクラスは、様々なカスタマイズフィールド（例：カラースキームの定義）を提供しています。

ログレベル

グローバルのログレベルはQuantum.Log.LogLevelで制御されます。初期ログレベルを設定するには、以下のスクリプト定義を使用します。

QUANTUM_LOGLEVEL_TRACE
QUANTUM_LOGLEVEL_DEBUG
QUANTUM_LOGLEVEL_INFO
QUANTUM_LOGLEVEL_WARN
QUANTUM_LOGLEVEL_ERROR

これらはQuantumEditorSettingsインスペクターから切り替えられます。

前述の通り、デバッグビルドのLog.Trace()/Log.Debug()メッセージは、それぞれTRACE/DEBUG定義がある場合のみログが出力されます。Unityエディター上では、常にDEBUG定義で実行されることに注意してください。

Photon Realtime ログ

Quantumで使用されるPhoton Realtimeライブラリ自体にもログレベルがあり、PhotonServerSettingsのPhoton.Realtime.Appsettingsから設定できます。

AppSettings.NetworkLogging：PhotonPeerと接続用のログレベルです。接続関連の問題のデバッグに便利です。
AppSettings.ClientLogging：RealtimeClientとコールバック用のログレベルです。クライアント状態・使用中のサーバー・呼び出した命令に関する情報の取得に便利です。

LOG_WARNING/LOG_INFO/LOG_DEBUGを定義しない限り、開発ビルド以外でERROR未満のRealtimeログは出力されません。

シミュレーションのエクスポート

Quantumシミュレーションコードは、Unityに依存しないスタンドアロンのC#プロジェクトにエクスポートできます。プロジェクトはUnityプロジェクトフォルダー内に生成され、すべてのシミュレーションソースファイルとリンクし、Assets/Photon/Quantum/Editor/Dotnet/Quantum.Dotnet.Debug.zipなどから抽出された非UnityのQuantum依存コードを使用します。

UnityプロジェクトのQuantumDotnetProjectSettingsアセットを選択し、どのシミュレーションソースコードを検索するかを定義します。
- 手動でIncludePathsを追加するか、UnityアセットラベルQuantumDotNetIncludeでフォルダーをマークします。
UnityプロジェクトのQuantumDotnetBuildSettingsアセットを選択し、DotNetプロジェクトをどのように生成/ビルドするかを制御します。

Show Folder After Generationを有効にし、Generate Dotnet Projectを押します。
- Unityプロジェクトフォルダーの相対パスProject Base Pathに、プロジェクトが生成されます。

エクスポートされたソリューション構造

生成されたソリューションには、以下の2つのプロジェクトが含まれます。

Lib - デバッグ/リリース設定の、解凍済みの非UnityのQuantum依存コードです
Quantum.Runner.Dotnet - Quantumリプレイを実行できる軽量のコンソールランナーが含まれます
Quantum.Simulation.Dotnet - 非UnityのQuantumシミュレーションプロジェクトとコードが含まれます

コンソールランナーの使用

IDEでソリューションをビルドします。
ターミナルを開き、ビルドexe（Quantum.Runner.exe）があるフォルダーに移動します。
次の引数を使用してexeを実行します。

bash

Quantum.Runner.exe --replay-path path/to/replay --lut-path path/to/lut --db-path path/to/db --checksum-path path/to/checksum

--replay-pathと--lut-path引数は必須です。

--db-path引数は、リプレイがDBを含む場合はオプションです。

--checksum-path引数は完全なオプションです。

スタンドアロンアセットファイルを取得するには、Tools/Quantum/Export/AssetDatabaseメニューの下にあるAsset Databaseメニューボタンを押してください。

LUTファイルを取得するには、UnityプロジェクトのAssets/Photon/Quantum/Resources/LUTフォルダーにアクセスしてください。

.qtnファイルのシンタックスハイライト

DSL（.qtn拡張子のファイル）でシンタックスハイライトを有効にするには、以下の各IDEガイドをご覧ください。

Visual Studio

Visual Studioでは、他のタイプ（例：C#）を関連付けることで、QTNファイルにシンタックスハイライトを追加できます。これはTools -> Options -> Text Editor -> File Extensionから実行できます。

File Types — .qtnファイルのDSLシンタックスハイライト（Visual Studio）

Visual Studio Code

Visual Studioでは、他のタイプ（例：C#）を関連付けることで、QTNファイルにシンタックスハイライトを追加できます。

設定を開く（Ctrl+、macOSではCmd+）
「Files: Associations」を検索する
「*.qtn」から「csharp」へファイルの関連付けを追加する

Visual Studio Code File Association settings — .qtnファイルのDSLシンタックスハイライト（Visual Studio）

JetBrains Rider

JetBrains Riderでは、新しいファイルタイプを定義することで、DSLファイル（.qtn拡張子のファイル）にシンタックスハイライトを追加できます。

ステップ1： File -> Settings -> Editor -> File Typesに移動します。

ステップ2： Recognized File Typesカテゴリーで、右側の+ボタンを押して新しいファイルタイプを追加します。

ステップ3: 行コメント、ブロックコメントなどの設定を確認します。
ステップ4: 以下のリストをキーワードレベル1に貼り付けます。

#define
#pragma
abstract
any
array
asset
asset_ref
bitset
button
byte
component
dictionary
entity_ref
enum
event
fields
filter
flags
global
has
import
input
int
list
local
long
not
player_ref
remote
sbyte
set
short
signal
struct
synced
uint
ulong
union
use
ushort
using

ステップ5: 以下のリストをキーワードレベル2に貼り付け、Okを押します。

(
)
*
:
;
<
=
>
?
[
]
{
}

ステップ6: File Name Patternsカテゴリーで、右側の+ボタンを押します。
ステップ7: タイプのワイルドカードとして*.qtnを入力します。

DSL Syntax Highlighting — .qtnファイルのDSLシンタックスハイライト（JetBrains Rider）

Unitypackageの内容
Quantumの依存関係
Quantum Hub
Quantumメニューのインストール
リリース/デバッグビルド
ロギング

ログレベル
Photon Realtime ログ

シミュレーションのエクスポート

エクスポートされたソリューション構造

.qtnファイルのシンタックスハイライト

Visual Studio
Visual Studio Code
JetBrains Rider