使いやすさとパフォーマンスを向上させるために、Unity では、クラス、関数、プロパティ (API) の動作方法が変更される場合があります。時には、これらの改善により、ある Unity のメジャーバージョンから別のバージョンに移行する際に、破壊的変更が発生する場合があります。
変更の影響を最小限に抑えるため、API アップデーターは、スクリプトやアセンブリ内の古いコードを特定し、更新します。
API アップデーターは、ScriptUpdater と AssemblyUpdater からなり、それぞれソースコード (スクリプト) とアセンブリ (DLL ファイル) の更新を担当します。
ノート: API アップデーターは、API の特定のエラーや警告のみを修正することができます。これらは、コンソールメッセージに UnityUpgradable と表示されます。API アップデーターが処理できないその他のエラーや警告は、手動で解決する必要があります。
スクリプトのコンパイル が発生すると、API アップデーターが自動的に実行されます。これは、例えば以下のような場合に発生します。
API アップデーターは、検出された古いコードを更新することを提案します。承諾されると API の推奨される更新バージョンで、古いコードを書き換えます。
例えば、API アップデーターは、次のような古いステートメントを変更します。
light.color = Color.red;
上の古いステートメントを以下のように変更します。
GetComponent<Light>().color = Color.red;
Unity がスクリプトコンパイルを起動する場合の API アップデーターのワークフローは、以下の通りです。
エディタースクリプトなど、古いコードを含むスクリプトがさまざまなコンパイルパスに含まれる場合、アップデーターが複数回実行されることがあります。
API アップデーターによるスクリプトの更新を許可しない場合、スクリプトのエラーや警告はコンソールに表示されます。API アップデーターが解決できるエラーや警告は、メッセージに (UnityUpgradable) と表示されます。
スクリプトに他のエラーがあり、API アップデーターを正常に実行できない場合、コンソールにはそのことを知らせるメッセージが表示されます。API アップデーターが更新を完了する前に、これらのエラーを解決する必要があります。
Unity をバッチモードでコマンドラインから実行する場合は、-accept-apiupdate オプションを使用して API アップデーターを実行します。詳細については、コマンドライン引数 を参照してください。
API アップデーターは、アセンブリに加えた変更を エディターログ に記録します。ログを記録する量を制御するには、UNITY_APIUPDATER_LOG_THRESHOLD 環境変数を希望のログしきい値に設定し、Unity を起動します。以下はその例です。
Windows:
c:> set UNITY_APIUPDATER_LOG_THRESHOLD=Debug
c:> \path\to\unity\Unity.exe
Linux:
$ export UNITY_APIUPDATER_LOG_THRESHOLD=Debug
$ /path/to/unity/Unity
Mac:
$ export UNITY_APIUPDATER_LOG_THRESHOLD=Debug
$ /path/to/unity/Unity
ノート: バージョン管理システム を使って、API アップデーターがプロジェクトのスクリプトに加える変更を確認することもできます。
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_APIUPDATER_LOG_THRESHOLD 環境変数の値について説明したものです。
| ログしきい値 | 説明 |
|---|---|
| Error (デフォルト値) | * API アップデーターは Error (エラー) メッセージのみをログに記録します。エラーメッセージは、API アップデーターが、修正する必要がある特定の更新を適用できないときにログに記録されます。(通常、修正するには、アセンブリの元の作成者がアセンブリの更新バージョンを提供することが必要です)。 |
| Warning | API アップデーターは、Warning (警告) および Error (エラー) メッセージを記録します。警告メッセージは、API アップデーターが、ユーザーが確認する必要がある変更を適用したときに記録されます。 |
| Info | API アップデーターは、 Informational (情報)、Warning (警告)、Error (エラー) メッセージを記録します。Info メッセージには、AssemblyUpdater によって適用された更新が含まれます。 |
| Debug | API アップデーターはすべてのメッセージをログに記録します。これは、トラブルシューティングに役立ちます。例えば、API アップデーターに問題があり、それを Unity に報告したい場合などに便利です。 |
API アップデーターがすべての古いコードを更新できなかったことを意味します。これは、ユーザーがスクリプトに対して読み取り専用権限しか持っていない場合など、アップデーターがその変更を保存できない場合に発生する可能性があります。
コンソールで前の行を確認し、アップデート処理中に発生した問題を確認してください。
2018–07–31 修正されたページ
“accept-apiupdate” コマンドラインオプションを Unity 2017.2 で追加
AssemblyUpdaterのログはUnity 2018.3で改善されました NewIn20183