Add a tutorial to package Godot projects as Flatpaks

[Calinou]

Now that there is a Godot BaseApp available on Flathub, we should write a tutorial to package a Godot project as a Flatpak. It should strive to be as short as possible and cover only the essentials, such as:

• Creating the required .desktop and AppStream metadata files. We can add templates to the documentation page itself.
• Creating a Flatpak manifest (based on a template) and editing it to suit the project.
• Setting up sandbox permissions depending on the project's needs.

For more advanced use cases, it should link to the Flatpak documentation.

[ssokolow]

I'm not an expert, but this manifest worked for me when I was experimenting with Flatpak:

{
    "app-id": "com.ssokolow.DodgeTheCreeps",
    "runtime": "org.freedesktop.Platform",
    "runtime-version": "19.08",
    "base": "org.godotengine.godot.BaseApp",
    "base-version": "3.2",
    "sdk": "org.freedesktop.Sdk",
    "command": "godot-runner",
    "modules": [
        {
            "name": "dodge_the_creeps",
            "buildsystem": "simple",
            "build-commands": [
                "install -D game.pck /app/bin/godot-runner.pck",
                "install -D LICENSE.txt /app/bin/LICENSE.txt"
            ],
            "sources": [
                {
                    "type": "file",
                    "path": "game.pck"
                },
                {
                    "type": "file",
                    "path": "LICENSE.txt"
                }
            ]
        }
    ],
    "finish-args": [
        "--share=ipc",
        "--socket=x11",
        "--socket=pulseaudio",
        "--device=dri"
    ]
}

I imagine --share=network would be necessary for network support and I'm not sure what the proper command would be to request access to joystick/gamepad input. The Flatpak docs are no help on that front. (My best guess is that, if --device=dri means /dev/dri/*, then --device=input should do the trick.)

I paired it with this Makefile task:

$(OUT_DIR):
	mkdir -p $(OUT_DIR)

$(lin_out).flatpak: $(lin_objects) $(FLATPAK_ID).json | $(OUT_DIR)
	flatpak-builder --repo=flatpak-repo --force-clean --delete-build-dirs \
		flatpak-build-dir $(FLATPAK_ID).json
	flatpak build-bundle flatpak-repo $@ $(FLATPAK_ID)

