Luis Carli

Publishing Web Exports from Godot 4

As of August 2023, assuming that the players are running up-to-date modern browsers, there are still two technical hurdles to be overcome to publish web-exported versions of Godot 4 projects:

  1. Because of how browsers handle security (and for loading optimization), the files need to be served from servers with specific configurations.
  2. A bug on MacOS Firefox and Chrome makes the games take an additional two or more minutes to load.

First, Godot 4 can’t be run single-threaded (as opposed to Godot 3), so its web exports need to leverage SharedArrayBuffer in browsers. To be able to use that feature, browsers require that the page be served from an HTTPS connection with some extra headers added. The following ones did the trick for me:

Cross-Origin-Embedder-Policy: "require-corp";
Cross-Origin-Opener-Policy: "same-origin";

The .wasm file created by Godot should be served with the application/wasm mime.type. Because of the usual size of that file (it contains the engine), configuring the server to use compression on the relevant mime.types makes a huge difference. With gzip, I saw up to 3.9x file reduction; a 29MB file became a 7.44MB file, resulting in much snappier loading. The .pck file contains the game script and resources; it can be served as application/octet-stream and can also be configured to be gzipped.

Second, in MacOS, the player needs to use the Safari browser (I dug deeper and wrote about the technical reasons here). To handle that, it’s possible to create a stop-gap by checking if the user is on a Mac and not on Safari, and display some information about that. With user-agent parsing through JavaScript on the browser, one way to do that is:

var isSafari = /^((?!chrome|android).)*safari/i.test(navigator.userAgent);
var isMac = navigator.userAgent.indexOf('Mac') > -1;

if (isMac && !isSafari) {

Preconfigured hosting services don’t seem to properly apply all (in most cases, any) of the server configurations presented here. Also, I haven’t seen web game hosting services handling graciously a fleeting problem like the Mac Firefox and Chrome bugs. I’m of the approach that, when possible, you should own the platform where you post your projects, so I ended up trying to handle the aforementioned problems myself. My results so far can be tested here.

Some info about my setup:

Previous — Blog

Why Godot 4 Web Exports on Mac only work on Safari?