Использование автоматического обновления API

Почему мой код нуждается в обновлении?

Иногда, в процессе разработки программного обеспечения Unity, мы принимаем решение о изменении и улучшении алгоритма работы классов, функций с свойств (API). Мы делаем это с акцентом на минимальном влиянии этих изменений на существующий пользовательский игровой код, но иногда, чтобы сделать что-то лучше, нам приходиться что-то нарушить.

Мы стараемся вводить такие крупные “ломающие что-либо” изменения только при переходе с одной значимой версии Unity к другой, и только в случаях, в которых это делает Unity более простой в использовании (пользователи столкнутся с меньшим количеством ошибок) или в случае значительного выигрыша в производительности и только полсле тщательного рассмотрения альтернатив. Однако, в результате этого, когда вы, например, открываете проект Unity 4 в Unity 5, вы можете обнаружить, что некоторые команды скриптов, которые вы использовали, изменились, исчезли или работают несколько иначе.

Один явный пример этого - это то, что в Unity 5 мы удалили “быстрый доступ”, который позволял вам прямо ссылаться на общие типы компонентов в GameObject, как например, gameObject.light, gameObject.camera, gameObject.audioSource и т.д.

Теперь в Unity 5 вам нужно использовать команду GetComponent для всех типов, кроме Transform. Поэтому, если вы открыли проект Unity 4, который использует gameObject.light в Unity 5, вы обнаружите, что определенные участки кода обозначены, как obsolete и должны быть обновлены.

Автоматическое обновление

Unity has an Automatic Obsolete API Updater which will detect uses of obsolete code in your scripts, and can offer to automatically update them. If you accept, it will rewrite your code using the updated version of the API.

Как всегда очевидно, важно делать резервную копию вашей работы на случай, если что-либо пойдет не так, особенно в случаях, когда вы разрешаете программному обеспечению переписывать ваш код! После того, как вы убедитесь, что сделали резервную копию и нажмете кнопку “Продолжить”, Unity перепишет все участки устаревшего кода в соответствии с рекомендуемой новой версией.

Так, например, если у вас есть скрипт, которые делает следующее:

light.color = Color.red;

Unity API updater преобразует это для вас, чтобы:

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

Общий процесс обновления следующий:

1. Открыть проект / импортировать пакет, содержащий скрипты / сборки с использованием устаревшего API
2. Unity компилирует скрипты
3. Обновление API проверяет наличие ошибок компилятора, которые известны, как “обновляемые”
4. Если имели место случаи в предыдущем шаге, то пользователю отображается диалог с предложением автоматического обновления, в противном случае, процесс заканчивается.
5. Если пользователь принимает обновление, то запускается обновление API (который обновит все скрипты, написанные на том же языке, что и скомпилированные в шаге 2)
6. Переход к шагу 2 (чтобы учесть весь обновленный код) до тех пор, пока не останется никаких обновленных скриптов в шаге 5.

Таким образом, вы можете видеть, что обновление может запускаться множество раз, если есть скрипты, которые компилируются в разных проходах (скрипты на разных языках, скрипты редактора и т.д.), использующие устаревший код.

Когда обновление API успешно закончится, вы получите оповещение в консоли:

Если вы выбрали не разрешать API обновлению обновить ваши скрипты, вы увидите ошибки скриптов в консоли, что будет нормой. Вы также заметите, что ошибки, которые обновление API могло исправить автоматически, помечены (UnityUpgradable) в сообщении об ошибке.

Если в дополнение к устаревшему использованию API, ваши скрипты имеют другие ошибки, то обновление API будет не в состоянии закончить свою работу до исправления таких этих ошибок. В этом случае, вы будете оповещены об этом в окне консоли сообщением типа:

“Некоторые скрипты имеют ошибки компиляции, которые могут не позволить обновить устаревшее использование API. Обновление устаревшего API будет продолжено автоматически после того, как эти ошибки будет исправлены.”

После исправления других ошибок в вашем скрипте, вы сможете снова запустить обновление API. Обновление API будет запущено автоматически при компиляции скриптов, однако, вы можете запустить обновление и вручную из меню Assets, здесь:

Command line mode

When running Unity from the command line, you can use the -accept-apiupdate option to cause the API Updater to run. See Command Line Arguments for more information.

Выявление ошибок

Если вы получили сообщение “Ошибка обновления 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[]) (completely different param type)
• PasteToStateMachineFromPasteboard
• CopyStateMachineDataToPasteboard
• AssetBundle: Load (changed behaviour)
• MeshCollider: bool smoothSphereCollisions (removed)
• TerrainData: PhysicMaterial physicMaterial (removed)

• 2017–08–07 Page amended with limited editorial review
  
• “accept-apiupdate” command line option added in Unity 2017.2