持续集成

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

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

此外，本页面还介绍如何设置自动化上传构建到：

Gitlab CI / Gitlab Pages

在 Gitlab 上使用任何 docker runner（例如 gitlab.com 的共享 runners）。

配置

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

 1stages:
 2  - build
 3  - deploy
 4
 5package:
 6  image: wonderlandengine/editor:latest
 7  stage: build
 8  script:
 9    # 为 WonderlandEditor 设置 WLE_CREDENTIALS 变量以登录
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    # 仅在 main/master 分支上部署到 pages
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 是包含访问令牌的变量。我们将在下一步配置它。

变量

在 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）应如下所示：

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

$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）应如下所示：

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

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

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

部署到 Netlify

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

配置

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

将 deploy 添加到阶段：

1stages:
2  - build
3  - deploy

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

1netlify:
2  image: node:15
3  stage: deploy
4  script:
5    - npm install -g netlify-cli
6    - 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，您需要将令牌添加到环境中：

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

推送构建

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

1  - npm i -g heyvr-cli
2  - 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 密钥：

1butler login

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

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

安装 Butler

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

1    image: dosowisko/butler

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

推送构建

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

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

参见 Itch.io 文档页面。

显式版本

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