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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
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.mjsindex 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.tsindex 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, thendiff --git a/desktop/src/engine/EditorControlSurface.ts b/desktop/src/engine/EditorControlSurface.tsindex 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.tsxindex 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 throughdiff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.jsonindex 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.mdindex 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): BtDefinitiondiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 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): BtDefinitiondiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 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): BtDefinitiondiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 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): BtDefinitiondiff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.mdindex 4037f13ab..dd15b8acb 100644--- a/sdk/etc/wasm.api.md+++ b/sdk/etc/wasm.api.md@@ -355,6 +355,7 @@ renderer_pollPreviewReadback: () => numberrenderer_pollSnapshotReadback: () => numberrenderer_releaseTarget: (handle: number) => voidrenderer_renderMaterialPreview: (materialId: number, w: number, h: number) => void+renderer_renderMeshPreview: (meshId: number, w: number, h: number) => voidrenderer_replayToDrawCall: (drawCallIndex: number) => voidrenderer_resize: (width: number, height: number) => voidrenderer_setClearColor: (r: number, g: number, b: number, a: number) => voiddiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 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): BtDefinitiondiff --git a/sdk/src/core-render.ts b/sdk/src/core-render.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.cppindex 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.hppindex 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.cppindex 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.mjsindex 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.mjsindex 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