アップグレードガイド
Unity 2018.3 へのアップグレード

自動 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 は旧型のコードをアップデートし、上書きします。

For example you had a script which did this:


light.color = Color.red;

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


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

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

  1. プロジェクトを開く / スクリプトを含むパッケージのインポート / 旧型 API を使用している箇所の整理

  2. Unity によるスクリプトのコンパイル

  3. API アップデーターが「アップデート可能」のエラーを出している箇所をチェック

  4. If any occurrence is found in the previous step, show a dialog to user offering automatic update, otherwise, we’ve finished.

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

  6. ステップ5でスクリプトの更新が行われた場合(すべてのアップデートコードも見逃さないよう)ステップ2に戻る

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

When the API Updater successfully finishes, the console displays the following notification:

Success notification
Success notification

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

APIアップデーターをキャンセルした場合にコンソールに表示されるエラー
APIアップデーターをキャンセルした場合にコンソールに表示されるエラー

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

他にエラーがあると API アップデーターの正常動作が妨げられます
他にエラーがあると API アップデーターの正常動作が妨げられます

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

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

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

コマンドラインモード

When running Unity in batch mode from the command line, use the -accept-apiupdate option to allow the API Updater to run. For more information, see Command Line Arguments.

Logging

A Version control system helps you see which changes the APIUpdater applies to a Project’s scripts. However, this can be difficult when dealing with pre-compiled assemblies. To see the list of changes made by the AssemblyUpdater (the APIUpdater component responsible for updating assemblies), set the UNITY_ASSEMBLYUPDATE_LOGTHRESHOLD environment variable to the desirable log threshold and start Unity. For example, on Windows you can enter:

c:> set UNITY_ASSEMBLYUPDATE_LOGTHRESHOLD=Debug

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

After AssemblyUpdater has finished, you can see the updates that have been applied in the 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>()'.

The valid values for the UNITY_ASSEMBLYUPDATE_LOGTHRESHOLD environment variable are, in increasing order of detail:

  • Error: The AssemblyUpdater only logs Error messages. Error messages are logged when the AssemblyUpdater fails to apply a specific update, which requires you to take corrective action (usually requesting the original assembly author to provide an updated version of the assembly).

  • Warning: The AssemblyUpdater only logs Warning, and Error messages. Warning messages usually indicate that the AssemblyUpdater has reached a state that could be a potential problem. These problems can depend on conditions not known to the AssemblyUpdater at the point the message was logged.

  • Info: The AssemblyUpdater only logs Informational, Warning, and Error messages. Info messages include updates applied by the AssemblyUpdater.

  • Debug: The AssemblyUpdater logs all messages. Debug help with troubleshooting. You may want to set the threshold to this level if you are having issues with the AssemblyUpdater and you want to report them to Unity.

Error is the default value when UNITY_ASSEMBLYUPDATE_LOGTHRESHOLD is not set.

トラブルシューティング

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

A common cause of this is if the updater was unable to save its changes - For example - the user may not have rights to modify the updated script because it is write protected.

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

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

制限

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


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

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

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


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

  • 2018–07–31 限られた 編集レビュー で修正されたページ

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

  • AssemblyUpdater logging improved in Unity 2018.3 NewIn20183

アップグレードガイド
Unity 2018.3 へのアップグレード