Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

ci: modernize workflows — shared setup action, retries, current action majors

yhh0254165bf5ba
diff --git a/.github/actions/setup/action.yml b/.github/actions/setup/action.yml
new file mode 100644
index 000000000..4b9797a00
--- /dev/null
+++ b/.github/actions/setup/action.yml
@@ -0,0 +1,28 @@
+name: Setup toolchain
+description: pnpm + Node (with pnpm cache) and a frozen install — the one place the toolchain versions live.
+
+inputs:
+ node-version:
+ description: Node.js major version.
+ default: '24'
+ install:
+ description: Run `pnpm install --frozen-lockfile` after the toolchain is set up.
+ default: 'true'
+
+runs:
+ using: composite
+ steps:
+ - uses: pnpm/action-setup@v6
+ with:
+ version: 10
+
+ - uses: actions/setup-node@v7
+ with:
+ node-version: ${{ inputs.node-version }}
+ cache: pnpm
+
+ # Frozen so a stale lockfile fails the run instead of being silently
+ # rewritten — reproducible installs across every job.
+ - if: inputs.install == 'true'
+ shell: bash
+ run: pnpm install --frozen-lockfile
diff --git a/.github/workflows/README.md b/.github/workflows/README.md
index 69cf81cd1..49df354fe 100644
--- a/.github/workflows/README.md
+++ b/.github/workflows/README.md
@@ -1,8 +1,13 @@
# CI Workflows
+Shared toolchain setup (pnpm + Node + a frozen install) lives in the
+`./.github/actions/setup` composite action, so pnpm/Node versions are pinned in
+exactly one place; every job just `uses: ./.github/actions/setup` after its
+checkout.
+
## Emscripten Version
-**Current pinned version**: 3.1.51
+**Current pinned version**: 5.0.0
This version is used across all workflows to ensure consistent WASM builds.
@@ -18,11 +23,12 @@ To update to a new version:
node build-tools/cli.js build -t all
```
-2. Update version in the following files:
- - `.github/workflows/build.yml` (line 52)
- - `.github/workflows/release-desktop.yml` (line 49)
- - `CONTRIBUTING.md` (Prerequisites section)
- - `build-tools/utils/emscripten.js` (error message)
+2. Update the `version:` under the **Setup Emscripten** step in:
+ - `.github/workflows/build.yml`
+ - `.github/workflows/release-desktop.yml`
+
+ and the matching references in `CONTRIBUTING.md` (Prerequisites) and
+ `build-tools/utils/emscripten.js` (error message).
3. Run CI build on a test branch to verify
@@ -33,28 +39,20 @@ To update to a new version:
### Version History
+- **5.0.0**: Current pinned version.
- **3.1.51** (2026-02-15): Initial pinned version, stable for WebGL2 + dynamic linking
## Compiler Cache (ccache)
-All CI workflows use [ccache](https://ccache.dev/) to speed up C++ compilation.
+The Emscripten jobs use [ccache](https://ccache.dev/) to speed up C++ compilation.
### Configuration
-- **Action**: `hendrikmuhs/[email protected]`
-- **Cache keys**:
- - Linux build: `${{ runner.os }}-build-linux`
- - Emscripten build: `${{ runner.os }}-emscripten`
- - Release builds: `${{ matrix.platform }}-release`
-- **Max cache size**:
- - CI builds: 500MB
- - Release builds: 1GB
-
-### Performance Impact
-
-- **First build** (cold cache): No change
-- **Incremental builds** (warm cache): 5-10x faster
-- **Full rebuild** (no code changes): ~90% time saved
+- **Action**: `hendrikmuhs/[email protected]`
+- **Cache key**: `${{ runner.os }}-emscripten` — shared by `build.yml`'s
+ `build-emscripten` job and `release-desktop.yml`'s `engine` job, so every
+ master push keeps the release engine build's cache warm.
+- **Max cache size**: 500MB
### Emscripten-specific Settings
@@ -68,64 +66,3 @@ For Emscripten builds, ccache uses special configuration (set in `cmake/Compiler
If cache becomes corrupted or stale:
1. Bump the cache key version in workflow files
2. Or manually clear via GitHub Actions UI: Settings → Actions → Caches
-
-## Bundle Size Tracking
-
-CI automatically tracks WASM and SDK bundle sizes on every build.
-
-### Current Baselines
-
-Baseline sizes are stored in `.github/bundle-size-baselines.json`:
-
-| File | Size | Threshold |
-|------|------|-----------|
-| wasm/web/esengine.wasm | 658KB | 800KB |
-| wasm/web/physics.wasm | 159KB | 200KB |
-| wasm/web/spine42.wasm | - | 300KB |
-| wasm/web/spine38.wasm | - | 300KB |
-| wasm/web/spine41.wasm | - | 300KB |
-| sdk/esm/esengine.js | 105KB | 150KB |
-
-### How It Works
-
-1. **Build with manifest**: `node build-tools/cli.js build -t all --manifest`
-2. **Track sizes**: `node build-tools/track-bundle-size.js check`
-3. **On PR**: Posts a comment with size changes
-4. **On threshold exceeded**: CI fails with error
-
-### Updating Baselines
-
-After intentional size changes (new features, optimizations):
-
-```bash
-node build-tools/cli.js build -t all --manifest
-node build-tools/track-bundle-size.js update
-git add .github/bundle-size-baselines.json
-git commit -m "chore: update bundle size baselines"
-```
-
-### PR Comment Format
-
-On pull requests, CI posts a comment showing size changes:
-
-```
-## 📦 Bundle Size Report
-
-| File | Size | Baseline | Change | Threshold | Status |
-|------|------|----------|--------|-----------|--------|
-| wasm/web/esengine.wasm | 658KB | 658KB | - | 800KB | ✓ OK |
-| wasm/web/physics.wasm | 162KB | 159KB | +3KB (+1.89%) | 200KB | ✓ OK |
-| sdk/esm/esengine.js | 105KB | 105KB | - | 150KB | ✓ OK |
-```
-
-### Adjusting Thresholds
-
-Edit thresholds in `build-tools/track-bundle-size.js`:
-
-```javascript
-const THRESHOLDS = {
- 'wasm/web/esengine.wasm': 800 * 1024, // 800KB
- 'wasm/web/physics.wasm': 200 * 1024, // 200KB
- // ...
-};
-```
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index bc8ccd623..3e660c3e0 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -13,40 +13,46 @@ concurrency:
group: build-${{ github.ref }}
cancel-in-progress: true
+# Least privilege: this workflow only reads the repo and moves artifacts (the
+# artifact API runs on its own runtime token, not contents). Nothing here writes
+# to the repo, so the default read-all token is narrowed to contents:read.
+permissions:
+ contents: read
+
jobs:
build-emscripten:
name: Web (Emscripten) + C++ tests
runs-on: ubuntu-latest
+ timeout-minutes: 40
+
+ # Single source of truth for the C++ doctest harnesses: the build-target
+ # list and the run loop both derive from CPP_TESTS, so a new harness can no
+ # longer be compiled-but-never-run (the two hand-kept lists had drifted).
+ env:
+ CPP_TESTS: >-
+ test_ecs test_events test_particle test_tilemap test_sparse_set
+ test_resource_pool test_shader_variant test_log_format test_registry_safety
+ test_shader_device test_draw_params test_texture_fb test_buffer_device
+ test_compressed_format test_batch_builder test_boundary_span test_webgpu_device
steps:
- - uses: actions/checkout@v4
+ - uses: actions/checkout@v7
with:
submodules: recursive
- - uses: pnpm/action-setup@v4
- with:
- version: 10
-
- - name: Setup Node.js
- uses: actions/setup-node@v4
- with:
- node-version: '24'
- cache: 'pnpm'
+ - uses: ./.github/actions/setup
- name: Setup Emscripten
- uses: mymindstorm/setup-emsdk@v14
+ uses: mymindstorm/setup-emsdk@v16
with:
version: 5.0.0
- name: Setup ccache
- uses: hendrikmuhs/[email protected]
+ uses: hendrikmuhs/[email protected]
with:
key: ${{ runner.os }}-emscripten
max-size: 500M
- - name: Install dependencies
- run: pnpm install
-
- name: Build Web target
run: node build-tools/cli.js build -t web --no-sync
@@ -67,20 +73,13 @@ jobs:
- name: Build C++ test harnesses
run: |
emcmake cmake -S . -B build/wasm/web-tests -DCMAKE_BUILD_TYPE=Release -DES_BUILD_WEB=ON -DES_BUILD_TESTS=ON
- cmake --build build/wasm/web-tests -j "$(nproc)" --target \
- test_ecs test_events test_particle test_tilemap test_sparse_set \
- test_resource_pool test_shader_variant test_log_format test_registry_safety \
- test_shader_device test_draw_params test_texture_fb test_buffer_device \
- test_compressed_format test_batch_builder test_boundary_span test_webgpu_device \
- webgpu_engine_bringup
+ # webgpu_engine_bringup is compiled (a link-time smoke) but not run below.
+ cmake --build build/wasm/web-tests -j "$(nproc)" --target $CPP_TESTS webgpu_engine_bringup
# The root package.json is ESM, so the emscripten-emitted .js must run as .cjs.
- name: Run C++ test harnesses
run: |
- for t in test_ecs test_events test_particle test_tilemap test_sparse_set \
- test_resource_pool test_shader_variant test_log_format test_registry_safety \
- test_shader_device test_draw_params test_texture_fb test_buffer_device \
- test_compressed_format test_batch_builder test_boundary_span test_webgpu_device; do
+ for t in $CPP_TESTS; do
cp "build/wasm/web-tests/bin/$t.js" "build/wasm/web-tests/bin/$t.cjs"
echo "=== $t"
node "build/wasm/web-tests/bin/$t.cjs"
@@ -93,7 +92,7 @@ jobs:
run: node build-tools/cli.js build -t all --no-sync
- name: Upload web wasm artifact
- uses: actions/upload-artifact@v4
+ uses: actions/upload-artifact@v7
with:
name: wasm-web
path: build/wasm/web/
@@ -102,19 +101,12 @@ jobs:
test:
name: Tests (SDK + Desktop)
runs-on: ubuntu-latest
+ timeout-minutes: 25
steps:
- - uses: actions/checkout@v4
+ - uses: actions/checkout@v7
- - uses: pnpm/action-setup@v4
- with:
- version: 10
-
- - name: Setup Node.js
- uses: actions/setup-node@v4
- with:
- node-version: '24'
- cache: 'pnpm'
+ - uses: ./.github/actions/setup
- name: Check GL boundary (no gl* outside GLDevice)
run: node tools/check-gl-boundary.mjs
@@ -122,9 +114,6 @@ jobs:
- name: Check render-command boundary (DrawCommands built only by BatchBuilder)
run: node tools/check-draw-command-boundary.mjs
- - name: Install dependencies
- run: pnpm install
-
# Filtered so the SDK is checked by ITS OWN pinned TypeScript (the workspace
# carries two majors — desktop is on 6.x); a bare root `pnpm exec tsc`
# resolves an arbitrary compiler. Mirrors the repo's `verify` gate exactly.
@@ -155,29 +144,19 @@ jobs:
name: Render verify (headless)
runs-on: ubuntu-latest
needs: build-emscripten
+ timeout-minutes: 40
steps:
- - uses: actions/checkout@v4
-
- - uses: pnpm/action-setup@v4
- with:
- version: 10
+ - uses: actions/checkout@v7
- - name: Setup Node.js
- uses: actions/setup-node@v4
- with:
- node-version: '24'
- cache: 'pnpm'
+ - uses: ./.github/actions/setup
- name: Download web wasm artifact
- uses: actions/download-artifact@v4
+ uses: actions/download-artifact@v8
with:
name: wasm-web
path: build/wasm/web/
- - name: Install dependencies
- run: pnpm install
-
- name: Build SDK
run: pnpm --filter ./sdk build
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index 574775e20..4bf5b49b6 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -18,25 +18,16 @@ concurrency:
jobs:
build:
runs-on: ubuntu-latest
+ timeout-minutes: 30
steps:
- name: Checkout
- uses: actions/checkout@v4
-
- - uses: pnpm/action-setup@v4
- with:
- version: 10
-
- - name: Setup Node.js
- uses: actions/setup-node@v4
- with:
- node-version: '22'
- cache: 'pnpm'
+ uses: actions/checkout@v7
# TypeDoc (starlight-typedoc) compiles sdk/src against sdk/tsconfig.json,
# which resolves ambient types (@types/node, minigame-api-typings) from
- # the sdk workspace's node_modules — install the workspace first.
- - name: Install workspace dependencies
- run: pnpm install --frozen-lockfile
+ # the sdk workspace's node_modules — the composite's frozen install stages
+ # the workspace first.
+ - uses: ./.github/actions/setup
- name: Install Doxygen
run: sudo apt-get update && sudo apt-get install -y doxygen graphviz
@@ -72,7 +63,7 @@ jobs:
touch docs/dist/.nojekyll
- name: Upload artifact
- uses: actions/upload-pages-artifact@v3
+ uses: actions/upload-pages-artifact@v5
with:
path: docs/dist
@@ -82,7 +73,8 @@ jobs:
url: ${{ steps.deployment.outputs.page_url }}
runs-on: ubuntu-latest
needs: build
+ timeout-minutes: 15
steps:
- name: Deploy to GitHub Pages
id: deployment
- uses: actions/deploy-pages@v4
+ uses: actions/deploy-pages@v5
diff --git a/.github/workflows/release-desktop.yml b/.github/workflows/release-desktop.yml
index 921f47253..274639ef7 100644
--- a/.github/workflows/release-desktop.yml
+++ b/.github/workflows/release-desktop.yml
@@ -10,6 +10,10 @@ on:
# burning a tag.
workflow_dispatch:
+# Read by default; the two jobs that touch the release raise it to contents:write.
+permissions:
+ contents: read
+
jobs:
# The single writer that creates the draft release. electron-builder's GitHub
# publisher creates a draft lazily when none exists, so parallel platform
@@ -20,10 +24,11 @@ jobs:
draft:
if: github.event_name == 'push'
runs-on: ubuntu-latest
+ timeout-minutes: 10
permissions:
contents: write
steps:
- - uses: actions/checkout@v4
+ - uses: actions/checkout@v7
# The release body is the tag's own section of CHANGELOG.md (the release
# commit lands the section before the tag, so it is always present here).
@@ -48,39 +53,30 @@ jobs:
engine:
name: Build engine (wasm)
runs-on: ubuntu-latest
+ timeout-minutes: 30
steps:
- - uses: actions/checkout@v4
+ - uses: actions/checkout@v7
with:
submodules: recursive
- - uses: pnpm/action-setup@v4
- with:
- version: 10
-
- - uses: actions/setup-node@v4
- with:
- node-version: 24
- cache: pnpm
+ - uses: ./.github/actions/setup
- name: Setup Emscripten
- uses: mymindstorm/setup-emsdk@v14
+ uses: mymindstorm/setup-emsdk@v16
with:
version: 5.0.0
- name: Setup ccache
- uses: hendrikmuhs/[email protected]
+ uses: hendrikmuhs/[email protected]
with:
key: ${{ runner.os }}-emscripten
max-size: 500M
- - name: Install dependencies
- run: pnpm install
-
- name: Build engine and sync to desktop
run: node build-tools/cli.js build -t all
- name: Upload engine artifact
- uses: actions/upload-artifact@v4
+ uses: actions/upload-artifact@v7
with:
name: engine-wasm
path: |
@@ -106,25 +102,17 @@ jobs:
- windows-latest
runs-on: ${{ matrix.platform }}
+ timeout-minutes: 40
permissions:
contents: write
steps:
- - uses: actions/checkout@v4
+ - uses: actions/checkout@v7
- - uses: actions/setup-node@v4
- with:
- node-version: 24
-
- - uses: pnpm/action-setup@v4
- with:
- version: 10
-
- - name: Install dependencies
- run: pnpm install
+ - uses: ./.github/actions/setup
- name: Download engine artifact
- uses: actions/download-artifact@v4
+ uses: actions/download-artifact@v8
with:
name: engine-wasm
path: desktop/public
@@ -137,9 +125,23 @@ jobs:
- name: Package and publish desktop app
if: github.event_name == 'push'
- run: pnpm --filter ./desktop exec electron-builder --publish always
+ shell: bash
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+ # electron-builder's GitHub publisher dedups assets on re-upload, so the
+ # whole command is idempotent — retry it to ride out GitHub API 5xx
+ # blips (a 503 on GET /releases has failed an otherwise-finished build
+ # mid-upload). Backs off 30s, 60s between attempts.
+ run: |
+ for attempt in 1 2 3; do
+ if pnpm --filter ./desktop exec electron-builder --publish always; then
+ exit 0
+ fi
+ echo "::warning::electron-builder publish attempt $attempt failed"
+ [ "$attempt" -lt 3 ] && sleep "$((attempt * 30))"
+ done
+ echo "::error::electron-builder publish failed after 3 attempts"
+ exit 1
- name: Package desktop app (dry run, no publish)
if: github.event_name != 'push'
@@ -147,7 +149,7 @@ jobs:
- name: Upload installer artifact (dry run)
if: github.event_name != 'push'
- uses: actions/upload-artifact@v4
+ uses: actions/upload-artifact@v7
with:
name: installer-${{ matrix.platform }}
path: |