WebGL プロジェクトのビルドと実行
Build フォルダーには、以下のファイルが含まれています ([ExampleBuild] は、ターゲットのビルドフォルダーの名を表します)。
| ファイル名 | 含まれるもの |
|---|---|
[ExampleBuild].loader.js |
Unity のコンテンツをロードするためにウェブページが必要とする JavaScript のコード。 |
[ExampleBuild].framework.js |
JavaScript のランタイムとプラグイン。 |
[ExampleBuild].wasm |
WebAssembly バイナリ。 |
[ExampleBuild].mem |
プレイヤーのヒープメモリを初期化するためのバイナリイメージ。Unity はマルチスレッドの WebAssembly ビルドのみに対してこのファイルを生成します。 |
[ExampleBuild].data |
アセットデータとシーン。 |
[ExampleBuild].symbols.json |
エラーのスタックトレースを解除するのに必要なデバッグシンボル名。このファイルは、Debug Symbols オプション (File > Build Settings > Player Settings) を有効にする場合、リリースビルドに対してのみ生成されます。 |
[ExampleBuild].jpg |
ビルドのロード中に表示される背景画像。このファイルは、Player 設定 (File > Build Settings > Player Settings > Splash Image) で Background Image が指定されている場合にのみ生成されます。詳しくはスプラッシュスクリーンのページを参照してください。 |
ビルドに対して Compression Method を有効にする場合、Unity は圧縮方法に対応する拡張子を識別し、Build サブフォルダー内のファイル名にこの拡張子を追加します。Decompression Fallback を有効にする場合、Unity はビルドのファイル名に .unityweb という拡張子を追加します。それ以外の場合、Unity は、Gzip 圧縮方式の場合は .gz、Brotli圧縮方式の場合は .br という拡張子を加えます。
詳細については、WebGL: 圧縮ビルドとサーバー設定 を参照してください。
Name Files As Hashes (Player 設定 内) を有効にすると、Unity はデフォルトのファイル名の代わりに、ファイルコンテンツのハッシュを使用します。これは、ビルドフォルダー内の各ファイルに適用されます。このオプションにより、ゲームビルドの更新版をサーバー上の同じフォルダーにアップロードし、ビルドの反復の間に変更されたファイルのみをアップロードすることができます。
WebGL Player をローカルに表示するには、Unity の Build And Run オプション (File > Build And Run) を使用するのが一番です。Unity はローカルのウェブサーバーを使ってビルドをホストし、ローカルホストの URL からそれを開きます。また、レスポンスヘッダーを適切に設定したカスタムのローカルウェブサーバーを使用することもできます。レスポンスヘッダーの設定については、WebGL: 圧縮ビルドとサーバー設定 を参照してください。
ノート: ファイルシステムから直接プレイヤーを開くと、ブラウザーによっては動作しないことがあります。これは、ローカルファイルの URL に適用されるセキュリティ制限によるものです。
ビルド設定
WebGL のビルド設定にアクセスするには、Build Settings ウィンドウ (File > Build Settings) を開きます。次に、Platform リストから WebGL を選択します。
Development Build
Development Build を有効にすると、プロファイラーサポートとデベロッパーコンソールが含まれる開発ビルドが生成され、アプリケーションのエラーを確認することができます。さらに、開発ビルドはコンテンツを縮小しません。 開発ビルドの JavaScript は人間が読める形式であり、Unity は関数名を保持しているため、エラーのスタックトレースを確認できます。ただし、これは開発ビルドが非常に大きく、配布するには大きすぎることを意味します。 Autoconnect Profiler と Deep Profiling Support を選択できるのは、Development Build 設定を有効にする場合のみです。
Autoconnect Profiler
Unity WebGL コンテンツをプロファイルするには、Autoconnect Profiler を有効にします。WebGL の場合、他のプラットフォームのように プロファイラー を実行中のビルドに接続することはできません。そのため、コンテンツをエディターに接続するにはこのオプションを使用する必要があります。これは、プロファイラーの接続は WebGL 上の WebSocket を使用して処理されるためです。ただし、ウェブブラウザーはコンテンツからの発信接続のみを許可します。
Deep Profiling Support Deep Profiling Support を有効にすると、Unity のプロファイラーがアプリケーション内のすべての関数呼び出しをプロファイルします。詳細については、詳細なプロファイリング のドキュメントを参照してください。
Player 設定
WebGL には、Player 設定 (Edit > Project Settings の順に移動し Player カテゴリを選択) にいくつかの追加オプションがあります。
Other Settings
Strip Engine Code
Strip Engine Code オプションにアクセスするには Other Settings を開きます。 このオプションはデフォルトでチェックされており、WebGL のコードストリップを有効にしています。このオプションをチェックすると、使用しないクラスのコードは含まれません。例えば、物理関連のコンポーネントや機能を使用しない場合は、物理エンジン全体がビルドから削除されます。 詳細は、後述の「ストリップ」のセクションを参照してください。
Publishing Settings
Enable Exceptions
Publishing Settings を開き、 Enable Exceptions にアクセスします。 Enable Exceptions を使用すると、予期しないコードの挙動 (通常はエラーと見なされる) を実行時に処理する方法を指定できます。以下のオプションが含まれます。
- None: 例外に関するサポートを必要としない場合はこれを選択します。これにより、最高のパフォーマンスと最小のビルドが得られます。このオプションでは、例外がスローされるとコンテンツはその設定のままエラーで停止します。
-
Explicitly Thrown Exceptions Only (default): これを選択すると、スクリプトの
throwステートメントから明示的に指定された例外をキャッチし、finallyブロックを確実に呼び出します。このオプションを選択すると、スクリプトから生成された JavaScript コードが長く遅くなります。これは、スクリプトがプロジェクトの主なボトルネックになっている場合にのみ問題になります。 -
Full Without Stacktrace: 以下をキャッチするには、このオプションを選択します。
- スクリプト内の
throwステートメントから明示的に指定された例外 (Explicitly Thrown Exceptions Only オプションと同じ) - Null 参照
- 範囲外の配列アクセス
- スクリプト内の
- Full With Stacktrace: このオプションは上記のオプションと似ていますが、スタックトレースもキャプチャします。 Unity はそれらの確認をコードに埋め込むことでこれらの例外を生成します。そのため、このオプションはパフォーマンスを低下させ、ブラウザーのメモリ使用量を増やします。このオプションはデバッグにのみ使用し、常に64ビットブラウザーでテストしてください。
Publishing Settings を選択して、Data Caching にアクセスします。
データキャッシング
Data Caching にアクセスするには、Publishing Settings (File > Build Settings > Player Settings > WebGL > Publishing Settings) を選択します。これにより、ブラウザーはメインデータファイルを IndexedDB データベースにキャッシュすることができます。
ブラウザーのデフォルトの HTTP キャッシュを使用しても、ブラウザーが特定のレスポンスをキャッシュすることを保証するものではありません。これは、ブラウザーの HTTP キャッシュの容量が限られており、大きすぎるファイルをキャッシュできない可能性があるためです。
ロードの速度を向上させるために、IndexedDB ではブラウザーの制限を超えるファイルをキャッシュすることができます。より多くのファイルをキャッシュすると、ダウンロードしたコンテンツが次回のビルド実行時にユーザーのマシンで利用可能になる可能性が高まります。
データキャッシングは、HTTP 応答用に IndexedDB キャッシュの .data ファイルのみをキャッシュします。AssetBundle をキャッシュするには、データキャッシュを有効にして、 unityInstance.Module.cacheControl() をオーバーライドする必要があります。\ nこれを行うには、Module.cacheControl(url) が要求された AssetBundleURL に対して must-revalidate を返すことを確認してください。例えば、createUnityInstance() が返す Promise のフルフィルメントコールバックで unityInstance.Module.cacheControl() 関数をオーバーライドできます。
createUnityInstance() の詳細については、WebGL: 圧縮ビルドとサーバー設定 を参照してください。
WebGL 用にパブリッシュするときは、コンテンツの開始前のダウンロード時間を妥当なものにするために、ビルドサイズを小さく抑えることが重要です。 アセットサイズを縮小するための一般的なヒントについては、ビルドサイズの削減 を参照してください。
配布サイズ
WebGL 用にパブリッシュするときは、コンテンツの開始前のダウンロード時間を妥当なものにするために、ビルドサイズを小さく抑えることが重要です。 アセットサイズを縮小するための一般的なヒントについては、ビルドサイズの削減 を参照してください。
WebGL に特有のヒントとコツ
テクスチャインポーター ですべての圧縮テクスチャに対してCrunch テクスチャ圧縮型式を指定します。
開発ビルドをデプロイしないでください。開発ビルドは圧縮も Minify もされていないので、ファイルサイズはずっと大きくなります。
Player 設定 (Edit > Project Settings の順に移動し Player カテゴリを選択) を開き、Publishing Settings パネルを開き、ビルドで例外を必要としない場合は Enable Exceptions を None に設定します。
Player 設定 (Edit > Project Settings の順に移動し Player カテゴリを選択) を開き、Other Settings パネルを開き、Strip Engine Code を有効にしてビルドを効率的に行います。
サードパーティ製のマネージ DLL を使用する場合は注意が必要です。依存が多く含まれるため、生成されるコードサイズが大幅に増加する可能性があるためです。
リリースビルドを作成する場合、Unity は WebGL の Player 設定の Publishing Settings で選択された Compression Format に従ってビルド出力ファイルを圧縮します。
これらのオプションやそれらを使ったビルドの生成に関して、詳しくは 圧縮ビルドの展開 を参照してください。
アセットバンドル
コンテンツを開始する前にすべてのアセットデータを事前にダウンロードする必要があるため、アセットを主要データファイルから アセットバンドル に移動することを検討すると良いでしょう。このようにすると、コンテンツをロードするためのシーンを小さくすることができ、素早くロードすることができます。その後、ユーザーがコンテンツを処理するときにオンデマンドで動的にアセットをロードします。アセットバンドルは、アセットデータのメモリ の管理にも役立ちます。AssetBundle.Unload を呼び出すことで、不要になったアセットのアセットデータをメモリからアンロードできます。
WebGL プラットフォームでアセットバンドルを使用する場合に、以下を考慮する必要があります。
メインビルドで使用されていないアセットバンドルでクラスタイプを使用すると、Unity はそれらのクラスのコードをビルドから削除することがあります。 アセットバンドルからアセットをロードしようとすると失敗する原因になる場合があります。それを修正するには BuildPlayerOptions.assetBundleManifestPath を使用するか、他のオプションについては後述の ストリップ のセクションを参照してください。
WebGL はスレッドをサポートしていませんが、http ダウンロードはダウンロードが終了したときにのみ利用可能になります。このため、Unity WebGL ビルドはダウンロードが完了した時にメインスレッド上のアセットバンドルデータを解凍してメインスレッドをブロックする必要があります。この中断を回避するために、LZMA アセットバンドル圧縮 は WebGL 上のアセットバンドルでは使用できません。アセットバンドルは、代わりに LZ4 を使用して圧縮されます。これは、オンデマンドで非常に効率的に解凍されます。 LZ4 よりも小さい圧縮サイズが必要な場合は、Webサーバーを設定して、アセットバンドルで (LZ4圧縮に加えて) gzip または Brotli 圧縮 を使用可能にできます。これを行う方法について詳しくは、圧縮ビルドの展開 を参照してください。
WebGL では、UnityWebRequestAssetBundle.GetAssetBundle による AssetBundle のキャッシュをサポートしています。このメソッドは、ブラウザーの IndexedDB API を使用してユーザーのデバイスにキャッシュを保存します。ブラウザーによっては IndexedDB のサポートが制限されている場合があり、またどのブラウザーでもディスクにデータを保存する際にユーザーの承認を求める場合があります。詳細については、WebGL ブラウザーの互換性 を参照してください。
ストリップ
Unity はデフォルトでビルドから未使用のコードをすべて削除します。 これは、Player 設定 (Edit > Project Settings > Player カテゴリ) の Other Settings 内の Strip Engine Code オプションで変更できます。ストリッピングを有効にしてビルドすることをお勧めします。
コードストリップを使用すると、Unity は使用されている (スクリプトコード内、または、シーン内のシリアル化されたデータ内で参照されている) UnityObject 派生クラスがないかプロジェクトをスキャンします。それから、どのクラスも使用されていない Unity のサブシステムをビルドから削除します。これにより、ビルドのコード数が減り、ダウンロードが少なくなり、パースするコードも減少します (したがって、コードの実行速度が速くなり、メモリの使用量も少なくなります)。
コードストリップの問題
コードストリップによって実際には必要なコードを削除すると、問題が生じる可能性があります。これは、メインビルドに含まれていないためにプロジェクトからストリップされたクラスを含むアセットバンドルを、実行時にロードすると発生する可能性があります。これが発生すると、ブラウザーの JavaScript コンソールに例えば、以下のようなエラーメッセージが表示されます (さらに他のエラーメッセージも表示される可能性があります)。
Could not produce class with ID XXX
これらのエラーをトラブルシュートするには、クラス ID リファレンス で ID (上記の例では XXX) を調べて、どのクラスのインスタンスを作成しようとしているかを確認します。そのような場合は、そのクラスへの参照をスクリプトかシーンに追加するか、link.xml ファイルをプロジェクトに追加することによって、そのクラスのコードを強制的にビルドに加えることができます。
以下は、Collider クラス (したがって Physics モジュール) をプロジェクト内で確実に保持する例です。この XML コードを link.xml というファイルに加え、そのファイルを Assets フォルダーに置きます。
<linker>
<assembly fullname="UnityEngine">
<type fullname="UnityEngine.Collider" preserve="all"/>
</assembly>
</linker>
ストリップがビルドの問題を引き起こしていると疑われる場合は、テスト中に Strip Engine Code オプションを無効にすることも可能です。
Unity には、適切なストリップを行うようプロジェクトを最適化するために、ビルドに含まれるモジュールやクラスを確認する便利な方法がありません。 ただし、含まれているクラスとモジュールの概要を確認するために、ビルドの後に生成される Temp/StagingArea/Data/il2cppOutput/UnityClassRegistration.cpp ファイルを確認できます。
Strip Engine Code オプションは Unity エンジンコードにのみ影響します。IL2CPP は常にマネージ DLL とスクリプトからバイトコードを取り除きます。このことは、コードの静的参照を通してではなく、リフレクションを通して動的にマネージ型を参照する必要がある場合に問題を引き起こすことがあります。リフレクションを通して型にアクセスする必要がある場合は、それらの型を保持するために link.xmlファイルを設定する必要もあります。link.xml ファイルの詳細については、iOS ビルドサイズの最適化 を参照してください。
ビルド出力ファイルの移動
Build フォルダーの場所を変更するには、WebGL テンプレートの index.html ファイルの buildUrl 変数を変更します。
Build フォルダー内のファイルの場所を変更するには、index.html ファイル内の config 変数のパラメーターで、それぞれの URL (すなわち、dataUrl、wasmCodeUrl、wasmMemoryUrl、wasmFrameworkUrl) を変更します。
コンテンツ配信ネットワーク (CDN) でファイルをホストする場合は、これらに外部サーバーの URL を指定できますが、これを行うためには、ホスティングサーバーでオリジン間リソース共有 (CORS) が有効になっている必要があります。CORS のについての詳細は、WebGL のネットワーク を参照してください。
インクリメンタルビルド
IL2CPP によってプロジェクト用に生成された C ++ コードは、インクリメンタルにコンパイルされます。つまり、最後にビルドしてから変更された C ++ コードのみが再度コンパイルされます。変更のないソースコードは、前回のビルドで生成されたものと同じオブジェクトファイルを再利用します。インクリメンタルな C ++ ビルドに使用されるオブジェクトファイルは、Unity プロジェクトの Library/il2cpp_cache ディレクトリに格納されます。
インクリメンタルコンパイルを使用しないで、生成された C ++ コードをゼロからクリーンにビルドするには、Unity プロジェクトの Library/il2cpp_cache ディレクトリを削除します。Unity エディターのバージョンが以前の WebGL ビルドで使用されていたものと異なる場合、Unity は自動的にゼロからクリーンなビルドを行います。
- Full Without Stacktrace は Unity 2017.3 で追加
- asm.js のリンカーターゲットを Unity 2019.1で 削除
- ビルドファイルの更新とデータキャッシングは Unity 2020.1 で追加