为 Web 导出

参见

这个页面描述的是如何将 Godot 项目导出到 HTML。如果你想要找的是从源码编译编辑器或导出模板二进制文件，请阅读 为 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公开议题列表 , 看看你关注的功能是否有议题. 如果没有, 请打开一个议题来表达你的兴趣.

使用 cookie 进行数据持久化

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

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

后台处理

这个标签页不再是用户浏览器的活动标签页时，项目就会被浏览器暂停。也就是说不会运行 _process()、_physics_process() 等函数，除非用户重新激活了这个标签页（切换到这个标签页）。如果用户在标签页外停留了过长的时间，就可能造成网络游戏的掉线。

这一限制不适用于丢失焦点的浏览器窗口。因此，对于用户而言，变通方法是让项目运行在一个单独的窗口中，而不是标签页。

线程

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

警告

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

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中的脚本语言不可能的方式与浏览器交互.

  1. func my_func():
  2.     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 返回

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

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

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

  1. func my_func3():
  2.     if OS.has_feature('JavaScript'):
  3.         JavaScript.eval("""
  4.             console.log('The JavaScript singleton is available')
  5.         """)
  6.     else:
  7.         print("The JavaScript singleton is NOT available")

小技巧

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

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

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