Index

Basic Deployment

By using Deploy you can create a deliverable of your game for your current architecture pretty easily. Simply adjust the system definition of your game to include the following fields:

:build-operation "deploy-op"
:build-pathname #+linux "my-game-linux.run"
                #+darwin "my-game-macos.o"
                #+win32 "my-game-windows"
                #+(and bsd (not darwin)) "my-game-bsd.run"
                #-(or linux bsd win32) "my-game"
:entry-point "my-game::main"
:defsystem-depends-on (:deploy)

You can adapt the build pathnames as you wish, as long as the pathname types stay consistent: .run for Linux, .o for MacOS, and none for Windows (.exe is added by default). You can also adapt the entry point as you choose. Usually it'll be a function similar to this:

(defun main ()
  (command-line-toplevel)
  (load-keymap :package #.*package*)
  (load-settings)
  (save-settings)
  (launch 'my-game))

You can now invoke (asdf:make :my-game) to build a release of your game. It'll be put into the bin/ subdirectory of your system source directory. You should be able to just ZIP that directory up and give it to people to play.

Pruning Asset Files

By default Trial copies all files in all asset pools it knows of. This may be over-eager, especially if you make use of asset bundles like trial-assets. To clean up some of the mess, you can use define-as-unused. It accepts asset names or wildcard pathnames so you can easily exclude entire directories or file types.

(define-as-unused trial
  "*.glsl"
  cat)

Using the Release Mechanism

It is often useful to automate the build for multiple operating systems and also automate the submission. For this purpose, the trial-release extension exists This is a system offering automation for pushing releases of your game to a zip, Steam, Itch.io, or other services.

Getting Set Up

First you'll want to create a new ASDF system for your game's release. The ASD file should be in a directory where your releases will be put, so ideally not in the game's source root. The ASD should be something like this:

(asdf:defsystem my-game-release
  :components ((:file "release"))
  :depends-on (:trial-release)
  :perform (asdf:build-op (op c) (uiop:symbol-call :org.shirakumo.fraf.trial.release :make)))

The release file can be something like this:

(org.shirakumo.fraf.trial.release:configure
 :itch (:user "my-itch-username")
 :steam (:user "my-steam-username")
 :system "my-game"
 :depots (:content ("pool/")
          :windows ("*.dll" "*.exe")
          :linux ("*.so" "*.run")
          :macos ("*.dylib" "*.o"))
 :bundles (:linux (:depots (:linux :content))
           :windows (:depots (:windows :content))
           :macos (:depots (:macos :content))
           :all (:depots (:linux :windows :macos :content)))
 :bundle (:targets #(:linux :windows))
 :upload (:targets #(:steam :itch)))

There are other configuration parameters you can set if necessary to customise the build and release process.

Outside of this, you'll have to have the following binaries set up in your PATH:

Once all of this is ready, you can run a build using (asdf:make :my-game-release) or manually invoking org.shirakumo.fraf.trial.release:make after loading that system.
For the sbcl-* variants, you can use the binaries and scripts from the following repository: https://gitea.tymoon.eu/shinmera/trial-deployment They have been pre-tested.

Build Configuration

You can configure the build with the following options, all under the :build scope:

Bundle Configuration

Some upload mechanisms require appropriate bundles to be configured. Bundles will also produce standalone ZIP files that you can distribute manually. To configure bundles, you must first configure depots. A depot is a list of paths in the release that belong to it. Each path in a depot may be either:

Once your depots are configured, you can specify the bundles. Each bundle under the :bundles scope should be a plist of the following options:

To configure which bundles are actually created when you run a default release build, fill the vector for :bundle :targets.

Upload Configurations

The Trial release mechanism supports a number of upload mechanisms to automatically distribute releases to different platforms. See the sections below on how to configure them. If you would like to automatically push releases, make sure to add the upload mechanism to the :upload :targets array.

Steam

Steam will require some VDF files to configure your build in addition. Please consult the SteamWorks documentation on how to do that. However, be aware that the base file should be called app-build.vdf and should be in the same directory as your my-game-release.asd file, and should have several fields set specially so the Trial release mechanism can operate properly. Here's an example:

"appbuild"{
  "appid" "1261430"
  "desc" "Kandria developer build"
  "buildoutput" "../steam/"
  "contentroot" "$CONTENT"
  "setlive" "$BRANCH"
  "preview" "$PREVIEW"
  "local" ""
  "depots"{
    "1261431" "../windows-depot.vdf"
    "1261432" "../linux-depot.vdf"
    "1261433" "../macos-depot.vdf"
    "1261434" "../content-depot.vdf"
  }
}

The Trial release build will automatically take this file and replace the $ variables, then copy it to a subdirectory where the upload happens, hence the ../ backrefs in the paths. The depot VDF files do not need any special configuration.

The steamcmd also needs to be available in your PATH.

In the configuration, the following keys are available in the :steam scope:

Itch

To upload to itch, you will need to have the butler program in your PATH. Make sure to run Butler once before to save the login credentials.

In the configuration, the following keys are available in the :itch scope:

GOG

To upload to GOG, you need the GOGGalaxyPipelineBuilder program in your PATH. You can run it first to cache credentials, or pass them in the Trial configuration.

In the configuration, the following keys are available in the :gog scope:

Keygen

To upload to a Keygen instance, you'll need to generate an oAuth application on your instance and also authorise a token using the standard oAuth flow. If you use pass, you should create a pass entry with your tokens and secrets in it. On the Keygen side, create a project and a file under the project for each of the bundles you want to upload. On the release side you'll of course need the corresponding bundles to upload.

In the configuration, the following keys are available in the :keygen scope:

HTTP

This will perform a simple HTTP request to upload bundle payloads.

In the configuration, the following keys are available in the :http scope:

Rsync

This will use the rsync tool to send the file to a remote server. rsync must be in the PATH and available on the remote server as well.

In the configuration, the following keys are available in the :rsync scope:

SSH

This will use an SSH connection to send the file to a remote server.

In the configuration, the following keys are available in the :ssh scope:

FTP

This will use an FTP connection to send the file to a remote server.

In the configuration, the following keys are available in the :ftp scope: