Webのエクスポート¶

参考

This page describes how to export a Godot project to HTML5. If you're looking to compile editor or export template binaries from source instead, read Web用のコンパイル.

HTML5エクスポートは、ブラウザにGodotエンジンで作られたゲームを公開することができます。これには、ユーザーのブラウザで WebAssembly と WebGL をサポートする必要があります。

重要

通常は F12 で開いたブラウザ統合開発者コンソールを使用して、JavaScript、エンジン、WebGL エラーなどの デバッグ情報 を表示します。

注意

There are significant bugs when running HTML5 projects on iOS (regardless of the browser). We recommend using iOS' native export functionality instead, as it will also result in better performance.

WebGL version¶

Depending on your choice of renderer, Godot can target WebGL 1.0 (GLES2) or WebGL 2.0 (GLES3).

WebGL 1.0 is the recommended option if you want your project to be supported on all browsers with the best performance.

Godot's GLES3 renderer targets high end devices, and the performance using WebGL 2.0 can be subpar. Some features are also not supported in WebGL 2.0 specifically.

Additionally, while most browsers support WebGL 2.0, this is not yet the case for Safari. WebGL 2.0 support is coming in Safari 15 for macOS, and is not available yet for any iOS browser (all WebKit-based like Safari). See Can I use WebGL 2.0 for details.

エクスポートオプション¶

実行可能なWeb書き出しテンプレートが使用可能な場合は、エディタの [シーンを停止] ボタンと [編集したシーンを再生] ボタンの間にボタンが表示され、既定のブラウザでゲームをすばやく開いてテストできます。

You can choose the Export Type to select which features will be available:

Regular: is the most compatible across browsers, will not support threads, nor GDNative.
Threads: will require the browser to support SharedArrayBuffer. See Can I use SharedArrayBuffer for details.
GDNative: enables GDNative support but makes the binary bigger and slower to load.

If you plan to use VRAM compression make sure that Vram Texture Compression is enabled for the targeted platforms (enabling both For Desktop and For Mobile will result in a bigger, but more compatible export).

カスタムHTMLシェルファイルへのパスが指定されている場合、デフォルトのHTMLページの代わりにそれが使用されます。Custom HTML page for Web exportを参照してください。

Head Includeは、生成されたHTMLページの <head> 要素に追加されます。これにより、たとえば、WebfontsやサードパーティのJavaScript APIをロードしたり、CSSを組み込んだり、JavaScriptコードを実行したりできます。

重要

Each project must generate their own HTML file. On export, several text placeholders are replaced in the generated HTML file specifically for the given export options. Any direct modifications to that HTML file will be lost in future exports. To customize the generated file, use the Custom HTML shell option.

警告

Export types other than Regular are not yet supported by the C# version.

制限事項¶

セキュリティとプライバシーの理由から、ネイティブプラットフォームで簡単に動作する多くの機能は、Web プラットフォーム上でより複雑になります。GodotゲームをWebに移植する際に注意する必要がある制限事項の一覧を次に示します。

重要

Browser vendors are making more and more functionalities only available in secure contexts, this means that such features are only be available if the web page is served via a secure HTTPS connection (localhost is usually exempt from such requirement).

ちなみに

Check the list of open HTML5 issues on GitHub to see if the functionality you're interested in has an issue yet. If not, open one to communicate your interest.

データ永続化のためのクッキーの使用¶

user:// ファイルシステムの永続性が必要な場合、ユーザーはCookie(特にIndexedDB)を許可する必要があります。 iframe で提供されているゲームを再生する場合は、サードパーティのCookieも有効にする必要があります。Incognito/privateブラウジングモードも永続性を妨げます。

OS.is_userfs_persistent() というメソッドを使うと、user:// ファイルシステムが永続的かどうかをチェックすることができますが、場合によっては誤検出することもあります。

Background processing¶

The project will be paused by the browser when the tab is no longer the active tab in the user's browser. This means functions such as _process() and _physics_process() will no longer run until the tab is made active again by the user (by switching back to the tab). This can cause networked games to disconnect if the user switches tabs for a long duration.

This limitation does not apply to unfocused browser windows. Therefore, on the user's side, this can be worked around by running the project in a separate window instead of a separate tab.

スレッド¶

As mentioned above multi-threading is only available if the appropriate Export Type is set and support for it across browsers is still limited.

警告

Requires a secure context. Browsers also require that the web page is served with specific cross-origin isolation headers.

GDNative¶

As mentioned above GDNative is only available if the appropriate Export Type is set.

The export will also copy the required GDNative .wasm files to the output folder (and must be uploaded to your server along with your game).

フルスクリーンとマウスキャプチャ¶

ブラウザは、任意に フルスクリーンに入る ことを許可しません。同じことが カーソルのキャプチャ にも当てはまります。代わりに、これらのアクションはJavaScript入力イベントへの応答として発生する必要があります。Godotでは、これは、_ input や _unhandled_input などの押された入力イベントコールバック内から全画面表示に入ることを意味します。Input シングルトンを照会するだけでは不十分です。関連する入力イベントは現在アクティブでなければなりません。

同じ理由で、エンジンが有効な入力イベントハンドラ内から起動されない限り、全画面表示のプロジェクト設定は機能しません。これには HTMLページのカスタマイズが必要です。

オーディオ¶

Chromeは、ウェブサイトでの音声の再生方法を制限しています。プレイヤーがオーディオを有効にするには、クリックしたりタップするなどの、キーを押す操作が必要がある場合があります。

参考

