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

문제가 발생할 때를 대비해 작업을 백업해놓는 것은 언제나 중요한 일이지만 특히 소프트웨어가 코드를 다시 쓰도록 할 때에는 특히 더 중요합니다! 백업을 확인한 후 “승인” 버튼을 클릭하면 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 업데이터를 실행할 수 있습니다. 자세한 내용은 커맨드 라인 인자를 참조하십시오.

문제 해결

“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–06–02 일부 편집 리뷰를 거쳐 페이지 수정됨
  
• Unity 2017.2에서 “accept-apiupdate” 커맨드 라인 옵션 추가