WebエクスポートHTMLページのカスタマイズ

エクスポートテンプレートに付属しているデフォルトのHTMLページではなく、カスタムHTML ページを使用することもできます。これにより、最終的なWebプレゼンテーションと動作を大幅にカスタマイズできます。カスタムHTMLページへのパスは、エクスポートオプションで Html/Custom Html Shell として指定されます。

デフォルトのHTMLページは、Godot Engineリポジトリの `/misc/dist/html/full-size.html <https://github.com/godotengine/godot/blob/master/misc/dist/html/full-size.html>`__にあります。デフォルトページのカスタマイズが役立つ簡単なユース ケースには、次のようなものがあります:

  • 別のディレクトリからファイルを読み込む
  • .pck ファイルの代わりに .zip ファイルをメインパックとして読み込む
  • メインパックファイルとは異なるディレクトリからエンジンファイルを読み込む
  • クリックしてプレイするボタンを追加して、ゲームをフルスクリーンモードで開始できるようにする
  • エンジンが起動する前に追加ファイルをロードして、後でファイル・システムで使用できるようにする
  • MainLoopスクリプトを起動するためにカスタム "コマンド ライン" 引数を渡す場合 ( -s など)

別のサンプルHTMLページは、`/misc/dist/html/fixed-size.html <https://github.com/godotengine/godot/blob/master/misc/dist/html/fixed-size.html>`__で入手できます。このページは、以下の出力ウィジェットを備えた固定サイズのcanvasを使用します。ただし、WebGLエラーなどの追加情報を表示できるため、F12ブラウザーコンソールを使う事をお勧めします。

プレースホルダの置換

ゲームをエクスポートするとき、HTMLページ内のいくつかのプレースホルダは、エクスポートに応じて値に置き換えられます。

プレースホルダ 置換内容
$GODOT_BASENAME 拡張子のないエクスポートされたファイルのベース名、例えば `` game.html`` をエクスポートする際の `` game``
$GODOT_DEBUG_ENABLED デバッグする場合は true 、それ以外の場合は false
$GODOT_HEAD_INCLUDE HTMLの `` <head> `` 要素の直前に含めるカスタム文字列

HTMLファイルは、JavaScriptファイル $GODOT_BASENAME.js を評価する必要があります。このファイルは、エンジンの起動に使用されるグローバル Engine オブジェクトを定義します下記参照

ブートスプラッシュイメージは $GODOT_BASENAME.png としてエクスポートされ、 <img /> 要素などで使用できます。

$GODOT_DEBUG_ENABLED は、出力コンソールやその他のデバッグ ツールを必要に応じて表示する場合に便利です。

$GODOT_HEAD_INCLUDE は、エクスポートオプション Html/Head Include で指定された文字列に置き換えられます。

Engine オブジェクト

JavaScriptグローバルオブジェクト Engine$GODOT_BASENAME.js によって定義され、エンジンの起動プロセスへのインターフェイスとして機能します。

このAPIは、`Promises <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises>`__に基づいており、それに関する基本的な理解が必要です。

オブジェクト自体には、次のメソッドしかありません:

Engine.load(basePath)

渡されたベースパスからエンジンをロードします。

引数:
  • basePath (string) -- ロードするエンジンのベースパス。
戻り値:

エンジンがロードされた結果、得られたPromise。

Engine.unload()

エンジンをアンロードしてメモリを解放します。

これは、engine.setUnloadAfterInit() を使用して明示的に無効にしない限り、エンジンが開始されると自動的に呼び出されます。

Engine.isWebGLAvailable([majorVersion = 1])

WebGLが利用可能かどうかを確認します。

引数:
  • majorVersion (number) -- WebGLのメジャーバージョンのチェック。WebGL 1.0 のデフォルトは1です。
戻り値:

指定されたメジャーバージョンのWebGLが利用可能な場合は true、そうでない場合は false

Engine.setWebAssemblyFilenameExtension(extension)

