自動 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 で開くと、該当するコードを使用している行は 古くて使用できなくなり、更新が必要になります。

自動アップデーター

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 メニューから以下のように手動で実行することもできます。

コマンドラインモード

コマンドラインから Unity を起動する場合、-accept-apiupdate オプションを使って API Updater を実行させることができます。詳しくは コマンドライン引数 を参照してください。

トラブルシューティング

「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(削除されました)

• 2017–08–07 限られた 編集レビュー で修正されたページ
  
• “accept-apiupdate” コマンドラインオプションを Unity 2017.2 で追加