This document is about: QUANTUM 2
SWITCH TO

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解決方案。

Build Configuration
在Visual Studio中切換組建設定
Rebuild
在Visual Studio中重新組建Quantum解決方案

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

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

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

  • Log.Debug()Log.Trace(),例如從Quantum程式碼專案中調用,將不再輸出紀錄。
  • 以及所有的Draw.Circle()方法。
  • NavMeshAgentConfig.ShowDebugAvoidanceShowDebugSteering將不再繪製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/QuantumCodeIntegrationtools/codeintegration_unity/QuantumCodequantum_unity/Assets/Photon
  3. quantum_code/quantum.code中的所有內容(binobjProperties目錄除外)複製到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.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#或Microsoft 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步:File Name Patterns分類中,按右側的+號。
  • 第7步: 輸入*.qtn作為該類型的萬用字元。
DSL Syntax Highlighting
在.QTN檔案中的DSL語法醒目提示(JetBrains Rider)。

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檔案。

位置tools\codegen\quantum.codegen.host.exe
平台Windows、Mono
用途quantum.codegen.host.exe project-folder|project-file
專案-資料夾到quantum.code.csproj所在的資料架的路徑。這個模式將選取在提供的資料夾中以遞迴方式找到的所有qtn檔案。
專案-檔案quantum.code.csproj檔案的路徑。這個模式將選取明確列為物件的所有qtn檔案:

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

Quantum Unity Codegen

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

位置tools\codegen_unity\quantum.codegen.unity.host.exe
平台Windows、Mono
用途quantum.codegen.unity.host.exe AssemblyPath OutputDir
組件路徑quantum.code.dll檔案的路徑。
OutputDir針對Unity指令碼的輸出資料夾。通常為quantum_unity\Assets。請見下方的預設路徑及如何自訂他們。

覆寫資產指令碼位置並停用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。

位置tools\codegen_unity\netcoreapp3.1\quantum.codegen.unity.host.exe
平台Windows、Linux
用途quantum.codegen.unity.host.exe --additional-deps AdditionalDepsDir
組件路徑quantum.code.dll檔案的路徑。
OutputDirO針對Unity指令碼的輸出資料夾。通常為quantum_unity\Assets。請見下方的預設路徑及如何自訂他們。
AdditionalDepsDir需要額外的相依性來載入Quantum dll,其通常位於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