エンジンをロードするとき、WebAssemblyモジュールのファイル名拡張子は wasm であると想定されています。この関数により、代替の拡張機能を使用できます。

Engine.setWebAssemblyFilenameExtension('dat');
// Load 'mygame.dat' as WebAssembly module.
Engine.load('mygame');

これは、特定のファイル拡張子を持つファイルのアップロードのみを受け付ける古いホストに便利です。

引数:
  • extension (string) -- ドットなしのファイル名拡張子。

注釈

ホストによっては、代替のファイル名拡張子を使用すると、起動時の最適化が妨げられる場合があります。これは、ファイルが application/wasm 以外のMIMEタイプで配信されるときに発生します。

Engine インスタンスの開始

Engine() はクラスとしても機能します:

class Engine()

開始できるエンジンのインスタンス、通常はゲーム。

new 演算子を使用してクラスをインスタンス化します:

var engine = new Engine();

これにより、Engine() インスタンスが生成されます。これをこれ以降の説明では、小文字の e を持つ engine と呼びます。

そのようなインスタンスを開始するには、グローバルな Engine オブジェクトをロードし、次に engine インスタンスを初期化し、最後に開始する必要があります。

engine.init([basePath])

インスタンスを初期化します。インスタンスは start 関数の1つ、通常は engine.startGame() で開始できます。

引数:
  • basePath (string) -- Engine.load() と同じ、エンジンへのベースパス。エンジンがまだロードされていない場合にのみ渡す必要があります。
戻り値:

エンジンがロードされ初期化されると得られるPromise。

engine.preloadFile(file[, path])

インスタンスを実行したら、ファイルシステムで使用できるようにファイルをロードします。インスタンスを開始する に呼び出す必要があります。

引数:
  • file -- タイプが文字列の場合、ファイルはそのパスからロードされます。 タイプが ArrayBuffer またはそのビューである場合、バッファはファイルのコンテンツとして使用されます。
  • path (string) -- ファイルを使用できるパス。file が文字列でない場合は必須です。渡されない場合、パスはロードされたファイルのURLから派生します。
戻り値:

ファイルがプリロードされると得られるPormise。

engine.start([arg1, arg2, ])

渡された文字列をコマンドライン引数として使用して、エンジンのインスタンスを開始します。これにより、エンジンの起動方法を細かく制御できますが、通常 engine.start で始まる他のメソッドはより単純であり、代わりにそちらを使用する必要があります。

インスタンスが engine.init() でまだ初期化されていない場合は、インスタンスが初期化されます。

エンジンは事前にロードする必要があります。

エンジンがロードされており、ページ上にcanvasが見つかる必要があります。

引数:
  • variadic (string) -- コマンドライン引数。
戻り値:

エンジンが起動すると得られるPromise。

engine.startGame(execName, mainPack)

Initializes the engine if not yet initialized, loads the executable, and starts the game with the main pack loaded from the passed URL.

If the engine isn't loaded yet, the base path of the passed executable name will be used to load the engine.

引数:
  • execName (string) -- Executable's name (URL) to start. Also used as base path to load the engine if not loaded already. Should not contain the file's extension.
  • mainPack (string) -- Path (URL) to the main pack to start.
戻り値:

ゲームが開始すると得られるPromise。

起動時の動作の設定

エンジンを起動する以外に、エンジン・インスタンスの他のメソッドを使用して動作を構成できます:

engine.setUnloadAfterInit(enabled)

インスタンスの初期化後にエンジンを自動的にアンロードするかどうかを指定します。

これにより、インスタンスが初期化されると不要になったファイルをアンロードすることにより、ブラウザのメモリが解放されます。ただし、エンジンのインスタンスをさらに起動する場合は、エンジンを再度ロードする必要があります。

デフォルトでは有効になっています。

引数:
  • enabled (boolean) -- エンジンを初期化後にアンロードする場合は true、そうでない場合は false
engine.setCanvas(canvasElem)

使用するcanvasを指定します。

