GitHub Actions: Test project exporting on CI

[Calinou]

This allows finding issues in headless project export early on, including when exporting for a dedicated server.

We also use this opportunity to check whether the audiovisual output between the project being run from its files and the exported PCK matches (it should always be a perfect match, assuming the same GPU is used for both runs). This can be used to catch audiovisual discrepancies, which could indicate a bug in the export process. This also tests Movie Maker mode functionality while we're at it.

The test project is currently part of the main repository, so I've attempted to minimize the file size while making use of as many Godot features as possible. We could move this test project to a separate repository, but this would increase the complexity of the setup and make it harder for contributors to test this project locally (as well as further improve it).

This export test is performed on the Linux Editor w/ Mono job, which will allow for testing C# (not implemented in this PR yet).

The development of this PR has already uncovered several bugs so far:

• Crash when importing a 3D scene with UV2 unwrap enabled in a double-precision development build #109097
• Shader baker still exports a shader cache for dedicated server exports #109098
• QOA assertion failure on import when running with sanitizers enabled #109099
• Baked VoxelGIData and LightmapGIData is still exported in dedicated server exports #109141
• Exporting a project from headless mode prints an error when VoxelGIData is present in the project #109145
• Per-instance shader parameter values are not correctly exported when the export is performed in --headless mode #109177
• CSV translation causes errors to be printed on export, even though it's functional (no issue open yet?)
  • I can't reproduce this in a new project, such as test_csv_export_error.zip.

Preview

The project features:

• LightmapGI setup, as well as most 3D rendering features enabled.
• Custom text and visual shaders (the black and white spheres), with parameters set to non-default values. Global and per-instance uniforms are also used in the text shader. The default parameters are red, while the overrides are green. If the project is run/exported correctly, you should only see green spheres, not red ones.
• All texture compression types (with and without mipmaps) as shown in the top-left corners. Size Limit is also used here, with a size of 29×29 to ensure we have valid behavior for texture sizes that aren't a multiple of 4.
• 3D scene import in all supported formats (the apples).
• Translation and font imports (standard, LCD subpixel, MSDF, bitmap).
• GDScript, C# and GDExtension C++ using godot-cpp.
  • C# work moved to this branch: https://github.com/Calinou/godot/tree/ci-test-project-export-csharp
  • GDExtension work moved to this ZIP: addons.zip
  • Actions code to build the extension:

Details

    - name: Build test GDExtension
      shell: sh
      run: |
        cd misc/test_project/addons/test_extension/
        git clone --depth=1 https://github.com/godotengine/godot-cpp.git src/godot-cpp/
        scons target=template_debug
        scons target=template_release
        cd ../../../../

• OBJ scene/mesh import
  • Moved to this branch due to errors being printed on export on CI (not on my machine): https://github.com/Calinou/godot/tree/ci-test-project-export-obj-voxelgi
• VoxelGI export
  • Moved to this branch due to errors being printed on export on CI (not on my machine): https://github.com/Calinou/godot/tree/ci-test-project-export-obj-voxelgi
  • Strip VoxelGIData and LightmapGIData using placeholders for dedicated server exports #112744 fixes the issue, so we can readd VoxelGI to the test project once that PR is merged.
• Audio playback
  • Removed due to leaked instances on exit, causing CI to fail.
  • Sound files to be readded when the issue is fixed: sounds.zip

TODO

• Add DDS and KTX texture loading.
• Add more resource types. Perhaps use an EditorScript to generate all of them, which might uncover some more bugs in the process.

For a future PR (due to the complexity):

• Test exporting to Android with both Gradle and APK workflows. This will require waiting on the Android build to finish, then making this CI job download the artifacts and use them for export. It would also require setting up the Android SDK before exporting.
• Test exporting to Windows and web platforms. Not as involved as Android, but it'll still require changing the CI setup to add dependencies to other platforms' workflows.
• Test exporting to macOS and iOS. This requires using a macOS host, which may not be technically feasible due to Metal rendering driver fails to run on Apple's software Metal implementation (paravirtual device) #101773.

[Repiteo]

This is fantastic for testing purposes, and already coming along really nicely; great job!

