Work in progress

The content of this page was not yet updated for Godot 4.2 and may be outdated. If you know how to improve this page or you can confirm that it's up to date, feel free to open a pull request.

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 (*()) -- 将要输出的可变数量的参数.