デフォルトでは、ページの最初のcanvas要素がレンダリングに使用されます。

引数:
  • canvasElem (HTMLCanvasElement) -- 使用するcanvas。
engine.setCanvasResizedOnStart(enabled)

開始時にプロジェクト設定で指定された幅と高さにcanvasのサイズを変更するかどうかを指定します。

デフォルトでは有効になっています。

引数:
  • enabled (boolean) -- 開始時にcanvasのサイズを変更する場合は true、それ以外の場合は false
engine.setLocale(locale)

デフォルトでは、エンジンはJavaScript環境から使用するロケールを推測しようとします。通常は、サーバ側でユーザが指定したロケールを使用するか、少なくともHTTPの Accept-Language ヘッダで要求されたロケールを使用することをお勧めします。このメソッドでは、そのようなカスタムロケール文字列を指定できます。

たとえば、PHPの場合:

engine.setLocale(<?php echo Locale::acceptFromHttp($_SERVER['HTTP_ACCEPT_LANGUAGE']); ?>);
引数:
  • locale (string) -- ロケール。

参考

ロケール のリスト。

engine.setExecutableName(execName)

実行可能ファイルの仮想ファイル名を指定します。

HTML5プラットフォーム用の実際の実行可能ファイルは存在しません。ただし、仮想ファイル名は、他のプラットフォームとの互換性のためにエンジンによって保存されます。

デフォルトでは、ロードされたエンジンファイルのベース名が使用されます。このメソッドでは、別の名前を指定できます。

これは OS.get_executable_path() の出力と、自動的に開始されるメインパック、ExecutableName.pck に影響します。

引数:
  • execName (string) -- 実行可能ファイル名。

プレゼンテーションのカスタマイズ

プレゼンテーションを実装するには、次のメソッドを使用します:

engine.setProgressFunc(callback)

ダウンロードの進行状況を表示するためのコールバックを設定します。

引数:
  • callback (function) -- 2つの数値引数でフレームごとに1回呼び出されるコールバック: これまでにロードされたバイト数と、ロードされる総バイト数。
function printProgress(current, total) {
    console.log("Loaded " + current + " of " + total + " bytes");
}
engine.setProgressFunc(printProgress);

total(総バイト数)が0の場合は、計算できません。考えられる理由は次のとおりです:

  • ファイルは、サーバー側のチャンク圧縮で配信されます
  • ファイルはChromium上のサーバー側の圧縮で配信されます
  • すべてのファイルのダウンロードがまだ開始されていません(通常はマルチスレッドを使用しないサーバー)

注釈

使いやすさを目的として、コールバックはフレームごとに1回だけ呼び出されるので、requestAnimationFrame() を使用する必要はありません。

engine.setStdoutFunc(callback)

標準出力ストリームコールバックを指定します。

引数:
  • callback (function) -- 1つの引数(出力する文字列)で呼び出されるコールバック関数。
function printStdout(text) {
    console.log(text);
}
engine.setStdoutFunc(printStdout);

このメソッドは通常、デバッグページでのみ使用する必要があります。$GODOT_DEBUG_ENABLED プレースホルダを使用して、これを確認できます。

デフォルトでは console.log() が使用されます。

engine.setStderrFunc(callback)

標準エラーストリームコールバックを指定します。

引数:
  • callback (function) -- 1つの引数(出力する文字列)で呼び出されるコールバック関数。
function printStderr(text) {
    console.warn("Error: " + text);
}
engine.setStderrFunc(printStderr);

このメソッドは通常、デバッグページでのみ使用する必要があります。$GODOT_DEBUG_ENABLED プレースホルダを使用して、これを確認できます。

デフォルトでは console.warn() が使用されます。

Emscripten Module へのアクセス

自分のしていることがわかっていれば、ランタイム環境(Emscripten Module )に engine.rtenv としてアクセスできます。使用方法については、公式のEmscriptenドキュメントをご確認ください: https://kripken.github.io/emscripten-site/docs/api_reference/module.html