自定义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:

  • 从其他目录加载文件
  • 加载 .zip 文件而不是 .pck 文件作为主包
  • 从主包文件以外的目录中加载引擎文件
  • 添加一个点击播放按钮,这样游戏可以在全屏模式下启动
  • 在引擎启动之前加载一些额外的文件,以便稍后在文件系统中可用
  • 传递自定义“命令行”参数,例如 -s 启动MainLoop脚本

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.

占位符替换

导出游戏时,HTML页面中的多个占位符将替换为值,具体取决于导出:

占位符 替换为
$GODOT_BASENAME 没有后缀的导出文件的基本名称,例如 game 在导出 game.html
$GODOT_DEBUG_ENABLED 如果调试就是 true ,否则是 false
$GODOT_HEAD_INCLUDE 自定义字符串,包含在HTML `` <head>`` 元素的结尾之前

HTML文件必须评估JavaScript文件 $ GODOT_BASENAME.js 。 这个文件定义了一个用于启动引擎的全局 Engine 对象,参见 see below 了解详细信息。

引导启动图像被导出为 $ GODOT_BASENAME.png 并且可以用于例如 在 <img /> 元素中。

$ GODOT_DEBUG_ENABLED 可用于可选地显示,例如 输出控制台或其他调试工具。

$GODOT_HEAD_INCLUDE 被导出选项 Html / Head Include 指定的字符串替换。

Engine 对象

JavaScript全局对象 Engine$GODOT_BASENAME.js 定义,并作为引擎启动过程的接口。

