为Web导出

为Web导出

HTML5导出允许将在Godot引擎中制作的游戏发布到浏览器. 这需要在用户浏览器中支持 WebAssembly 和 WebGL .

重要

使用浏览器集成的开发人员控制台, 通常使用 F12 打开, 来查看 调试信息 , 如Javascript, 引擎和WebGL错误.

注意

在iOS上运行HTML5项目有严重的bug 这与浏览器无关.推荐使用 iOS’ native export functionality ,同时它也有更好的性能.

WebGL版本

根据你对渲染器的选择，Godot可以面向WebGL 1.0（GLES2）或WebGL 2.0（GLES3）。

如果你想让你的项目在所有的浏览器上都得到支持，并且有最好的性能，建议选择WebGL 1.0。

Godot的GLES3渲染器以高端设备为目标，使用WebGL 2.0的性能可能不理想。有些功能在WebGL 2.0中也不被特别支持。

此外，虽然大多数浏览器都支持WebGL 2.0，但对于的 Safari 来说并不同。WebGL 2.0支持将在MacOS的Safari 15中出现，而对于任何**iOS** 的浏览器来说还未支持（像Safari一样都是基于WebKit内核）。参阅 Can I use WebGL 2.0 。

导出选项

如果可以使用可运行的Web导出模板, 则编辑器中的 停止场景 和 播放编辑的场景 按钮之间会出现一个按钮, 可以在默认浏览器中快速打开游戏进行测试.

你可以选择 导出类型 ，以选择哪些功能将被使用:

Regular: 跨浏览器的兼容性最好，不支持线程，也不支持GDNative。
Threads: 将要求浏览器支持 SharedArrayBuffer 。参阅 Can I use SharedArrayBuffer 。
GDNative: 启用GDNative支持，但使二进制文件更大，加载速度更慢。

如果你打算使用 VRAM compression ，请确保为目标平台启用 Vram Texture Compression （同时启用 For Desktop 和 For Mobile 将导致更大，但更兼容的导出）。

如果给出了 自定义HTML Shell 文件的路径, 则将使用它来代替默认的HTML页面. 请参阅导出自定义HTML页面.

Head Include 被附加到生成的HTML页面的 <head> 元素中. 例如, 这允许加载webfonts和第三方JavaScript APIs, 包括CSS或运行JavaScript代码.

重要

每个项目必须生成他们自己的HTML文件。在导出时，几个文本占位符会在生成的HTML文件中被替换，专门用于给定的导出选项。任何对该HTML文件的直接修改都会在以后的导出中丢失。要自定义生成的文件，请使用** 自定义HTML shell**选项。

警告

C# 版本尚不支持除 Regular 之外的 导出类型 。

限制

出于安全和隐私的原因, 许多在本机平台上轻松工作的功能在Web平台上更加复杂. 以下列出了将Godot游戏移植到Web时应注意的限制.

重要

浏览器供应商正在使越来越多的功能只在安全上下文中可用，这意味着这些功能只有在通过安全的HTTPS连接提供网页时才可用（localhost通常不受这种要求影响）。

小技巧

查看GitHub上的 HTML5公开议题列表 , 看看你关注的功能是否有议题. 如果没有, 请打开一个议题来表达你的兴趣.

如果需要持久化 user:// 文件系统, 用户必须 允许cookie (特别是IndexedDB). 当玩 iframe 中呈现的游戏时, 还必须启用 第三方 cookie. 隐身/隐私浏览模式也会防止持久性.

方法 OS.is_userfs_persistent() 可用于检查 user:// 文件系统是否持久, 但在某些情况下会误报.

线程

如前所述以上多线程只有在设置了适当的 导出类型 的情况下才可用，而且对跨浏览器的支持仍然有限。

警告

需要一个安全上下文。浏览器也开始要求在提供网页时要有特定的跨源隔离头。

GDNative

正如前面提到的以上 GDNative只有在设置了适当的 导出类型 时才可用。

导出也将复制所需的GDNative .wasm 文件到导出文件夹（必须与游戏一起上传到你的服务器）。

全屏和鼠标捕获

浏览器不允许任意 进入全屏 . ** 捕获光标** 也是如此. 相反, 这些操作必须作为对JavaScript输入事件的响应而发生. 在Godot中, 这意味着从按下的输入事件, 例如 _input 或 _unhandled_input, 回调中进入全屏. 查询 Input 单例是不够的, 相关的输入事件当前必须是活动的.

出于同样的原因, 除非从有效的输入事件处理程序中启动引擎, 否则全屏项目设置将不起作用. 这需要定制HTML 页面.

音频

Chrome 限制网站播放音频的方式. 可能需要玩家单击或轻按或按住一个键来启用音频.

参见

Google提供了有关其网络音频自动播放政策的其他信息.

警告

访问麦克风需要安全上下文。

网络

由于缺乏浏览器的支持，低级别的网络没有实现。

目前，只有 HTTP client, HTTP requests, WebSocket (client) 和 WebRTC 被支持。

