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.

chore(release): verify installed editor upgrades before publishing

yhhba773d9242dc
diff --git a/.github/workflows/release-desktop.yml b/.github/workflows/release-desktop.yml
index f79a91d7e..c92b32111 100644
--- a/.github/workflows/release-desktop.yml
+++ b/.github/workflows/release-desktop.yml
@@ -363,7 +363,7 @@ jobs:
- windows-latest
runs-on: ${{ matrix.platform }}
- timeout-minutes: 40
+ timeout-minutes: 50
permissions:
contents: write
@@ -511,6 +511,94 @@ jobs:
desktop/release/*.zip
retention-days: 3
+ - name: Install the previous Windows release and upgrade the saved project
+ if: runner.os == 'Windows'
+ shell: pwsh
+ env:
+ GH_TOKEN: ${{ github.token }}
+ run: |
+ $ErrorActionPreference = 'Stop'
+ $version = (Get-Content package.json -Raw | ConvertFrom-Json).version
+ $previous = [regex]::Matches((Get-Content CHANGELOG.md -Raw), '^## \[(\d+\.\d+\.\d+)\]', 'Multiline') | ForEach-Object { $_.Groups[1].Value } | Where-Object { $_ -ne $version } | Select-Object -First 1
+ if (!$previous) { throw 'No previous release declared in CHANGELOG' }
+ $downloads = Join-Path $env:RUNNER_TEMP 'estella-upgrade-downloads'
+ $installed = Join-Path $env:RUNNER_TEMP 'estella-upgrade-installed'
+ $project = Join-Path $env:RUNNER_TEMP 'estella-upgrade-project'
+ $evidence = Join-Path $env:GITHUB_WORKSPACE 'out/installer-acceptance'
+ New-Item -ItemType Directory -Force $downloads | Out-Null
+ gh release download "v$previous" --repo $env:GITHUB_REPOSITORY --pattern "Estella-Editor-Setup-$previous.exe" --dir $downloads
+ if ($LASTEXITCODE -ne 0) { throw 'Previous installer download failed' }
+ $oldInstaller = Join-Path $downloads "Estella-Editor-Setup-$previous.exe"
+ $install = Start-Process -FilePath $oldInstaller -ArgumentList '/S', "/D=$installed" -WindowStyle Hidden -Wait -PassThru
+ if ($install.ExitCode -ne 0) { throw "Previous installer exit $($install.ExitCode)" }
+ $exe = Join-Path $installed 'estella-editor.exe'
+ $front = Join-Path $installed 'resources/app.asar.unpacked/dist-electron/mcp/editor-mcp.mjs'
+ if ((Get-Item $exe).VersionInfo.FileVersion -ne $previous) { throw 'Previous installed version mismatch' }
+ node tools/exercise-installed-upgrade.mjs seed $front $exe $project $evidence (Join-Path $installed 'resources/examples/platformer')
+ if ($LASTEXITCODE -ne 0) { throw 'Previous installed project save failed' }
+ $candidate = Join-Path $env:GITHUB_WORKSPACE "desktop/release/Estella-Editor-Setup-$version.exe"
+ $upgrade = Start-Process -FilePath $candidate -ArgumentList '/S', "/D=$installed" -WindowStyle Hidden -Wait -PassThru
+ if ($upgrade.ExitCode -ne 0) { throw "Candidate installer exit $($upgrade.ExitCode)" }
+ if ((Get-Item $exe).VersionInfo.FileVersion -ne $version) { throw 'Upgraded installed version mismatch' }
+ node tools/exercise-installed-upgrade.mjs verify $front $exe $project $evidence
+ if ($LASTEXITCODE -ne 0) { throw 'Installed project upgrade failed' }
+ $env:ESTELLA_E2E_FRONT = $front
+ $env:ESTELLA_MCP_EDITOR_ARGS = '--mcp-hidden --force-device-scale-factor=1'
+ $env:ESTELLA_E2E_EXPORT = '1'
+ Push-Location desktop
+ node scripts/editor-mcp-editor-e2e.mjs
+ Pop-Location
+ if ($LASTEXITCODE -ne 0) { throw 'Installed editor end-to-end check failed' }
+
+ - name: Install the previous macOS release and upgrade the saved project
+ if: runner.os == 'macOS'
+ shell: bash
+ env:
+ GH_TOKEN: ${{ github.token }}
+ run: |
+ set -euo pipefail
+ version=$(node -p "require('./package.json').version")
+ previous=$(node --input-type=module -e "import fs from 'node:fs';const v=JSON.parse(fs.readFileSync('package.json')).version;console.log([...fs.readFileSync('CHANGELOG.md','utf8').matchAll(/^## \\[(\\d+\\.\\d+\\.\\d+)\\]/gm)].map(m=>m[1]).find(x=>x!==v)??'')")
+ test -n "$previous"
+ downloads="$RUNNER_TEMP/estella-upgrade-downloads"
+ installed="$RUNNER_TEMP/estella-upgrade-installed"
+ project="$RUNNER_TEMP/estella-upgrade-project"
+ evidence="$GITHUB_WORKSPACE/out/installer-acceptance"
+ mount="$RUNNER_TEMP/estella-upgrade-volume"
+ mkdir -p "$downloads" "$installed" "$mount"
+ gh release download "v$previous" --repo "$GITHUB_REPOSITORY" --pattern "Estella-Editor-$previous-arm64.dmg" --dir "$downloads"
+ trap 'hdiutil detach "$mount" >/dev/null 2>&1 || true' EXIT
+ hdiutil attach -quiet -nobrowse -readonly "$downloads/Estella-Editor-$previous-arm64.dmg" -mountpoint "$mount"
+ app="$installed/estella-editor.app"
+ ditto "$mount/estella-editor.app" "$app"
+ hdiutil detach "$mount"
+ test "$(/usr/libexec/PlistBuddy -c 'Print :CFBundleShortVersionString' "$app/Contents/Info.plist")" = "$previous"
+ front="$app/Contents/Resources/app.asar.unpacked/dist-electron/mcp/editor-mcp.mjs"
+ exe="$app/Contents/MacOS/estella-editor"
+ node tools/exercise-installed-upgrade.mjs seed "$front" "$exe" "$project" "$evidence" "$app/Contents/Resources/examples/platformer"
+ # Keep the old installation intact as evidence; install the new DMG at
+ # the same application path, as replacing a bundle in Finder does.
+ mv "$app" "$RUNNER_TEMP/estella-previous-installed.app"
+ hdiutil attach -quiet -nobrowse -readonly "desktop/release/Estella-Editor-$version-arm64.dmg" -mountpoint "$mount"
+ ditto "$mount/estella-editor.app" "$app"
+ hdiutil detach "$mount"
+ test "$(/usr/libexec/PlistBuddy -c 'Print :CFBundleShortVersionString' "$app/Contents/Info.plist")" = "$version"
+ codesign --verify --deep --strict "$app"
+ node tools/exercise-installed-upgrade.mjs verify "$front" "$exe" "$project" "$evidence"
+ export ESTELLA_E2E_FRONT="$front"
+ export ESTELLA_MCP_EDITOR_ARGS='--mcp-hidden --force-device-scale-factor=1'
+ export ESTELLA_E2E_EXPORT=1
+ (cd desktop && node scripts/editor-mcp-editor-e2e.mjs)
+
+ - name: Keep installed upgrade evidence
+ if: always()
+ uses: actions/upload-artifact@v7
+ with:
+ name: installed-upgrade-${{ matrix.platform }}
+ path: out/installer-acceptance
+ if-no-files-found: warn
+ retention-days: 3
+
# Publishing is the last step, and the one that has to be sure. A release missing
# a runtime template is a Download button that 404s — which is what 0.33.0
# shipped, because the templates were not built yet and nothing checked. So the
diff --git a/RELEASING.md b/RELEASING.md
index 0f5b6fced..7a1a1f87b 100644
--- a/RELEASING.md
+++ b/RELEASING.md
@@ -95,6 +95,8 @@ gh run download $candidateRun --repo esengine/estella --pattern 'native-template
每项写 PASS、FAIL 或 UNANSWERED,附证据和平台。缺设备或缺工具属于 UNANSWERED。
关键功能失败须修复;纯测试环境问题只有在同一问题被另一种有效验证覆盖、并记录原因和结果后才能放行。
+候选打包的 Windows/macOS job 还会在干净主机上安装上一正式版本,保存并重新打开 2D 项目,再从候选 NSIS/DMG 升级同一安装位置。`installed-upgrade-*` 产物记录升级前后场景、启动日志和结果;检查保留实体顺序、Prefab 数据及 Play/Stop 后的保存内容,并在实际安装程序上运行编辑器端到端和 Web 导出。它不代替上面的 OS 焦点、输入与真机验收,也不证明自动更新通道的网络下载流程。
+
## 4. 推送标签并正式发布
验收完成后,在同一冻结检出确认版本号、两仓库状态、远端 master 和 gitlink。
diff --git a/tools/exercise-installed-upgrade.mjs b/tools/exercise-installed-upgrade.mjs
new file mode 100644
index 000000000..44429d28e
--- /dev/null
+++ b/tools/exercise-installed-upgrade.mjs
@@ -0,0 +1,102 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+import { spawn, spawnSync } from 'node:child_process';
+import { cp, mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import assert from 'node:assert/strict';
+
+const [mode, front, executable, project, evidence, example] = process.argv.slice(2);
+assert(['seed', 'verify'].includes(mode) && front && executable && project && evidence,
+ 'Usage: seed|verify <installed-front> <installed-exe> <project> <evidence> [old-example]');
+await mkdir(evidence, { recursive: true });
+if (mode === 'seed') {
+ assert(example, 'Seed needs the previous installed version’s example');
+ await cp(example, project, { recursive: true,
+ filter: file => !/[/\\](\.esengine|node_modules|dist)([/\\]|$)/.test(file) });
+}
+const child = spawn(process.execPath, [front, '--editor', '--hidden', '--editor-exe', executable], {
+ stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true, detached: process.platform !== 'win32',
+ env: { ...process.env, ESTELLA_MCP_ALLOW_WRITES: '1' },
+});
+let buffer = '', stderr = '', sequence = 0;
+const pending = new Map();
+child.stderr.on('data', data => { stderr += data; });
+child.stdout.on('data', data => {
+ buffer += data;
+ let newline;
+ while ((newline = buffer.indexOf('\n')) >= 0) {
+ const line = buffer.slice(0, newline); buffer = buffer.slice(newline + 1);
+ let message;
+ try { message = JSON.parse(line); } catch { continue; }
+ pending.get(message.id)?.(message);
+ }
+});
+const rpc = (method, params) => new Promise((resolve, reject) => {
+ const id = ++sequence;
+ const timer = setTimeout(() => { pending.delete(id); reject(Error(`Timeout ${method}`)); }, 180000);
+ pending.set(id, message => {
+ clearTimeout(timer); pending.delete(id);
+ if (message.error || message.result?.isError) reject(Error(JSON.stringify(message)));
+ else resolve(message.result);
+ });
+ child.stdin.write(JSON.stringify({ jsonrpc: '2.0', id, method, params }) + '\n');
+});
+const call = (name, args = {}) => rpc('tools/call', { name, arguments: args });
+const json = async (name, args) => JSON.parse((await call(name, args)).content[0].text);
+const sceneFile = path.join(project, 'assets/scenes/main.esscene');
+const snapshotFile = path.join(evidence, 'previous-scene.json');
+try {
+ await rpc('initialize', { protocolVersion: '2024-11-05', capabilities: {},
+ clientInfo: { name: 'installer-upgrade-acceptance', version: '1' } });
+ await call('open_project', { root: project });
+ await call('open_scene', { path: 'assets/scenes/main.esscene' });
+ const idle = await json('wait_idle', { timeoutMs: 120000 });
+ assert(idle.idle, `Installed project never became idle: ${JSON.stringify(idle)}`);
+ if (mode === 'seed') {
+ const id = await json('add_entity');
+ assert(Number.isFinite(id), 'Previous installed editor did not create an entity');
+ await call('rename_entity', { id, name: 'UpgradeSavedMarker' });
+ await call('save_scene');
+ // Saving collapses live prefab instances into on-disk deltas. Reopen with
+ // the previous editor so the comparison names what was actually saved,
+ // including its entity order, rather than an unsaved expanded model.
+ await call('open_scene', { path: 'assets/scenes/main.esscene' });
+ const reopened = await json('wait_idle', { timeoutMs: 120000 });
+ assert(reopened.idle, `Previous saved scene did not settle: ${JSON.stringify(reopened)}`);
+ const snapshot = await json('serialize_scene');
+ assert(JSON.stringify(snapshot).includes('UpgradeSavedMarker'), 'Saved marker absent from scene');
+ await writeFile(snapshotFile, JSON.stringify(snapshot));
+ await writeFile(path.join(evidence, 'previous-scene.esscene'), await readFile(sceneFile));
+ } else {
+ const expected = JSON.parse(await readFile(snapshotFile, 'utf8'));
+ const opened = await json('serialize_scene');
+ await writeFile(path.join(evidence, 'upgraded-opened-scene.json'), JSON.stringify(opened, null, 2));
+ assert.deepEqual(opened, expected, 'Upgrade changed the saved scene model');
+ await call('set_play', { state: 'playing' });
+ const deadline = Date.now() + 120000;
+ let state;
+ do {
+ state = await json('get_play_state');
+ assert(!state.error, `Installed Play failed: ${JSON.stringify(state)}`);
+ if (state.ready) break;
+ await new Promise(resolve => setTimeout(resolve, 250));
+ } while (Date.now() < deadline);
+ assert(state.ready, `Installed Play never became ready: ${JSON.stringify(state)}`);
+ await call('set_play', { state: 'stopped' });
+ assert.deepEqual(await json('serialize_scene'), expected, 'Installed Play/Stop changed authored state');
+ await call('save_scene');
+ assert.deepEqual(JSON.parse(await readFile(sceneFile, 'utf8')),
+ JSON.parse(await readFile(path.join(evidence, 'previous-scene.esscene'), 'utf8')),
+ 'Upgrade rewrote saved scene content');
+ }
+ const result = { mode, executable, project, savedScenePreserved: true };
+ await writeFile(path.join(evidence, `${mode}.json`), JSON.stringify(result, null, 2));
+ console.log(`PASS upgrade project ${JSON.stringify(result)}`);
+} finally {
+ if (process.platform === 'win32') {
+ spawnSync('taskkill.exe', ['/PID', String(child.pid), '/T', '/F'], { windowsHide: true, stdio: 'ignore' });
+ } else {
+ try { process.kill(-child.pid, 'SIGTERM'); } catch { /* already stopped */ }
+ }
+ await writeFile(path.join(evidence, `${mode}-host.log`), stderr);
+}
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 6e3a148ca..85b01d800 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -28,6 +28,8 @@ export const NOTES_FLOOR = 'v0.65.0';
* the reader recognises anyway.
*/
export const NOTED = {
+ 'chore(release): verify installed editor upgrades before publishing':
+ { internal: 'Release acceptance installs the previous and candidate packages on clean CI hosts and verifies saved project continuity before publication; editor and runtime behavior are unchanged.' },
'fix(editor): keep camera preview refresh within its CPU budget':
{ note: 'Camera previews keep a conservative CPU budget.' },
'fix(release): publish a verified frame of the exported sample':