持续集成

Wonderland Editor Docker Image 允许设置高效的持续集成和交付 Wonderland Engine 项目。

本页面描述如何使用最流行的 CI 服务进行高效的自动化构建和部署：

此外，本页面还介绍如何设置上传构建到以下平台的自动化过程：

Gitlab CI / Gitlab Pages 

在 Gitlab 上使用任何 Docker Runner（例如 gitlab.com 的共享 Runners）。

配置 

您的 .gitlab-ci.yml 应如下所示：

stages:
  - build
  - deploy

package:
  image: wonderlandengine/editor:latest
  stage: build
  script:
    # 为 WonderlandEditor 设置 WLE_CREDENTIALS 变量以登录
    - 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:
    # 仅在 main/master 分支上部署到 pages
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
  before_script:
    - apk add gzip
  script:
    - gzip -k deploy/*.*
    - mv deploy public
  artifacts:
    paths:
      - public

$WLE_CREDENTIALS 是一个包含访问令牌的变量。我们将在下一步中配置它。

变量 

在 Gitlab Web 界面中找到 Gitlab CI 的变量：设置 > CI/CD > 变量。

点击“添加变量”并命名为 WLE_CREDENTIALS。其值应为 API-Token，可以在 账户页面 的“API-Token”下检索。填写名称和过期日期，然后点击“创建新 API-Token”。可以从列表顶部的新创建条目中复制令牌。

对于公共项目，请确保启用“保护变量”，以防止未合并的合并请求能够访问 CI 变量。

缓存 

编辑器中最耗时的任务是压缩纹理。如果结果被缓存（在 cache/ 目录中），这将快得多。因此建议为 CI 缓存指定此文件夹，或将文件检入源代码控制中。

GitHub Workflows / GitHub Pages 

在 GitHub 上使用任何启用 Docker 的 Runner（例如 GitHub 提供的 Runners）。

配置 

您的工作流文件（例如 .github/workflows/github-pages.yml）应如下所示：

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 是您的项目文件。

$WLE_CREDENTIALS 是一个包含 email:password 的密钥。我们将在下一步中配置它。

deploy-pages 作业将仅在您的仓库的默认分支上运行（通常为 main）。

密钥 

在 GitHub Web 界面中找到 GitHub Workflows 的密钥： 设置 > 密钥 > 动作。

点击右上角的“新建仓库密钥”并命名为 WLE_CREDENTIALS。 其值应为 API-Token，可以在 账户页面 的“API-Token”下检索。填写名称和过期日期，然后点击“创建新 API-Token”。可以从列表顶部的新创建条目中复制令牌。

密钥不会传递给来自分叉的拉取请求，这意味着您的工作流可能不会为外部协作者的拉取请求运行。

Bitbucket CI 

在 GitHub 上使用任何启用 Docker 的 Runner（例如 GitHub 提供的 Runners）。

配置 

您的流水线文件（例如 bitbucket-pipelines.yml）应如下所示：

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 是您的项目文件。

$WLE_CREDENTIALS 是一个包含 email:password 的密钥。我们将在下一步中配置它。

请注意，Bitbucket 当前不提供类似于 Gitlab Pages 或 GitHub Pages 的静态页面托管服务。 相反，您可以将此与 deploy to netlify 结合使用。

部署到 Netlify 

在这里我们使用 Netlify CLI 进行“持续部署”。

配置 

按照 Gitlab CI 中的说明配置 .gitlab-ci.yml。

将 deploy 添加到阶段：

stages:
  - build
  - deploy

然后将以下 deploy 作业附加到文件末尾：

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

变量 

在 Gitlab Web 界面中找到 Gitlab CI 的变量：设置 > CI/CD > 变量。

添加一个密钥为 NETLIFY_AUTH_TOKEN 的变量，并将其值设置为 Netlify 访问令牌。您可以在 此处 创建它。

同样，添加另一个密钥为 NETLIFY_SITE_ID 的变量。将其值设置为您要部署的站点的“站点 ID”。可以在 站点设置 > 常规 > 站点详细信息 > 站点信息 中找到。（如果您还没有创建站点，请按照 此处 的指南）。

发布到 HeyVR 

要从 CI 发布到 HeyVR，您可以使用非官方的 “heyvr-cli” 包在 npm 上。

最终的发布步骤需要在 HeyVR 开发者门户中完成。

认证 

在 HeyVR 账户设置 中的“开发者访问令牌”下检索 API 密钥。

添加一个名为 HEYVR_ACCESS_TOKEN 的 CI 变量或密钥，其值为该令牌。

对于 GitHub Workflows，您需要将令牌添加到环境中：

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

推送构建 

从 CI 推送构建时，请确保项目被打包到 deploy/ 文件夹中，并将以下命令添加到您的 CI 脚本中：

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

“heyvr-game-id” 是您在 heyvr 上创建的游戏的 slug。

对于 GitHub Actions，将 $CI_COMMIT_TAG 替换为 ${{ github.ref_name }}。

发布到 Itch.io 

Itch.io 提供了一个名为 “butler” 的 CLI 工具，用于将构建上传到您的游戏页面。

认证 

要为 Gitlab CI 或 GitHub Workflows 自动化发布，您需要通过运行以下命令检索 API 密钥：

butler login

该命令将打印写入 API 密钥的文件的路径。复制内容并添加一个名为 BUTLER_API_KEY 的 CI 变量或密钥。

有关更多信息，请参见 Itch.io 文档页面。

安装 Butler 

要在您的 CI 作业中使 butler 命令可用，您可以使用一个预装了 butler 的 Docker 镜像：

    image: dosowisko/butler

在这里我们使用 dosowisko/butler，但还有许多替代方案。

推送构建 

从 CI 推送构建时，请确保项目被打包到 deploy/ 文件夹中，并将以下命令添加到您的 CI 脚本中：

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

参见 Itch.io 文档页面。

显式版本 

您还可以在从标签部署时附加显式版本号。 对于 Gitlab CI，使用 --userversion $CI_COMMIT_TAG，对于 GitHub Actions 使用 --userversion ${{ github.ref_name }}。

Source Control