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 you can tell apart from another mesh

esengine1ba6a837491d
diff --git a/desktop/scripts/headless-verify.mjs b/desktop/scripts/headless-verify.mjs
index 65784fa7b..5616d8be3 100644
--- a/desktop/scripts/headless-verify.mjs
+++ b/desktop/scripts/headless-verify.mjs
@@ -137,7 +137,8 @@ function finish(result, server) {
const pickOk = !result.pick || result.pick.hit === result.pick.want;
const renderedOk = result.capture?.rendered ?? false;
const ok = result.ok && renderedOk && (result.expect?.ok ?? true) &&
- (result.resize?.ok ?? true) && (result.preview?.ok ?? true) && (result.grid?.ok ?? true) &&
+ (result.resize?.ok ?? true) && (result.preview?.ok ?? true) &&
+ (result.meshPreview?.ok ?? true) && (result.grid?.ok ?? true) &&
deviceLossOk && meshOk && pickOk;
console.log(`\n[verify:render] ${ok ? 'PASS' : 'FAIL'} — ${SCENE} (${BACKEND})`);
console.log('DRIVE_RESULT ' + JSON.stringify(result));
@@ -525,6 +526,34 @@ app.whenReady().then(async () => {
return { ok: got.every((g, k) => Math.abs(g - cfg.rgb[k]) <= tol), want: cfg.rgb, got, w, h };
})()`);
}
+ // Optional offscreen MESH-preview assertion (ESTELLA_VERIFY_MESH_PREVIEW =
+ // {w,h}). The claim is the FRAMING a mesh thumbnail adds over a material ball:
+ // the geometry lands inside the frame and reaches it, at any authored scale.
+ let meshPreview = null;
+ if (process.env.ESTELLA_VERIFY_MESH_PREVIEW) {
+ const cfg = JSON.parse(process.env.ESTELLA_VERIFY_MESH_PREVIEW);
+ meshPreview = await exec(`(async () => {
+ const cfg = ${JSON.stringify(cfg)};
+ const cap = await window.__estellaHeadless.api.renderSceneMeshPreview(cfg.w, cfg.h);
+ if (!cap) return { ok: false, reason: 'no scene mesh' };
+ const { width: w, height: h, rgba } = cap;
+ const lit = (x, y) => { const i = (y * w + x) * 4; return rgba[i] | rgba[i + 1] | rgba[i + 2]; };
+ let border = 0;
+ for (let x = 0; x < w; x++) { if (lit(x, 0)) border++; if (lit(x, h - 1)) border++; }
+ for (let y = 0; y < h; y++) { if (lit(0, y)) border++; if (lit(w - 1, y)) border++; }
+ // Reaching the outer eighth is what "fitted" means, and it holds for any
+ // shape — a fill ratio would only hold for one that is roughly square.
+ const pad = Math.floor(w / 8);
+ let reach = 0;
+ for (let y = 0; y < h; y++) {
+ for (let x = 0; x < w; x++) {
+ const outer = x < pad || y < pad || x >= w - pad || y >= h - pad;
+ if (outer && lit(x, y)) reach++;
+ }
+ }
+ return { ok: border === 0 && reach > 0, border, reach, w, h };
+ })()`);
+ }
// Optional editor-grid assertion (ESTELLA_VERIFY_GRID = minor spacing, world
// units): flip the grid on (this activates the editor view it draws through),
// capture, flip it off, and assert the frames differ — proving the custom-draw
@@ -561,7 +590,7 @@ app.whenReady().then(async () => {
return { differingPixels: differing, ok: differing > 300 };
`);
}
- finish({ ok: true, entityCount, drawCalls, capture, expect, resize, preview, grid, deviceLoss, meshResident, meshAsset, meshMaterial, meshPrefab, setField, pick }, server);
+ finish({ ok: true, entityCount, drawCalls, capture, expect, resize, preview, meshPreview, grid, deviceLoss, meshResident, meshAsset, meshMaterial, meshPrefab, setField, pick }, server);
} catch (e) {
finish({ ok: false, error: String((e && e.stack) || e) }, server);
}
diff --git a/desktop/src/engine/AssetBinding.ts b/desktop/src/engine/AssetBinding.ts
index 668dbdbad..174b39688 100644
--- a/desktop/src/engine/AssetBinding.ts
+++ b/desktop/src/engine/AssetBinding.ts
@@ -61,6 +61,20 @@ class AssetBindingImpl {
return this.preload?.materialHandles.get(path) ?? 0;
}
+ /**
+ * The live mesh handle for @p path, loading it into this realm if nothing has
+ * yet — what an inspector preview needs, since a mesh nothing references is
+ * never in a scene preload and has no engine-side cache to ask.
+ */
+ async meshHandle(path: string): Promise<number> {
+ const known = this.preload?.meshHandles.get(path);
+ if (known) return known;
+ const assets = EngineHost.getResource(Assets);
+ if (!assets) return 0;
+ await this.loadForSlot(assets, 'mesh', AssetRegistry.assetRef(path) ?? path, path);
+ return this.preload?.meshHandles.get(path) ?? 0;
+ }
+
/**
* The async half: a projection resolved `ref` COLD (assigned after the scene
* preload, or re-written on disk). Load it through its slot's loader, then
diff --git a/desktop/src/engine/EditorControlSurface.ts b/desktop/src/engine/EditorControlSurface.ts
index e761e6230..77d65d754 100644
--- a/desktop/src/engine/EditorControlSurface.ts
+++ b/desktop/src/engine/EditorControlSurface.ts
@@ -25,7 +25,7 @@ import type {
SceneNode,
} from '@/types';
import type { SceneData, PrefabData, SubsystemStatus, EventBindingRow } from 'esengine';
-import { Material, Sprite, Renderer } from 'esengine';
+import { Material, Sprite, Mesh2D, Renderer, renderMeshPreview } from 'esengine';
import { EngineHost } from './EngineHost';
import { isRequiredEmpty, componentByName, userSchema, coerceEnumInput, componentAuthorability, inspectorFields, modelAddableComponentEntries } from './schema';
import { ViewportController } from './ViewportController';
@@ -975,6 +975,23 @@ export class EditorControlSurfaceImpl {
return null;
}
+ /**
+ * The same, for the mesh a scene entity draws — a thumbnail of geometry rather
+ * than of a material. Null when no loaded mesh is in the scene.
+ */
+ async renderSceneMeshPreview(w: number, h: number): Promise<ViewportCapture | null> {
+ const world = EngineHost.world;
+ if (!world) return null;
+ for (const e of world.getAllEntities()) {
+ if (!world.has(e, Mesh2D)) continue;
+ const mesh = (world.get(e, Mesh2D) as { mesh: number }).mesh;
+ if (!mesh) continue;
+ const img = await renderMeshPreview(world.getWasmModule(), mesh, w, h);
+ if (img) return { rgba: new Uint8Array(img.data), width: img.width, height: img.height };
+ }
+ return null;
+ }
+
/** Live counts for quick assertions (entity count + last frame's merged draw calls). */
getStats(): { entities: number; drawCalls: number } {
return {
diff --git a/desktop/src/panels/Details.tsx b/desktop/src/panels/Details.tsx
index 175a52f96..7aa2fa8ce 100644
--- a/desktop/src/panels/Details.tsx
+++ b/desktop/src/panels/Details.tsx
@@ -57,6 +57,7 @@ import { controllerCurrentPage, drivenField, readComponentData, readModelField,
import { useOutliner } from '@/outliner/OutlinerController';
import { isFolderUnder, folderName } from '@/outliner/folders';
import { EngineHost } from '@/engine/EngineHost';
+import { AssetBinding } from '@/engine/AssetBinding';
import { SceneStore } from '@/engine/SceneStore';
import { SceneQuery, buildEntityInfo, buildInspector } from '@/engine/SceneQuery';
import { SceneModel } from '@/engine/SceneModel';
@@ -64,7 +65,7 @@ import { InspectorClipboard } from '@/engine/inspectorClipboard';
import { SceneCommands } from '@/engine/SceneCommands';
import { EntityOps } from '@/engine/entityOps';
import { PlayInspect } from '@/engine/PlayInspect';
-import { parseLocaleTable, EasingType, BUILTIN_SHADER_TEMPLATES } from 'esengine';
+import { parseLocaleTable, EasingType, BUILTIN_SHADER_TEMPLATES, renderMeshPreview } from 'esengine';
import type { SceneData, InputMapAsset, ActionType, Binding, LocaleTableAsset, PluralCategory, GearValue, GearTween, MaterialAssetData } from 'esengine';
import { modelAddableComponentEntries, subscribeSchemas, getSchemaRevision, boxGroupsFor, isRequiredEmpty, inspectorFields, type BoxGroupDef } from '@/engine/schema';
import { inspectorRegistry, buildContributedSection, isInfoRow } from '@/plugins/inspector';
@@ -1861,6 +1862,35 @@ function TexturePlatformOverrides({ importer, write }: { importer: Record<string
// The asset inspector for every type without a bespoke editor. Renders read-only
// metadata plus, for types with an importer schema, editable Import Settings
// (written to the `.meta` sidecar) through the shared ComponentSection engine.
+/**
+ * A thumbnail of an `.esmesh`, rendered by the engine through the same path the
+ * viewport uses. Without one every mesh an import produced is the same icon —
+ * and a model arrives as several of them.
+ */
+const MESH_PREVIEW_PX = 148;
+
+function MeshPreview({ path }: { path: string }) {
+ const canvasRef = useRef<HTMLCanvasElement>(null);
+ useEffect(() => {
+ let alive = true;
+ void AssetBinding.meshHandle(path).then(async (handle) => {
+ const canvas = canvasRef.current;
+ if (!alive || !handle || !canvas) return;
+ const img = await renderMeshPreview(
+ EngineHost.world?.getWasmModule(), handle, canvas.width, canvas.height);
+ if (alive && img) canvas.getContext('2d')?.putImageData(img, 0, 0);
+ });
+ return () => { alive = false; };
+ }, [path]);
+ return (
+ <div className="cb-prev" style={{ height: MESH_PREVIEW_PX + 12 }}>
+ <div className="pv">
+ <canvas ref={canvasRef} width={MESH_PREVIEW_PX} height={MESH_PREVIEW_PX} />
+ </div>
+ </div>
+ );
+}
+
function GenericAssetInspector({ path }: { path: string }) {
const name = baseName(path);
const type = AssetRegistry.assetTypeAt(path);
@@ -1998,6 +2028,8 @@ function GenericAssetInspector({ path }: { path: string }) {
Import Settings sit above the fold (the reason to open an asset). */}
{type === 'audio' ? (
<AudioWavePreview path={path} />
+ ) : type === 'mesh' ? (
+ <MeshPreview path={path} />
) : isImage && importer && (type === 'texture' || type === 'sprite') ? (
// A texture's preview IS its 9-slice editor: the border is the one
// import setting you cannot sensibly type in, and it writes through
diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.json
index c9d78891a..cd0f516ab 100644
--- a/docs/astro/src/data/apiStability.generated.json
+++ b/docs/astro/src/data/apiStability.generated.json
@@ -3,10 +3,10 @@
"counts": {
"public": 113,
"beta": 62,
- "experimental": 1529,
+ "experimental": 1530,
"deprecated": 3
},
- "total": 1704,
+ "total": 1705,
"subsystems": [
{
"id": "ecs",
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 28bd6c8b0..71ff70d13 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 113 public · 55 beta · 1414 experimental · 3 deprecated
+Symbols: 113 public · 55 beta · 1415 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -10886,6 +10886,11 @@ PrefabsPlugin
(def: FsmDefinition, oldName: string, newName: string): FsmDefinition
```
+## renderMeshPreview — function @experimental
+```
+(module: unknown, mesh: number, w: number, h: number): Promise<ImageData | null>
+```
+
## reparentBtNode — function @experimental
```
(def: BtDefinition, id: string, newParentId: string): BtDefinition
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 3b81913d0..ca1fef750 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index.native
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 113 public · 60 beta · 1433 experimental · 3 deprecated
+Symbols: 113 public · 60 beta · 1434 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -11129,6 +11129,11 @@ PrefabsPlugin
(def: FsmDefinition, oldName: string, newName: string): FsmDefinition
```
+## renderMeshPreview — function @experimental
+```
+(module: unknown, mesh: number, w: number, h: number): Promise<ImageData | null>
+```
+
## reparentBtNode — function @experimental
```
(def: BtDefinition, id: string, newParentId: string): BtDefinition
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 17f23efe3..716326b18 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index.node
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 113 public · 57 beta · 1413 experimental · 3 deprecated
+Symbols: 113 public · 57 beta · 1414 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -10891,6 +10891,11 @@ PrefabsPlugin
(def: FsmDefinition, oldName: string, newName: string): FsmDefinition
```
+## renderMeshPreview — function @experimental
+```
+(module: unknown, mesh: number, w: number, h: number): Promise<ImageData | null>
+```
+
## reparentBtNode — function @experimental
```
(def: BtDefinition, id: string, newParentId: string): BtDefinition
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index aac973d33..de6c4229c 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/minigame
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 113 public · 55 beta · 1434 experimental · 3 deprecated
+Symbols: 113 public · 55 beta · 1435 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -11141,6 +11141,11 @@ PrefabsPlugin
(def: FsmDefinition, oldName: string, newName: string): FsmDefinition
```
+## renderMeshPreview — function @experimental
+```
+(module: unknown, mesh: number, w: number, h: number): Promise<ImageData | null>
+```
+
## reparentBtNode — function @experimental
```
(def: BtDefinition, id: string, newParentId: string): BtDefinition
diff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.md
index 4037f13ab..dd15b8acb 100644
--- a/sdk/etc/wasm.api.md
+++ b/sdk/etc/wasm.api.md
@@ -355,6 +355,7 @@ renderer_pollPreviewReadback: () => number
renderer_pollSnapshotReadback: () => number
renderer_releaseTarget: (handle: number) => void
renderer_renderMaterialPreview: (materialId: number, w: number, h: number) => void
+renderer_renderMeshPreview: (meshId: number, w: number, h: number) => void
renderer_replayToDrawCall: (drawCallIndex: number) => void
renderer_resize: (width: number, height: number) => void
renderer_setClearColor: (r: number, g: number, b: number, a: number) => void
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 3f016fab0..599a1364f 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/wechat
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 113 public · 55 beta · 1424 experimental · 3 deprecated
+Symbols: 113 public · 55 beta · 1425 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -10913,6 +10913,11 @@ PrefabsPlugin
(def: FsmDefinition, oldName: string, newName: string): FsmDefinition
```
+## renderMeshPreview — function @experimental
+```
+(module: unknown, mesh: number, w: number, h: number): Promise<ImageData | null>
+```
+
## reparentBtNode — function @experimental
```
(def: BtDefinition, id: string, newParentId: string): BtDefinition
diff --git a/sdk/src/core-render.ts b/sdk/src/core-render.ts
index 190b77c01..b4b2924b0 100644
--- a/sdk/src/core-render.ts
+++ b/sdk/src/core-render.ts
@@ -88,6 +88,8 @@ export {
type TextureRef,
} from './render/material';
+export { renderMeshPreview } from './render/assetPreview';
+
export {
BUILTIN_SHADER_TEMPLATES,
builtinShaderTemplate,
diff --git a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts b/sdk/src/ecs/bridge/nativeEngineApi.generated.ts
index 50e7e11aa..924069fae 100644
--- a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts
+++ b/sdk/src/ecs/bridge/nativeEngineApi.generated.ts
@@ -65,7 +65,15 @@ export interface NativeEngineApi {
material_setTexture?(materialId: number, name: string, textureHandle: number): void;
material_setUniform?(materialId: number, name: string, arity: number, v0: number, v1: number, v2: number, v3: number): void;
material_undefine?(materialId: number): void;
+ mesh2d_makeAllResident?(registry: unknown): number;
+ mesh2d_makeResident?(registry: unknown, entity: number): number;
mesh2d_setGeometry?(registry: unknown, entity: number, posUvPtr: number, vertexCount: number, colorsPtr: number, indicesPtr: number, indexCount: number): void;
+ mesh2d_setMaterialAll?(registry: unknown, materialId: number): number;
+ mesh2d_setMesh?(registry: unknown, entity: number, meshHandle: number): void;
+ mesh2d_setMeshAll?(registry: unknown, meshHandle: number): number;
+ mesh_create?(posUvPtr: number, vertexCount: number, colorsPtr: number, indicesPtr: number, indexCount: number): number;
+ mesh_createFromChannels?(channelsPtr: number, channelCount: number, vertexStride: number, vertexPtr: number, vertexBytes: number, indexPtr: number, indexCount: number, minX: number, minY: number, minZ: number, maxX: number, maxY: number, maxZ: number): number;
+ mesh_release?(meshHandle: number): void;
particle_getAliveCount?(entity: number): number;
particle_play?(registry: unknown, entity: number): void;
particle_reset?(registry: unknown, entity: number): void;
@@ -143,6 +151,7 @@ export interface NativeEngineApi {
renderer_pollSnapshotReadback?(): number;
renderer_releaseTarget?(handle: number): void;
renderer_renderMaterialPreview?(materialId: number, w: number, h: number): void;
+ renderer_renderMeshPreview?(meshId: number, w: number, h: number): void;
renderer_replayToDrawCall?(drawCallIndex: number): void;
renderer_resize?(width: number, height: number): void;
renderer_setClearColor?(r: number, g: number, b: number, a: number): void;
@@ -170,6 +179,7 @@ export interface NativeEngineApi {
renderer_takeFrameCapture?(handle: number, dest: number, destSize: number): boolean;
renderer_updateTransforms?(registry: unknown): void;
rm_acquireTextureByPath?(rm: unknown, path: string): number;
+ rm_adoptTextureContent?(rm: unknown, target: number, source: number): boolean;
rm_createCompressedTexture?(rm: unknown, width: number, height: number, format: number, dataPtr: number, dataLen: number, mipLevels: number): number;
rm_createLabelAtlasFont?(rm: unknown, textureHandle: number, texWidth: number, texHeight: number, chars: string, charWidth: number, charHeight: number): number;
rm_createShader?(rm: unknown, vertSrc: string, fragSrc: string): number;
@@ -191,6 +201,7 @@ export interface NativeEngineApi {
rm_setTextureBudget?(rm: unknown, bytes: number): void;
rm_setTextureMetadata?(rm: unknown, handleId: number, left: number, right: number, top: number, bottom: number): void;
rm_supportsCompressedFormat?(rm: unknown, format: number): boolean;
+ rm_texturesAwaitingReupload?(rm: unknown): string;
rm_trimTextureCache?(rm: unknown): number;
rm_updateTextureSubregion?(rm: unknown, handleId: number, x: number, y: number, width: number, height: number, pixelsPtr: number, pixelsLen: number): void;
tilemap_advanceAnimations?(entity: number, dtMs: number): void;
@@ -304,7 +315,15 @@ export function createNativeEngineApi(
bind('material_setTexture', 'es_material_setTexture', false);
bind('material_setUniform', 'es_material_setUniform', false);
bind('material_undefine', 'es_material_undefine', false);
+ bind('mesh2d_makeAllResident', 'es_mesh2d_makeAllResident', true);
+ bind('mesh2d_makeResident', 'es_mesh2d_makeResident', true);
bind('mesh2d_setGeometry', 'es_mesh2d_setGeometry', true);
+ bind('mesh2d_setMaterialAll', 'es_mesh2d_setMaterialAll', true);
+ bind('mesh2d_setMesh', 'es_mesh2d_setMesh', true);
+ bind('mesh2d_setMeshAll', 'es_mesh2d_setMeshAll', true);
+ bind('mesh_create', 'es_mesh_create', false);
+ bind('mesh_createFromChannels', 'es_mesh_createFromChannels', false);
+ bind('mesh_release', 'es_mesh_release', false);
bind('particle_getAliveCount', 'es_particle_getAliveCount', false);
bind('particle_play', 'es_particle_play', true);
bind('particle_reset', 'es_particle_reset', true);
@@ -382,6 +401,7 @@ export function createNativeEngineApi(
bind('renderer_pollSnapshotReadback', 'es_renderer_pollSnapshotReadback', false);
bind('renderer_releaseTarget', 'es_renderer_releaseTarget', false);
bind('renderer_renderMaterialPreview', 'es_renderer_renderMaterialPreview', false);
+ bind('renderer_renderMeshPreview', 'es_renderer_renderMeshPreview', false);
bind('renderer_replayToDrawCall', 'es_renderer_replayToDrawCall', false);
bind('renderer_resize', 'es_renderer_resize', false);
bind('renderer_setClearColor', 'es_renderer_setClearColor', false);
@@ -409,6 +429,7 @@ export function createNativeEngineApi(
bind('renderer_takeFrameCapture', 'es_renderer_takeFrameCapture', false);
bind('renderer_updateTransforms', 'es_renderer_updateTransforms', true);
bind('rm_acquireTextureByPath', 'es_rm_acquireTextureByPath', true);
+ bind('rm_adoptTextureContent', 'es_rm_adoptTextureContent', true);
bind('rm_createCompressedTexture', 'es_rm_createCompressedTexture', true);
bind('rm_createLabelAtlasFont', 'es_rm_createLabelAtlasFont', true);
bind('rm_createShader', 'es_rm_createShader', true);
@@ -430,6 +451,7 @@ export function createNativeEngineApi(
bind('rm_setTextureBudget', 'es_rm_setTextureBudget', true);
bind('rm_setTextureMetadata', 'es_rm_setTextureMetadata', true);
bind('rm_supportsCompressedFormat', 'es_rm_supportsCompressedFormat', true);
+ bind('rm_texturesAwaitingReupload', 'es_rm_texturesAwaitingReupload', true);
bind('rm_trimTextureCache', 'es_rm_trimTextureCache', true);
bind('rm_updateTextureSubregion', 'es_rm_updateTextureSubregion', true);
bind('tilemap_advanceAnimations', 'es_tilemap_advanceAnimations', false);
diff --git a/sdk/src/render/assetPreview.ts b/sdk/src/render/assetPreview.ts
new file mode 100644
index 000000000..30a5c1c7c
--- /dev/null
+++ b/sdk/src/render/assetPreview.ts
@@ -0,0 +1,61 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file Offscreen thumbnails of an asset, through the engine's own render path.
+ * A material ball and a mesh differ by ONE call; what follows — readback,
+ * pixels, row flip — is shared, since a second copy of it is a second
+ * place for the row order to be wrong.
+ */
+import type { ESEngineModule } from '../wasm';
+import { awaitReadback, READBACK_READY } from './readback';
+
+/**
+ * The preview slice: one draw entry per asset kind plus the readback. Narrowed from
+ * the wasm module rather than required of every core — the readback pointer has no
+ * native wrapper, so a host without it is checked for at the call.
+ */
+export type PreviewCore = Pick<ESEngineModule,
+ 'renderer_renderMaterialPreview' | 'renderer_renderMeshPreview' | 'renderer_pollPreviewReadback'
+ | 'renderer_getPreviewSize' | 'renderer_getPreviewWidth'
+ | 'renderer_getPreviewHeight' | 'renderer_getPreviewPtr' | 'HEAPU8'>;
+
+/** The connected core, when it answers the preview surface; null otherwise. */
+export function previewCore(m: unknown): PreviewCore | null {
+ const p = m as PreviewCore | null;
+ return typeof p?.renderer_renderMaterialPreview === 'function' ? p : null;
+}
+
+/**
+ * Run @p draw against the offscreen target and resolve with its pixels. The
+ * readback rides the engine's async seam: immediate on GL, resolved when the
+ * staging-buffer map lands on WebGPU — one awaited call either way.
+ */
+export async function drawPreview(m: PreviewCore, draw: () => void): Promise<ImageData | null> {
+ draw();
+ if (await awaitReadback(() => m.renderer_pollPreviewReadback()) !== READBACK_READY) return null;
+ const size = m.renderer_getPreviewSize();
+ const w = m.renderer_getPreviewWidth();
+ const h = m.renderer_getPreviewHeight();
+ if (size === 0 || w === 0 || h === 0) return null;
+ const pixels = new Uint8ClampedArray(m.HEAPU8.buffer, m.renderer_getPreviewPtr(), size);
+ // Readback rows are bottom-up; flip so the thumbnail is upright.
+ const flipped = new Uint8ClampedArray(size);
+ const rowBytes = w * 4;
+ for (let y = 0; y < h; y++) {
+ flipped.set(pixels.subarray(y * rowBytes, (y + 1) * rowBytes), (h - 1 - y) * rowBytes);
+ }
+ return new ImageData(flipped, w, h);
+}
+
+/**
+ * A thumbnail of a loaded `.esmesh`, seen from off-axis and framed to its own
+ * bounds — a mesh is authored at whatever scale its source used, and head-on it
+ * is a silhouette. Null if the engine isn't ready or the mesh isn't loaded.
+ */
+export async function renderMeshPreview(
+ module: unknown, mesh: number, w: number, h: number,
+): Promise<ImageData | null> {
+ const m = previewCore(module);
+ if (!m || typeof m.renderer_renderMeshPreview !== 'function' || !mesh) return null;
+ return drawPreview(m, () => m.renderer_renderMeshPreview(mesh, w, h));
+}
diff --git a/sdk/src/render/material.ts b/sdk/src/render/material.ts
index b143d2677..0def48f1b 100644
--- a/sdk/src/render/material.ts
+++ b/sdk/src/render/material.ts
@@ -10,7 +10,7 @@ import type { EngineApi } from '../ecs/bridge/engineApi';
import type { ESEngineModule } from '../wasm';
import { WasmBridge } from '../wasm/WasmBridge';
import { requireResourceManager } from '../wasm/resourceManager';
-import { awaitReadback, READBACK_READY } from './readback';
+import { drawPreview, previewCore } from './assetPreview';
import type { Vec2, Vec3, Vec4 } from '../types';
import { BlendMode } from './blend';
import { reflectEsshader } from './shaderReflect';
@@ -151,23 +151,6 @@ type MaterialCore = Required<Pick<NonNullable<EngineApi>,
'material_compileEsshader' | 'material_define' | 'material_setUniform'
| 'material_setTexture' | 'material_undefine'>>;
-/**
- * What the material-ball thumbnail additionally needs: the renderer's preview
- * readback plus the module heap it lands in. Editor-only — a device renders no
- * thumbnails, and the readback pointer has no native wrapper — so it is narrowed
- * here (and checked at the call) instead of being required of every core.
- */
-type PreviewCore = MaterialCore & Pick<ESEngineModule,
- 'renderer_renderMaterialPreview' | 'renderer_pollPreviewReadback'
- | 'renderer_getPreviewSize' | 'renderer_getPreviewWidth'
- | 'renderer_getPreviewHeight' | 'renderer_getPreviewPtr' | 'HEAPU8'>;
-
-/** The connected core, when it answers the preview surface; null otherwise. */
-function previewCore(m: MaterialCore | null): PreviewCore | null {
- const p = m as PreviewCore | null;
- return typeof p?.renderer_renderMaterialPreview === 'function' ? p : null;
-}
-
/** Guarded view of the core: after a wasm abort a call throws instead of reaching
* a dead module; a native host's bindings never abort. */
class MaterialBridge extends WasmBridge<NonNullable<EngineApi>> {
@@ -560,23 +543,7 @@ export const Material = {
*/
async renderPreview(material: MaterialHandle, w: number, h: number): Promise<ImageData | null> {
const m = previewCore(module);
- if (!m) return null;
- m.renderer_renderMaterialPreview(material, w, h);
- if (await awaitReadback(() => m.renderer_pollPreviewReadback()) !== READBACK_READY) {
- return null;
- }
- const size = m.renderer_getPreviewSize();
- const pw = m.renderer_getPreviewWidth();
- const ph = m.renderer_getPreviewHeight();
- if (size === 0 || pw === 0 || ph === 0) return null;
- const pixels = new Uint8ClampedArray(m.HEAPU8.buffer, m.renderer_getPreviewPtr(), size);
- // Readback rows are bottom-up; flip so the thumbnail is upright.
- const flipped = new Uint8ClampedArray(size);
- const rowBytes = pw * 4;
- for (let y = 0; y < ph; y++) {
- flipped.set(pixels.subarray(y * rowBytes, (y + 1) * rowBytes), (ph - 1 - y) * rowBytes);
- }
- return new ImageData(flipped, pw, ph);
+ return m ? drawPreview(m, () => m.renderer_renderMaterialPreview(material, w, h)) : null;
},
releaseAll(): void {
diff --git a/sdk/src/wasm.ts b/sdk/src/wasm.ts
index 5987a4ac1..2a064af9e 100644
--- a/sdk/src/wasm.ts
+++ b/sdk/src/wasm.ts
@@ -552,6 +552,7 @@ export interface ESEngineModule {
renderer_getSnapshotWidth(): number;
renderer_getSnapshotHeight(): number;
renderer_renderMaterialPreview(materialId: number, w: number, h: number): void;
+ renderer_renderMeshPreview(meshId: number, w: number, h: number): void;
/** Same 0/1/2 readback contract as renderer_pollSnapshotReadback. */
renderer_pollPreviewReadback(): number;
renderer_getPreviewPtr(): number;
diff --git a/src/esengine/bindings/RendererBindings.cpp b/src/esengine/bindings/RendererBindings.cpp
index 08ddae310..d51d17e05 100644
--- a/src/esengine/bindings/RendererBindings.cpp
+++ b/src/esengine/bindings/RendererBindings.cpp
@@ -1150,6 +1150,61 @@ void renderer_renderMaterialPreview(u32 materialId, i32 w, i32 h) {
g_renderFrame->renderToTarget(reg, vp, static_cast<u32>(w), static_cast<u32>(h));
}
+/**
+ * A thumbnail of a loaded mesh, into the same offscreen target the material
+ * preview uses and by the same route (a throwaway scene through the real collect
+ * path) — so a thumbnail shows what the viewport would. The eye stands off-axis
+ * because a model seen head-on is a silhouette.
+ */
+void renderer_renderMeshPreview(u32 meshId, i32 w, i32 h) {
+ if (!g_renderFrame || w <= 0 || h <= 0) return;
+ auto* rm = ctx().tryGet<resource::ResourceManager>();
+ const Mesh* res = rm ? rm->getMesh(resource::MeshHandle{meshId}) : nullptr;
+ if (!res) return;
+
+ ecs::Registry reg;
+ auto entity = reg.create();
+ reg.emplace<ecs::Transform>(entity);
+ auto& mesh = reg.emplace<ecs::Mesh2D>(entity);
+ mesh.mesh = resource::MeshHandle{meshId};
+ mesh.lit = true;
+ mesh.opaque = true;
+
+ auto light = reg.create();
+ auto& lightTransform = reg.emplace<ecs::Transform>(light);
+ lightTransform.position = glm::vec3(0.0f, 0.0f, 1.0f);
+ reg.emplace<ecs::Light2D>(light).type = static_cast<i32>(ecs::Light2DType::Directional);
+
+ if (g_transformSystem) {
+ esengine::World world{reg, ctx().services(), 0.0f};
+ g_transformSystem->update(world);
+ }
+
+ // Frame the mesh's own bounds: an .esmesh is authored at whatever scale its
+ // source used, so a fixed box would show one model whole and another as a dot.
+ const glm::vec3 centre = (res->localMin + res->localMax) * 0.5f;
+ const f32 radius = std::max(glm::length(res->localMax - res->localMin) * 0.5f, 1e-4f);
+ const glm::vec3 eye = centre + glm::normalize(glm::vec3(0.6f, 0.45f, 1.0f)) * (radius * 4.0f);
+ const glm::mat4 view = glm::lookAt(eye, centre, glm::vec3(0.0f, 1.0f, 0.0f));
+
+ // The box is measured AFTER the turn: a flat model seen off-axis is much
+ // smaller than its diagonal, and framing by the diagonal draws it as a stamp
+ // in the middle of an empty thumbnail.
+ f32 half = 1e-4f;
+ for (i32 corner = 0; corner < 8; ++corner) {
+ const glm::vec3 world{
+ (corner & 1) ? res->localMax.x : res->localMin.x,
+ (corner & 2) ? res->localMax.y : res->localMin.y,
+ (corner & 4) ? res->localMax.z : res->localMin.z,
+ };
+ const glm::vec3 v = glm::vec3(view * glm::vec4(world, 1.0f));
+ half = std::max({half, std::abs(v.x), std::abs(v.y)});
+ }
+ half *= 1.08f;
+ const glm::mat4 proj = glm::ortho(-half, half, -half, half, 0.01f, radius * 8.0f);
+ g_renderFrame->renderToTarget(reg, proj * view, static_cast<u32>(w), static_cast<u32>(h));
+}
+
// Same 0/1/2 contract as renderer_pollSnapshotReadback, for the material preview.
i32 renderer_pollPreviewReadback() {
return g_renderFrame ? g_renderFrame->pollPreviewReadback() : 2;
diff --git a/src/esengine/bindings/RendererBindings.hpp b/src/esengine/bindings/RendererBindings.hpp
index bb0e2d847..566ac7902 100644
--- a/src/esengine/bindings/RendererBindings.hpp
+++ b/src/esengine/bindings/RendererBindings.hpp
@@ -181,6 +181,7 @@ u32 renderer_getSnapshotWidth();
u32 renderer_getSnapshotHeight();
void renderer_renderMaterialPreview(u32 materialId, i32 w, i32 h);
+void renderer_renderMeshPreview(u32 meshId, i32 w, i32 h);
i32 renderer_pollPreviewReadback();
uintptr_t renderer_getPreviewPtr();
u32 renderer_getPreviewSize();
diff --git a/src/esengine/bindings/WebSDKEntry.cpp b/src/esengine/bindings/WebSDKEntry.cpp
index 348f00de3..4169099c6 100644
--- a/src/esengine/bindings/WebSDKEntry.cpp
+++ b/src/esengine/bindings/WebSDKEntry.cpp
@@ -727,6 +727,7 @@ EMSCRIPTEN_BINDINGS(esengine_renderer) {
emscripten::function("renderer_getSnapshotWidth", &esengine::renderer_getSnapshotWidth);
emscripten::function("renderer_getSnapshotHeight", &esengine::renderer_getSnapshotHeight);
emscripten::function("renderer_renderMaterialPreview", &esengine::renderer_renderMaterialPreview);
+ emscripten::function("renderer_renderMeshPreview", &esengine::renderer_renderMeshPreview);
emscripten::function("renderer_pollPreviewReadback", &esengine::renderer_pollPreviewReadback);
emscripten::function("renderer_getPreviewPtr", &esengine::renderer_getPreviewPtr);
emscripten::function("renderer_getPreviewSize", &esengine::renderer_getPreviewSize);
diff --git a/tools/check-render-scenes.mjs b/tools/check-render-scenes.mjs
index 6d226c949..f9f86cb3a 100644
--- a/tools/check-render-scenes.mjs
+++ b/tools/check-render-scenes.mjs
@@ -42,7 +42,8 @@ for (const s of SCENES) {
// renders anything at all. Allowed, as a sentence — the same bargain the
// golden corpus strikes with parityGap.
const asserts = s.env.ESTELLA_VERIFY_EXPECT || s.env.ESTELLA_VERIFY_GRID || s.env.ESTELLA_VERIFY_PREVIEW
- || s.env.ESTELLA_VERIFY_DEPTH_LAYERS || s.env.ESTELLA_VERIFY_YSORT || s.id === 'sprite-default';
+ || s.env.ESTELLA_VERIFY_MESH_PREVIEW || s.env.ESTELLA_VERIFY_DEPTH_LAYERS
+ || s.env.ESTELLA_VERIFY_YSORT || s.id === 'sprite-default';
if (!asserts && !s.rendersOnly) {
fail(`"${s.id}" asserts nothing — give it an ESTELLA_VERIFY_EXPECT, or say in rendersOnly why it has none`);
}
diff --git a/tools/renderScenes.mjs b/tools/renderScenes.mjs
index 3ba6b22a6..aca5419ac 100644
--- a/tools/renderScenes.mjs
+++ b/tools/renderScenes.mjs
@@ -144,6 +144,10 @@ export const SCENES = [
// an imported model like a sprite — a wrong picture, not a missing one. Red
// tint, so the engine's own mesh shader (white) cannot pass for it.
{ id: "mesh-builtin-lit", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_MESH_ASSET: "/scenes/lit-triangles.esmesh", ESTELLA_VERIFY_MESH_MATERIAL: "/scenes/mesh-material-lit/builtinlit.esmaterial", ESTELLA_VERIFY_SCENE: "/scenes/mesh-lit.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/mesh-lit.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "4", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.30,\"y\":0.556,\"rgb\":[255,0,0],\"tol\":40},{\"x\":0.70,\"y\":0.556,\"rgb\":[0,0,0],\"tol\":40}]" } },
+ // A thumbnail of the geometry itself, offscreen through the viewport's own
+ // path. What it adds over a material ball is the FRAMING: the gate asks for a
+ // clear border (nothing escaped) and an outer eighth reached (nothing shrank).
+ { id: "mesh-preview", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_MESH_PREVIEW: "{\"w\":128,\"h\":128}", ESTELLA_VERIFY_MESH_ASSET: "/scenes/lit-triangles.esmesh", ESTELLA_VERIFY_SCENE: "/scenes/mesh-lit.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/mesh-lit.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "4" } },
// A mesh assigned IN THE EDITOR: a cold ref reaches the World only through the
// live loader + re-projection. The quad covers the gap between the scene's own
// two triangles, so the frame says which geometry is drawn — and the hit test