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

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

The default HTML page is available in the Godot Engine repository at /misc/dist/html/full-size.html. Some simple use-cases where customizing the default page is useful include:

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

Another sample HTML page is available at /misc/dist/html/fixed-size.html. This page uses a fixed size canvas with an output widget below. However, the F12 browser console should be preferred as it can display additional information, such as WebGL errors.

プレースホルダ置換

When exporting the game, several placeholders in the HTML page are replaced with values depending on the export:

プレースホルダ Substituted by
$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 is replaced with the string specified by the export option Html/Head Include.

Engine オブジェクト

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

The API is based on and requires basic understanding of Promises.

The object itself has only the following methods:

Engine.load(basePath)

Load the engine from the passed base path.

引数:
  • basePath (string) -- Base path of the engine to load.
戻り値:

Promise which resolves once the engine is loaded.

Engine.unload()

Unload the engine to free memory.

This is called automatically once the engine is started unless explicitly disabled using engine.setUnloadAfterInit().

Engine.isWebGLAvailable([majorVersion = 1])

Check whether WebGL is available.

引数:
  • majorVersion (number) -- The major WebGL version to check for. Defaults to 1 for WebGL 1.0.
戻り値:

true if the given major version of WebGL is available, false otherwise.

Engine.setWebAssemblyFilenameExtension(extension)

When loading the engine, the filename extension of the WebAssembly module is assumed to be wasm. This function allows usage of an alternate extension.

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

This is useful for outdated hosts that only accept uploads of files with certain filename extensions.

引数:
  • extension (string) -- Filename extension without preceding dot.

注釈

Depending on the host, using an alternate filename extension can prevent some start-up optimizations. This occurs when the file is delivered with a MIME-type other than application/wasm.

Engine インスタンスの開始

Engine() also acts a class:

class Engine()

An instance of the engine that can be started, usually a game.

Instantiate the class using the new operator:

var engine = new Engine();

This yields an Engine() instance, referred to as engine with a lower-case e from here.

To start such an instance, the global Engine object must be loaded, then the engine instance must be initialized and finally started.

engine.init([basePath])

Initialize the instance. The instance can then be started with one of the start functions, usually engine.startGame().

引数:
  • basePath (string) -- The base path to the engine, same as in Engine.load(). Must be passed only if the engine hasn't been loaded yet.
戻り値:

Promise that resolves once the engine is loaded and initialized.

engine.preloadFile(file[, path])

Load a file so it is available in the file system once the instance runs. Must be called before starting the instance.

引数:
  • file --

    If type is string, the file will be loaded from that path.

    If type is ArrayBuffer or a view on one, the buffer will used as the content of the file.

  • path (string) -- Path by which the file will be available. Mandatory if file is not a string. If not passed, the path is derived from the URL of the loaded file.
戻り値:

Promise that resolves once the file is preloaded.

engine.start([arg1, arg2, ])

Starts the instance of the engine, using the passed strings as command line arguments. This allows great control over how the engine is started, but usually the other methods starting with engine.start are simpler and should be used instead.

If the instance has not yet been initialized with engine.init(), it will be.

The engine must be loaded beforehand.

Requires that the engine has been loaded, and that a canvas can be found on the page.

引数:
  • variadic (string) -- Command line arguments.
戻り値:

Promise that resolves once the engine started.

engine.startGame(mainPack)

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

エンジンがまだ読み込まれていない場合は、渡されたURLの基本パスを使用してエンジンを読み込みます。

This function ignores overrides of filenames and their extensions to start only the main pack passed as argument.

引数:
  • mainPack (string) -- Path to the main pack to start. Also used as base path to load the engine if not loaded already.
戻り値:

Promise that resolves once the game started.

起動時の動作の設定

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

engine.setUnloadAfterInit(enabled)

Specify whether the Engine will be unloaded automatically after the instance is initialized.

This frees browser memory by unloading files that are no longer needed once the instance is initialized. However, if more instances of the engine will be started, the Engine will have to be loaded again.

Enabled by default.

引数:
  • enabled (boolean) -- true if the engine shall be unloaded after initializing, false otherwise.
engine.setCanvas(canvasElem)

Specify a canvas to use.

By default, the first canvas element on the page is used for rendering.

引数:
  • canvasElem (HTMLCanvasElement) -- The canvas to use.
engine.setCanvasResizedOnStart(enabled)

Specifies whether the canvas will be resized to the width and height specified in the project settings on start.

Enabled by default.

引数:
  • enabled (boolean) -- true if the canvas shall be resized on start, false otherwise.
engine.setLocale(locale)

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

For example, with PHP:

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

参考

List of locales.

engine.setExecutableName(execName)

Specify the virtual filename of the executable.

A real executable file doesn't exist for the HTML5 platform. However, a virtual filename is stored by the engine for compatibility with other platforms.

By default, the base name of the loaded engine files is used. This method allows specifying another name.

This affects the output of OS.get_executable_path() and the automatically started main pack, ExecutableName.pck.

引数:
  • execName (string) -- Executable name.

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

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

engine.setProgressFunc(callback)

Set the callback for displaying download progress.

引数:
  • callback (function) -- Callback called once per frame with two number arguments: bytes loaded so far, and total bytes to load.
function printProgress(current, total) {
    console.log("Loaded " + current + " of " + total + " bytes");
}
engine.setProgressFunc(printProgress);

合計が0の場合は、計算できません。考えられる理由は次のとおりです:

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

注釈

For ease of use, the callback is only called once per frame, so that usage of requestAnimationFrame() is not necessary.

engine.setStdoutFunc(callback)

Specify the standard output stream callback.

引数:
  • callback (function) -- Callback function called with one argument, the string to print.
function printStdout(text) {
    console.log(text);
}
engine.setStdoutFunc(printStdout);

This method should usually only be used in debug pages. The $GODOT_DEBUG_ENABLED placeholder can be used to check for this.

By default, console.log() is used.

engine.setStderrFunc(callback)

Specify the standard error stream callback.

引数:
  • callback (function) -- Callback function called with one argument, the string to print.
function printStderr(text) {
    console.warn("Error: " + text);
}
engine.setStderrFunc(printStderr);

This method should usually only be used in debug pages. The $GODOT_DEBUG_ENABLED placeholder can be used to check for this.

By default, console.warn() is used.

Emscripten Module へのアクセス

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