Version: 2021.2
API アップデーター
Upgrading to Unity 2021.1

Upgrading to Unity 2021.2

ノート: このセクションのアドバイスには、リリース順に従ってください。例えば、プロジェクトを 2018 年から 2020 年にアップグレードする必要がある場合、2020 年のアップグレードガイドを読む前に、2019 年のアップグレードガイドを読んで変更すべき点がないかどうかを確認します。

This page lists changes in the Unity 2021.2 version which might affect existing projects when you upgrade from version 2021.1 beta to 2021.2.

環境照明 - アンビエントプローブとスカイボックスリフレクションプローブが自動的にベイクされるように

Unity’s Progressive Lightmapper now automatically generates the ambient probe and the skybox reflection probe for every scene by default. This means that a scene automatically receives environment lighting in accordance with the settings in the Environment tab in the Lighting settings panel. The Editor updates the ambient probe and skybox reflection probe every time the environment lighting changes, until you generate lighting. When you bake with the Generate Lighting control, the Editor stops updating the probes, and only updates them again at the next bake. When you enable the Auto Generate option, the Editor continues to update the probes every time the environment lighting changes. If you generate lighting and then delete this lighting data by removing the Lighting Data Asset from the project, the Editor automatically generates the ambient probe and skybox reflection probe again.

プロジェクトのアップグレードを行う際に、対応が必要な状況があります。これは、プロジェクトに環境ライティングの影響をまったく受けたくない場合で、以下の条件のときです。

  • ライティングデータアセットを持っていない。
  • Auto Generate が有効になっていない。
  • Environment の影響が黒以外の色に設定されている。

このような場合は、Window > Rendering > Lighting Settings > Environment に移動し、以下のいずれかの変更を行って、自動生成されたアンビエントプローブとスカイボックスのリフレクションプローブの環境への影響を無効にし てください。

  • オプション 1: Intensity Multiplier を 0 に設定します。
  • オプション 2: 黒い Skybox Material を使用します。
  • オプション 3: Color または Gradient モードで、 Source に黒色を使用します。

パーティクルシステムの Force Field

以前は、一部の Force Field プロパティが異なるフレームレート (または Time Manager 設定で Time Scale を使用する場合)で異なる動作をすることがありました。

パーティクルシステムは、30fps の基準フレームレートを使用してシミュレーションを行うようになりました。アプリケーションが異なるフレームレートで動作する場合、以下の設定は以前のバージョンの Unity と比較して動作が異なる可能性があります。

  • Gravity
  • Rotation
  • Vector Fields

これらの設定が影響を受ける場合は、望ましい外観になるようにその部分の強度を調整してください。

パーティクルシステムの Start Delay + Rate over Distance 放出

以前は、Rate over Distance 放出は Start Delay の設定を無視していました。現在では、Start Delay 設定が定義されている場合、距離に基づく放出の開始を遅らせることができます。

このフィールドが以前に設定されていた場合、調整が必要な場合があります。

BuildReport - PackedAssets

PackedAssets.file は、直接代替することなく廃止されました。以前は、BuildReport.files に ID またはインデックスを意味する整数が格納されていました。 BuildReport のファイルを検索するには、PackedAssets.shortPath を使用してください。

Terrain API は実験的機能から昇格 (WIP)

実験的な Terrain API は、非実験的な名前空間に移動されました。また、Terrain API にいくつか小さな変更を加えました。実験的な Terrain API を使用していた場合、代わりに以下の API を使用してください。

  • UnityEngine.TerrainTools;
  • UnityEditor.TerrainTools;
  • UnityEngine.TerrainUtils;

