Quantum プロジェクト

はじめに

特殊なワークフローにQuantum SDKを統合するための背景情報、チュートリアル、ベストプラクティスを集めたものです。

ビルドのリリースとデバッグ

Quantumプロジェクトは、そのDLLと参照を直接Unityプロジェクトに出力します（デフォルトでは QuantumSDKquantum_unity_Assets FilterPhotonQuantumAssemblies ）。Visual Studio (またはRider)で選択されたビルド構成に応じて、QuantumSDKのAssembliesdebugまたはreleaseからDLLが参照およびコピーされます。

debugからreleaseに切り替えるには、希望する構成にQuantumソリューションをリビルドします。

デバッグビルドは quantum.code.csproj をデバッグし、ブレークポイントを置くことができるようになります。ソリューションのリビルド後、Visual Studio (またはRider)を実行中のUnity Editorにアタッチします。

デバッグビルドは、リリースビルドと比較して、重大なパフォーマンス上のペナルティ があります。パフォーマンステストには、常にQuantumリリースビルド (およびUnity IL2CPP) を使用してください。これについては プロファイリング のセクションを参照してください。

デバッグビルドには、開発中に役立つアサーション、例外、チェック、デバッグ出力が含まれています。これらはリリース構成では無効となります。以下がその例です：

• Log.Debug() および Log.Trace()、例えばQuantumコードプロジェクトから呼ばれますが、もうログの出力はおこないません。
• すべての Draw.Circle() メソッドも同様です。
• NavMeshAgentConfig.ShowDebugAvoidanceおよびShowDebugSteeringは、もうギズモを描きません。
• 物理のような低いレベルのシステム内では、アサーションと例外は無効かされています。

Quantum-Unityコードの統合

UnityでQuantumシミュレーションコードをインポートして保持する方法を示すガイドです。

注: この手順には、Unity 2019.4以上が必要です。

Quantumでのデフォルトの作業方法は、シミュレーションコード（quantum_code）をUnity（quantum_unity）から完全に分離することです。二重のソリューションアプローチは誰にでも好まれるものではありません。そこでQuantum v2では、QuantumEditorSettings.MergeWithVisualStudioSolution設定により、quantum_codeプロジェクトをUnityが生成するソリューションに含めるオプションを導入しました。しかし、シミュレーションコードをUnityの内部に持つことが望ましい場合もあります。例えば、Visual StudioやRiderのライセンスがなくても、シミュレーションコードの修正や再構築ができるようになります。

この方法を使うために、プロジェクトを変換することができます。

重要: これは一方通行の変換です。

Unityで追加/削除したファイルは、quantum_code/quantum.code/quantum.code.csprojには追加/削除されません。これは、プロジェクトを使用するつもりがない場合は問題ありませんが、コンソールランナーやサーバープラグインを使用する予定がある場合は、自分で手動でプロジェクトを更新する必要があります。

統合の手順（古い方法）

Unityプロジェクトにファイルをコピーする方法もあります：

1.quantum_unity/Assets/Photon/Quantum/Assemblies/quantum.code.dllを削除します。
2. tools/codeintegration_unity/QuantumCodeIntegrationをquantum_unity/Assets/Photonにコピーします。
3. quantum_unity/Assets/Photon/QuantumCodeディレクトリを作成します。
4. tools/codeintegration_unity/PhotonQuantumCode.asmdefと tools/codeintegration_unity/PhotonQuantumCode.asmdef.metaを quantum_unity/Assets/Photon/QuantumCode にコピーします。
5. quantum_code/quantum.codeから bin と obj を除くすべてを quantum_unity/Assets/Photon/QuantumCode にコピーします。

Gotchas

• PhotonQuantumCode.asmdef は Unity アセンブリの参照を明示的に削除しています。これは非決定論的なUnityのコードがシミュレーションのコードと混ざらないようにするためで、これによりスタンドアロンプロジェクトとしてのquantum_codeに戻る方法が常に確保されます。

N.B.: Unityアセンブリを含めることで発生する問題は、サポートされません。

• もし「ニワトリと卵」のような問題（codegenが古くてコンパイルできない、コンパイルエラーがあってcodegenを実行できない）に遭遇し、Quantum/Code Integrationメニューがない場合は、コンソールを使って手動でcodegenを実行することができます（Windows以外のプラットフォームでは、monoという接頭辞をつけてください）。:
  • tools/codegen/quantum.codegen.host.exe quantum_unity/Assets/Photon/QuantumCode
  • tools/codegen_unity/quantum.codegen.unity.host.exe quantum_unity/Library/ScriptAssemblies/PhotonQuantumCode.dll quantum_unity/Assets

Quantum DSLの統合

ここでは、Quantum DSL ファイルとそのコンパイルをワークフローに統合する方法について説明します。

Qtn ファイルの発見