Googleは、`Webオーディオの自動再生ポリシー<https://sites.google.com/a/chromium.org/dev/audio-video/autoplay> ` に関する追加情報を提供しています。

警告

Access to microphone requires a secure context.

ネットワーク¶

Low level networking is not implemented due to lacking support in browsers.

Currently, only HTTP client, HTTP requests, WebSocket (client) and WebRTC are supported.

The HTTP classes also have several restrictions on the HTML5 platform:

StreamPeer へのアクセスおよび変更はできません

スレッド/ブロックモードは使用できません

フレームごとに複数回進行できないため、ループ内のポーリングはフリーズします

チャンク応答なし

ホスト検証を無効にできません

同一生成元ポリシーに従います

クリップボード¶

Clipboard synchronization between engine and the operating system requires a browser supporting the Clipboard API, additionally, due to the API asynchronous nature might not be reliable when accessed from GDScript.

警告

Requires a secure context.

Gamepads¶

Gamepads will not be detected until one of their button is pressed. Gamepads might have the wrong mapping depending on the browser/OS/gamepad combination, sadly the Gamepad API does not provide a reliable way to detect the gamepad information necessary to remap them based on model/vendor/OS due to privacy considerations.

警告

Requires a secure context.

起動スプラッシュが表示されない¶

デフォルトのHTMLページは、ロード中に起動スプラッシュを表示しません。ただし、画像はPNGファイルとしてエクスポートされるため、カスタムHTMLページで表示できます。

Shader language limitations¶

When exporting a GLES2 project to HTML5, WebGL 1.0 will be used. WebGL 1.0 doesn't support dynamic loops, so shaders using those won't work there.

ファイルの提供¶

Web用にエクスポートすると、プレゼンテーション用のデフォルトのHTMLページなど、Webサーバーから提供される複数のファイルが生成されます。カスタムHTMLファイルを使用できます。Custom HTML page for Web exportを参照して下さい。

生成された .html ファイルは、Apacheサーバーで DirectoryIndex として使用でき、いつでも index.html などの名前に変更できますが、その名前はデフォルトでは全く依存しません。

HTMLページは、ブラウザウィンドウ内で最大サイズでゲームを描画します。この方法で、ほとんどのWebゲームホスティングサイトで一般的であるように、ゲームのサイズで <iframe> に挿入できます。

エクスポートされた他のファイルは、 .html ファイルの横にある名前のままで提供されます。 .wasm ファイルは、エンジンを実装するバイナリWebAssemblyモジュールです。 .pck ファイルは、ゲームを含むGodotメインパックです。 .js ファイルには起動コードが含まれており、エンジンにアクセスするために .html ファイルによって使用されます。 .png ファイルには、ブートスプラッシュイメージが含まれています。デフォルトのHTMLページでは使用されませんが、カスタムHTMLページに含まれています。

.pck ファイルはバイナリで、通常はMIMEタイプ application/octet-stream で配信されます。.wasm ファイルは application/wasm として配信されます。

注意

application/wasm 以外のMIMEタイプでWebAssemblyモジュール(.wasm)を配信すると、起動時の最適化が妨げられる可能性があります。

サーバー側の圧縮でファイルを配信することは、通常はサイズが大きい .pck ファイルと .wasm ファイルで特に推奨されます。WebAssemblyモジュールは、gzip圧縮によって元のサイズの約4分の1にまで圧縮されています。

Hosts that provide on-the-fly compression: GitHub Pages (gzip)

Hosts that don't provide on-the-fly compression: itch.io, GitLab Pages (supports manual gzip precompression)

スクリプトからJavaScriptを呼び出す¶

Webビルドでは、JavaScript シングルトンが実装されます。同名のJavaScript関数と同様に機能する eval と呼ばれる単一のメソッドを提供します。文字列を引数として受け取り、JavaScriptコードとして実行します。これにより、Godotに統合されたスクリプト言語では不可能な方法でブラウザと対話できます。

func my_func():
    JavaScript.eval("alert('Calling JavaScript per GDScript!');")

最後のJavaScriptステートメントの値はGDScriptの値に変換され、特定の状況下では eval() によって返されます:

JavaScriptの number はGDScriptの float として返されます

JavaScriptの boolean はGDScriptの bool として返されます

JavaScriptの string はGDScriptの String として返されます

JavaScriptの ArrayBuffer, TypedArray および DataView はGDScriptの PoolByteArray として返されます

func my_func2():
    var js_return = JavaScript.eval("var myNumber = 1; myNumber + 2;")
    print(js_return) # prints '3.0'

その他の JavaScriptの値は null として返されます。

HTML5 export templates may be built without support for the singleton to improve security. With such templates, and on platforms other than HTML5, calling JavaScript.eval will also return null. The availability of the singleton can be checked with the JavaScript feature tag:

func my_func3():
    if OS.has_feature('JavaScript'):
        JavaScript.eval("""
            console.log('The JavaScript singleton is available')
        """)
    else:
        print("The JavaScript singleton is NOT available")

ちなみに

上記の my_func3() のように、3つの引用符 """ で囲まれたGDScriptの複数行の文字列は、JavaScriptコードを読みやすくするのに役立ちます。

eval メソッドはグローバルな実行コンテキストでコードを実行するかどうかを指定する2番目のオプションのブール引数も受け入れます。デフォルトではグローバルな名前空間を汚染しないように false になります:

func my_func4():
    # execute in global execution context,
    # thus adding a new JavaScript global variable `SomeGlobal`
    JavaScript.eval("var SomeGlobal = {};", true)