自動 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;

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

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

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

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

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

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

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

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

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

コマンドラインモード

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

トラブルシューティング

「API Updating failed. Check previous console messages.」というメッセージが表示された場合、 API アップデーターが作業中に問題が発生したということです。

一般的にこの問題はアップデーターが変更した点を保存できなかった場合に起こります。例えば、更新されたスクリプトを修正する権限がユーザーにない場合などです。

コンソールで表示されている行を確認すれば、アップデートプロセスで発生した問題を確認できるはずです。

この例では、 API アップデーターが失敗したのはスクリプトファイルに書き込む権限がないことが原因でした。

制限

API アップデーターは、すべての API の変更を自動的に修正することはできません。一般的に、アップグレード可能な API には、Obsolete (旧型) を示すメッセージ内に (UnityUpgradable) と記されます。以下がその例です。

[Obsolete("Foo property has been deprecated. Please use Bar (UnityUpgradable)")]

API アップデーターは (UnityUpgradable) と記された API のみを処理できます。

スクリプトの唯一の更新可能 API にコンポーネントかゲームオブジェクト共通のプロパティーが含まれており、スクリプトがそれらのプロパティーのメンバーにしかアクセスできない場合、API アップデーターが実行されないことがあります。一般的なプロパティーの例は renderer と rigidbody です。これらのプロパティーのメンバーは rigidbody.mass と renderer.bounds などです。これを回避するには、任意のスクリプトに以下の例のようなダミーのメソッドを追加して、API アップデーターを起動します。

private object Dummy(GameObject o) { return o.rigidbody;}.

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

アップグレードガイド

Unity 2017.3 へのアップグレード