Usando la Actualización Automática del API

¿Por qué mi código necesita ser actualizado?

Algunas veces, durante el desarrollo del software de Unity, tomamos la decisión de cambiar y mejorar la manera en que las clases, funciones y propiedades (el API) funcionan. Hacemos esto con un esfuerzo en causar el menor impacto sobre el código existente de los usuarios. Pero algunas veces, para hacer las cosas mejor, tenemos que romper cosas.

We tend to only introduce these significant “breaking changes” when moving from one significant version of Unity to another, and only in cases that it makes Unity easier to use (meaning users will incur fewer errors) or brings measurable performance gains, and only after careful alternative consideration. However, the upshot of this is that if you were to - for example - open a Unity 4 project in Unity 5, you might find some of the scripting commands that you used have now been changed, removed, or work a little differently.

One obvious example of this is that in Unity 5, we removed the “quick accessors” which allowed you to reference common component types on a GameObject directly, such as gameObject.light, gameObject.camera, gameObject.audioSource, etc.

In Unity 5, you now have to use the GetComponent command for all types, except transform. Therefore if you open a Unity 4 project that uses gameObject.light in Unity 5, you will find that particular line of code is obsolete and needs to be updated.

The automatic updater

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.

Obviously, as always, it’s important to have a backup of your work in case anything goes wrong, but particularly when you’re allowing software to rewrite your code! Once you’ve ensured you have a backup, and clicked the “Go Ahead” button, Unity will rewrite any instances of obsolete code with the recommended updated version.

Entonces, si por ejemplo usted tuviera un script que hiciera esto:

light.color = Color.red;

Unity’s API updater would convert that for you to:

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

El flujo de trabajo en general del updater es como sigue:

1. Abra un project / importe un paquete que contenga scripts / assemblies con uso de API obsoleto
2. Unity activa una compilación script
3. El API updater revisa por errores de compilación en partículas que son conocidos como “updatable” (actualizables)
4. If we find any occurrence in previous step, show a dialog to user offering automatic update, otherwise, we’ve finished.
5. If user accepts the update, then run API updater (which will update all scripts written in the same language being compiled in step 2)
6. Go to step 2 (to take any updated code into account) until no scripts get updated in step 5

So, from the list above you can see the updater may run multiple times if there are scripts which fall into different compilation passes (Eg, scripts in different languages, editor scripts, etc) that use obsolete code.

When the API Updater finishes successfully, you will get a notification in the console, like this:

If you choose not to allow the API updater to update your scripts, you will see the script errors in your console as normal. You will also notice that the errors which the API Updater could update automatically are marked as (UnityUpgradable) in the error message.

If your script has other errors, in addition to obsolete API uses, the API updater may not be able to fully finish its work until you have fixed the other errors. In this case, you’ll be notified in the console window with a message like this:

“Some scripts have compilation errors which may prevent obsolete API usages to get updated. Obsolete API updating will continue automatically after these errors get fixed.”

Once you have fixed the other errors in your script, you can run the API updater again. The API updater runs automatically when a script compilation is triggered, but you can also run it manually from the Assets menu, here:

Solución de Problemas

If you get a message saying “API Updating failed. Check previous console messages.” this means the API updater encountered a problem that prevented it from finishing its work.

A common cause of this is if the updater was unable to save its changes - if for example - the user does not have rights to modify the updated script. It might be write protected, for instance.

By checking the previous lines in the console as instructed, you should be able to see the problems that occurred during the update process.

Limitaciones

No todo cambio de la API puede ser arreglado automáticamente por el actualizador. Abajo hay una lista de los cambios actuales del API que no pueden ser arreglados por el actualizador:

• Mesh.GetTriangleStrip() / SetTriangleStrip()
• TextureImporter: ReadTextureImportInstructions(UnityEditor.TextureImportInstructions, UnityEditor.BuildTarget) -> ReadTextureImportInstructions(UnityEditor.BuildTarget, out UnityEngine.TextureFormat, out UnityEngine.ColorSpace, out System.Int32)
• InteractiveCloth /SkinnedCloth -> Cloth (No es posible en absoluto.)
• 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[]) (un tipo de parámetro completamente diferente)
• PasteToStateMachineFromPasteboard
• CopyStateMachineDataToPasteboard
• AssetBundle: Load (cambio de comportamiento)
• MeshCollider: bool smoothSphereCollisions (quitado)
• TerrainData: PhysicMaterial physicMaterial (quitado)