HTML5 shell类参考

为web导出的项目向JavaScript环境暴露了 Engine() 类,从而可以更好地控制引擎的启动过程.

这个API是以异步的方式建立的,需要对 Promises 的基本理解.

引擎

Engine 类提供了在Web上加载和启动导出项目的方法.对于默认的导出设置,这已经是导出的HTML页面的一部分.要了解 Engine 类的实际使用,请参见 自定义Web导出的HTML页面 .

静态方法

Promise

load ( string basePath )

void

unload ( )

boolean

isWebGLAvailable ( [ number majorVersion=1 ] )

实例方法

Promise

init ( [ string basePath ] )

Promise

preloadFile ( string|ArrayBuffer file [, string path ] )

Promise

start ( EngineConfig override )

Promise

startGame ( EngineConfig override )

void

copyToFS ( string path, ArrayBuffer buffer )

void

requestQuit ( )

class Engine(initConfig)

用给定的配置创建一个新的引擎实例.

  • 参数

静态方法

  • Engine.``load(basePath)

    从指定的基本路径加载引擎.

    • 参数

      • basePath (string) — 引擎加载的底层路径.

      返回

      一个一旦加载引擎就会解析的Promise.

      返回类型

      Promise

  • Engine.``unload()

    卸载引擎以释放内存.

    这个方法将被自动调用,取决于配置.参见 :js:attr: unloadAfterInit .

  • Engine.``isWebGLAvailable([majorVersion=1])

    检查 WebGL 是否可用.(可选)指定要检查的特定 WebGL 版本.

    • 参数

      • majorVersion (number) — 要检查的主要WebGL版本.

      返回

      如果给定的WebGL的主要版本是可用的.

      返回类型

      boolean

实例方法

  • Engine.prototype.``init([basePath])

    初始化引擎实例.如果引擎还没有被加载,可以选择将基本路径传递给引擎来加载它.参见 Engine.load() .

    • 参数

      • basePath (string) — 引擎加载的底层路径.

      返回

      一旦引擎被加载和初始化,一个 Promise 就会被解析.

      返回类型

      Promise

  • Engine.prototype.``preloadFile(file[, path])

    加载一个文件,这样一旦运行,它就可以在实例的文件系统中使用.必须在启动实例 之前 调用.

    如果没有提供, path 是从加载文件的URL中导出的.

    • 参数

      • file (string|ArrayBuffer) — 要预装的文件,如果是一个 string ,文件将从该路径加载.如果是一个 ArrayBuffer 或一个视图,该缓冲区将被用作文件的内容.

      • path (string) — 用于访问文件的路径.如果 file 不是一个字符串,则为必需的.

      返回

      一个一旦文件被加载就会解析的Promise.

      返回类型

      Promise

  • Engine.prototype.``start(override)

    使用给定的覆盖配置(如果有的话)启动引擎实例. startGame 可以在典型情况下代替使用.

    如果实例没有被初始化,它将初始化它.对于手动初始化,请参阅 init .引擎必须事先加载.

    如果在页面上找不到画布,或者没有在配置中指定,则失败.

    • 参数

      返回

      引擎启动后解析的Promise.

      返回类型

      Promise

  • Engine.prototype.``startGame(override)

    使用给定的配置覆盖(如果有的话)启动游戏实例.

    如果实例没有被初始化,将初始化它.对于手动初始化,见 init .

    如果未加载引擎,则将加载引擎,并预加载主pck.

    该方法将初始配置(或重写)时同时设置 executable 和 mainPack 属性(通常由编辑器在导出过程中完成).

    • 参数

      返回

      一旦游戏开始就会解析Promise.

      返回类型

      Promise

  • Engine.prototype.``copyToFS(path, buffer)

    在指定的 path 上创建一个文件,在实例的文件系统中将通过该文件创建为 buffer .

    • 参数

      • path (string) — 将创建文件的位置.

      • buffer (ArrayBuffer) — 文件的内容.

  • Engine.prototype.``requestQuit()

    请求退出当前实例.

    这就类似用户在窗口管理器中按下关闭按钮,如果引擎已经崩溃,或者卡在循环中,就不会有任何效果.

