Exporting builds from Godot

Adding flags to exported builds

I didn’t look into this too much, but what I did want is a way to determine if I was using a debug build, and that’s easy (reference): OS.has_feature("debug"). When exporting, if you want this debug feature to exist, just type "debug" into the “Features” tab:

Note that exporting with the debug feature is not the same as exporting such that C#‘s #if DEBUG will work.

Installing export templates

This needs to be done before any kind of export:

• Make sure you’ve downloaded Godot export templates from Editor → Manage Export Templates…:

macOS (reference)

• Make sure to install export templates (reference)
• All you need to do is:
  • Set the export path (e.g. ./output.app)
  • Fill out the bundle identifier (e.g. com.example.game)
  • If you’re not going to sign/notarize the app, then you should also enable Codesign → Entitlements → Disable Library Validation (it says to enable that option if you’re using ad-hoc signing, which should be the case, and you can verify that by reading the yellow warning text at the bottom of the export window).
  • Click “Export All…”
• To run it, just do open ./output.app on the command line

Exporting Windows builds using a Mac

If you get that warning about needing rcedit, you can just uncheck Application → Modify Resources, which means you won’t have a custom icon on Windows. If you do want a custom icon, then install rcedit (and apparently WINE) following these instructions. If you don’t want to use rcedit, they have instructions farther down that page saying that you can compile Windows export templates yourself with godot.ico replaced by your icon. I assume you can also replace any of the other metadata by modifying this file, but I didn’t test this.

To use WINE for this through the Godot UI (reference):

• Get Wine. I already had it as part of Whisky, and mine was located here: ~/Library/Application Support/com.isaacmarovitz.Whisky/Libraries/Wine/bin
• Fill out Godot → Editor Settings → Export → Windows → wine with that path. Don’t include quotation marks.
• Fill out the sibling option, rcedit, with the path to rcedit that you download from GitHub
• Export as you normally would with “Modify Resources” checked, meaning it will inject this information using rcedit.

To use WINE through the command line, just run rcedit according to their instructions. E.g. this changes the icon: ./wine64 ./rcedit-x64.exe ./my-game.exe --set-icon ./my-icon.ico

For some examples of how this looks for other games on Windows:

Web export

Note that as of 02/14/2024, you cannot do a web export from the .NET version of Godot, so make sure you open the non-Mono version; it says so right in the export dialog:

How to export

• Make sure to install export templates (reference)
• Set the export path (e.g. ./out/web/index.html)
  • Note: the out/web folder needs to exist for this to work
  • It’s a good idea to make an intermediate folder like html or out since you’ll get more files than just the HTML file.
• Click “Export Project…” or do it through the command line

Hosting the web export

With any means of hosting on the web, you may eventually see an error like this:

Error
The following features required to run Godot projects on the Web are missing:
Cross Origin Isolation - Check web server configuration (send correct headers)
SharedArrayBuffer - Check web server configuration (send correct headers)

This means that the headers haven’t been set correctly by the web server. Sub-sections below talk about how to fix this.

Hosting locally

• Note: regardless of how you do this, you’ll need to do a new web export every time you want to update the game for people playing it. Also, you probably need to restart the server unless you only made client-side changes.
• The easiest way to do this is to use the Python script that they link from this page (here’s a direct link to the Python script, but maybe this’ll change eventually).
  • The concrete steps are very simple:
    • Download that page as host.py
    • Run python3 host.py -r path_to_the_folder_containing_your_html_file
  • If you don’t do this and instead try to host with something like http-server ., you’ll get an error like this:
• If you want to easily share this with people without having to upload this anywhere, just use Cloudflare Tunnels.
  • When setting up the tunnel, you can choose “HTTP” and Cloudflare will automatically set up a certificate for you so that it works over HTTPS, which is apparently required by Godot for the secure-context stuff.

Hosting on a shared web host

If the host is based on Apache (e.g. it can be LiteSpeed Web Server), then it supports .htaccess files, which means you can upload an .htaccess file alongside your .html file that looks like this:

<IfModule mod_headers.c>
  Header add Cross-Origin-Opener-Policy "same-origin"
  Header add Cross-Origin-Embedder-Policy "require-corp"
</IfModule>

Hosting on itch.io

This should be straightforward. There’s some additional context around the header stuff here. I hosted a game on Itch a while ago, so I didn’t think there was much to write notes about this time around.

Accessing files from exported builds

Godot has two main ways of accessing files:

• DirAccess.GetFiles
• ResourceLoader.ListDirectory

These do slightly different things and have some quirks to them:

• DirAccess will only list files on-disk. This means that if you have an .svg file in your project and you’re running a build through Godot, then you’ll see that .svg file on-disk. However, after exporting a build from Godot and running, the .svg file will no longer exist. Instead, this file is imported into Godot (hence the existence of a .import file).
• ResourceLoader.ListDirectory will list only resources and directories.
  • Resources are any of these, e.g. a scene, an asset that had an .import file, a .tres file, etc.
    • The way that imported resources work is that Godot will consult the .import file to find the underlying data inside the .godot folder. This folder isn’t checked in to source control, so it’s possible that you have an .import file with no corresponding data. This can happen if you delete, say, foo.svg from outside of Godot without also deleting its foo.svg.import (which Godot would have done for you if you’d deleted through the editor).
      • In this case, attempting to use ResourceLoader.Load("res://foo.svg") will fail on an unexported build, but the exported build is apparently smart enough to know that the .import file has no underlying data.
  • Directories will end in a slash, e.g. Builds/ or Src/.

The conclusion is that if you’re trying to load resources that have .import files, you must use ResourceLoader.ListDirectory or else you’ll see empty directories on exported builds. For example, for Skeleseller, I wanted to preload all SVG files, so I needed ResourceLoader.ListDirectory because DirAccess.GetFiles couldn’t find .svg files since they were imported.

The final quirk here is that file names can be changed during export. This is what the [remap] property is at the top of any .import file. ResourceLoader.ListDirectory is aware of these, so you wouldn’t need to do anything special. But DirAccess.GetFiles will only find foo.tscn.remap instead of foo.tscn. However, you can’t load a resource via foo.tscn.remap. This is yet another reason to use ResourceLoader over DirAccess for fetching resources.

Troubleshooting

Export buttons are disabled

This could be due to not having export templates installed. See Exporting builds from Godot#Installing export templates.

Exported game crashes on macOS

Instead of doing open YourGame.app, do cd YourGame.app/Contents/MacOS → ./YourGame. That should show errors that won’t show when you use open.

In my specific case, I saw ERROR: Can't load dependency: res://Src/SceneScripts/Main.cs., which seemed could have been a Godot issue but turned out to be my issue 🤦‍♂️.

Exported game has the wrong executable name

I was exporting to out/windows.zip, so my executable was named windows.exe. It’s better to just output to something like out/windows/YOUR_GAME_NAME.zip so that it gets the correct name.