アップグレードガイド
Upgrading to Unity 2018.1

自動 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 がアップデートされたコードで上書きされます。

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 アップデーターの正常動作が妨げられます

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

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

API アップデーターは Assets メニューから手動実行することもできます。
API アップデーターは Assets メニューから手動実行することもできます。

コマンドラインモード

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

トラブルシューティング

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

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