2단계. Hive Axyl SDK 설치

Hive Axyl SDK를 설치하려면 Unity 프로젝트를 Hive Axyl 패키지 레지스트리에 연결하고 SDK 런타임을 추가합니다. Hive Axyl SDK는 현재 Unity 엔진만 지원합니다.

1. 설치 전 준비

Hive Axyl SDK를 설치하기 전에 Unity 버전, API 호환성 수준, Scripting Backend 설정을 확인합니다.

Unity 버전: Unity 6 (6000.0 LTS) 이상
Player Settings > Api Compatibility Level: .NET Standard 2.1
Player Settings > Scripting Backend: IL2CPP 권장, Mono 지원

Unity 6 (6000.0 LTS)보다 낮은 버전에서는 레지스트리를 등록해도 Hive Axyl 패키지가 Unity Package Manager 목록에 나타나지 않습니다.

Windows에서 개발하거나 Windows 앱을 빌드한다면 Windows 실행 선행 조건도 준비하세요.

Windows 실행 선행 조건

Windows에서는 앱을 실행할 모든 PC에 Microsoft Visual C++ 2015-2022 재배포 가능 패키지(x64)를 반드시 설치해야 합니다. SDK가 Windows에서 사용하는 네이티브 플러그인이 이 런타임을 요구하기 때문입니다. 런타임이 없으면 SDK 초기화 시점에 HiveAxyl_Core 네이티브 플러그인을 로드하지 못했다는 DllNotFoundException이 발생합니다.

설치 대상: 개발용 PC를 포함해 앱을 실행할 모든 PC
설치 파일: aka.ms/vs/17/release/vc_redist.x64.exe
버전 조건: 2015-2022 통합본

위 파일을 내려받아 앱을 실행할 PC마다 설치하세요. 반드시 2015-2022 통합본이어야 합니다. VCRUNTIME140_1.dll이 2019 이후 배포본부터 포함되므로, 더 예전 재배포 패키지가 이미 설치되어 있어도 초기화는 실패합니다.

네이티브 플러그인은 Unity C# 코드가 아닌 운영체제용 바이너리로 빌드해 패키지에 담은 구성 요소입니다. 이 런타임은 Windows에 기본 포함되어 있지 않고 Unity도 플레이어와 함께 설치하지 않습니다.

DllNotFoundException이 발생해도 패키지에는 플러그인 파일이 정상적으로 들어 있습니다. 누락된 것은 이 파일이 의존하는 런타임입니다.

Note

Steam으로 배포하는 앱은 Steamworks 앱 설정의 재배포 목록에 이 패키지를 넣어 앱과 함께 설치되도록 할 수 있습니다.

2. Unity 프로젝트에 SDK 연결

Unity 프로젝트가 Hive Axyl 패키지를 의존성으로 내려받아 참조하도록 설정합니다. Unity Package Manager(UPM)가 패키지를 프로젝트에 등록하면 공통 런타임과 스크립트 컴파일 환경이 함께 준비됩니다.

Hive Axyl SDK는 Scoped Registry로만 설치합니다. 다른 설치 방식은 지원하지 않습니다. Scoped Registry는 패키지 이름 접두사를 지정해 특정 패키지 저장소를 UPM에 등록하는 방식으로, Packages/manifest.json에 선언합니다. 자세한 내용은 Scoped Registry만 지원하는 이유를 참조하세요.

레지스트리를 등록하고 패키지를 설치하는 방법은 두 가지입니다. 둘 중 하나만 사용하세요. Unity 에디터에서 등록하면 Unity가 Packages/manifest.json에 대신 기록하므로 두 방법의 결과는 같습니다.

방법 1: Unity 에디터에서 레지스트리 등록과 패키지 설치: Unity 에디터의 Project Settings와 Package Manager에서 작업
방법 2: Packages/manifest.json에 레지스트리와 패키지 등록: 텍스트 편집기로 여는 Packages/manifest.json에서 작업

방법 1: Unity 에디터에서 레지스트리 등록과 패키지 설치

Unity 메뉴에서 레지스트리를 등록한 뒤, Package Manager 목록에서 SDK 공통 패키지를 설치합니다.

Unity 에디터에서 Edit > Project Settings > Package Manager를 여세요.
Scoped Registries 아래 +를 선택하세요.
아래 값을 입력하세요.
- Name: Hive Axyl
- URL: https://package.openupm.com
- Scope(s): com.com2usplatform.hiveaxyl
Name은 Unity Package Manager 목록에 표시할 이름이므로 원하는 값을 넣으세요. 이 문서에서는 Hive Axyl을 사용합니다. URL은 Unity 패키지를 공개로 배포하는 레지스트리인 OpenUPM의 주소입니다. Scope(s)에 com.com2usplatform.hiveaxyl을 지정하면 이 접두사로 시작하는 모든 Hive Axyl 패키지를 이 레지스트리에서 찾습니다.
Apply를 선택하세요.
Window > Package Manager를 여세요.
왼쪽 목록에서 My Registries > Hive Axyl을 선택하세요. 등록한 레지스트리가 제공하는 Hive Axyl 패키지 목록이 나타납니다.
SDK 공통 패키지인 com.com2usplatform.hiveaxyl.core를 선택하고 Install을 선택하세요.

7번을 건너뛰어도 다음 단계에서 기능 모듈을 설치할 때 com.com2usplatform.hiveaxyl.core가 함께 설치됩니다. 다만 레지스트리 등록이 정상인지 이 시점에 확인할 수 있으므로 7번을 그대로 따라하세요.