Though, the test project itself shouldn't be in the repo. It's not something to worry about during this testing phase, but we should do something similar to the regression test project where it's downloaded from a remote location

[mihe]

Anything that can be done to help move this one forward? I'd love to see this merged in some form for 4.6, since it would've helped catch one or two of the regressions that I ran into during the last beta.

[Calinou]

Anything that can be done to help move this one forward? I'd love to see this merged in some form for 4.6, since it would've helped catch one or two of the regressions that I ran into during the last beta.

I'll take a look at it again next week. Once I get CI to pass, we can look into creating a new repository in the @godotengine organization then update this PR to remove the test project from it (and make it clone the other repository instead).

There's already https://github.com/godotengine/godot-tests, but we don't seem to be using the tests from that repository anywhere currently.

The alternative is to modify https://github.com/godotengine/regression-test-project to include two projects side-by-side (the existing project + the new one).

What do you think?

[akien-mga]

There's already https://github.com/godotengine/godot-tests, but we don't seem to be using the tests from that repository anywhere currently.

I guess using that repository makes sense. Eventually we might want to run more of this kind of integration tests which could be hosted in that repo. The existing tests may or may not be obsolete but you can likely replace the project_export one with your new project.

[Calinou]

I'm getting a CI failure due to sanitizers on the regression test project (not the project added by this PR). How come it doesn't occur on master? I just rebased my PR on top of current master.

[Calinou]

CI is passing now, so I've opened a PR on godot-tests with the test project:

• Add test project export for CI godot-tests#35

Once the above PR is merged, I'll change this PR to download the test project from godot-tests instead of embedding it here.

[mihe]

@Calinou Any plans on resuming the GDExtension part of this if/when this is merged, or did you find yourself stuck on the dynamic library loading issue you were having?

[Calinou]

@Calinou Any plans on resuming the GDExtension part of this if/when this is merged, or did you find yourself stuck on the dynamic library loading issue you were having?

Yes, I'll look into it once this is merged. I've tried to use --export-release "Linux" instead of --export-pack, but it didn't seem to work (possibly because I accidentally left the output path as /tmp/test_project.zip instead of /tmp/test_project.x86_64, and this seemed to create a zipped export with missing GDExtension libraries).

I've reverted the PR to use --export-pack for now, but ideally, I would expect --export-pack to copy GDExtension libraries next to the PCK/ZIP just like --export-release (since it knows the platform it's exporting for).

[akien-mga]

Once the above PR is merged, I'll change this PR to download the test project from godot-tests instead of embedding it here.

Just a reminder that this still needs to be done before merging.

[akien-mga]

Seems like the project is using an outdated export preset:

ERROR: Invalid export preset name: Linux.
The following presets were detected in this project's `export_presets.cfg`:

        "Linux/X11"

   at: _fs_changed (editor/editor_node.cpp:1331)
ERROR: 'ERROR:' found in log and GODOT_CHECK_CI_LOG_ALL_ERRORS is set.

[mihe]

Was there anything in particular holding this up?

We got hit with yet another export determinism issue (#115914), so I'd love to see some sort of export determinism check added to CI, which this project would seem to be a good candidate for. I'd be happy to take that on once this is merged.

[Calinou]

Was there anything in particular holding this up?

I've rebased the PR and pushed a tentative CI fix. It should be good to merge when CI passes.

Edit: CI is failing due to GitHub having trouble right now. Re-running CI tomorrow should make it work.

I'd be happy to take that on once this is merged.

Sure, feel free to open a PR once this one is merged 🙂

[Repiteo]

Thanks!

[JoNax97]

Hi! Does this fully address the improvements described in the priorities page? or is more work to be done?

Thanks!

[Calinou]

Hi! Does this fully address the improvements described in the priorities page? or is more work to be done?

There's still more work to be done, which is why I left that priority in when I updated the page:

• Update Priorities page to match status as of January 2026 godot-website#1238

Some limitations (like the shader baker not working in headless builds) can't be fully addressed by design due to requiring GPU access, but perhaps we can document a workaround for them by running the editor with llvmpipe or SwiftShader (and keeping a X11/Wayland session active if on a server). Implementing support for offscreen rendering will make the process a bit nicer (as no window would spawn when exporting a project in non-headless mode), but it's not strictly required.