HTML5 shell 类参考
- 引擎
  - 静态方法
  - 实例方法
- 引擎配置
  - 属性

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)

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

参数
- initConfig (EngineConfig()) — 此实例的初始配置.

静态方法

Engine.load(basePath)

从指定的基本路径加载引擎.
- 参数
  - basePath (string()) — 引擎加载的底层路径.
  返回
  
  一个一旦加载引擎就会解析的Promise.
  
  返回类型
  
  Promise
Engine.unload()

卸载引擎以释放内存.

该方法可以被配置为自动调用。请参阅 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 . 引擎必须事先加载.

如果在页面上找不到画布, 或者没有在配置中指定, 则失败.
- 参数
  - override (EngineConfig()) — 一个可选的配置重写.
  返回
  
  引擎启动后解析的Promise.
  
  返回类型
  
  Promise
Engine.prototype.startGame(override)

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

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

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

该方法将初始配置(或重写)时同时设置 executable 和 mainPack 属性(通常由编辑器在导出过程中完成).
- 参数
  - override (EngineConfig()) — 一个可选的配置重写.
  返回
  
  一旦游戏开始就会解析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 编辑器的导出过程设置）。
- 类型
  
  字符串
  
  值
  
  ""
mainPack

要加载的游戏pck的更换名称. 否则使用可执行文件名.
- 类型
  
  字符串
  
  值
  
  null
locale

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

如果没有指定，将使用浏览器的区域设置。请参阅完整的支持的区域设置列表。
- 类型
  
  字符串
  
  值
  
  null
canvasResizePolicy

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

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

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

2 意味着 Godot 将调整画布的大小以匹配整个浏览器窗口。
- 类型
  
  数字
  
  值
  
  2
args

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

请参阅命令行教程。

注意：startGame 将始终添加 --main-pack 参数。
- 类型
  
  Array.<string>
  
  值
  
  []
onExecute(path, args)

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

This is for example used in the Web Editor template to switch between Project Manager and editor, and for running the game.
- 参数
  - path (string()) — Godot想要执行的路径.
  - args (Array.) — 要执行的 “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 (*()) — 将要输出的可变数量的参数.