Webのエクスポート

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

重要

通常は 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 2

OpenGL ES 3 レンダラーがGodotから削除され Vulkan が採用されるまで、GLES3 オプションが選択されている場合、HTML5エクスポートでは WebGL 2 が使用されます。

警告

Using WebGL 2 is not recommended due to its expected removal from Godot without replacement.

WebGL 2はすべてのブラウザーでサポートされているわけではありません。FirefoxChromium系 (クローム、オペラ)は、最も人気のあるWebGL 2をサポートしているブラウザですが、SafariEdge では動作しません。iOS では、すべてのブラウザは、WebKitの(すなわち、Safariなど)に基づいているので、同様に動作しません。

GodotのWebGL 2レンダラーには3Dの問題があり、メンテナンスが行われなくなりました。

エクスポートオプション

実行可能な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

  • 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 then 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:// ファイルシステムが永続的かどうかをチェックすることができますが、場合によっては誤検出することもあります。

スレッド

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 are also starting to 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

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)