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] ボタンを押すと、古いコードは新しい推奨されたバージョンで上書きされます。

例えば、以下のようなスクリプトがあったとします。

light.color = Color.red;

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

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

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

1. 古い API を使用した スクリプト/アセンブリを含むプロジェクトを開く、または、そのようなスクリプト/アセンブリをを含むパッケージをインポートします。

2. Unity がスクリプトのコンパイルを始めます。

3. API アップデーターが「更新可能」であるコンパイラーエラーをチェックします。

4. 前の手順で可能なアップデートが見つかった場合は、ユーザーに自動更新のためのダイアログを表示します。そうでない場合は終了します。　

5. ユーザーがアップデートを承諾すると、 API アップデーターが実行されます (これにより、ステップ 2 でコンパイルされたものと同じ言語で書かれたすべてのスクリプトが更新されます)。

6. 5 でスクリプトの更新が行われなくなるまで (更新されたコードがすべて検討されるよう) 2 に戻る

この手順では、異なるコンパイルパス (例えば、異なる言語で書かれたスクリプト、エディタースクリプトなど) に分類されるスクリプトがある場合、アップデーターは複数回実行される場合があります。

API アップデーターが正常に終了すると、コンソールに以下の通知が表示されます。

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

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

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

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

コマンドラインモード

Unityをバッチモードでコマンドラインから実行する場合は、 -accept-apiupdateオプションを使用して APIアップデーターを実行します。詳細については、コマンドライン引数 を参照してください。

ロギング

バージョン管理 システムは、APIUpdaterがプロジェクトのスクリプトに適用する変更を確認するのに役立ちます。ただし、事前コンパイルされたアセンブリを処理することが、難しい場合があります。AssemblyUpdater (アセンブリの更新を担当するAPIUpdaterコンポーネント) によって加えられた変更のリストを表示するには、UNITY_ASSEMBLYUPDATE_LOGTHRESHOLD 環境変数に望ましいログを出力するための値を設定して Unity を開始します。例えば、Windows では以下を入力します。

c:> set UNITY_ASSEMBLYUPDATE_LOGTHRESHOLD=Debug

c:> \path\to\unity\Unity.exe

AssemblyUpdater が終了した後、Editor.log に適用された更新が表示されます。

[AssemblyUpdater] Property access to 'UnityEngine.Rigidbody
UnityEngine.GameObject::get_rigidbody()' in 'System.Void
Test.ClassReferencingObsoleteUnityAPIThroughEditorAssembly::Run()' replaced with 'T
UnityEngine.GameObject::GetComponent<UnityEngine.Rigidbody>()'.

UNITY_ASSEMBLYUPDATE_LOGTHRESHOLD環境変数の有効な値は、ディテールの昇順になります。

• Error: AssemblyUpdaterは Error メッセージのみをログに記録します。エラーメッセージは、AssemblyUpdaterが特定の更新を適用できないときにログに記録されます。これを行うには、修正する必要があります(通常、元のアセンブリの作成者にアセンブリの更新バージョンを提供することを要求します)。

• Warning: AssemblyUpdater は Warning と Error メッセージのみをログに記録します。警告メッセージは通常、AssemblyUpdater が潜在的な問題の可能性のある状態に達したことを示しています。これらの問題は、メッセージがログされた時点で AssemblyUpdater が認識できない条件に依存します。

• Info: AssemblyUpdaterは Informational、Warning、Error メッセージのみをログに記録します。情報メッセージには、AssemblyUpdaterによって適用される更新が含まれます。

• Debug: AssemblyUpdaterはすべてのメッセージを記録します。トラブルシューティングに関するデバッグヘルプAssemblyUpdaterに問題があり、それらをUnityに報告したい場合は、しきい値をこのレベルに設定します。

Error は、 UNITY_ASSEMBLYUPDATE_LOGTHRESHOLDが設定されていない場合のデフォルト値です。

トラブルシューティング

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

これの一般的な原因は、アップデーターが変更を保存できなかった場合です。例えば、書き込み制限されているため、更新されたスクリプトの変更権限がユーザーにない場合があります。

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

制限

API アップデーターは、すべての API の変更を自動的に修正することはできません。一般的に、アップグレード可能な API には、古い API であることを示すメッセージ内に (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–07–31 修正されたページ

• “accept-apiupdate” コマンドラインオプションを Unity 2017.2 で追加

• AssemblyUpdaterのログはUnity 2018.3で改善されました NewIn20183