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.

feat(editor): projects self-portrait — the viewport becomes thumbnail.png on save

yhh334041e9efb9
diff --git a/desktop/electron/main.ts b/desktop/electron/main.ts
index 405b8d22c..83d72a582 100644
--- a/desktop/electron/main.ts
+++ b/desktop/electron/main.ts
@@ -414,6 +414,22 @@ ipcMain.handle('project:createAsset', (_e, destDir: string, baseName: string, co
createAsset(requireRoot(), destDir, baseName, content, type),
);
+// The project's launcher cover: capture the composited page region the renderer
+// passes (its viewport canvas, center-cropped to 16:9) and write it to the project
+// root as thumbnail.png, downscaled to a 640-wide PNG. Called on scene save, so a
+// project's card always shows its last-saved look.
+ipcMain.handle('project:thumbnail', async (_e, rect: { x: number; y: number; width: number; height: number }) => {
+ if (!win) return;
+ const img = await win.webContents.capturePage({
+ x: Math.round(rect.x),
+ y: Math.round(rect.y),
+ width: Math.round(rect.width),
+ height: Math.round(rect.height),
+ });
+ const scaled = img.getSize().width > 640 ? img.resize({ width: 640 }) : img;
+ await writeFile(path.join(requireRoot(), 'thumbnail.png'), scaled.toPNG());
+});
+
ipcMain.handle('fs:read', (_e, relPath: string) => readInRoot(requireRoot(), relPath));
ipcMain.handle('fs:write', (_e, relPath: string, contents: string) =>
writeInRoot(requireRoot(), relPath, contents),
diff --git a/desktop/electron/preload.ts b/desktop/electron/preload.ts
index 4f090a289..1c92a1909 100644
--- a/desktop/electron/preload.ts
+++ b/desktop/electron/preload.ts
@@ -59,6 +59,9 @@ const api = {
/** Show a Save-As dialog; returns a project-relative scene path (null if cancelled). */
saveSceneDialog: (defaultRel?: string): Promise<string | null> =>
ipcRenderer.invoke('project:saveDialog', defaultRel),
+ /** Capture a page region (CSS px) and write it as the project's cover (`thumbnail.png`). */
+ thumbnail: (rect: { x: number; y: number; width: number; height: number }): Promise<void> =>
+ ipcRenderer.invoke('project:thumbnail', rect),
/** Copy a template into `<location>/<name>`; returns the new project root. */
createFromTemplate: (templateDir: string, location: string, name: string): Promise<string> =>
ipcRenderer.invoke('project:createFromTemplate', templateDir, location, name),
diff --git a/desktop/src/main.tsx b/desktop/src/main.tsx
index d0fb425ee..af7bb1610 100644
--- a/desktop/src/main.tsx
+++ b/desktop/src/main.tsx
@@ -68,6 +68,7 @@ if (new URLSearchParams(location.search).has('automation')) {
playState: () => PlayRealm.getSnapshot(),
reveal: (id: string) => dockApi.revealAndExpand(id),
togglePerfOverlay: () => PerfMonitor.toggleOverlay(),
+ captureThumbnail: () => ProjectStore.captureThumbnail(),
surface: EditorControlSurface,
};
}
diff --git a/desktop/src/project/ProjectStore.ts b/desktop/src/project/ProjectStore.ts
index 969437ccf..7347e2d42 100644
--- a/desktop/src/project/ProjectStore.ts
+++ b/desktop/src/project/ProjectStore.ts
@@ -1009,6 +1009,7 @@ class ProjectStoreImpl {
await this.persistLastScene(st.currentScene);
EditorHistory.markSaved();
Toasts.push(`Saved ${st.currentScene.split('/').pop()}`, 'success');
+ void this.captureThumbnail();
}
/** Write the current world to a project-relative path (explicit, no lossy guard). */
@@ -1018,6 +1019,39 @@ class ProjectStoreImpl {
await this.persistLastScene(relPath);
EditorHistory.markSaved();
Toasts.push(`Saved ${relPath.split('/').pop()}`, 'success');
+ void this.captureThumbnail();
+ }
+
+ /**
+ * Refresh the project's cover (`thumbnail.png` at the root — the launcher card
+ * image): capture the composited viewport, center-cropped to the card's 16:9.
+ * Editor chrome overlaid on the viewport (gizmos, perf HUD) is hidden for the
+ * capture frame via a body class. Fire-and-forget from save — a cover refresh
+ * must never turn into a save failure.
+ */
+ async captureThumbnail(): Promise<void> {
+ try {
+ const capture = window.estella.project.thumbnail;
+ const canvas = EngineHost.canvas;
+ if (!capture || !canvas || !this.state) return;
+ const r = canvas.getBoundingClientRect();
+ if (r.width < 64 || r.height < 64) return; // no meaningful cover from a collapsed viewport
+ let w = r.width;
+ let h = (r.width * 9) / 16;
+ if (h > r.height) {
+ h = r.height;
+ w = (r.height * 16) / 9;
+ }
+ document.body.classList.add('thumb-capture');
+ // Two frames + a beat, so the overlay-hidden state has been PRESENTED before
+ // the grab — capturePage samples the last composited frame, not the DOM.
+ await new Promise((res) => requestAnimationFrame(() => requestAnimationFrame(() => setTimeout(res, 60))));
+ await capture({ x: r.x + (r.width - w) / 2, y: r.y + (r.height - h) / 2, width: w, height: h });
+ } catch {
+ // never surface — the cover is cosmetic
+ } finally {
+ document.body.classList.remove('thumb-capture');
+ }
}
/**
diff --git a/desktop/src/theme/app.css b/desktop/src/theme/app.css
index 9206360dc..82a4a869b 100644
--- a/desktop/src/theme/app.css
+++ b/desktop/src/theme/app.css
@@ -689,6 +689,15 @@
background: rgba(76, 143, 214, 0.04);
}
+/* Cover capture (ProjectStore.captureThumbnail): for the capture frame, hide every
+ viewport overlay except the rendered scene itself — no gizmo icons, toolbars, or
+ perf HUD in a project cover. The play layer stays (a play-mode capture should
+ show the game), minus its Stop badge. */
+body.thumb-capture .viewport > :not(.viewport__stage):not(.viewport__play),
+body.thumb-capture .viewport__play-stop {
+ visibility: hidden !important;
+}
+
/* Light2D gizmo: the wrap is translated to the light (rAF); icon + SVG draw at its origin,
tinted by the wrap's `color` (set to the light color) via currentColor. */
.viewport__light-gizmo {
diff --git a/examples/effects-gallery/thumbnail.png b/examples/effects-gallery/thumbnail.png
new file mode 100644
index 000000000..168b491c3
Binary files /dev/null and b/examples/effects-gallery/thumbnail.png differ
diff --git a/examples/enemy-ai/thumbnail.png b/examples/enemy-ai/thumbnail.png
new file mode 100644
index 000000000..a859fe0d9
Binary files /dev/null and b/examples/enemy-ai/thumbnail.png differ