本API基于并要求对承诺有基本的理解。 <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises>`__.

对象本身只有以下方法:

Engine.load(basePath)

从已通过的底层路径加载引擎。

参数:
  • basePath (string) – 引擎加载的底层路径。
返回:

当引擎加载时承诺解决。

Engine.unload()

卸载引擎以释放内存。

除非使用:js:func:`引擎.初始化后卸载`显式禁用,否则引擎一旦启动就会自动调用。

Engine.isWebGLAvailable([majorVersion = 1])

检查WebGL是否可用。

参数:
  • majorVersion (number) – 主要WebGL版本检查。*WebGL 1.0*默认值为1。
返回:

如果WebGL的主要版本可用,则为真,否则为假。

Engine.setWebAssemblyFilenameExtension(extension)

加载引擎时,WebAssembly模块的文件名扩展假定为“wasm”。这个函数允许使用替代扩展。

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

对于过时的主机来说,只接受某些文件扩展名的文件的上传,是非常有用的。

参数:
  • extension (string) – 文件名扩展没有前面的点。

注解

根据主机,使用替代文件名扩展可以防止某些启动优化。当文件使用mime类型交付时,就会发生这种情况。而不是 应用程序/wasm

启动 Engine 实例

:js:类:`引擎`还是一个类:

class Engine()

可以启动的引擎实例,通常是一个游戏。

使用“new”操作符实例化类:

var engine = new Engine();

这将生成一个:js:类:`引擎`实例,在这里用小写的“e”代替“engine”。

要启动这样的实例,必须加载全局 Engine 对象,然后必须初始化并启动 engine 实例。

engine.init([basePath])

初始化实例。然后可以使用其中一个``开始`` 函数启动实例,通常是:js:函数:“引擎.开始游戏”。

参数:
  • basePath (string) – 引擎的基本路径与:js:函数:`引擎.加载`相同。只有在引擎尚未加载时才能通过。
返回:

承诺一旦加载并初始化引擎就会解析。

engine.preloadFile(file[, path])

这会加载一个文件,以便在启动实例后在文件系统中可用。 必须在启动实例**之前** 调用。

参数:
  • file

    如果类型是字符串,则文件将从该路径加载。

    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.

引擎必须预先加载。

需要的引擎已经加载完毕,可以在页面上找到画布。

参数:
  • variadic (string) – 命令行参数。
返回:

引擎启动后解析的承诺。

engine.startGame(mainPack)

初始化引擎(如果还没有初始化),并使用从传递的URL加载的主包启动游戏。

如果尚未加载引擎,则将使用传递的URL的基本路径来加载引擎。

这个函数忽略文件名及其扩展名的覆盖,只启动作为参数传递的主包。

参数:
  • mainPack (string) – 从主包路径启动游戏。如果还没有加载引擎,也可用作加载引擎的基本路径。
返回:

当游戏启动后承诺解析。

配置启动行为

除启动引擎外,引擎实例的其他方法还允许配置行为:

engine.setUnloadAfterInit(enabled)

指定初始化实例后是否自动卸载引擎。

这通过卸载初始化实例后不再需要的文件来释放浏览器内存。 但是,如果将启动更多引擎实例,则必须再次加载引擎。

默认启用。

参数:
  • enabled (boolean) – 如果引擎在初始化后卸载,则为“真”,否则为“假”。
engine.setCanvas(canvasElem)

指定要使用的画布。

默认情况下,页面上的第一个画布元素用于呈现。

参数:
  • canvasElem (HTMLCanvasElement) – 使用的画布。
engine.setCanvasResizedOnStart(enabled)

设置是否将画布调整为启动时项目设置中指定的宽度和高度。

默认启用。

参数:
  • enabled (boolean) – 如果在开始时需要调整画布大小,则为”真”,否则为“假”。
engine.setLocale(locale)

默认情况下,引擎将尝试从JavaScript环境猜测要使用的语言环境。通常最好使用服务器端用户指定的区域设置,或者至少使用HTTP Accept-Language header中请求的区域设置。该方法允许指定这样的自定义区域设置字符串。

例如,使用PHP的情况:

engine.setLocale(<?php echo Locale::acceptFromHttp($_SERVER['HTTP_ACCEPT_LANGUAGE']); ?>);
参数:
  • locale (string) – 地区设置。

参见

列表:参考:地区设置<文档_地区设置>.

engine.setExecutableName(execName)

指定可执行文件的虚拟文件名。

HTML5平台不存在真正的可执行文件。但是,引擎存储虚拟文件名是为了与其他平台兼容。

默认情况下,使用加载的引擎文件的基本名称。此方法允许指定另一个名称。

这将影响:参考:操作系统.获取可执行文件路径()<类_操作系统_方法_获取可执行文件路径>`和自动启动的主包:文件:`{可执行文件名称}.pck

参数:
  • execName (string) – 可执行文件名称。

自定义演示文稿

以下方法用于实现演示:

engine.setProgressFunc(callback)

设置显示下载进度的回调函数。

参数:
  • callback (function) – 每帧调用一个回调函数,有两个数值类型的参数:目前已加载的字节数,以及要加载的总字节数。
function printProgress(current, total) {
    console.log("Loaded " + current + " of " + total + " bytes");
}
engine.setProgressFunc(printProgress);

如果总数为0,则无法计算。 可能的原因包括:

  • 文件随服务器端分块压缩一起提供
  • 文件在Chromium上通过服务器端压缩提供
  • 并非所有文件下载都已开始(通常在没有多线程的服务器上)

注解

为便于使用,每帧只调用一次回调,因此,没有必要使用“请求动画帧()”。

engine.setStdoutFunc(callback)

指定标准输出流回调。

参数:
  • callback (function) – 回调函数调用带有一个参数,要打印的字符串。
function printStdout(text) {
    console.log(text);
}
engine.setStdoutFunc(printStdout);

这些方法通常只在调试页面中使用。 可以使用”$GODOT_调试_激活”占位符来检查这一点。

默认情况下,使用的是“console.log()”。

engine.setStderrFunc(callback)

调整标准错误流回调。

参数:
  • callback (function) – 回调函数调用带有一个参数,要打印的字符串。
function printStderr(text) {
    console.warn("Error: " + text);
}
engine.setStderrFunc(printStderr);

这些方法通常只在调试页面中使用。 可以使用”$GODOT_调试_激活”占位符来检查这一点。

默认情况下,使用的是“console.warn()”。

访问Emscripten Module

如果您知道您在做什么,您可以访问运行时环境(Emscripten的 Module )作为 engine.rtenv 。 查看官方Emscripten文档以获取有关如何使用它的信息:https://kripken.github.io/emscripten-site/docs/api_reference/module.html