Quantum Project

概述

以下是一系列的背景資訊、教學課程和最佳做法，來自訂 Quantum SDK整合，並放到特製化的工作流程中。

版本和偵錯組建

Quantum專案將其dll檔和參照直接輸出到Unity專案中（預設為QuantumSDK\quantum_unity\Assets\Photon\Quantum\Assemblies\）。根據在Visual Studio（或Rider）中選擇的組建設定，參照和複製來自QuantumSDK\assemblies\debug或\release的dll檔。

要從debug組建切換到release組建，請使用所需的設定重新組建Quantum解決方案。

偵錯組建將可以偵錯quantum.code.csproj和放置中斷點。在重新組建解決方案後，將Visual Studio（或Rider）附加到正在運行的Unity編輯器。

與版本組建相比，偵錯組建具有明顯的負面效能影響。對於效能測試，請始終使用Quantum版本組建（和 Unity IL2CPP）。在分析章節中閱讀有關此內容的更多資訊。

偵錯組建包含判斷提示、例外狀況、檢查和偵錯輸出，它們在開發過程中提供幫助，且在版本設定中被停用。例如：

• Log.Debug()和Log.Trace()，例如從Quantum程式碼專案中調用，將不再輸出紀錄。
• 以及所有的Draw.Circle()方法。
• NavMeshAgentConfig.ShowDebugAvoidance和ShowDebugSteering將不再繪製Gizmos。
• 像物理等低層級系統中的判斷提示和例外狀況被停用。

Quantum-Unity程式碼整合

在Unity中匯入和保存Quantum模擬程式碼的示範指南。

請注意： 該程序需要Unity 2019.4及更高版本。

以Quantum工作的預設方式是讓模擬程式碼(quantum_code)與Unity(quantum_unity)完全分離。雙重解決方案方法並不是每個人都喜歡，因此在Quantum v2中，我們引進了另一個選項，以在Unity使用QuantumEditorSettings.MergeWithVisualStudioSolution設定來生成的解決方案中去包含quantum_code專案。但是，仍有一些案例可能需要在Unity內部有模擬程式碼。例如，它允許使用者在沒有Visual Studio或Rider授權的情況下修改和重新組建模擬程式碼。

您可以轉換您的專案，以使用這種方法。

重要： 這是一種單向轉換。

您在Unity中新增／刪除的任何檔案都不會新增到quantum_code/quantum.code/quantum.code.csproj中或從中刪除。如果不打算使用該專案，那麼這並不是個問題；如果您打算使用主控台執行器和／或伺服器外掛程式，則您必須自己手動更新專案。

整合步驟

1. 刪除quantum_unity/Assets/Photon/Quantum/Assemblies/quantum.code.dll
2. 複製tools/codeintegration_unity/QuantumCodeIntegration和tools/codeintegration_unity/QuantumCode到quantum_unity/Assets/Photon
3. 將quantum_code/quantum.code中的所有內容（bin、obj和Properties目錄除外）複製到quantum_unity/Assets/Photon/QuantumCode

如果在打開Unity專案後，由於缺少已生成的程式碼而導致編譯錯誤，請透過 Quantum/Code Integration/Run All CodeGen選單運行CodeGen。

Gotchas

• PhotonQuantumCode.asmdef明確刪除Unity組件參照。這是為了確保非確定性的Unity程式碼不會與模擬程式碼混合；這確保了作為一個獨立專案總有辦法回到 quantum_code。

請注意： 包含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檔案將作為quantum_code.csproj的預先組建步驟進行編譯，這是透過調用tools\codegen\quantum.codegen.host.exe作為預先組建步驟，並使用cs-proj檔案或一個資料夾作為參數。我們推薦兩種方式來設定CodeGen：

1.（預設）將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檔案。

將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#或Microsoft 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步： 在File Name Patterns分類中，按右側的+號。
• 第7步： 輸入*.qtn作為該類型的萬用字元。

Quantum程式碼生成工具

Quantum使用了兩個程式碼生成工具，它們需要在quantum.code.dll編譯之前和之後運行。

編譯前：Quantum CodeGen (CodeGen.cs)

編譯後：Quantum Unity CodeGen（Unity指令碼）

Quantum Codegen

將找到的qtn檔案轉換為C#程式碼(Core/CodeGen.cs)，來執行Quantum DSL程式碼生成。有兩種模式，一種以遞迴方式選擇所有qtn檔案，而另一種只檢查csproj檔案中明確命名的qtn檔案。

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

Quantum Unity Codegen

運行Quantum Codegen產生Unity資產指令碼(AssetBase)、編輯器、prototype類別和AOT檔案的部分，其中包括針對AOT編譯器的必要類別和泛型宣告。

覆寫資產指令碼位置並停用AOT檔案生成

建立檔案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="\r\n"/>
  </appSettings>
</configuration>

Quantum Unity Codegen (Netcore)

此版本的Quantum Codegen Unity工具將能夠載入使用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>