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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
ci: modernize workflows — shared setup action, retries, current action majors
yhh0254165bf5ba
diff --git a/.github/actions/setup/action.yml b/.github/actions/setup/action.ymlnew file mode 100644index 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-lockfilediff --git a/.github/workflows/README.md b/.github/workflows/README.mdindex 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.0This 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/CompilerIf cache becomes corrupted or stale:1. Bump the cache key version in workflow files2. 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.ymlindex 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++ testsruns-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_devicesteps:- - uses: actions/checkout@v4+ - uses: actions/checkout@v7with: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@v16with:version: 5.0.0- name: Setup ccache- uses: hendrikmuhs/[email protected]+ uses: hendrikmuhs/[email protected]with:key: ${{ runner.os }}-emscriptenmax-size: 500M- - name: Install dependencies- run: pnpm install-- name: Build Web targetrun: node build-tools/cli.js build -t web --no-sync@@ -67,20 +73,13 @@ jobs:- name: Build C++ test harnessesrun: |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 harnessesrun: |- 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; docp "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@v7with:name: wasm-webpath: build/wasm/web/@@ -102,19 +101,12 @@ jobs:test:name: Tests (SDK + Desktop)runs-on: ubuntu-latest+ timeout-minutes: 25steps:- - 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-latestneeds: build-emscripten+ timeout-minutes: 40steps:- - 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@v8with:name: wasm-webpath: build/wasm/web/- - name: Install dependencies- run: pnpm install-- name: Build SDKrun: pnpm --filter ./sdk builddiff --git a/.github/workflows/docs.yml b/.github/workflows/docs.ymlindex 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: 30steps:- 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 Doxygenrun: 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@v5with:path: docs/dist@@ -82,7 +73,8 @@ jobs:url: ${{ steps.deployment.outputs.page_url }}runs-on: ubuntu-latestneeds: build+ timeout-minutes: 15steps:- name: Deploy to GitHub Pagesid: deployment- uses: actions/deploy-pages@v4+ uses: actions/deploy-pages@v5diff --git a/.github/workflows/release-desktop.yml b/.github/workflows/release-desktop.ymlindex 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: 10permissions:contents: writesteps:- - 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: 30steps:- - uses: actions/checkout@v4+ - uses: actions/checkout@v7with: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@v16with:version: 5.0.0- name: Setup ccache- uses: hendrikmuhs/[email protected]+ uses: hendrikmuhs/[email protected]with:key: ${{ runner.os }}-emscriptenmax-size: 500M- - name: Install dependencies- run: pnpm install-- name: Build engine and sync to desktoprun: node build-tools/cli.js build -t all- name: Upload engine artifact- uses: actions/upload-artifact@v4+ uses: actions/upload-artifact@v7with:name: engine-wasmpath: |@@ -106,25 +102,17 @@ jobs:- windows-latestruns-on: ${{ matrix.platform }}+ timeout-minutes: 40permissions:contents: writesteps:- - 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@v8with:name: engine-wasmpath: desktop/public@@ -137,9 +125,23 @@ jobs:- name: Package and publish desktop appif: github.event_name == 'push'- run: pnpm --filter ./desktop exec electron-builder --publish always+ shell: bashenv: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@v7with:name: installer-${{ matrix.platform }}path: |