This document is about: QUANTUM 3

SWITCH TO

QUANTUM 1 QUANTUM 2 QUANTUM 3

Quantumプロジェクト

Unitypackageの内容

Quantum 3 SDKは unitypackage ファイルとして配布されています。大きく分けて二つのセクションに分かれています: Assets/Photon と Assets/QuantumUser。前者は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 内に含まれていることができます（例: 部分メソッド）。

Quantum 2.1プロジェクトから移行するユーザー向けに、Quantumアセンブリ定義をオプトアウトすることも可能です。

Assets/Photon

Assets/Photon: このフォルダーにはPhoton Quantumやその他のパッケージが含まれています。ここにあるファイルの変更は、アップグレード時に上書きされます。
Assets/Photon/PhotonLibs (and PhotonRealtime): QuantumがQuantumクラウドに接続し通信するために使用する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の使用は強く推奨されません。このアセンブリからのコードは、Quantum 2の quantum.code.csproj のようにスタンドアロンの .csproj として簡単に作業できます。
Quantum.Unity: QuantumのUnityとの統合に特化したコードが含まれています。さらに、CodeGenはコンポーネントプロトタイプをラップする MonoBehaviours を生成します。
Quantum.Unity.Editor: Quantum.Simulation および Quantum.Unity のためのエディターコードが含まれています。
Quantum.Unity.Editor.CodeGen: CodeGen統合コードが含まれています。このアセンブリは他のQuantumアセンブリとは完全に独立しているため、コンパイルエラーがあっても常に実行できます - これにはセーフモードを終了する必要がある場合があります。

Quantumの依存関係

Quantum Hub

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

重要なQuantum構成ファイルが欠けている場合（例：PhotonServerSettings）、Hubウィンドウがポップアップし、インストールボタンを押すことを推奨します。

インストールプロセスは、次のQuantumバージョンのアップグレードによって上書きされることができないファイルをローカルにインストールすることを処理します。

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

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

このメニューは、ランダムなオンラインマッチを開始したり、パーティを作成したりするための機能的かつグラフィカルなゲーム内メニューです。

カスタマイズの可能性についての詳細情報はこちらをご覧ください: Sample Menu Customization。

リリースおよびデバッグビルド

Quantumライブラリ（Quantum.Deterministic.dll、Quantum.Engine.dll、Quantum.Corium.dll）は、リリースおよびデバッグ設定の両方で提供されます。正しいライブラリをUnityが認識するために QUANTUM_DEBUG グローバルスクリプティング定義が使用されます。

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

注意点: 定義はプラットフォームごとに設定する必要があるため、リリースビルドを作成する際にデバッグバージョンがすべてのプラットフォームで無効になっていないリスクがあります。

デバッグビルドはリリースビルドに比べて著しいパフォーマンスの低下があります。パフォーマンステストでは必ずQuantumのリリースビルド（およびUnity IL2CPP）を使用してください。これについてはプロファイリングセクションで詳しく説明しています。

開発ビルドには、開発中に役立つアサーション、例外、チェック、およびデバッグ出力が含まれていますが、これはリリース設定では無効になります。例えば：

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

ロギング

Quantumは、シミュレーションコードからログを出力し、その独自のログ出力を生成するための静的Quantum.Logクラスを提供します。

namespace Quantum {
  public unsafe class MyQuantumSystem : SystemMainThread {
    public override void Update(Frame f) {
      Log.Debug($"Updating MyQuantumSystem tick {f.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 ScriptableObjectに見つかるPhoton.Realtime.AppSettingsで制御できます。

AppSettings.NetworkLogging: PhotonPeerおよび接続のためのログレベル。接続関連の問題をデバッグするのに便利です。
AppSettings.ClientLogging: RealtimeClientおよびコールバックのためのログレベル。クライアントの状態、使用しているサーバー、呼び出した操作に関する情報を取得するのに便利です。

開発ビルド以外では、ERROR未満の重大度のRealtimeログは、LOG_WARNING、LOG_INFO、およびLOG_DEBUGを定義しない限りロギングされません。

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

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

Unityプロジェクト内で QuantumDotnetProjectSettings アセットを選択し、検索するシミュレーションソースを定義します。
- 追加の IncludePaths を手動で追加するか、QuantumDotNetInclude Unityアセットラベルでフォルダーをマークします。
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では、QTNファイルに対して他のタイプ（例：C#やMicrosoft Visual C++）と関連付けることで構文ハイライトを追加することができます。これを行うには、Tools -> Options -> Text Editor -> File Extension に移動します。

File Types — .qtnファイルでのDSL構文ハイライト（Visual Studio）。

Visual Studio Code

Visual Studio Codeでも、QTNファイルに対して他のタイプ（例：C#）と関連付けることで構文ハイライトを追加できます。

設定を開きます（Ctrl + , または macOSの場合はCmd + ,）。
「Files: Associations」を検索します。
"*.qtn"を「csharp」として新しいファイル関連付けを追加します。

Visual Studio Code File Association settings — .qtnファイルでのDSL構文ハイライト（Visual Studio Code）。

JetBrains Rider

JetBrains Riderでは、.qtn拡張子を持つDSLファイルに構文ハイライトを追加するために、新しいファイルタイプを定義することができます。

ステップ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