Continuous Integration

The Wonderland Editor Docker Image allows setting up efficient continuous integration and delivery of Wonderland Engine projects.

This page describes how to set up efficient automated builds and deployment with the most popular CI services:

Additionally, this page describes how to set up automation for uploading builds to:

Gitlab CI / Gitlab Pages

Using any docker runner (e.g. the gitlab.com shared runners) on Gitlab.

Configuration

Your .gitlab-ci.yml should look like follows:

 1stages:
 2  - build
 3  - deploy
 4
 5package:
 6  image: wonderlandengine/editor:latest
 7  stage: build
 8  script:
 9    # Set up the WLE_CREDENTIALS variable for WonderlandEditor to log in
10    - WonderlandEditor --windowless --package --project Project.wlp
11  cache:
12    key: ${CI_COMMIT_REF_SLUG}
13    paths:
14      - cache/
15  artifacts:
16    paths:
17      - deploy
18
19pages:
20  image: alpine:3.14
21  stage: deploy
22  rules:
23    # Only deploy to pages on main/master branch
24    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
25  before_script:
26    - apk add gzip
27  script:
28    - gzip -k deploy/*.*
29    - mv deploy public
30  artifacts:
31    paths:
32      - public

$WLE_CREDENTIALS is a variable containing an access token. We will configure it in the next step.

Variables

Find variables for Gitlab CI in the Gitlab web interface: Settings > CI/CD > Variables.

Click “Add Variable” and name it WLE_CREDENTIALS. Its value should be an API-Token, which you can retrieve in the account page, under “API-Token”. Fill in the name and expiration date, then click “Create New API-Token”. The token can be copied from the newly created entry at the top of the list.

For public projects make sure to enable “Protect variable” to prevent unmerged merge requests from being able to access the CI variable.

Cache

The most time-consuming task in the editor is compressing textures. This is significantly faster, if the results are cached (in the cache/ directory). It is therefore useful to either specify this folder for the CI cache, or check in the files into source control.

GitHub Workflows / GitHub Pages

Using any docker-enabled runner (e.g. the GitHub hosted runners) on GitHub.

Configuration

Your workflow file (e.g. .github/workflows/github-pages.yml) should look like follows:

 1on: [push]
 2
 3permissions:
 4  contents: read
 5  pages: write
 6  id-token: write
 7
 8jobs:
 9  package:
10    runs-on: ubuntu-latest
11    container:
12      image: wonderlandengine/editor:latest
13    steps:
14    - name: Install Git
15      run: apt-get update && apt-get install -y git git-lfs
16    - uses: actions/checkout@v4
17      with:
18        lfs: true
19    - name: Package
20      run: /usr/local/bin/entrypoint.sh WonderlandEditor --windowless --package --project Project.wlp --output ./public/
21      env:
22          WLE_CREDENTIALS: ${{ secrets.WLE_CREDENTIALS }}
23    - name: Gzip
24      run: find ./public/ -type f ! -name '*.gz' -exec gzip -k "{}" \;
25    - name: Upload artifact
26        uses: actions/upload-pages-artifact@v3
27        with:
28          path: ./public
29
30  deploy-pages:
31    needs: package
32    runs-on: ubuntu-latest
33    if: ${{ format('refs/heads/{0}', github.event.repository.default_branch) == github.ref }}
34    steps:
35      - name: Deploy to GitHub Pages
36        uses: actions/deploy-pages@v4

Project.wlp is your project file.

$WLE_CREDENTIALS is a secret containing email:password. We will configure it in the next step.

The deploy-pages job will only run on the default branch of your repository (usually main).

Secrets

Find secrets for GitHub Workflows in the GitHub web interface: Settings > Secrets > Actions.

Click “New repository secret” on the top right and name it WLE_CREDENTIALS. Its value should be an API-Token, which you can retrieve in the account page, under “API-Token”. Fill in the name and expiration date, then click “Create New API-Token”. The token can be copied from the newly created entry at the top of the list.

Secrets are not passed to pullrequests from forks, which means your workflow may not run for pullrequests from outside collaborators.

Bitbucket CI

Using any docker-enabled runner (e.g. the GitHub hosted runners) on GitHub.

Configuration

Your pipelines file (e.g. bitbucket-pipelines.yml) should look like follows:

 1image: wonderlandengine/editor:latest
 2
 3pipelines:
 4  default:
 5    - step:
 6        name: 'Build'
 7        script:
 8          - /usr/local/bin/entrypoint.sh WonderlandEditor --windowless --package --project Project.wlp
 9        artifacts:
10          - deploy/**

Project.wlp is your project file.

$WLE_CREDENTIALS is a secret containing email:password. We will configure it in the next step.

Note that Bitbucket currently does not offer a service for static page hosting like Gitlab Pages or GitHub Pages. Instead, you can combine this with deploy to netlify.

Deploy to Netlify

Here we are using Netlify CLI for the “continuous deployment”.

Configuration

Configure .gitlab-ci.yml as described in Gitlab CI.

Add deploy to the stages:

1stages:
2  - build
3  - deploy

Then append the following deploy job to the end of the file:

1netlify:
2  image: node:15
3  stage: deploy
4  script:
5    - npm install -g netlify-cli
6    - netlify deploy --dir=public --prod

Variables

Find variables for Gitlab CI in the Gitlab web interface: Settings > CI/CD > Variables.

Add a variable with a key as NETLIFY_AUTH_TOKEN and set its value to the netlify access token. You can create it here.

Similarly, add another variable with a key as NETLIFY_SITE_ID. Set its value to the “Site ID” of the site that you want to deploy. This will be found on site settings > General > Site details > Site information. (In case you haven’t created a site, follow the guide here).

Publish to HeyVR

To publish from CI to HeyVR you can use the inofficial “heyvr-cli” package on npm.

The final publishing step needs to be done in the HeyVR developer portal.

Authentication

Retrieve an API key in your HeyVR Account Settings under “Developer Access Token”.

Add a CI variable or secret HEYVR_ACCESS_TOKEN with the token as a value.

For GitHub Workflows you need to add the token to the environment:

1  env:
2    HEYVR_ACCESS_TOKEN: ${{ secrets.HEYVR_ACCESS_TOKEN }}

Pushing Builds

When pushing builds from CI, make sure the project is packaged into the deploy/ folder and add the following command to your CI script:

1  - npm i -g heyvr-cli
2  - heyvr --version $CI_COMMIT_TAG --gameId "heyvr-game-id"

The “heyvr-game-id” is the slug of the game you created on heyvr.

For GitHub Actions, replace $CI_COMMIT_TAG with ${{ github.ref_name }}.

Publish to Itch.io

Itch.io provides a CLI tool called “butler” for uploading builds to your game pages.

Authentication

To automate publishing for Gitlab CI or GitHub Workflows, you will need to retrieve an API key by running:

1butler login

The command will print the path to the file it wrote API key to. Copy the contents and add a CI variable or secret called BUTLER_API_KEY.

See the Itch.io documentation page for more information.

Installing Butler

To have the butler command available on your CI job, you can use a docker image that comes with butler pre-installed:

1    image: dosowisko/butler

Here we use dosowisko/butler, but there are many alternatives.

Pushing Builds

When pushing builds from CI, make sure the project is packaged into the deploy/ folder and add the following command to your CI script:

1  - butler push ./deploy user/game:channel-name

See the Itch.io documentation page.

Explicit Version

You may also append an explicit version number when deploying from tags. For Gitlab CI, use --userversion $CI_COMMIT_TAG and for GitHub Actions use --userversion ${{ github.ref_name }}.