업그레이드 가이드
Unity 5.6으로 업그레이드(Upgrading to Unity 5.6)

자동 API 업데이터 사용(Using the Automatic API Updater)

코드를 왜 업데이트해야 합니까?

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가 사용되지 않는 코드를 추천 업데이트 버전으로 다시 작성합니다.

따라서 다음과 같은 스크립트가 있는 경우

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 업데이터가 제대로 작동하지 않을 수 있습니다.

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

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

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

문제 해결

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

일반적인 원인은 업데이터가 변경 사항을 저장하지 못 했을 경우입니다. 예를 들어 사용자에게 업데이트된 스크립트를 수정할 권한이 없다면 쓰기 보호가 되었을 가능성이 있습니다.

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

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

제한 사항

업데이터가 모든 API 변경사항을 자동으로 고치는 것은 아닙니다. 아래는 업데이터로 고쳐지지 않는 현재의 API 변경사항 리스트입니다.

  • Mesh.GetTriangleStrip() / SetTriangleStrip()
  • TextureImporter: ReadTextureImportInstructions(UnityEditor.TextureImportInstructions, UnityEditor.BuildTarget) -> ReadTextureImportInstructions(UnityEditor.BuildTarget, out UnityEngine.TextureFormat, out UnityEngine.ColorSpace, out System.Int32)
  • InteractiveCloth /SkinnedCloth -> Cloth (전부 불가능)
  • GameObjectUtility: GetNavMeshLayerNames() -> GetNavMeshAreaNames()
  • WWW: WWW(string, byte[], System.Collections.Hashtable) -> WWW(string, byte[], System.Collections.Dictionary)
  • AudioClip: Create(string,int,int,int,bool,bool) -> Create(string,int,int,int,bool)
  • IPackerPolicy: OnGroupAtlases(UnityEditor.BuildTarget, UnityEditor.Sprites.PackerJob, UnityEditor.TextureImporter[]) -> OnGroupAtlases(UnityEditor.BuildTarget, UnityEditor.Sprites.PackerJob, System.Int32[]) (완전히 다른 파라미터 타입)
  • PasteToStateMachineFromPasteboard
  • CopyStateMachineDataToPasteboard
  • AssetBundle: Load (동작이 변경됨)
  • MeshCollider: bool smoothSphereCollisions (제거됨)
  • TerrainData: PhysicMaterial physicMaterial (제거됨)
업그레이드 가이드
Unity 5.6으로 업그레이드(Upgrading to Unity 5.6)