API 업데이터 사용

Unity 소프트웨어를 개발할 때에는 클래스, 함수, 프로퍼티(API)의 동작을 바꾸거나 향상시켜야 할 때가 있습니다. 또한 기존 게임 코드에 미치는 영향을 최소화하려고 노력하지만 전반적 개선을 위해 기존의 것을 완전히 바꿔야 할 때도 있습니다.

하나의 Unity의 주요 버전에서 다른 것으로 이동할 때, 이런 변화가 Unity를 좀더 사용하기 쉽게 만들어 주거나(사용자가 오류를 줄일 수 있다는 의미), 측정할 수 있는 성능 게인을 가져오는 경우에 주의 깊게 대안을 고려한 후 이런 중요한 “변경사항”을 소개하곤 합니다. 하지만 이것의 결과로, 예를 들면 Unity 5에서 Unity 4 프로젝트를 연다면 사용 중이던 스크립트 명령어가 바뀌었거나 제거됐거나 약간 다르게 동작하는 것을 발견합니다.

Unity 5에서 사용자가 게임 오브젝트에서 직접 gameObject.light, gameObject.camera, gameObject.audioSource 등의 공통 컴포넌트 타입을 참조하게 해주던 기능인 “퀵 액세서”를 제거한 것이 그 단적인 예입니다.

Unity 5에서는 사용자가 트랜스폼을 제외한 모든 타입에서 GetComponent 명령을 사용해야 합니다. 따라서 gameObject.light를 사용하는 Unity 4 프로젝트를 Unity 5에서 연다면 코드에서 특정 라인이 사용되지 않아 업데이트가 필요하다는 사실을 발견합니다.

자동 업데이터

Unity는 사용자의 스크립트에서 사용되지 않는 코드의 사용을 감지하고 자동적으로 업데이트를 제공하는 API Updater 기능이 있습니다. 사용자가 동의하면 API의 업데이트된 버전을 사용해 코드를 재작성합니다.

문제가 발생할 때를 대비해 항상 작업을 백업해 두어야 합니다. 특히 소프트웨어가 코드를 다시 쓰도록 할 때에는 특히 더 중요합니다! 백업을 확인한 후 “Go Ahead” 버튼을 클릭하면 Unity가 사용되지 않는 코드를 추천 업데이트 버전으로 다시 작성합니다.

예를 들어 다음과 같은 스크립트가 있을 수 있습니다.

light.color = Color.red;

Unity의 API 업데이터는 이를 아래처럼 변환합니다.

GetComponent<Light>().color = Color.red;

업데이터의 전체적인 워크플로는 다음과 같습니다.

1. 프로젝트를 열고 스크립트를 포함하는 패키지를 임포트하고 사용되지 않는 API를 어셈블리합니다.

2. Unity가 스크립트 컴파일을 시작합니다.

3. API 업데이터가 “업데이트 가능한” 컴파일 오류를 확인합니다.

4. 이전 단계에서 오류가 발견되면 사용자에게 자동 업데이트 또는 종료 다이얼로그를 표시합니다.

5. 업데이트를 수락하면 API 업데이터가 실행됩니다. (2단계에서 컴파일된 것과 동일한 언어로 작성된 전체 스크립트를 업데이트합니다.)

6. 5단계에서 스크립트가 더 이상 업데이트되지 않을 때까지 (업데이트된 코드를 고려) 2단계로 갑니다.

따라서 사용되지 않는 코드를 사용하는 다른 컴파일 패스(예: 다른 언어로 된 스크립트, 에디터 스크립트 등)에서 처리되는 스크립트가 있다면 위의 리스트에서 업데이터가 여러 번 실행되는 것을 볼 수 있습니다.

API 업데이터가 작업을 마치면 콘솔에 다음과 같은 알림이 표시됩니다.

API 업데이터로 스크립트를 업데이트하지 않기로 선택한 경우 콘솔의 스크립트 오류가 평상시처럼 보입니다. 또한 API 업데이터가 자동적으로 업데이트할 수 있는 오류는 오류 메시지에서 (UnityUpgradable)로 표시됩니다.

사용하지 않는 API 외에 스크립트에 다른 오류가 있다면 그 오류를 해결하기 전까지 API 업데이터가 작업을 완전히 완료하지 않습니다. 이 경우 콘솔 창에 다음과 같은 메시지가 나옵니다.

“일부 스크립트에 컴파일 오류가 있어서 사용되지 않는 API 업데이트가 되지 않을 수 있습니다. 사용하지 않는 API 업데이트는 오류가 수정되면 자동으로 재개됩니다.”

스크립트에서 다른 오류를 수정하고나서 API 업데이터를 다시 실행할 수 있습니다. API 업데이터는 스크립트 컴파일이 시작되면 자동으로 실행되지만 다음처럼 Assets 메뉴에서 수동으로 실행할 수도 있습니다.

커맨드 라인 모드

