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): a mesh and a material look like themselves in the browser

esengine8c23a9d03117
diff --git a/desktop/src/panels/ContentBrowser.tsx b/desktop/src/panels/ContentBrowser.tsx
index f5b6daaeb..fae1ca9fc 100644
--- a/desktop/src/panels/ContentBrowser.tsx
+++ b/desktop/src/panels/ContentBrowser.tsx
@@ -3,6 +3,7 @@
import { Fragment, useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from 'react';
import { ChevronRight, LayoutGrid, List, Import, FolderOpen, Folder, FolderPlus, ArrowLeft, ArrowRight, ArrowUp, ArrowDownUp, Play, EyeOff, Plus, Search } from 'lucide-react';
import { AssetIcon, assetTint } from '@/components/icons';
+import { canRenderThumbnail, thumbnailFor, subscribeThumbnails } from '@/project/assetThumbnails';
import { EmptyState } from '@/components/EmptyState';
import { IconButton } from '@/components/IconButton';
import { ConfirmDialog } from '@/components/ConfirmDialog';
@@ -101,6 +102,22 @@ function useDir(relPath: string | null): { entries: DirEntry[]; loading: boolean
// on Enter or blur, cancels on Escape, and pre-selects the base name (sans
// extension). Stops pointer/key events so it doesn't trigger the tile's
// select/open/drag while editing.
+/**
+ * A tile's picture: an engine-drawn thumbnail where one exists, the type's icon
+ * otherwise. The render is asked for during paint and answered later, so this
+ * subscribes rather than awaits — a folder of fifty meshes mounts fifty tiles,
+ * and each is one shared job keyed by path.
+ */
+function AssetThumb({ path, type }: { path: string; type: AssetType }) {
+ const drawable = canRenderThumbnail(type);
+ const url = useSyncExternalStore(
+ subscribeThumbnails,
+ () => (drawable ? thumbnailFor(path) : null),
+ );
+ if (!url) return <AssetIcon type={type} size={30} />;
+ return <img src={url} alt="" draggable={false} className="th-render" />;
+}
+
function RenameInput({
name,
onCommit,
@@ -1309,7 +1326,9 @@ export function ContentBrowser() {
// of image memory for the twenty thumbnails actually on screen.
<img src={`estella://project/${path}`} alt="" draggable={false} loading="lazy" decoding="async" />
) : (
- <AssetIcon type={type} size={30} />
+ // A mesh or a material is drawn by the engine; anything else keeps
+ // its icon, and so does one whose render has not landed yet.
+ <AssetThumb path={path} type={type} />
)}
{!it.isDir && TYPE_CODE[type] && <span className="badge">{TYPE_CODE[type]}</span>}
{DELIVERY_MODE_META[deliv].badge && (
diff --git a/desktop/src/project/assetThumbnails.ts b/desktop/src/project/assetThumbnails.ts
new file mode 100644
index 000000000..3992b6bcd
--- /dev/null
+++ b/desktop/src/project/assetThumbnails.ts
@@ -0,0 +1,91 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file Thumbnails for assets an icon cannot describe — a mesh, a material.
+ * Both are drawn by the engine through the path the viewport uses, so
+ * the two differ by one call and share everything after it. Rendered on
+ * demand, once per path, and dropped when the file changes.
+ */
+import { Material, renderMeshPreview } from 'esengine';
+import { EngineHost } from '@/engine/EngineHost';
+import { AssetBinding } from '@/engine/AssetBinding';
+import { AssetRegistry } from './AssetRegistry';
+import { fsRefresh } from './fsRefresh';
+
+/** Square edge, in device pixels. A grid tile is ~96 CSS px; this survives a 2x screen. */
+const SIZE = 192;
+
+/** Types this can draw. Anything else keeps its icon, which is the honest answer. */
+const DRAWABLE = new Set(['mesh', 'material']);
+
+export function canRenderThumbnail(type: string): boolean {
+ return DRAWABLE.has(type);
+}
+
+type Entry = { url: string | null; rev: number };
+
+const cache = new Map<string, Entry>();
+const pending = new Map<string, Promise<string | null>>();
+const listeners = new Set<() => void>();
+
+/** The disk's own version is the cache's: a re-imported mesh must not keep the
+ * picture of the file it replaced, and there is no second thing to bump. */
+const revisionNow = (): number => fsRefresh.get();
+
+export function subscribeThumbnails(fn: () => void): () => void {
+ listeners.add(fn);
+ const offDisk = fsRefresh.subscribe(fn);
+ return () => {
+ listeners.delete(fn);
+ offDisk();
+ };
+}
+
+/** A canvas the ImageData is put through — toDataURL is the only way to an <img>. */
+function toDataUrl(image: ImageData): string {
+ const canvas = document.createElement('canvas');
+ canvas.width = image.width;
+ canvas.height = image.height;
+ canvas.getContext('2d')?.putImageData(image, 0, 0);
+ return canvas.toDataURL('image/png');
+}
+
+async function render(path: string, type: string): Promise<ImageData | null> {
+ if (type === 'mesh') {
+ const handle = await AssetBinding.meshHandle(path);
+ return handle ? renderMeshPreview(EngineHost.world?.getWasmModule(), handle, SIZE, SIZE) : null;
+ }
+ const handle = AssetBinding.materialHandle(path);
+ return handle ? Material.renderPreview(handle, SIZE, SIZE) : null;
+}
+
+/**
+ * The thumbnail for @p path, or null while one is being drawn (and forever, for
+ * an asset that cannot be). Callers re-read after {@link subscribeThumbnails}
+ * fires; the render is started once per path and shared by every tile asking.
+ */
+export function thumbnailFor(path: string): string | null {
+ const hit = cache.get(path);
+ if (hit && hit.rev === revisionNow()) return hit.url;
+ if (pending.has(path)) return null;
+
+ const type = AssetRegistry.assetTypeAt(path);
+ if (!canRenderThumbnail(type) || EngineHost.getSnapshot().status !== 'ready') return null;
+
+ const at = revisionNow();
+ const job = render(path, type)
+ .then((image) => (image ? toDataUrl(image) : null))
+ .catch(() => null)
+ .then((url) => {
+ pending.delete(path);
+ // A render that finished after an invalidation describes a file that is
+ // no longer there; drop it rather than caching a stale picture.
+ if (at === revisionNow()) {
+ cache.set(path, { url, rev: at });
+ for (const fn of listeners) fn();
+ }
+ return url;
+ });
+ pending.set(path, job);
+ return null;
+}
diff --git a/desktop/src/theme/content.css b/desktop/src/theme/content.css
index cf9616ea9..2dba42a95 100644
--- a/desktop/src/theme/content.css
+++ b/desktop/src/theme/content.css
@@ -76,6 +76,9 @@
.asset.is-dragging, .lr.is-dragging { opacity: 0.45; }
.asset .th { position: relative; width: 100%; aspect-ratio: 1; border-radius: var(--r-md) var(--r-md) 0 0; display: grid; place-items: center; color: rgba(255, 255, 255, 0.85); overflow: hidden; background: var(--srf-4); }
.asset .th img { width: 100%; height: 100%; object-fit: cover; }
+/* An engine-drawn thumbnail is a square render on transparency: contained, not
+ cropped, and on the tile's own surface rather than an image's edge-to-edge fill. */
+.asset .th img.th-render { object-fit: contain; padding: 6px; }
.asset .th .badge { position: absolute; top: 5px; left: 5px; font-size: var(--fs-3xs); font-weight: 700; letter-spacing: 0.4px; padding: 1px 4px; border-radius: var(--r-xs); background: rgba(0, 0, 0, 0.5); color: var(--on-accent); font-family: var(--mono); }
/* Startup-scene marker — the scene the editor opens, Play boots, exports ship first. */
.asset .th .badge.start { left: auto; right: 5px; display: grid; place-items: center; padding: 2px 3px; background: var(--star); }
diff --git a/desktop/tests/asset-thumbnails.test.ts b/desktop/tests/asset-thumbnails.test.ts
new file mode 100644
index 000000000..e300e3846
--- /dev/null
+++ b/desktop/tests/asset-thumbnails.test.ts
@@ -0,0 +1,53 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file The thumbnail cache's own contract: which types it claims, that it
+ * never blocks a paint, and that a disk change re-asks. What it DRAWS is
+ * two pixel gates' business (mesh-preview, the material preview probe).
+ */
+import { describe, it, expect, vi } from 'vitest';
+
+vi.mock('esengine', () => ({
+ Material: { renderPreview: vi.fn(async () => null) },
+ renderMeshPreview: vi.fn(async () => null),
+}));
+vi.mock('@/engine/EngineHost', () => ({
+ EngineHost: { getSnapshot: () => ({ status: 'idle' }), world: null },
+}));
+vi.mock('@/engine/AssetBinding', () => ({
+ AssetBinding: { meshHandle: vi.fn(async () => 0), materialHandle: () => 0 },
+}));
+vi.mock('@/project/AssetRegistry', () => ({
+ AssetRegistry: { assetTypeAt: (p: string) => (p.endsWith('.esmesh') ? 'mesh' : 'texture') },
+}));
+
+import { canRenderThumbnail, thumbnailFor, subscribeThumbnails } from '@/project/assetThumbnails';
+import { fsRefresh } from '@/project/fsRefresh';
+
+describe('asset thumbnails', () => {
+ it('claims only what the engine can draw', () => {
+ expect(canRenderThumbnail('mesh')).toBe(true);
+ expect(canRenderThumbnail('material')).toBe(true);
+ // A texture is its own picture and a prefab has none — both keep their tile.
+ expect(canRenderThumbnail('texture')).toBe(false);
+ expect(canRenderThumbnail('prefab')).toBe(false);
+ });
+
+ it('answers during a paint, never blocking on a render', () => {
+ // Called from render(), so it returns what it has — null until one lands.
+ expect(thumbnailFor('assets/tree.esmesh')).toBeNull();
+ expect(thumbnailFor('assets/tree.png')).toBeNull();
+ });
+
+ it('re-asks when the DISK changes, not only when a render lands', () => {
+ // A re-imported mesh keeps its path; without this a tile would show the
+ // picture of the file it replaced until the panel remounted.
+ let woken = 0;
+ const off = subscribeThumbnails(() => { woken++; });
+ fsRefresh.bump();
+ expect(woken).toBe(1);
+ off();
+ fsRefresh.bump();
+ expect(woken).toBe(1);
+ });
+});