自動APIアップデーターの使用

なぜコードのアップデートが必要なのか

Unity の開発を進めていると、クラス、関数やプロパティーによる（API）動作方式の変更や改善が必要となることがあります。我々はユーザーの書いたコードに極力影響がでないよう努めますが、よりよい物を作るためにこの方針を破らねばならないこともあります。

これらの顕著な変更点は、Unity のメジャーアップデートがあり、仕様がより簡単なものになった場合（発生するエラーが少ないという意味で）か、目覚ましいパフォーマンスの向上がある場合、慎重に考慮を重ねたうえで導入される傾向にあります。そのため、仮に Unity 4 のプロジェクトを Unity 5 で開いた場合、使用していたスクリプトコマンドが変更、削除または動作が少しばかり変更されているかもしれません。

分かりやすい例を Unity 5 で見てみましょう。我々はゲームオブジェクトにアタッチされている一般的なコンポーネントを直接参照できる gameObject.light, gameObject.camera, gameObject.audioSource などの「クイックアクセサ」を撤廃しました。

Unity 5 では、 GetComponent コマンドを transform を除くすべての型に対して使用しなければいけません。したがって gameObject.light を使用している Unity 4 のプロジェクトを Unity 5 で開くと、該当するコードを使用している行では obsolete と表示されており、更新が必要になります。

自動アップデーター

Unity にはスクリプトで旧型のコードを使用しているヶ所を検知する 自動旧型 API アップデーター があり、自動アップデートの提案が可能です。承諾した場合、APIアップデートされたコードで上書きされます。

ご存知のとおり、どこかが上手くいかない可能性を考慮してバックアップを常に取っておくことは重要です。しかし、ソフトウェアにコードの上書きを許可する場合は取り分け注意してください。バックアップを確実に取り、「Go Ahead」ボタンを押したら Unity は旧型のコードをアップデートしたバージョンで上書きします。

そのため、例として以下のようなスクリプトを書いていた場合。

light.color = Color.red;

Unity の API アップデーターは以下のように書き換えます。

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

アップデーターの全体的な動作は以下のとおりです。

1. プロジェクトを開く / スクリプトを含むパッケージのインポート / 旧型 API を使用しているヶ所の整理
2. Unity によるスクリプトのコンパイル
3. API アップデーターが「アップデート可能」のエラーを出しているヶ所をチェック
4. ステップ3で該当するヶ所を発見した場合、自動アップデートを提案するダイアログを表示し、そうでない場合は完了
5. ユーザーがアップデートを承諾した場合、 API アップデーターを実行（これにより、ステップ2でコンパイルされた言語と同じものにすべてのスクリプトを更新します）
6. ステップ5でスクリプトの更新が行われた場合（いかなるアップデートコードも見逃さないよう）ステップ2に戻る

上記のリストを見ると、旧型コードを使用する異なるコンパイルパス（例：異なる言語で書かれたスクリプト、エディタースクリプトなど）に分類されるスクリプトがある場合、アップデーターは複数回実行されるのが分かるでしょう。

API アップデーターが正常に完了した場合、コンソールに以下のような文が表示されるでしょう。

API アップデーターに更新を させなかった 場合、通常はコンソールにスクリプトエラーが出ていると思われます。 API アップデーターによる自動更新が可能なエラーは、エラーメッセージに (UnityUpgradable) と記されます。

旧型 API の使用以外の問題がある場合、 エラーを解決しない限り API アップデーターは作業を完了できないかもしれません。この場合、コンソールウィンドウで以下のようなメッセージが表示されるでしょう。

スクリプトの中には旧型 API アップデートを妨げるコンパイルエラーがあることもあります。旧型 API のアップデートはこれらのエラーを修正した後自動的に継続されます。

スクリプトのエラーを修正すると、 API アップデーターを再度実行できます。 API アップデーターはスクリプトのコンパイルが起こったとき自動的に実行されますが、 Assets メニューから以下のように手動で実行することもできます。

トラブルシューティング

「API Updating failed. Check previous console messages.」というメッセージが表示された場合、 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 (挙動が変更されました)
• MeshCollider: bool smoothSphereCollisions (削除されました)
• TerrainData: PhysicMaterial physicMaterial(削除されました)