flatpaker

Script to mostly automate creating flatpaks from published Ren'Py and Linux builds of RPGMaker MV and MZ. Open to additional support

What is it?

It's a script that automatically handles much of the task of generating a flatpak for pre-built projects, including adding patches or mods. You write a small, simple toml file, fetch the sources, and get a ready to publish flatpak.

It currently does the following automatically:

• Generates an appstream xml file
• Generates a .desktop file
• Extracts an icon from the game source, and installs it
• patches the game to honor $XDG_DATA_HOME for storing game data inside the sandbox (instead of needing $HOME access)
• allows local install or publishing to a repo
• allows generating static deltas after building
• sets up the sandbox to allow audio and display, but nothing else

For Ren'Py:

• provides a runtime with up to date renpy and deps, built against the freedesktop Platform libraries. using the shared runtime saves space, as well as ensures that all games can be run with Wayland support.
• strips .rpy files to save space (keeping the rpyc files)

For RPG Maker:

• provides a runtime with a newer nwjs installed, saving disk space
• using this nwjs also gives guaranteed wayland support
• It also allows running MV and MZ games that don't ship Linux builds, using the Windows build

Why?

I like playing Ren'Py and RPG Maker games sometimes. I also don't always trust random pre-compiled binaries from the internet. Flatpak provides a nice, convenient way to sandbox applications. It also makes supporting Steam Deck and Fedora immutable a breeze. But generating flatpaks by hand is a lot of work, especially when most of the process will be exactly the same for every project. The use of up-to-date runtimes saves more disk space and allows for the sandbox to provide even better security by using Wayland instead of X11 (or XWayland).

How do I use it?

1. Download the compressed project
2. Download any mods or addons (optional)
3. Generate a toml description flatpaker generate com.developer.game "Game Name" engine archive.zip
4. Edit the generated description to fill in missing information
5. run flatpaker build-runtimes --export=install (which adds the runtimes and sdks)
6. Run one of:

• flatpaker build --export=install *.toml to install for your user
• flatpaker build --export=repo --gpg-sign *.toml to export to a local ostree repo
• flatpaker build --export=flat-manager *.toml to export to a flat-manager instance

Toml Format

[common]
  name = 'Game or VN'  # use properly formatted name like "The Cool Adventures of Bob", or "Bob's Quest 7: Lawnmower Confusion"
  reverse_url = 'com.example.JDoe'  # name will be appended
  # "Game" is added automatically
  # used freedesktop menu categories. see: https://specifications.freedesktop.org/menu-spec/latest/apas02.html
  categories = ['Simulation']
  engine = 'renpy8'  # Or 'rpgmaker', 'renpy7', 'renpy7-py3'

[appdata]
  summary = "A short summary, one sentence or so."
  description = """
    A longer description.

    probably on multiple \
    lines
    """

  # This is an optional value for the license of the renpy project itself.
  # If unset it defaults to LicenseRef-Proprietary.
  # if you have specific terms which are not an Open Source license, you can use the form:
  # LicenseRef-Proprietary=https://www.example.com/my-license
  # See: https://spdx.org/specifications for more information
  license = "SPDX identifier"

[appdata.content_rating]
  # optional
  # Uses OARS specifications. See: https://hughsie.github.io/oars/
  # keys should be ids, and the values are must be a rating (as a string):
  # none, mild, moderate, or intense
  language-profanity = "mild"

[appdata.releases]
  # optional
  # in the form "date = version"
  "2023-01-01" = "1.0.0"

# Requires at least one entry
[[sources.archives]]
  # path must be set if this is provided
  path = "relative to toml or absolute path"

  # Optional, defaults to 1. How many directory levels to remove from this component
  strip_comonents = 2

  # Optional, will be automatically calculated if not provided, but providing it can speed up building
  sha256 = "abcd..."

  # Optional, will run these shell commands after extracting this archive
  commands = [
    'sed -i s/foo/bar/ extracted_source',
  ]

# Optional
[[sources.patches]]
  # path must be set if this is provided
  path = "relative to toml or absolute path"

  # Optional, defaults to 1. How many directory levels to remove from this component
  strip_comonents = 2

