This document is about: QUANTUM 2
SWITCH TO

Quantum プロジェクト

はじめに

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

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

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

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

Build Configuration
Toggle Build Configuration In Visual Studioでビルド構成を切り替え
Rebuild
Visual Studioで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/QuantumCodeIntegrationquantum_unity/Assets/Photonにコピーします。
3. quantum_unity/Assets/Photon/QuantumCodeディレクトリを作成します。
4. tools/codeintegration_unity/PhotonQuantumCode.asmdeftools/codeintegration_unity/PhotonQuantumCode.asmdef.metaquantum_unity/Assets/Photon/QuantumCode にコピーします。
5. quantum_code/quantum.codeから binobj を除くすべてを 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.csprojPreBuildEventを次のように変更します。

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に移動します。
File Types
JetBrains Riderの`File Types`の設定。
  • ステップ 2: Recognized File Typesのカテゴリーで、右端の+マークを押して、新しいファイルタイプを追加します。
New File Type
JetBrains Riderの`New File Type`ウィンドウ。
  • ステップ 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.
DSL Syntax Highlighting
.QTNファイルにおけるDSLシンタックスハイライティング(JetBrains Rider)。

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ファイル名を明示的に確認するのみのものです。

Locationtools\codegen\quantum.codegen.host.exe
PlatformWindows, Mono
Usagequantum.codegen.host.exe project-folder|project-file
project-folder quantum.code.csprojが所在するフォルダへのパス。このモードは提供されたフォルダにあるすべてのqtnファイルを再帰的に選択します。
project-file quantum.code.csprojが所在するフォルダへのパス。このモードはアイテムとしてリストされたqtnファイルを選択します。:

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

Quantum Unity Codegen

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

Locationtools\codegen_unity\quantum.codegen.unity.host.exe
PlatformWindows, Mono
Usagequantum.codegen.unity.host.exe AssemblyPath OutputDir
AssemblyPathPath to quantum.code.dll file.
OutputDirOutput folder for Unity scripts. Usually quantum_unity\Assets. See default paths and how to customize them below.

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を読み込むことができます。.

Locationtools\codegen_unity\netcoreapp3.1\quantum.codegen.unity.host.exe
PlatformWindows, Linux
Usagequantum.codegen.unity.host.exe --additional-deps AdditionalDepsDir
AssemblyPathPath to quantum.code.dll file.
OutputDirOutput folder for Unity scripts. Usually quantum_unity\Assets. See default paths and how to customize them below.
AdditionalDepsDirAdditional dependencies are required to load the quantum dlls which are usually located in assemblies\release.

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>
Back to top