(Where lin_out is within OUT_DIR and that's why it's a pre-requisite. Obviously, I haven't yet added AppStream metadata, an icon, and a .desktop file to the experiment.)

[poperigby]

@ssokolow I just tried using that manifest, but flatpak-builder said Failed to download sources: module Lorien: Can't find file at game.pck . What should I do to fix that? Here's my manifest file:

{
    "app-id": "com.flatpak.Lorien",
    "runtime": "org.freedesktop.Platform",
    "runtime-version": "20.08",
    "base": "org.godotengine.godot.BaseApp",
    "base-version": "3.3",
    "sdk": "org.freedesktop.Sdk",
    "command": "godot-runner",
    "modules": [
        {
            "name": "Lorien",
            "buildsystem": "simple",
            "build-commands": [
                "install -D game.pck /app/bin/godot-runner.pck",
                "install -D LICENSE.txt /app/bin/LICENSE.txt"
            ],
            "sources": [
                {
                    "type": "file",
                    "path": "game.pck"
                },
                {
                    "type": "file",
                    "path": "LICENSE.txt"
                }
            ]
        }
    ],
    "finish-args": [
        "--share=ipc",
        "--socket=x11",
        "--socket=pulseaudio",
        "--device=dri"
    ]
}

[ssokolow]

@PopeRigby I'm not an expert, but here's how I did it when it worked:

1. Make sure "Embed Pck" is disabled when you're exporting. (You should get an executable and a .pck file of the same name)
2. Ensure the .pck file is named game.pck or edit the flatpak manifest to look for a different name. (I think game.pck was just the default Godot gave me.)
3. Put the .pck file and the manifest in the same folder
4. Run flatpak-builder with the current directory set to the directory containing the .pck file and manifest.

install -D is just a beefed up file-copying command, so the build-commands section is just copying game.pck and LICENSE.txt from the current directory to the locations in the flatpak build where org.godotengine.godot.BaseApp will expect to find them.

(Basically, as I understand it, Flatpak operates in two stages. First the sources section lists files to be downloaded or copied into the temporary build environment and then the build-commands section is commands which take the temporary build environment as input and modify the /app folder that will become the flatpak package as output. The idea being that downloading sources can be done using only trusted code, and compiling the sources can be done inside a sandbox... similar to how a from-source package manager like Gentoo's Portage works.)

[ssokolow]

Also, now that I have a bunch of games and related stuff installed off Flathub, it looks like, pending a more fine-grained solution, --device=all is the current convention for getting joystick access. (Though, apparently, that still doesn't enable hotplug support because doing that without indirecting gamepad access through a Wayland API would require splitting two sides of an unstable/internal udev API across the sandbox/packaging boundary.)

Given the known shortcomings in the documentation for the arguments used by finish-args, I don't know what other valid values there are for --device=....

...and here's the other relevant issue discussing gamepads within Flatpak:

https://github.com/flatpak/xdg-desktop-portal/issues/536

[poperigby]

So you have to manually export the Godot project every time it gets updated?

[ssokolow]

I'm a Godot beginner. I haven't had time to look into how to automate exporting. What I provided is just the non-Godot steps in the process.

Still, my advice holds true either way. Whether you script it or use the GUI, you need to make sure "Embed Pck" is off, and make sure the exported .pck filename matches what the flatpak manifest is set up to take as input.

[poperigby]

Oh right, I could probably do it through the Godot CLI.

[ssokolow]

If you want to export the .pck file using Godot's CLI, the command would be:

godot --quiet --no-window --export-pack "$(EXPORT_PRESET_NAME}" game.pck ${PROJECT_ROOT}/project.godot

Moving that inside the Flatpak manifest would require pulling a copy of Godot into the build environment that's been built with support for running --export-pack in a headless configuration and I'm not familiar enough with Flatpak to know what the recommended way to do that is.

For example, this should probably work if such a binary is available in the build environment as godot and you've named your Linux export preset "Linux/X11" in Godot's export dialog:

{
    "app-id": "com.ssokolow.DodgeTheCreeps",
    "runtime": "org.freedesktop.Platform",
    "runtime-version": "21.08",
    "base": "org.godotengine.godot.BaseApp",
    "base-version": "3.3",
    "sdk": "org.freedesktop.Sdk",
    "command": "godot-runner",
    "modules": [
        {
            "name": "dodge_the_creeps",
            "buildsystem": "simple",
            "build-commands": [
                "godot --quiet --no-window --export-pack 'Linux/X11' /app/bin/godot-runner.pck dodge_the_creeps/project.godot",
                "install -D LICENSE.txt /app/bin/LICENSE.txt"
            ],
            "sources": [
                {
                    "type": "dir",
                    "path": "dodge_the_creeps"
                }
            ]
        }
    ],
    "finish-args": [
        "--share=ipc",
        "--socket=x11",
        "--socket=pulseaudio",
        "--device=dri"
    ]
}

[sweethoneycode]

I would love to see a template tutorial that covers this as I am looking to build my games for flatpak. It would be cool if it were an export option eventually for simplicity.

[Laserology]

This would be great if offered as an export option, alongside the typical Linux/x11 export option, as that would reduce the steps required for pushing updates and maintainence time. Being able to set properties in the config menu and pressing a button to export sounds much nicer than changing bits in various files for setting up permissions and such.

Also, if being built with Godot flatpak edition, it would entirely remove the requirement for users to install the required flatpak-builder package and it's dependancies onto their system, because I believe it's offered in one of the standard freedesktop SDK packages. Fingers crossed this gets somewhere