# Optional
[[sources.files]]
  # path must be set if this is provided
  path = "relative to toml or absolute path"

  # Optional, if set the file will be installed to this name
  # Does not have to be set for .rpy files that go in the game root directory
  dest = "where to install"

  # Optional, will be automatically calculated if not provided, but providing it can speed up building
  sha256 = "abcd..."

  # Optional, will run these shell commands after this file is added
  commands = [
    'sed -i s@/bin/bash@/usr/bin/env bash@ script.sh',
  ]

Sources will be evaluated by:

1. archives, with their command entry
2. files, with their command entry
3. patches

Quirks

Additionally, some games have quirks that make them difficult to package. Some of these quirks can be worked around.

Any quirk starting with x_ or x- is an experimental quirk, and may be removed at any time. If you find yourself relying on them, please open an issue.

For example:

[quirks]
  force_window_gui_icon = true

Generic

• x_configure_prologue: string: A block of shell commands to run after unpacking all of the sources and applying patches, but before any build steps take place. This is slated for removal as the commands argument to archives and files should be able to fix all of this.

Renpy

• force_window_gui_icon: bool. Use game/gui/window_icon.png instead of extracting icons from the exe or icns files. This is generally unnecessary, but some games have customized window_icons but not exe icons.

• x_renpy_archived_window_gui_icon: string. Extract a gui/window_icon.png file from the named archive instead of extracting from the exe or icns files. This is generally unnecessary, but see above.

Configuration

Some options can be given on the command line or via a configuration file. That file must be written to $XDG_CONFIG_HOME/flatpaker/config.toml (if unset $XDG_CONFIG_HOME defaults to ~/.config).

[common]
  # A gpg private key to sign with, overwritten by the --gpg option
  gpg-key = "0x123456789"

  # The absolute path to a repo to write to. overwritten by the --repo option
  repo = "/path/to/a/repo/to/export"

  # The default export mode
  # May be one of: "none", "install", "repo", "flat-manager"
  export = "none"

[flat-manager]
  # The address that the flat-manager instance listens on
  remote = "https://flat-manager.example.com:8080"

  # The default repo on that flat-manager instance to push to
  repo = "stable"

  # Only one of the following may be set. This is the repo key that
  # will be passed to the flat-manager client.

  # A pair of strings to pass to `keyring.get_password()`
  # The token can be written into the keyring with the command line tool
  # `keyring set <serivce name> <keyname>`.
  token-keyring = ["service name", "keyname"]

  # A file containing the key
  # Both environment variables and `~` can be used here
  # This is the only form that can be set on the command line
  token-file = "/secret.d/flat-manager/1"

  # The keyfile written straight into the config file
  token-str = "ABC123"

What is required?

• python >= 3.10
• python-keyring (if using flat-manager export with a secret stored in a keyring)
• python-tomlkit
• flatpak-builder
• flatpak
• flat-manager-client (if using flat-manager export)
• git (if building runtimes)

Schema

A Json based schema is provided, which can be used with VSCode's EvenBetterToml extension. It may be useful elsewhere.

FAQ and Things You Should Know

Ren'Py 7 Python 3 runtime

tl;dr: This runtime is deprecated and will be removed in the future, unless someone reports a game that uses it.

This runtime is still based on the older Freedesktop 24.08 runtime. This runtime will reach EOL in 2026/09. Updating to 25.08 or 26.08 is not trivial.

Ren'Py 7 cannot be built with a Python newer than 3.12, due to it's reliance on Cython 0.29, which does not support a new Python 3 release. This means I would either need to build a second copy of Python 3 into the runtime (possible), update Ren'Py 7 (and its dependencies) to build with newer Cython (possible, but harder, more likley to introduce bugs).

I also have yet to find a single Ren'Py game that actually uses it, everything Python 3 based uses Ren'Py 8, and everythign using Ren'Py 7 uses Python 2 (or works with Python 2). I originally created the Ren'Py 7 Python 3 runtime for completeness and because it was interesting and easy.