커맨드 라인에서 Unity를 배치 모드로 실행하는 경우 -accept-apiupdate 옵션을 사용하여 API 업데이터를 실행하십시오. 자세한 내용은 커맨드 라인 인자를 참조하십시오.

로깅

버전 관리 시스템을 이용하면 APIUpdater가 프로젝트의 스크립트에 적용하는 변경 사항을 확인할 수 있습니다. 하지만 사전 컴파일된 어셈블리의 경우에는 불가능할 수 있습니다. AssemblyUpdater(어셈블리 업데이트를 담당하는 APIUpdater 컴포넌트)에서 적용한 변경 사항 리스트를 확인하려면 UNITY_ASSEMBLYUPDATE_LOGTHRESHOLD 환경 변수를 올바른 로그 임계값으로 설정하고 Unity를 시작하십시오. 예를 들어, Windows의 경우 다음과 같이 입력할 수 있습니다.

c:> set UNITY_ASSEMBLYUPDATE_LOGTHRESHOLD=Debug

c:> \path\to\unity\Unity.exe

AssemblyUpdater가 작업을 마치면 Editor.log에서 적용된 업데이트를 확인할 수 있습니다.

[AssemblyUpdater] Property access to 'UnityEngine.Rigidbody
UnityEngine.GameObject::get_rigidbody()' in 'System.Void
Test.ClassReferencingObsoleteUnityAPIThroughEditorAssembly::Run()' replaced with 'T
UnityEngine.GameObject::GetComponent<UnityEngine.Rigidbody>()'.

UNITY_ASSEMBLYUPDATE_LOGTHRESHOLD 환경 변수에 대한 유효한 값은 다음과 같습니다(상세한 순서).

• Error: AssemblyUpdater가 Error 메시지만 기록합니다. 오류 메시지는 AssemblyUpdater가 특정 업데이트를 적용하지 못할 때 발생하며, 이 경우 수정 조치를 취해야 합니다(대개 원본 어셈블리 작성자에게 업데이트된 버전의 어셈블리를 제공하도록 요청함).

• Warning: AssemblyUpdater가 Warning 및 Error 메시지만 기록합니다. Warning 메시지는 보통 AssemblyUpdater가 잠재적 문제가 될 수 있는 상태에 도달했음을 나타냅니다. 이러한 문제는 메시지가 기록된 시점에 AssemblyUpdater에 알려지지 않은 조건에 따라 다릅니다.

• Info: AssemblyUpdater가 Informational, Warning, Error 메시지만 기록합니다. 정보 메시지에는 AssemblyUpdater에서 적용한 업데이트 내용이 포함됩니다.

• Debug: AssemblyUpdater가 모든 메시지를 기록합니다. 디버그는 문제 해결에 유용하게 사용할 수 있습니다. AssemblyUpdater 문제가 있고 이를 Unity 보고하려는 경우 임계값을 이 수준으로 설정해야 합니다.

UNITY_ASSEMBLYUPDATE_LOGTHRESHOLD가 설정되지 않은 경우 Error 가 기본값입니다.

문제 해결

“API 업데이트가 실패했습니다. 이전 콘솔 메시지를 확인해주십시오.”라는 메시지는 API 업데이터에 문제가 발생하여 작업을 완료할 수 없다는 의미입니다.

업데이터가 변경 사항을 저장하지 못한 경우에 흔히 발생합니다. 예를 들어 사용자가 쓰기 보호가 설정되어 있어서 업데이트된 스크립트를 수정하지 못할 수 있습니다.

오류 메시지의 지침에 따라 콘솔에서 이전 라인을 체크하면 업데이트 프로세스에서 발생한 문제를 볼 수 있습니다.

제한 사항

API 업데이터는 모든 API 변경 사항을 자동으로 수정할 수 없습니다. 일반적으로 업그레이드 가능한 API는 사용되지 않음을 알리는 메시지에 (UnityUpgradable)라고 표시됩니다. 예:

[Obsolete("Foo 프로퍼티는 지원이 중단되었습니다. Bar 프로퍼티를 사용하십시오. (UnityUpgradable)")]

API 업데이터는 (UnityUpgradable)로 표시된 API만 처리합니다.

스크립트의 업데이트 가능한 API에 컴포넌트 또는 게임 오브젝트 공통 프로퍼티가 포함되어 있고 해당 스크립트가 해당 프로퍼티의 멤버에만 액세스하는 경우에는 API 업데이터가 실행되지 않을 수 있습니다. 공통 프로퍼티의 예로는 renderer와 rigidbody가 있고, 해당 프로퍼티의 멤버 예로는 rigidbody.mass와 renderer.bounds가 있습니다. 이 문제를 해결하려면 스크립트에 더미 메서드를 추가하여 API 업데이터를 트리거하십시오. 예:

private object Dummy(GameObject o) { return o.rigidbody;}.

• 2018–07–31 페이지 수정됨

• Unity 2017.2에서 “accept-apiupdate” 커맨드 라인 옵션 추가

• Unity 2018.3에서 AssemblyUpdater 로그 기능이 향상됨 NewIn20183