以下は、API 変更の全リストです。

  • ほとんどの場合、UnityEngine.Experimental.TerrainAPIUnityEditor.Experimental.TerrainAPI は、それぞれ UnityEngine.TerrainToolsUnityEditor.TerrainTools に変更され ています。ランタイム API の一部は、新しい UnityEngine.TerrainUtils 名前空間に移されています。
  • TerrainPaintTool<T> クラスの GetDesc() は、GetDescription() に名称変更されました。
  • TerrainUtility クラスは UnityEngine.Experimental.TerrainAPI から UnityEngine.TerrainUtils へ移されています。
  • TerrainUtility.TerrainMap クラスは内部クラスではなくなり、UnityEngine.TerrainUtils 名前空間に属します。
  • TerrainMap.TileCoord 構造体は TerrainMap クラスではなくなり、TerrainTileCoord に名称変更され、UnityEngine.TerrainUtils 名前空間に含まれるようになりまし た。
  • UnityEditor.Experimental.TerrainAPI.BrushPreviewMode enum は TerrainBrushPreviewMode に名称変更され、UnityEditor.TerrainTools 名前空間に移されました。
  • TerrainPaintUtilityEditor.BuiltinPaintMaterialPasses enum は TerrainPaintUtilityEditor クラスから UnityEditor.TerrainTools 名前空間に移されました。また、TerrainBuiltinPaintMaterialPasses に名称変更されました。
  • IOnInspectorGUI の 3 つの ShowBrushGUI 関数は、異なるオーバーロードされた関数ではなく、デフォルトのパラメーター値を持つ 1 つの関数に統合されました。
  • TerrainFilter は削除されました。System.Predicate<Terrain> を代わりに使用してください。

Texture2D.Resize は Reinitialize に名称変更

Texture2D.Resize とそのオーバーロードは Texture2D.Reinitialize に名称が変更されました。

API Updater は自動的にこの名前を変更します。そうでない場合は、Texture2D.Resize の使用箇所を Texture2D.Reinitialize に変更してください。

Android の変更点

