업그레이드 가이드
Upgrading to Unity 2018.3 beta

자동 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 버전을 사용해 코드를 재작성합니다.

API 업데이트 다이얼로그
API 업데이트 다이얼로그

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

For example you had a script which did this:


light.color = Color.red;

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


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

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

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

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

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

  4. If any occurrence is found in the previous step, show a dialog to user offering automatic update, otherwise, we’ve finished.

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

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

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

When the API Updater successfully finishes, the console displays the following notification:

Success notification
Success notification

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

API 업데이터가 취소됐을 때 콘솔에 표시되는 오류
API 업데이터가 취소됐을 때 콘솔에 표시되는 오류

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

 스크립트의 다른 오류로 인해 API 업데이터가 제대로 작동하지 않을 수 있습니다.
스크립트의 다른 오류로 인해 API 업데이터가 제대로 작동하지 않을 수 있습니다.

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

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

Assets 메뉴에서 API 업데이터를 수동으로 실행할 수 있습니다.
Assets 메뉴에서 API 업데이터를 수동으로 실행할 수 있습니다.

커맨드 라인 모드

When running Unity in batch mode from the command line, use the -accept-apiupdate option to allow the API Updater to run. For more information, see Command Line Arguments.

Logging

A Version control system helps you see which changes the APIUpdater applies to a Project’s scripts. However, this can be difficult when dealing with pre-compiled assemblies. To see the list of changes made by the AssemblyUpdater (the APIUpdater component responsible for updating assemblies), set the UNITY_ASSEMBLYUPDATE_LOGTHRESHOLD environment variable to the desirable log threshold and start Unity. For example, on Windows you can enter:

c:> set UNITY_ASSEMBLYUPDATE_LOGTHRESHOLD=Debug

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

After AssemblyUpdater has finished, you can see the updates that have been applied in the 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>()'.

The valid values for the UNITY_ASSEMBLYUPDATE_LOGTHRESHOLD environment variable are, in increasing order of detail:

  • Error: The AssemblyUpdater only logs Error messages. Error messages are logged when the AssemblyUpdater fails to apply a specific update, which requires you to take corrective action (usually requesting the original assembly author to provide an updated version of the assembly).

  • Warning: The AssemblyUpdater only logs Warning, and Error messages. Warning messages usually indicate that the AssemblyUpdater has reached a state that could be a potential problem. These problems can depend on conditions not known to the AssemblyUpdater at the point the message was logged.

  • Info: The AssemblyUpdater only logs Informational, Warning, and Error messages. Info messages include updates applied by the AssemblyUpdater.

  • Debug: The AssemblyUpdater logs all messages. Debug help with troubleshooting. You may want to set the threshold to this level if you are having issues with the AssemblyUpdater and you want to report them to Unity.

Error is the default value when UNITY_ASSEMBLYUPDATE_LOGTHRESHOLD is not set.

문제 해결

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

A common cause of this is if the updater was unable to save its changes - For example - the user may not have rights to modify the updated script because it is write protected.

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

이 예제에서 API 업데이터는 스크립트 파일에 쓰기 권한이 없기 때문에 실패했습니다.
이 예제에서 API 업데이터는 스크립트 파일에 쓰기 권한이 없기 때문에 실패했습니다.

제한 사항

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


[Obsolete("Foo property has been deprecated. Please use Bar (UnityUpgradable)")]

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

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


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

  • 2018–07–31 일부 편집 리뷰를 거쳐 페이지 수정됨

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

  • AssemblyUpdater logging improved in Unity 2018.3 NewIn20183

업그레이드 가이드
Upgrading to Unity 2018.3 beta