HTTP类在HTML5平台上也有若干限制:

无法访问或更改 StreamPeer

Threaded/Blocking 模式不可用

每帧不能进行多次, 因此循环中的轮询将冻结

没有分块响应

无法禁用主机验证

遵循同源政策

剪贴板

在引擎和操作系统之间同步剪贴板需要浏览器剪贴板 API ，此外，由于该 API 的异步性，从 GDScript 访问时可能不可靠。

警告

需要安全上下文。

游戏手柄

按下游戏手柄上面的任一按钮之后，这个游戏手柄才能被检测到。根据浏览器、操作系统、游戏手柄三者的组合不同，游戏手柄的映射可能有误，可惜由于隐私方面的考虑，游戏手柄 API 并没有提供可靠的方法来检测游戏手柄的信息，因而无法根据模型、供应商、操作系统来进行重新映射。

警告

需要安全上下文。

启动画面不显示

默认的 HTML 页面在加载时不显示启动界面。然而，该图像会被导出为 PNG 文件，因此可以通过自定义 HTML 页面来显示。

着色器语言限制

导出 GLES2 项目到 HTML5 时，会使用 WebGL 1.0。WebGL 1.0 不支持动态循环，所以使用这一特性的着色器会失效。

提供文件

导出为Web生成多个要从Web服务器提供的文件, 包括用于演示的默认HTML页面. 可以使用自定义HTML文件, 请参阅导出自定义HTML页面 .

生成的 .html 文件可以在Apache服务器中用作 DirectoryIndex, 并且可以在任何时候重命名为例如 index.html, 默认情况下永远不会依赖它的名称.

HTML页面在浏览器窗口内以最大尺寸绘制游戏. 这样, 就可以将其插入游戏大小的 <iframe> 中, 这在大多数网络游戏托管站点中很常见.

其他导出的文件在 .html 文件旁边, 按原样提供, 名称不变. .wasm 文件是实现引擎的二进制WebAssembly模块. .pck 文件是包含你的游戏的Godot主包. .js 文件包含启动代码, .html 文件使用它来访问引擎. .png 文件包含启动画面图像. 默认HTML页面中未使用它, 但自定义HTML 页面中包含了它.

.pck 文件是二进制文件, 通常与MIME类型 application/octet-stream 一起分发. .wasm 文件以 application/wasm 分发.

警告

分发WebAssembly模块(.wasm)时, 使用一个 application/wasm 以外的MIME类型, 可能会阻止某些启动优化.

建议使用服务器端压缩来分发文件, 尤其是对通常很大的 .pck 和 .wasm 文件.WebAssembly模块压缩特别好, 通过gzip压缩缩小到原始大小的四分之一.

提供即时压缩的主机: GitHub Pages (gzip)

不提供即时压缩的主机: itch.io, GitLab 页面 ( 支持手动gzip预压缩 )

从脚本调用JavaScript

在Web构建中, 实现了 JavaScript 单例. 它提供一个名为 eval 的方法, 其工作方式与同名的JavaScript函数类似. 它将字符串作为参数, 并将其作为JavaScript代码执行. 这允许以与集成到Godot中的脚本语言不可能的方式与浏览器交互.

func my_func():
    JavaScript.eval("alert('Calling JavaScript per GDScript!');")

最后一个JavaScript语句的值转换为GDScript值, 并在某些情况下由 eval() 返回:

JavaScript number 作为GDScript的 float 返回

JavaScript boolean 作为GDScript的 bool 返回

JavaScript string 作为GDScript的 String 返回

JavaScript RellBuffer, TypedArray 和 DataView 作为GDScript的 PoolByteArray 返回

func my_func2():
    var js_return = JavaScript.eval("var myNumber = 1; myNumber + 2;")
    print(js_return) # prints '3.0'

任何其他JavaScript值都返回为 null .

HTML5 导出模板可能为了提高安全性而在构建时关闭单例支持。使用这样的模板或者在 HTML5 以外的平台上调用 JavaScript.eval 也会返回 null。可以通过 JavaScript feature 标签来检查单例的可用性：

func my_func3():
    if OS.has_feature('JavaScript'):
        JavaScript.eval("""
            console.log('The JavaScript singleton is available')
        """)
    else:
        print("The JavaScript singleton is NOT available")

小技巧

GDScript中的多行字符串由3双引号 """ 包围, 如同上文中的 my_func3() 那样, 有助于保证JavaScript代码的可读性.

eval 方法也接受第二个可选的布尔参数，它指定是否在全局执行上下文中执行代码，默认为 false 以防止污染全局命名空间：

func my_func4():
    # execute in global execution context,
    # thus adding a new JavaScript global variable `SomeGlobal`
    JavaScript.eval("var SomeGlobal = {};", true)

为Web导出

为Web导出

WebGL版本

导出选项

限制

使用cookie进行数据持久化

线程

GDNative

全屏和鼠标捕获

音频

网络

剪贴板

游戏手柄

启动画面不显示

着色器语言限制

提供文件

从脚本调用JavaScript