Continuous Integration

Das Wonderland Editor Docker Image ermöglicht es dir, eine effiziente kontinuierliche Integration und Bereitstellung von Wonderland Engine-Projekten einzurichten.

Diese Seite beschreibt, wie man effiziente automatisierte Builds und Bereitstellungen mit den beliebtesten CI-Diensten einrichtet:

• Gitlab CI
• GitHub Workflows

Zusätzlich wird beschrieben, wie man die Automatisierung für das Hochladen von Builds einrichtet:

• HeyVR
• itch.io

Gitlab CI / Gitlab Pages 

Verwende einen beliebigen Docker-Runner (z.B. die geteilten Runner von gitlab.com) auf Gitlab.

Konfiguration 

Deine .gitlab-ci.yml sollte wie folgt aussehen:

stages:
  - build
  - deploy

package:
  image: wonderlandengine/editor:latest
  stage: build
  script:
    # Setze die WLE_CREDENTIALS-Variable, damit sich WonderlandEditor einloggen kann
    - 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:
    # Nur auf der Haupt-/Master-Branch auf Pages bereitstellen
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
  before_script:
    - apk add gzip
  script:
    - gzip -k deploy/*.*
    - mv deploy public
  artifacts:
    paths:
      - public

$WLE_CREDENTIALS ist eine Variable, die ein Zugangstoken enthält. Wir werden es im nächsten Schritt konfigurieren.

Variablen 

Finde Variablen für Gitlab CI in der Gitlab-Weboberfläche: Einstellungen > CI/CD > Variablen.

Klicke auf “Variable hinzufügen” und nenne sie WLE_CREDENTIALS. Der Wert sollte ein API-Token sein, das du auf der Kontoseite unter “API-Token” abrufen kannst. Fülle den Namen und das Ablaufdatum aus und klicke auf “Neues API-Token erstellen”. Das Token kann aus dem neu erstellten Eintrag oben in der Liste kopiert werden.

Für öffentliche Projekte stelle sicher, dass du “Variable schützen” aktivierst, um zu verhindern, dass nicht fusionierte Merge Requests auf die CI-Variable zugreifen können.

Cache 

Die zeitaufwändigste Aufgabe im Editor ist das Komprimieren von Texturen. Dies ist erheblich schneller, wenn die Ergebnisse zwischengespeichert werden (im Cache-Verzeichnis). Es ist daher nützlich, dieses Verzeichnis für den CI-Cache anzugeben oder die Dateien in die Quellkontrolle einzuchecken.

GitHub Workflows / GitHub Pages 

Nutze einen beliebigen Docker-fähigen Runner (z.B. die von GitHub gehosteten Runner) auf GitHub.

Konfiguration 

Deine Workflow-Datei (z.B. .github/workflows/github-pages.yml) sollte wie folgt aussehen:

on: [push]

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

jobs:
  package:
    runs-on: ubuntu-latest
    container:
      image: wonderlandengine/editor:latest
    steps:
    - name: Git installieren
      run: apt-get update && apt-get install -y git git-lfs
    - uses: actions/checkout@v4
      with:
        lfs: true
    - name: Packen
      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: Artefakt hochladen
        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: Auf GitHub Pages bereitstellen
        uses: actions/deploy-pages@v4

Project.wlp ist deine Projektdatei.

$WLE_CREDENTIALS ist ein Geheimnis, das email:password enthält. Wir werden es im nächsten Schritt konfigurieren.

Der deploy-pages Job wird nur auf dem Standardzweig deines Repositories ausgeführt (normalerweise main).

Geheimnisse 

Finde Geheimnisse für GitHub Workflows in der GitHub-Weboberfläche: Einstellungen > Geheimnisse > Aktionen.

Klicke oben rechts auf “Neues Repository-Geheimnis” und nenne es WLE_CREDENTIALS. Der Wert sollte ein API-Token sein, das du auf der Kontoseite unter “API-Token” abrufen kannst. Fülle den Namen und das Ablaufdatum aus und klicke auf “Neues API-Token erstellen”. Das Token kann aus dem neu erstellten Eintrag oben in der Liste kopiert werden.

Geheimnisse werden nicht an Pull Requests von Forks weitergegeben, was bedeutet, dass dein Workflow möglicherweise nicht für Pull Requests von externen Mitarbeitern ausgeführt wird.

Bitbucket CI 

Verwende einen beliebigen Docker-fähigen Runner (z.B. die von GitHub gehosteten Runner) auf GitHub.

Konfiguration 

Deine Pipelines-Datei (z.B. bitbucket-pipelines.yml) sollte wie folgt aussehen:

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 ist deine Projektdatei.

$WLE_CREDENTIALS ist ein Geheimnis, das email:password enthält. Wir werden es im nächsten Schritt konfigurieren.

Beachte, dass Bitbucket derzeit keinen Dienst zum Hosting von statischen Seiten wie Gitlab Pages oder GitHub Pages anbietet. Stattdessen kannst du dies mit der Bereitstellung auf Netlify kombinieren.

Deploy to Netlify 

Hier verwenden wir das Netlify CLI, um die “kontinuierliche Bereitstellung” vorzunehmen.

Konfiguration 

Konfiguriere .gitlab-ci.yml wie im Abschnitt Gitlab CI beschrieben.

Füge das Deployment zu den Stufen hinzu:

stages:
  - build
  - deploy

Füge dann den folgenden Deploy-Job am Ende der Datei hinzu:

netlify:
  image: node:15
  stage: deploy
  script:
    - npm install -g netlify-cli
    - netlify deploy --dir=public --prod

Variablen 

Finde Variablen für Gitlab CI in der Gitlab-Weboberfläche: Einstellungen > CI/CD > Variablen.

Füge eine Variable mit dem Schlüssel NETLIFY_AUTH_TOKEN hinzu und setze ihren Wert auf den Netlify-Zugangstoken. Du kannst ihn hier erstellen.

Füge ebenfalls eine weitere Variable mit dem Schlüssel NETLIFY_SITE_ID hinzu. Setze ihren Wert auf die “Site ID” der Seite, die du bereitstellen möchtest. Dies findest du unter Site-Einstellungen > Allgemein > Site-Details > Site-Informationen. (Falls du noch keine Seite erstellt hast, folge der Anleitung hier).

Publish to HeyVR 

Um von CI aus auf HeyVR zu veröffentlichen, kannst du das inoffizielle “heyvr-cli”-Paket auf npm verwenden.

Der finale Veröffentlichungsschritt muss im HeyVR-Entwicklerportal erfolgen.

Authentifizierung 

Rufe einen API-Schlüssel in deinen HeyVR-Kontoeinstellungen unter “Developer Access Token” ab.

Füge eine CI-Variable oder ein Geheimnis HEYVR_ACCESS_TOKEN mit dem Token als Wert hinzu.

Für GitHub Workflows musst du das Token zur Umgebung hinzufügen:

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

Builds hochladen 

Wenn du Builds von CI aus hochlädst, stelle sicher, dass das Projekt ins deploy/ Verzeichnis gepackt ist und füge den folgenden Befehl zu deinem CI-Skript hinzu:

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

Die “heyvr-game-id” ist der Slug von dem Spiel, das du auf HeyVR erstellt hast.

Für GitHub Actions ersetze $CI_COMMIT_TAG mit ${{ github.ref_name }}.

Publish to Itch.io 

Itch.io bietet ein CLI-Tool namens “butler” zum Hochladen von Builds auf deine Spielseiten.

Authentifizierung 

Um die Veröffentlichung für Gitlab CI oder GitHub Workflows zu automatisieren, musst du einen API-Schlüssel abrufen, indem du folgenden Befehl ausführst:

butler login

Der Befehl gibt den Pfad zur Datei aus, in die er den API-Schlüssel geschrieben hat. Kopiere die Inhalte und füge eine CI-Variable oder ein Geheimnis namens BUTLER_API_KEY hinzu.

Siehe die Itch.io-Dokumentationsseite für weitere Informationen.

Butler installieren 

Um den butler Befehl in deinem CI-Job verfügbar zu haben, kannst du ein Docker-Image verwenden, das Butler vorinstalliert hat:

    image: dosowisko/butler

Hier verwenden wir dosowisko/butler, aber es gibt viele Alternativen.

Builds hochladen 

Wenn du Builds von CI aus hochlädst, stelle sicher, dass das Projekt ins deploy/ Verzeichnis gepackt ist und füge den folgenden Befehl zu deinem CI-Skript hinzu:

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

Siehe die Itch.io-Dokumentationsseite für weitere Informationen.

Explizite Version 

Du kannst auch eine explizite Versionsnummer beim Bereitstellen von Tags anhängen. Für Gitlab CI verwende --userversion $CI_COMMIT_TAG und für GitHub Actions verwende --userversion ${{ github.ref_name }}.