설치할 패키지 이름을 이미 알고 있다면 목록에서 찾지 않고 바로 설치해도 됩니다. Package Manager 왼쪽 위 + > Install package by name…을 선택하고 패키지 이름을 입력하세요.

방법 2: Packages/manifest.json에 레지스트리와 패키지 등록

Unity 프로젝트의 Packages/manifest.json을 텍스트 편집기로 열어 Hive Axyl Scoped Registry와 SDK 공통 패키지를 등록합니다. scopes에 com.com2usplatform.hiveaxyl을 지정하면 이 접두사로 시작하는 모든 Hive Axyl 패키지를 이 레지스트리에서 찾습니다.

manifest.json

{
"scopedRegistries": [
    {
    "name": "Hive Axyl",
    "url": "https://package.openupm.com",
    "scopes": [
        "com.com2usplatform.hiveaxyl"
    ]
    }
],
"dependencies": {
    "com.com2usplatform.hiveaxyl.core": "1.0.0"
}
}

버전 규칙

Hive Axyl 패키지는 릴리스마다 모든 패키지에 같은 버전을 붙여 함께 배포됩니다. 공식 지원하는 구성은 설치한 Hive Axyl 패키지를 모두 같은 릴리스 버전으로 맞춘 조합이므로, 다음 단계에서 기능 모듈을 추가할 때도 com.com2usplatform.hiveaxyl.core와 같은 버전을 사용하세요.

서로 다른 버전의 Hive Axyl 패키지를 섞은 구성은 지원하지 않으며 동작을 보증하지 않습니다. SDK는 설치나 초기화 시점에 패키지 버전이 같은지 검사하지 않습니다. UPM은 패키지 하나에 버전 하나만 설치하므로, 서로 다른 버전을 지정하면 그중 한 버전으로 정리되고 어떤 버전이 선택됐는지는 알려주지 않습니다.

Steam Add-on을 사용할 때 필요한 추가 레지스트리

Steam 로그인 Add-on과 Steam 결제 Add-on을 설치하면 Steamworks 연동 패키지인 com.com2usplatform.hiveaxyl.steamworks가 함께 설치됩니다. 이 패키지는 Steamworks SDK를 C#에서 호출하도록 감싼 외부 패키지 com.rlabrecque.steamworks.net을 의존성으로 요구합니다. 앞에서 등록한 Hive Axyl 레지스트리 항목은 Scope(s)에 지정한 com.com2usplatform.hiveaxyl로 시작하는 패키지만 찾으므로, 이 외부 패키지를 찾을 항목이 따로 필요합니다.

앞에서 사용한 방법 그대로 레지스트리를 하나 더 등록하세요. 방법 1을 사용했다면 방법 1: Unity 에디터에서 레지스트리 등록과 패키지 설치의 1번부터 4번까지를 다시 진행해 아래 값을 입력하세요. 방법 2를 사용했다면 Packages/manifest.json의 scopedRegistries 배열에 아래 값을 가진 항목을 하나 더 추가하세요.

Name: rlabrecque
URL: https://package.openupm.com
Scope(s): com.rlabrecque

Steam 로그인과 Steam 결제를 사용하지 않는 앱은 이 레지스트리를 등록하지 않아도 됩니다.

Scoped Registry만 지원하는 이유

Scoped Registry 외의 방식으로는 네이티브 구성 요소가 빠지거나 Hive Axyl 패키지 간 의존성이 해석되지 않습니다.

Hive Axyl SDK의 네이티브 구성 요소는 배포 패키지에만 들어 있습니다. 따라서 소스 저장소를 Git URL로 직접 참조하는 방식으로는 완전한 SDK를 설치할 수 없습니다.
Hive Axyl 패키지끼리의 의존성을 UPM이 대신 해석해 줍니다. 예를 들어 인증 패키지 하나만 선언해도 그 패키지가 요구하는 com.com2usplatform.hiveaxyl.core를 UPM이 같은 레지스트리에서 함께 내려받습니다.

3. 설치 문제 해결

패키지 목록이 비어 있거나 설치가 실패하면 아래 증상별로 원인을 확인하세요.

레지스트리의 Hive Axyl 패키지 목록이 비어 있음

My Registries에 등록한 레지스트리는 보이지만 Hive Axyl 패키지 목록이 비어 있다면 Unity 버전이 Unity 6 (6000.0 LTS) 이상인지, 현재 네트워크에서 레지스트리 주소에 접근할 수 있는지 확인하세요.

레지스트리 주소 연결 오류

레지스트리 주소에 연결하지 못했다는 오류가 발생하면 레지스트리 주소를 정확히 입력했는지, 현재 네트워크에서 그 주소에 접근할 수 있는지 확인하세요.

Steamworks 외부 패키지를 찾을 수 없음

com.rlabrecque.steamworks.net 패키지를 찾을 수 없다는 오류가 발생하면, Steam Add-on을 사용할 때 필요한 추가 레지스트리에 따라 Scope(s)가 com.rlabrecque인 레지스트리 항목을 등록했는지 확인하세요.

Add-on 기능이 동작하지 않음

Add-on을 설치했는데 해당 기능이 동작하지 않으면, Add-on을 사용할 때 함께 설치할 모듈에 따라 그 Add-on이 확장하는 기능 모듈도 설치했는지 확인하세요.

원인을 해결해도 같은 오류가 반복됨

실패한 결과가 Packages/packages-lock.json에 남아 있으면 원인을 해결해도 같은 오류가 반복됩니다. 이 파일을 삭제하고 Unity를 다시 여세요.

다음 단계

Hive Axyl SDK 인증 모듈을 설치하려면 모듈 설치를 참조하세요.