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
中或從中刪除。如果不打算使用該專案,那麼這並不是個問題;如果您打算使用主控台執行器和/或伺服器外掛程式,則您必須自己手動更新專案。
整合步驟
- 刪除
quantum_unity/Assets/Photon/Quantum/Assemblies/quantum.code.dll
- 複製
tools/codeintegration_unity/QuantumCodeIntegration
和tools/codeintegration_unity/QuantumCode
到quantum_unity/Assets/Photon
- 將
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檔案。
位置 | tools\codegen\quantum.codegen.host.exe |
平台 | Windows、Mono |
用途 | quantum.codegen.host.exe project-folder|project-file |
專案-資料夾 | 到quantum.code.csproj所在的資料架的路徑。這個模式將選取在提供的資料夾中以遞迴方式找到的所有qtn檔案。 |
專案-檔案 | quantum.code.csproj檔案的路徑。這個模式將選取明確列為物件的所有qtn檔案:
|
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 檔案的路徑。 |
OutputDir | O針對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