引擎配置

用于根据 Godot 导出选项配置引擎实例的对象,如果需要,可重写自定义 HTML 模板中的对象.

属性

类型

名称

boolean

unloadAfterInit

HTMLCanvasElement

canvas

字符串

executable

字符串

mainPack

字符串

locale

数字

canvasResizePolicy

Array.<string>

args

函数

onExecute

函数

onExit

函数

onProgress

函数

onPrint

函数

onPrintError

EngineConfig

引擎配置对象.这只是一个类型,像创建一个普通对象一样创建它,例如:

const MyConfig = { executable: 'godot', unloadAfterInit: false }

属性说明

  • unloadAfterInit

    在实例被初始化后,是否自动卸载引擎.

    • 类型

      boolean

      值

      true

  • canvas

    要使用的HTML DOM Canvas对象.

    默认情况下,如果没有指定任何元素,将使用文档中的第一个画布元素.

    • 类型

      HTMLCanvasElement

      值

      null

  • executable

    WASM文件的名称,不含扩展名.(由Godot Editor导出过程设置).

    • 类型

      字符串

      值

      ""

  • mainPack

    要加载的游戏pck的更换名称.否则使用可执行文件名.

    • 类型

      字符串

      值

      null

  • locale

    指定语言代码,为游戏选择合适的本地化.

    如果没有指定,将使用浏览器的语言环境.请参阅完整的 supported locales .

    • 类型

      字符串

      值

      null

  • canvasResizePolicy

    画布大小调整策略决定了Godot应该如何调整画布的大小.

    0 意味着Godot不做任何大小调整.如果您想通过模板中的javascript代码来控制画布的大小,这将很有用.

    1 意味着Godot在启动时,以及通过引擎功能改变窗口大小时,会调整画布的大小.

    2 意味着Godot将调整画布的大小以匹配整个浏览器窗口.

    • 类型

      数字

      值

      2

  • args

    启动时作为命令行参数传递的参数.

    参见 命令行教程 .

    Note: startGame 将始终添加 --main-pack 参数.

    • 类型

      Array.<string>

      值

      []

  • onExecute(path, args)

    用于处理Godot的 OS.execute 调用的回调函数.

    例如在Web Editor模板中使用,用于在项目管理器和编辑器之间切换,以及运行游戏.

    • 参数

      • path (string) — Godot想要执行的路径.

      • args (Array.<string>) — 要执行的 “command” 的参数.

  • onExit(status_code)

    当Godot实例退出时,用于通知的回调函数.

    注意: 如果引擎崩溃或无响应,该函数不会被调用.

    • 参数

      • status_code (number) — Godot退出时返回的状态码.

  • onProgress(current, total)

    回调函数,用于显示下载进度.

    该函数在下载文件时每帧被调用一次,所以没有必要使用 requestAnimationFrame() .

    如果回调函数接收到的字节总数为0,这意味着无法计算.可能的原因包括:

    • 文件随服务器端分块压缩一起提供

    • 文件在Chromium上通过服务器端压缩提供

    • 并非所有文件下载都已开始(通常在没有多线程的服务器上)

    • 参数

      • current (number) — 到目前为止,已下载的字节数.

      • total (number) — 要下载的总字节数.

  • onPrint([…var_args])

    用于处理标准输出流的回调函数.这个方法通常应该只在调试页面使用.

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

    • 参数

      • var_args (*) — 将要输出的可变数量的参数.

  • onPrintError([…var_args])

    用于处理标准错误流的回调函数.这个方法通常应该只在调试页面使用.

    默认情况下,使用 console.error() .

    • 参数

      • var_args (*) — 将要输出的可变数量的参数.