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:

stages:
  - build
  - deploy

package:
  image: wonderlandengine/editor:latest
  stage: build
  script:
    # Set up the WLE_CREDENTIALS variable for WonderlandEditor to log in
    - WonderlandEditor --windowless --package --project Project.wlp
  cache:
    key: ${CI_COMMIT_REF_SLUG}
    paths:
      - cache/
  artifacts:
    paths:
      - deploy

pages:
  image: alpine:3.14
  stage: deploy
  rules:
    # Only deploy to pages on main/master branch
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
  before_script:
    - apk add gzip
  script:
    - gzip -k deploy/*.*
    - mv deploy public
  artifacts:
    paths:
      - 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:

on: [push]

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  package:
    runs-on: ubuntu-latest
    container:
      image: wonderlandengine/editor:latest
    steps:
    - name: Install Git
      run: apt-get update && apt-get install -y git git-lfs
    - uses: actions/checkout@v4
      with:
        lfs: true
    - name: Package
      run: /usr/local/bin/entrypoint.sh WonderlandEditor --windowless --package --project Project.wlp --output ./public/
      env:
          WLE_CREDENTIALS: ${{ secrets.WLE_CREDENTIALS }}
    - name: Gzip
      run: find ./public/ -type f ! -name '*.gz' -exec gzip -k "{}" \;
    - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./public

  deploy-pages:
    needs: package
    runs-on: ubuntu-latest
    if: ${{ format('refs/heads/{0}', github.event.repository.default_branch) == github.ref }}
    steps:
      - name: Deploy to GitHub Pages
        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:

image: wonderlandengine/editor:latest

pipelines:
  default:
    - step:
        name: 'Build'
        script:
          - /usr/local/bin/entrypoint.sh WonderlandEditor --windowless --package --project Project.wlp
        artifacts:
          - 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:

stages:
  - build
  - deploy

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

netlify:
  image: node:15
  stage: deploy
  script:
    - npm install -g netlify-cli
    - 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:

  env:
    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:

  - npm i -g heyvr-cli
  - 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:

butler 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:

    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:

  - 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 }}.

Source Control