Android のビルドパイプラインの大部分はインクリメンタルになり、Unity は以前のビルドパイプラインにあった以下の機能を排除しました。

  • Unity は Assets/Plugins/Android/[res, assets] にある Gradle プロジェクトのアセットを Gradle プロジェクトにコピーしなくなりました。
    • 以前は、このフォルダーに Gradle リソースを配置し、Unity がそれらを Gradle プロジェクトにコピーすることができました。現在は、AAR または Android Library プラグイン を使って、アプリケーションに追加の Gradle リソースを渡す必要があります。
    • このフォルダーにプロジェクトアセットを配置すると、Unity はビルドエラーメッセージを表示します。
  • Unity は GENERATED BY UNITY. REMOVE THIS COMMENT TO PREVENT OVERWRITING WHEN EXPORTING AGAIN* コメントの中のファイルを無視しなくなりました。
    • 以前は、このコメントを削除しても、Unity はファイルを上書きしませんでした。コメントを削除しない場合、Unity は常に build.gradle、manifest、UnityPlayerActivity のファイルを再生成していました。
    • 新しいビルドパイプラインを使用して変更を持続させたい場合は、テンプレートを使用てください。
  • Android プロジェクトをエクスポートするとき、Unity は symbols の zip パッケージを作成しなくなりました。シンボルは unityLibrary\symbols ディレクトリにあり、zip で圧縮することができるようになりました。この変更の理由は、プロジェクトをエクスポートしたときにすべてのシンボルファイルが利用できるわけではないからです。Gradle はアプリケーションをビルドするときに libil2cpp.so シンボルを生成します。
  • obb が apk と互換性があるかどうかを確認する方法を変更しました。apk と obb の両方が unity_obb_guid ファイルを持ち、両者のコンテンツが一致すれば、Unity は互換性があるものとして扱います。
  • [PatchPackage(../ScriptReference/BuildOptions.PatchPackage.html) を使用するカスタムのビルドスクリプトの場合、Patch/Patch & Run がすべてのタイプのアセットで動作するようになり、Script Only Build が必要でなくなったことに注意してください。

UI Toolkit - 画像のデフォルトの scaleMode を変更

デフォルトの Image.scaleMode が ScaleAndCrop から ScaleToFit に変更されました。

The expected behavior for an image is to scale to the size of the element, so we changed the default value of Image.scaleMode to ScaleToFit. If you didn’t override the Image scale mode, some cropped images might shrink to fit the size of the element. If ScaleAndCrop was the expected mode for your images, you can override their style by adding the following value in your UXML file inline style:

-unity-background-scale-mode: scale-and-crop;

また、オーバーライドしてスタイルクラスを作成し、ScaleAndCrop を必要とする画像に適用することも可能です。

Mono アップグレードの動作変更

基盤となる C# ランタイム、Mono が最新版にバージョンアップされました。これには、Mono の既存バージョンからの多くの修正と、いくつかの注目すべき動作の変更が含まれています。

  • Directory.GetFiles は、ソートされたリストを返すことが保証しなくなりました。
    • これまでは、常にアルファベット順にソートされたアイテムリストが返されていました。プロジェクトで毎回同じ順序でアイテムを返す必要がある場合は、返されたリストをソートしてください。例えば、次のようになります。nvar files = Directory.GetFiles(dir).OrderBy(f => f);
  • Object.GetHashCode は異なる値を返すようになったので、オペレーティングシステム間の決定論的なハッシュアルゴリズムとして信頼すべきではありません。
    • 一般的に、GetHashCode の結果を現在のプロセスの外部で使用すべきではありません。つまり、シリアル化したり、次に新しいプロセスでコードが実行されたときに同じであることを期待しないでください。Unity では、MD5 のような決定論的なハッシュアルゴリズムを使用することを推奨しています。
  • いくつかのバグフィックスにより、新しい例外がスローされるようになりました。また、一部の例外メッセージの内容が変更されています。
    • この新しい動作は、自動テストのシナリオで特に顕著になり、テストが特定の例外メッセージのログを解析している場合、期待される動作を変更する必要があるかもしれません。

Adaptive Performance

Adaptive Performance パッケージのバージョン 3.0 が使用できるようになりました。バージョン 3.0 へのアップグレードの方法に関しては、Adaptive Performance アップグレードガイド を参照してください。

RenderTexture の DepthStencilFormat

以前は、RenderTexture.depth プロパティを 32 ビットに設定すると、プラットフォームによっては D24_S8 になることがありました。現在、32 ビットに設定すると、現在のプラットフォームでその形式がサポートされている場合、深度コンポーネントに 32 ビットを使用して D32_S8 になります。ただし、この場合、深度バッファのメモリ使用量が 2 倍になります。

新しいRenderTexture.depthStencilFormat プロパティは、グラフィックス API がビデオメモリ内のリソースを作成するために使用する形式を返します。このプロパティを使用して、特定の形式を要求することもできます。ただし、すべてのプラットフォームがすべての深度ステンシル形式をサポートするわけではありません。DepthStencilFormat プロパティをサポートされていない形式に設定すると、Unity は自動的に、深度およびステンシルコンポーネントに同等以上のビット数を持つ、互換性のある形式を選択します。

アップグレード

RenderTexture アセットは、選択した深度ステンシル形式をシリアル化するようになりました。形式の代わりにビット数を受け取る API を使用する場合、これらのビットは形式にマップされ、その形式がシリアラル化されます。深度を 16 ビットより大きく設定した古いバージョンの RenderTexture アセットは、D24_S8 を使用するように自動的にアップグレードされます。

DirectX グラフィックス API を使用する一部のプラットフォーム (Windowsなど) では、16 ビットより大きく設定するとグラフィックスバックエンドが内部で D32_S8 形式を選択するため、深度ビットの少ない形式になります。すべてのプラットフォームで一貫したアップグレードを保証するために、すべてのプラットフォームで自動アップグレードに D24_S8 が使用されています。ただし、プロジェクトに RenderTexture アセットがある場合、プロジェクトのレンダー出力に視覚的なアーティファクトが発生する可能性があります。これらのアセットを確認し、必要に応じて深度ステンシル形式を D32_S8 に変更してください。以下の問題が発生する可能性があります。

  • 使用する RenderTexture によって、メモリサイズが増加する可能性があります。しかし、報告されたメモリは現在正しいものです。
  • 深度プロパティを 32 ビットに設定すると 32 ビットの深度コンポーネントが得られるため、メモリ使用量が増加します。これを避けるには、ビットを 24 に設定し、プラットフォームでサポートされている場合は D24_S8 を使用してください。
  • If a platform doesn’t support D24_S8, Unity falls back to the compatible format D32_S8 by default. To prevent this, in the Inspector window, disable the Enable Compatible Format property on an asset. If Unity doesn’t support the format D32_S8 and it can’t fall back, you see the error message “RenderTexture.Create failed: depth/stencil format unsupported. There is no compatible format on this platform or this fallback to a compatible format is disabled in the import inspector.”. In most cases, to fix the issue you can turn on Enable Compatible Format.

グラフィックス形式 DepthAuto、ShadowAuto、VideoAuto を非推奨に

以下のグラフィックス形式は現在非推奨となっています。

  • DepthAuto
  • ShadowAuto
  • VideoAuto

These “Auto” formats are unclear about the exact format that’s used and might vary by platform.

これらの非推奨形式の使用を廃止する手順は、形式と使用ケースに依存します。

For VideoAuto

To get the current platform’s automatic video format, use SystemInfo.GetGraphicsFormat(DefaultFormat.Video).

For DepthAuto/ShadowAuto used to indicate a depth-only render texture.

GraphicsFormat API では、DepthAuto または ShadowAuto を使用して、深度のみのレンダリング、およびカラーバッファを使用しないレンダーテクスチャを作成することがよくあります。この使用例は以下の通りです。

  • renderTextureDescriptor.graphicsFormat = GraphicsFormat.ShadowAuto
  • RenderTexture.GetTemporary(width, height, bits, GraphicsFormat.ShadowAuto)

深度のみ (カラーなし) のレンダリングを示すには、新しいカラー形式として GraphicsFormat.None を使用します。 renderTextureDescriptor.graphicsFormat = GraphicsFormat.None;

ShadowAuto を使用する場合は、RenderTextureDescriptor の shadowSamplingMode を ShadowSamplingMode.CompareDepths に設定して深度テクスチャの深度比較サンプリングを有効にし、RenderTextureDescriptor を受け取るオーバーロードを使用するようにコードを変更します。 renderTextureDescriptor.shadowSamplingMode = ShadowSamplingMode.CompareDepths;

For DepthAuto/ShadowAuto in other situations

In some situations the DepthAuto/ShadowAuto formats represented an “automatically selected depth format appropriate for the current platform”. To replace the deprecated values in this case, use SystemInfo.GetGraphicsFormat(DefaultFormat.Depth/Shadow)

WebGL: Emscripten を 2.0.19 に更新

上級者向けに提供していた asm.js リンカーターゲットは廃止されました。

  • Unity 2021.2 では、WebGL プラットフォームで使用される基礎となる Emscripten コンパイラーがバージョン 2.0.19 に更新されました。これにより、ネイティブコードのオブジェクトファイル形式がアップグレードされたため、プロジェクト内のすべてのネイティブコードプラグイン (C/C++ コードプラグイン) の再コンパイルが必要になります。例えば、Unity Asset Store からクローズドソースのサードパーティプラグインを使用している場合は、制作者に Unity 2021.2 用のアップデート版を依頼することを忘れないでください。
  • Emscripten ランタイム JavaScript 関数 Pointer_stringify() は、現在非推奨です。代わりに、関数 UTF8ToString() を呼び出して、WebAssembly ヒープから UTF8 エンコードされたヌル終端 (null-terminated) C 文字列を JavaScript 文字列にマーシャリングしてください。

Progressive GPU Lightmapper が CPU OpenCL デバイスサポートを終了

Progressive GPU Lightmapper は、CPU OpenCL デバイスをサポート終了しました。サポートされている GPU が見つからず、CPU OpenCL デバイスが検出される場合、そのデバイスがスキップされ、Progressive CPU Lightmapper にフォールバックされることを警告メッセージが通知します。Progressive CPU Lightmapper は、ライトマップの CPU ベースの計算のパフォーマンスを向上させます。 この動作の変更は自動的に行われ、ライトマップは期待どおりに計算されます。

OnPostprocessAllAssets の動作変更

Unity がアセットインポート処理中に InitializeOnLoad メソッドを呼び出すと、アセットのロードに失敗することがあります。アセットインポート中、アセットデータベースは更新状態にあり、Unity はどのアセットが既にインポートされているかを判断できません。InitializeOnLoad メソッドは、インポートされていないアセットをロードすることはできません。

アセットインポートプロセスを改善するために、OnPostprocessAllAssets コールバックが改善されました。特に、OnPostprocessAllAssets コールバックが強化されています。

  • ドメインリロード後、アセットデータベースの準備状態が保証されている場合に初期化を実行できます。
  • didDomainReload パラメーターを含み、ドメインが再ロードされた場合、true に設定されます。
  • アセット操作をサポートします。これにはアセットのロードも含まれ、メニュー項目によるアセットのロードと同じように動作します。
  • アセットデータベースのインポートループから抜け出しました。コールバック処理は、アセットインポートが完了するまで先送りします。

アセット操作を必要とするドメイン関連の初期化ロジックを OnPostprocessAllAsset コールバックに移動します。InitializeOnLoad メソッド内でアセット操作を実行しません。

以下の動作変更コード例では、以前、アセット操作を先送りにされていたかを示しています。

例 1

public class AssetPostprocessorTester1 : AssetPostprocessor
{
    static void OnPostprocessAllAssets(string[] importedAssets, string[] deletedAssets, string[] movedAssets, string[] movedFromAssetPaths)
    {
        var assetPath = "Assets/hello.txt";

        if (File.Exists(assetPath))
        {
            var txtObj = AssetDatabase.LoadAssetAtPath<TextAsset>("Assets/hello.txt");
            AssetDatabase.DeleteAsset("Assets/hello.txt");

            if (txtObj == null)
                Debug.Log("New Behaviour: Asset object is unloaded");
            else
                Debug.Log("Old Behaviour: Asset is loaded for deleted asset!!");
        }
    }
}

例 2

 public class AssetPostprocessorTester2 : AssetPostprocessor
 {
    static void OnPostprocessAllAssets(string[] importedAssets, string[] deletedAssets, string[] movedAssets, string[] movedFromAssetPaths)
    {
        var assetPath = "Assets/SomeText.txt";
        if (!File.Exists(assetPath))
        {
            File.WriteAllText(assetPath, "hello world");

            AssetDatabase.ImportAsset(assetPath);
            var txtObj = AssetDatabase.LoadAssetAtPath<TextAsset>(assetPath);

            if (txtObj == null)
                Debug.Log("Old Behaviour: Asset hasn't been imported yet");
            else
                Debug.Log("New Behaviour: Asset is imported and loaded");
        }
    }
 }

次の例には、didDomainReloadパラメーターを持つ新しい OnPostprocessAllAssets バリアントが含まれています。

static void OnPostprocessAllAssets(string[] importedAssets, string[] deletedAssets, string[] movedAssets, string[] movedFromAssetPaths, bool didDomainReload)
{
    if (didDomainReload)
        Debug.Log("Domain has been reloaded");
    else
        Debug.Log("Domain did not reload during import");
}

すべてのドメインの再ロードは、アセットデータベース内で処理されるようになりました。

OnPostprocessAllAssets は、アセット操作でよりよく動作するようになりましたが、このコールバックでの処理は、アセットデータベースのリフレッシュとドメインの再ロード時間を増加させます。InitializeOnLoad メソッドもドメインの再ロード時間を増加させます。これらのコールバックでの処理を最小限にすることが、繰り返しの間のエディターの応答性を向上させるためには効率的です。

Mixed モードの影のないポイントライトとスポットライトは Subtractive ライティングモードで直接光をベイク

Mixed mode point and spot lights now consistently contribute baked direct light in Scenes using Subtractive lighting mode, regardless of their Shadow Type setting. As a result, specular lighting for Static GameObjects may appear to be missing in affected Scenes. To resolve this issue, replace affected Mixed mode lights with Realtime mode Lights. Alternatively, use Baked Indirect or Shadowmask lighting mode(s) with Mixed lights.

シェーダーキーワードシステムの改良

シェーダキーワードシステムは、シェーダまたはコンピュートシェーダごとに最大 65534 のローカルキーワードと、プロジェクトごとに 232–2 のグローバルキーワードを使用できるようになりました。シェーダーまたはコンピュートシェーダーで宣言するすべてのキーワードは、このシェーダーに対してローカルになりました。 _local というサフィックスを持つディレクティブで宣言したキー ワードは、グローバルキーワードの状態に影響されません。

シェーダ内のパスは、以下のキーワードを宣言します。

  • #pragma shader_feature FOO BAR
  • #pragma shader_feature_local BOO BAZ

When using this pass, keywords FOO and BAR are enabled if they’re enabled either globally or on the material. Keywords BOO and BAZ are only enabled if they’re enabled on the material.

Unity は .NET Standard 2.1 API をサポート

Unity は、.NET Standard 2.1 API のすべての API を含む、.NET 基本クラスライブラリの多くの追加 API をサポートするようになりました。新しい API と競合するコードがある場合、プロジェクトはコンパイルに失敗する可能性があります。

以前のバージョンの Unity で作成したプロジェクトをアップグレードする際にエラーを避けるために、.NET Standard 2.1 で利用可能になった型やメソッドと競合しないようにコードを確認し、更新してください。

競合の原因としては、以下のようなものがあります。

  • あいまいな参照
  • 拡張メソッド
  • プリコンパイルされたアセンブリ

Resolve ambiguous references

.NET Standard 2.1 が加える型やメソッドと競合する名前を持つ型やメソッドをコードに実装すると、コンパイルに失敗します。名前の競合は、あいまいな参照が原因の C# コンパイラーエラーにつながる可能性があります。

例えば、MyCompany.MyCode.Range という型をプロジェクトのコードに加える場合、既存の System.Range 型と競合する可能性があります。using System;using MyCompany; の両方のステートメントを含むコードは、コンパイルに失敗します。

エラーを防ぐため、C# のコードでは、名前が競合する型については、すべて名前空間を指定してください。

Resolve conflicting extension methods

既存のコードに .NET Standard 2.1 が直接型に実装した拡張メソッドがある場合、拡張メソッドの名前を変更するか、基本クラスライブラリで実装されたメソッドを使用するかを選択できます。

例えば、プロジェクトのコードは、ArraySegment 型に CopyTo という拡張メソッドを実装したとします。.NET Standard 2.1 では、ArraySegment にビルトインの CopyTo というメソッドがあります。この場合、CopyTo 拡張メソッドの名前を変更するか、または、完全にそれを削除してビルトインのメソッドを使用するかを選択できます。

Resolve conflicting assemblies

もしプロジェクトが、現在基本クラスライブラリの一部となっている型やメソッドを実装したプリコンパイルされたアセンブリ (つまりマネージプラグイン) を使用している場合は、プロジェクトからこれらのアセンブリを削除してビルトインの実装を使用するようにしてください。

例えば、Unity の以前のバージョンでは、System.Span 値の型にアクセスするために、NuGet から System.Memory.dll アセンブリを使用する必要がありました。現在、.NET Standard 2.1 では、基本クラスライブラリで System.Span が提供されています。 System.Memory.dll マネージプラグインを Unity 2021.2 で使用しようとすると、プロジェクトはビルドに失敗します。

Windows XR プラグインを削除

Microsoft は、Windows XR プラグインを非推奨とし、OpenXR プラグインを通じて Windows Mixed Reality (WMR) 機能とデバイスをサポートするようになりました。

  • Windows XR プラグインは、Unity 2021.2 で削除されました。
  • Unity 2021.2 で既存のプロジェクトを開くと、アップデート処理により Windows XR プラグインが存在する場合は削除されます。
  • Windows Mixed Reality 用のプロジェクトを継続して使用するためには、Unity OpenXR プラグインを有効にする必要があります。
  • Depending on which features you are using, you must also install Microsoft’s Mixed Reality OpenXR support plugin and possibly additional tools from the Microsoft Mixed Reality Toolkit.

Unity OpenXR プラグインにアップグレードする場合は、以下を行います。

  1. Project Settings ウィンドウを開きます。
  2. XR Plug-in Management セクションの Plug-in Providers リストで、OpenXR を有効にします。 必要に応じて、OpenXR プラグインをダウンロードしインストールします。

OpenXR プラグインが有効になると、Microsoft が提供する Mixed Reality Feature Tool を使って、必要なサポートパッケージをインストールできます。

WMR の機能、ツール、サンプルをインストールまたはアップデートするには、以下を行います。

  1. Mixed Reality Feature Tool をダウンロードし、実行します。
  2. アップデートする Unity プロジェクトを選択し、Discover Features をクリックします。
  3. Platform Support で、Mixed Reality OpenXR Plugin を選択します。
  4. 追加したい機能があれば選択します。
  5. Get features をクリックします。
  6. Import、Approve の順にクリックして、処理を完了します。
  7. Unity Project Settings の XR Plug-in Management セクションに戻り、追加された機能を有効にして設定します。

Windows Mixed Reality を使用するための Unity プロジェクトの新規および更新の設定については、Microsoft のドキュメントサイトの Setting up your XR configuration を参照してください。

API アップデーター
Upgrading to Unity 2021.1