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.

fix(release): publish a verified frame of the exported sample

yhh42f9dad30851
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index ca32a3e38..e15829ca8 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -12,10 +12,22 @@ on:
tags:
- 'docs-v*'
workflow_call:
+ inputs:
+ engine-artifact-run:
+ type: string
+ required: false
+ default: ''
workflow_dispatch:
+ inputs:
+ engine-artifact-run:
+ description: 'Candidate release run containing release-site-frame; blank retains the published game frame.'
+ type: string
+ required: false
+ default: ''
permissions:
contents: read
+ actions: read
pages: write
id-token: write
@@ -85,10 +97,31 @@ jobs:
# section is labelled with no JavaScript and no cross-origin request.
# The links themselves are the mirror's stable `latest/` names, which
# stay correct for releases published after this deploy.
- sed -i "s/__ESTELLA_VERSION__/$(node -p "require('./desktop/package.json').version")/g" docs/dist/index.html
+ sed -i "s/__ESTELLA_VERSION__/$(node -p "require('./package.json').version")/g" docs/dist/index.html
echo 'estellaengine.com' > docs/dist/CNAME
touch docs/dist/.nojekyll
+ - name: Stage a verified frame of the shipped game
+ env:
+ GH_TOKEN: ${{ github.token }}
+ FRAME_RUN: ${{ inputs.engine-artifact-run }}
+ FRAME_SHA: ${{ github.sha }}
+ run: |
+ if [ -n "$FRAME_RUN" ]; then
+ gh run download "$FRAME_RUN" --repo "$GITHUB_REPOSITORY" --name release-site-frame --dir docs/dist
+ else
+ curl --fail --location https://estellaengine.com/celestial-heights-frame.png --output docs/dist/celestial-heights-frame.png
+ curl --fail --location https://estellaengine.com/hero-provenance.json --output docs/dist/hero-provenance.json
+ fi
+ node --input-type=module <<'JS'
+ import {readFileSync} from 'node:fs';
+ import {createHash} from 'node:crypto';
+ const info=JSON.parse(readFileSync('docs/dist/hero-provenance.json','utf8'));
+ const image=readFileSync('docs/dist/celestial-heights-frame.png');
+ if(info.project!=='examples/celestial-heights'||!info.gitSha||createHash('sha256').update(image).digest('hex')!==info.sha256)throw Error('Game frame provenance mismatch');
+ if(process.env.FRAME_RUN && info.gitSha!==process.env.FRAME_SHA)throw Error('Game frame was captured from another commit');
+ JS
+
- name: Upload artifact
uses: actions/upload-pages-artifact@v5
with:
diff --git a/.github/workflows/release-desktop.yml b/.github/workflows/release-desktop.yml
index 08af23db7..f79a91d7e 100644
--- a/.github/workflows/release-desktop.yml
+++ b/.github/workflows/release-desktop.yml
@@ -83,7 +83,7 @@ jobs:
engine:
name: Build engine (wasm)
runs-on: ubuntu-latest
- timeout-minutes: 30
+ timeout-minutes: 40
steps:
- uses: actions/checkout@v7
@@ -129,6 +129,23 @@ jobs:
desktop/public/wasm-quickgame
retention-days: 3
+ - name: Install the virtual display dependencies
+ run: |
+ sudo apt-get update
+ sudo apt-get install -y xvfb libasound2t64 libgtk-3-0t64 libgbm1
+
+ - name: Capture the shipped example for the website
+ run: node tools/capture-release-frame.mjs out/release-site-frame
+
+ - name: Upload the real game frame and provenance
+ uses: actions/upload-artifact@v7
+ with:
+ name: release-site-frame
+ path: |
+ out/release-site-frame/celestial-heights-frame.png
+ out/release-site-frame/hero-provenance.json
+ retention-days: 3
+
# The native app's compiled half — the engine, Dawn, QuickJS, the linked-in
# runtimes — carries no project data, so it is built ONCE per release and
# published as a runtime template the editor installs. This is what frees a
@@ -624,7 +641,10 @@ jobs:
docs:
needs: publish
uses: ./.github/workflows/docs.yml
+ with:
+ engine-artifact-run: ${{ github.run_id }}
permissions:
contents: read
+ actions: read
pages: write
id-token: write
diff --git a/CHANGELOG.md b/CHANGELOG.md
index a71e75665..338af3674 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -22,6 +22,8 @@ published separately; it ships inside the editor.
### Fixed
+- **The website preview comes from the exported game.** Release builds capture the Celestial Heights Web sample and publish its source commit and image checksum alongside the frame.
+
- **Stopping editor Play stops game audio.** Single-player Stop now releases the game App and its plugins while keeping the engine renderer warm for re-Play. BGM and scripted/source voices are stopped, pending audio loads cannot resume playback, and a Stop during startup cancels the realm. This applies to both the editor UI and MCP (`set_play: stopped`).
- **Entity activity follows the hierarchy.** Rendering, skeletal animation, particles and UI honor inherited activity, and transform updates remain consistent for deep hierarchies.
diff --git a/README.md b/README.md
index 01a5ace6e..1c9ac68c9 100644
--- a/README.md
+++ b/README.md
@@ -24,9 +24,9 @@
Estella is a **2D/3D game engine** with a TypeScript SDK driven by a high-performance **C++** core — as WebAssembly on the web, and compiled ahead of time on native platforms. It outputs games that run in **web browsers**, on the **desktop**, in **WeChat MiniGames**, as single-file **playable ads**, and as native **Android / iOS** apps. A visual editor is available as a separate, free download.
<div align="center">
- <img src="docs/assets/editor-hero-c5bfd2f3.png" alt="An action-RPG scene open in the Estella editor" width="900" />
+ <img src="https://estellaengine.com/celestial-heights-frame.png" alt="The Celestial Heights 2D sample running in a released Web build" width="900" />
<br/>
- <sub><i>Celestial Heights — an action-RPG scene in the Estella editor, with the full scene graph in the outliner.</i></sub>
+ <sub><i>Celestial Heights — a 2D sample captured from the exported game. Release builds generate this frame and publish its provenance alongside it.</i></sub>
</div>
## Why Estella?
diff --git a/docs/landing/index.html b/docs/landing/index.html
index 439c0bc2a..e45d25ac9 100644
--- a/docs/landing/index.html
+++ b/docs/landing/index.html
@@ -446,9 +446,9 @@
<div class="shot">
<figure>
- <img src="/editor-hero-c5bfd2f3.png" width="1480" height="920"
- alt="An action-RPG scene open in the Estella editor, with the scene graph in the outliner" loading="lazy" />
- <figcaption>Celestial Heights — an action-RPG scene in the Estella editor.</figcaption>
+ <img src="/celestial-heights-frame.png" width="1280" height="720"
+ alt="The Celestial Heights 2D sample running in a released Web build" loading="lazy" />
+ <figcaption>Celestial Heights — a 2D sample captured from the exported game.</figcaption>
</figure>
</div>
</section>
diff --git a/tools/capture-release-frame.mjs b/tools/capture-release-frame.mjs
new file mode 100644
index 000000000..bb13a6725
--- /dev/null
+++ b/tools/capture-release-frame.mjs
@@ -0,0 +1,25 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+import {execFileSync, spawnSync} from 'node:child_process';
+import {mkdirSync, readFileSync, writeFileSync} from 'node:fs';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {createHash} from 'node:crypto';
+import {runElectron} from './lib/electronRun.mjs';
+
+const root=path.resolve(path.dirname(fileURLToPath(import.meta.url)),'..');
+const out=path.resolve(root,process.argv[2]??'out/release-site-frame');
+const subject=path.join(out,'game');
+mkdirSync(out,{recursive:true});
+const exported=spawnSync(process.execPath,['pipeline/bin/estella.mjs','export','examples/celestial-heights',
+ '--platform','web','--out',subject],{cwd:root,encoding:'utf8'});
+if(exported.status!==0)throw Error(`Site subject export failed: ${exported.stderr}`);
+const frame=path.join(out,'celestial-heights-frame.png');
+const capture=runElectron(['tools/launchers/launch-export.mjs','--dir',subject,'--w','1280','--h','720',
+ '--settle','60','--timeout','120000','--out',frame],{cwd:root,encoding:'utf8'});
+if(capture.status!==0)throw Error(`Site subject capture failed: ${capture.stdout}\n${capture.stderr}`);
+const provenance={schema:1,project:'examples/celestial-heights',version:JSON.parse(readFileSync(path.join(root,'package.json'),'utf8')).version,
+ gitSha:execFileSync('git',['rev-parse','HEAD'],{cwd:root,encoding:'utf8'}).trim(),
+ sha256:createHash('sha256').update(readFileSync(frame)).digest('hex'),capture:'exported Web game, hidden Electron, 60 settled frames',width:1280,height:720};
+writeFileSync(path.join(out,'hero-provenance.json'),JSON.stringify(provenance,null,2)+'\n');
+console.log(JSON.stringify(provenance));
diff --git a/tools/releaseGate.mjs b/tools/releaseGate.mjs
index 2bb917097..13b42d31a 100644
--- a/tools/releaseGate.mjs
+++ b/tools/releaseGate.mjs
@@ -301,7 +301,7 @@ export const CRITERIA = [
// A machine can compare two images; deciding that one of them is honest
// marketing is not a thing to compute. Whether the frame is sound is the
// flagship's parity run; whether it is the frame on the site is a person's.
- manual: 'release captain, over docs/assets + docs/landing: the hero comes from a build of examples/celestial-heights',
+ manual: 'release captain, over the release-site-frame artifact and docs/landing: verify hero-provenance.json identifies this source commit and the frame matches the exported examples/celestial-heights game',
},
{
id: 'diagnostics-from-a-release-build',
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index d17f44716..e3b98b1f5 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 = {
+ 'fix(release): publish a verified frame of the exported sample':
+ { note: 'The website preview comes from the exported game.' },
'fix(render): preserve sprites with incompatible WebGL S3TC dimensions':
{ note: 'Compressed sprites keep their authored dimensions on WebGL.' },
'fix(sdk): keep indexed access valid for strict consumers':