@bscotch/runway

Runway: Opinionated game versioning and deployment tools

Bscotch has multiple game projects, all developed in Gamemaker Studio 2 and intended to be kept up-to-date with the latest dependency updates as well as with changes to production and deployment practices.

Gamemaker as a tool is only focused on the actual code and game assets themselves, providing minimal tooling for production around game development.

Runway provides a unified collection of commandline tools to assist Bscotch game developers in automating, simplifying, and standardizing management of game projects themselves (basically everything that is not code and assets manageable within GMS2 itself).

Background

Versioning

We use a limited subset of semver ("semantic versioning") for managing deployment versions. The terms related to this are hard to keep track of and sometimes not officially defined, so for clarity we provide the terms we use here:

For sample version "1.2.3-rc.5":

• The "major" version is "1"
• The "minor" version is "2"
• The "patch" version is "3"
• The "version" or "main version" is "1.2.3" and includes all of its release candidates
• The generic word for "major", "minor", or "patch" is "subversion"
• A "release" is the specific rc.X of a given version, also synonymous with the entire version string

Requirements

• Node.js v16+
• A Rumpus account with admin permissions

Installation

This can be installed via NPM either locally on a per-game-project basis via npm install @bscotch/gamedev-toolkit. Running the resulting CLI commands in this case requires prefixing all of them with npx .

Because all games should be using the most up-to-date version of this toolkit, it is also fine to install Runway globally instead of per-project, via npm install -g @bscotch/gamedev-toolkit. This allows running the CLI commands directly without the npx prefix.

Usage

Configuration

Each of the CLI commands can make use of configuration settings in your root package.json file. They must be in a very specific format, which you can see in the relevant source file.

You'll need to log into both the dev and beta servers in order for all CLI commands to succeed.

Do this by installing the Rumpus node SDK via npm install @bscotch/gamedev-toolkit, either locally or globally, and then running:

• (local) npx rumpus login --beta
• (local) npx rumpus login --dev -b SERVERUSER:SERVERPASS

or

• (global) rumpus login --beta
• (global) rumpus login --dev -b SERVERUSER:SERVERPASS

Where SERVERUSER:SERVERPASS credentials come from the "app configuration" section of dev.bscotch.net.

Hooks

Any given project may require some custom tooling on top of the generic functionality provided by Runway. Instead of centralizing non-general tooling here, Runway allows for custom "hooks" triggered at defined moments (whether using the CLI or directly using the functions).

After running any CLI command you'll end up with a directory .runway/hooks in your project root, which will be populated with a sample executable script per hook. To get a hook working, drop the .sample part of the extension and populate it however you want! Hooks are expected to be in Node.js, but you can call other programs with your script if required.

You can also add these files yourself if there are no samples in your project yet.

Available hooks:

• before-version-increment: Runs when the version-incrementer method/CLI commands are called. It runs after the new versions are successfully identified but before any file changes occur. There could still be downstream errors after this hook is run.
• after-version-increment: Runs after the version-incrementer has updated all local files with the new versions but before the new git commit is made or git tags added.
• after-version-increment-push: Runs after all version-incrementing-related tasks are complete, including creation of the new version commit and tags and the push to the remote.
• before-deploy: Runs when the deployment method/command is called, prior to the build order being created.
• after-deploy: Runs after a build order is created.

Version Management

For the Bscotch versioning workflow, increments to semver versions indicate a desire to collapse all changes since the last version change into a deployable build of the game. Versioning a game via the Runway CLI will cause all other triggered behavior to also occur (creation of build orders, updating of the patchnotes, and sending of alerts).

Major, minor, and patch numbers are only incremented on the develop branch. Every change to the version must also include the -rc.0 "preversion" postfix. This is what identifies that version as being a new "release candidate".

When a particular rc.0 version is considered a true candidate for release to the public, it starts going through the candidate workflow on a release/VERSION branch, where only the rc.X preversion can be incremented (following the BscotchFlow approach).

• runway major: If on develop, increment the major version and add -rc.0.
• runway minor: If on develop, increment the minor version and add -rc.0.
• runway patch: If on develop, increment the patch version and add -rc.0.
• runway rc: If on a release/VERSION branch, increment the -rc.X suffix.
• runway release: If on develop and on a rc.0 version, then create a new branch called release/VERSION and check it out (this does not trigger any version-increment hooks).

In all cases, a secondary "Build Version" is also globally incremented (independent of branch). The "Build Version" is used to overwrite the version fields in all Gamemaker 2 "options" files, so that all executables will have this version baked in (this is because most platforms do not support full semver with prerelease versions).

Versioning Lifecycle

1. Versioning command called.
2. Validation of command matching current branch and project state.
3. Compute new versions based on Git history (main version) and Git tags (build version).
4. Run before-version-increment hook (if defined).
5. Update all local project files with the new version.
6. Run after-version-increment hook (if defined).
7. Commit all changes as a "version commit" (where the message is the semver string).
8. Add tags for version (v0.0.0) and build-version (build-0.0.0).
9. Push the commit and tags to the remote.
10. Run after-version-increment-push hook (if defined).
11. Changelogs are created and uploaded (unless skipped), triggering releated hooks.
12. Deployment (unless skipped), triggering related hooks.
13. Alerts are sent, if defined in the config file.

New Release Lifecycle

1. runway release command called.
2. Validation that the project is in a state that allows creation of a release branch.
3. Run before-release hook (if defined).
4. Create new branch named release/VERSION, check it out, and push.
5. Run after-release hook (if defined).

Creating Build Orders

Upon changing the version number, or triggered independently, the Runway allows creation of GamePipe build orders. The game project's package.json file must have all the appropriate "GamePipe" field content for builds to work.

• runway deploy: Create a build order if on a branch-appropiate version commit.

Deployment Lifecycle

1. Deployment CLI command called
2. Validation that project is in a deployable state.
3. Run before-deploy hook (if defined).
4. Find or create a GamePipe project in Rumpus for this repo.
5. Create a build order and submit it to Rumpus.
6. Run after-deploy hook (if defined).

Changelogs

Game project changelogs are automatically created using the git logs of the project. They are created using the Bscotch Changelogs module, following its requirements. Changelogs are created on a per-branch basis.

• runway changelog: (Aliased to changelogs, patchnotes.) Create and upload changelogs based on the current branch.

Changelog Lifecycle

1. Changelog CLI command called.
2. Validation that projects is in a state where a changelog would make sense.
3. Compute the changelog based on the Git history.
4. Run after-changelog-create hook (if defined).
5. Upload the changelog to Rumpus.
6. Run after-changelog-upload hook (if defined).

Modules

Gamemaker Studio does not have a practical, native solution for creating portable modules for use by multiple projects. We've implemented our own, where a "module" is defined as a subset of GMS2 project resources whose path includes a specific name.

For example, the "BscotchPack" module would include any sprites in the asset folder Sprites/BscotchPack, and sounds in Sounds/extraFolder/BscotchPack, etc.

Specify which modules your project depends on in the config file (see reference).

Call CLI commands to manually import modules whenever you please. The CLI uses your config by default, but also lets you specify other modules by repository or local directory (use the CLI help for more details).

• runway module import