qtnファイルは、cs-projファイルまたはフォルダを引数にして、tools\codegen\quantum.codegen.host.exeをプリビルドステップとして呼び出すことで、quantum_code.csprojのプリビルドステップとしてコンパイルされます。codegenのセットアップには、2つの方法を推奨しています。

1. (DEFAULT) qtnファイルを quantum_code.csproj に明示的に追加する:。

XML

  <ItemGroup>
    <None Include="Foo\bar.qtn" />
    <None Include="Oof\rab.qtn" />
  </ItemGroup>

PreBuildEventは次のようになります。

python

# win
"$(ProjectDir)..\..\tools\codegen\quantum.codegen.host.exe" "$(ProjectPath)"
# mac
mono "$(ProjectDir)..\..\tools\codegen\quantum.codegen.host.exe" "$(ProjectPath)"

2.もしtools\codegen\quantum.codegen.host.exeがファイルの代わりに呼び出された場合、フォルダ内のすべてのqtn-fileを検索します。

quantum_code.csprojのPreBuildEventを次のように変更します。

python

# win
"$(ProjectDir)..\..\tools\codegen\quantum.codegen.host.exe" "$(ProjectDir)"
# mac
mono "$(ProjectDir)..\..\tools\codegen\quantum.codegen.host.exe" "$(ProjectDir)"

Qtn ファイルのシンタックスハイライティング

QTNファイルのシンタックスハイライトを有効にするには、各IDEのガイドに従ってください。

Visual Studio

Visual Studio では、QTN ファイルを他のタイプ（C# や Microsft Visual C++ など）に関連付けることで、QTN ファイルにシンタックスハイ ライトを追加することができます。これを行うには、Tools -> Options -> Text Editor -> File Extensionに進みます。

JetBrains Rider

JetBrains Riderでは、新しいファイルタイプを定義することで、QTNファイルワにシンタックスハイライトを追加することができます。

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

• ステップ 2: Recognized File Typesのカテゴリーで、右端の+マークを押して、新しいファイルタイプを追加します。

• ステップ 3: 行コメント、ブロックコメントなどの設定を確認してください。
• ステップ 4: そのリストをキーワードレベル1（下記参照）に貼り付けます。

C#

#define
#pragma
abstract
any
array
asset
asset_ref
bitset
button
byte
collision
component
dictionary
entity
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（下記参照）に貼り付けます。

C#

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

• ステップ 6: In the File Name Patterns category, press the + sign at the right.
• ステップ 7: Enter *.qtn as the wildcard for the type.

Quantumコード生成ツール

Quantumは、2種類のコード生成ツールを使用しており、それぞれquantum.code.dllのコンピレーション前後に必要なものとなっています。

コンピレーション前: Quantum Codegen (CodeGen.cs)

コンピレーション後: Quantum Unity Codegen (Unity scripts)

Quantum Codegen

検索したqtnファイルをC#コード(Core/CodeGen.cs)に変換することで、Quantum DSLコード生成を実行します。モードには2通りあり、1つはすべてのqtnファイルを再帰的に選択するものでもう一つはcsprojファイル内のqtnファイル名を明示的に確認するのみのものです。

    <ItemGroup>
        <None Include="Example\Example.qtn"/>
    </ItemGroup>

Quantum Unity Codegen

Quantum codegen パートを実行し、Unity アセットスクリプト (AssetBase)、エディタ、prototype クラス、AOT ファイル（AOT コンパイラに必要なクラスと汎用宣言が含まれています）を生成します。

Overwrite Asset Script Location And Disable AOT File Generation

tools\codegen_unity\quantum.codegen.unity.dll.configファイルを作成します。

XML

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <appSettings>
    <add key="RelativeLinkDrawerFilePath" value="Quantum/Editor/PropertyDrawers/Generated/AssetLinkDrawers.cs"/>
    <add key="RelativeAssetScriptFolderPath" value="Quantum/AssetTypes/Generated"/>
    <add key="RelativeGeneratedFolderPath" value="Quantum/Generated"/>
    <add key="GenerateAOTFile" value="true"/>
    <add key="EndOfLineCharacters" value="&#xD;&#xA;"/>
  </appSettings>
</configuration>

Quantum Unity Codegen (Netcore)

このバージョンのQuantum codegen Unity toolはnetstandard2.0でコンパイルされたquantum.code.dllを読み込むことができます。.

Visual StudioからPostBuildEventとしてセットアップ:

XML

<PostBuildEvent Condition="'$(OS)' == 'Windows_NT'">"$(ProjectDir)..\..\tools\codegen_unity\netcoreapp3.1\quantum.codegen.unity.host.exe" "$(TargetDir)\quantum.code.dll" "$(ProjectDir)..\..\quantum_unity\Assets" --additional-deps "$(ProjectDir)..\..\assemblies\$(Configuration)"</PostBuildEvent>