Quantum 프로젝트

소개

Quantum SDK를 전문 워크플로우로 통합하기 위한 배경 정보, 튜토리얼 및 모범 사례입니다.

릴리즈 및 디버그 빌드

Quantum 프로젝트는 dll 및 참조 파일들을 직접 유니티 프로젝트(기본값 QuantumSDK\quantum_unity\Assets\Photon\Quantum\Assemblies\에 출력합니다). Visual Studio(또는 Rider) 에서 선택한 빌드 환경 구성에 따라서 QuantumSDK\assemblies\debug 또는 \release의 dll 이 참조되고 복사됩니다.

debug 에서 release 로 전환하기 위해, 원하는 환경구성으로 Quantum 솔루션을 재빌드합니다.

디버그 빌드를 사용하면 quantum.code.csproj를 디버그하고 중단점을 배치할 수 있습니다. 솔루션을 재구성한 후 실행 중인 유니티 에디터에 Visual Studio(또는 Rider)를 연결합니다.

디버그 빌드에는 릴리스 빌드에 비해 중대한 성능 페널티가 있습니다. 성능 테스트의 경우 항상 Quantum 릴리스 빌드(및 Unity IL2CPP)를 사용합니다. 이에 대한 자세한 내용은 프로파일링 섹션을 참조하세요.

디버그 빌드에는 개발 중에 도움이 되고 릴리스 구성에서 비활성화된 어설션, 예외, 검사 및 디버그 출력이 포함되어 있습니다. 예:

• 예를들어 Log.Debug() 와 Log.Trace()는 Quantum 코드 프로젝트에서 더 이상 로그를 출력하지 않습니다.
• 모든 Draw.Circle() 메소드
• NavMeshAgentConfig.ShowDebugAvoidance 와 ShowDebugSteering 은 더 이상 gizmos를 그릴 수 없습니다.
• 물리학과 같은 낮은 수준의 시스템 내에서의 어설션과 예외는 비활성화됩니다.

Quantum-유니티 코드 통합

유니티에서 Quantum 시뮬레이션 코드를 가져오고 유지하는 방법을 설명하는 안내서입니다.

노트: 다음 절차는 유니티 2019.4 이상이 필요합니다.

퀀텀을 사용하는 기본 방법은 시뮬레이션 코드(quantum_code)를 유니티(quantum_unity)와 완전히 분리하는 것입니다. 이중 솔루션 접근 방식은 모든 사람의 마음에 들지 않으므로 Quantum v2에서는 유니티가 QuantumEditorSettings.MergeWithVisualStudioSolution 로 생성하는 솔루션에 quantum_code 프로젝트를 포함하는 옵션을 도입했습니다. 그러나 유니티 내에 시뮬레이션 코드가 있는 것이 바람직한 사용 사례도 있습니다. 예를 들어, 사용자는 Visual Studio 또는 Rider에 대한 라이센스 없이 시뮬레이션 코드를 수정하고 재구성할 수 있습니다.

이 방법을 사용하도록 프로젝트를 변환할 수 있습니다.

중요: 단방향 변환입니다.

유니티에서 추가/제거하는 모든 파일은 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로 복사합니다.

유니티 프로젝트를 연 후 생성된 코드가 누락되어 컴파일 오류가 발생하는 경우 Quantum/Code Integration/Run All CodeGen 메뉴를 통해 코드젠을 실행합니다.

Gotchas

• PhotonQuantumCode.asmdef가 유니티 어셈블리 참조를 명시적으로 제거합니다. 이는 결정적이지 않은 유니티 코드가 시뮬레이션 코드와 혼합되지 않도록 하기 위함입니다. 이렇게 하면 독립 실행형 프로젝트로 항상 quantum_code로 돌아갈 수 있습니다.

주의: 유니티 어셈블리 포함으로 인해 발생하는 문제는 어떠한 지원도 받지 못합니다.

• "닭이 먼저냐 알이 먼저냐?"라는 문제에 부딪히는 이유가 무엇이든 간에(코드젠이 오래되어 컴파일할 수 없으며 컴파일 오류가 있기 때문에 코드젠을 실행할 수 없음) Quantum/코드 통합 메뉴가 없는 경우(윈도우가 아닌 플랫폼에서는 항상 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 파일은 tools\codegen\quantum.codegen.host.exe를 cs-proj 파일 또는 폴더를 매개 변수로 사용하여 quantum_code.csproj의 사전 빌드 단계로 컴파일됩니다. 다음 두 가지 방법으로 코드젠을 설정할 수 있습니다.

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++)과 연결하여 구문 강조 표시를 추가할 수 있습니다. 이렇게 하려면 도구 -> 옵션 -> 텍스트 편집기 -> 파일 확장으로 이동하십시오.

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: 파일 이름 패턴 카테고리에서, 우측에 있는 + 기호를 누릅니다.
• 단계 7: 유형에 대하여 *.qtn를 입력합니다.

Quantum 코드 생성 도구

Quantum은 quantum.code.dll 컴파일 전후에 실행하는 데 필요한 두 가지 코드 생성 도구를 사용합니다.

컴파일 전: Quantum Codegen (CodeGen.cs)

컴파일 후: Quantum Unity Codegen (유니티 스크립트)

Quantum Codegen

발견된 Qtn 파일을 C# 코드(Core/CodeGen.cs )로 변환하여 Quantum DSL 코드 생성을 실행합니다. 두 가지 모드가 있습니다. 하나는 모든 Qtn 파일을 재귀적으로 선택하는 반면 다른 하나는 csproj 파일의 명시적 이름만 확인합니다.

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

Quantum Unity Codegen

유니티 에셋 스크립트(AssetBase), 편집기, prototype 클래스 및 AOT 컴파일러에 필요한 클래스와 일반 선언이 포함된 AOT 파일을 생성하는 Quantum 코드젠 파트를 실행합니다.

에셋 스크립트 위치 덮어쓰기 및 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="&#xD;&#xA;"/>
  </appSettings>
</configuration>

Quantum Unity Codegen (Netcore)

이 버전의 Quantum codegen 유니티 도구는 netstandard 2.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>