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 can be dropped into a scene

esenginecde89149dd73
diff --git a/desktop/src/engine/entitySources.ts b/desktop/src/engine/entitySources.ts
index 363512a84..00b070150 100644
--- a/desktop/src/engine/entitySources.ts
+++ b/desktop/src/engine/entitySources.ts
@@ -109,6 +109,15 @@ export function spritePrefab(name: string, textureRef: string, size: { x: number
return preset(name, [['Transform', {}], ['Sprite', { texture: textureRef, size: { x: size.x, y: size.y } }]]);
}
+/**
+ * A Transform + Mesh2D prefab referencing a `.esmesh`. `lit` follows the file:
+ * geometry carrying normals was authored to be shaded, which is the same call
+ * the model import makes when it writes a prefab of its own.
+ */
+export function meshPrefab(name: string, meshRef: string, lit: boolean): PrefabData {
+ return preset(name, [['Transform', {}], ['Mesh2D', { mesh: meshRef, lit }]]);
+}
+
/**
* A Transform + Sprite + SpriteAnimator prefab referencing a `.esanim` clip.
* The Sprite is seeded with the clip's static pose (sheet texture + frame-0 UV
diff --git a/desktop/src/engine/meshSummary.ts b/desktop/src/engine/meshSummary.ts
index 62a92fd9e..267f4174f 100644
--- a/desktop/src/engine/meshSummary.ts
+++ b/desktop/src/engine/meshSummary.ts
@@ -18,6 +18,8 @@ export interface MeshSummary {
extent: string;
/** The channels the file declares, in its own order: `position, uv, normal`. */
channels: string;
+ /** Whether it carries normals — geometry authored to be shaded. */
+ hasNormals: boolean;
}
const CHANNEL_NAMES: Record<number, string> = {
@@ -50,6 +52,7 @@ export function summarizeMesh(bytes: Uint8Array): MeshSummary | null {
channels: mesh.channels
.map((c) => CHANNEL_NAMES[c.semantic] ?? `#${c.semantic}`)
.join(', '),
+ hasNormals: mesh.channels.some((c) => c.semantic === MeshChannel.Normal),
};
}
diff --git a/desktop/src/panels/Viewport.tsx b/desktop/src/panels/Viewport.tsx
index 2943776e7..344145fb7 100644
--- a/desktop/src/panels/Viewport.tsx
+++ b/desktop/src/panels/Viewport.tsx
@@ -2234,6 +2234,9 @@ export function Viewport() {
} else if (IMAGE_RE.test(path)) {
e.preventDefault();
void ProjectStore.instantiateSpriteFromPath(path, wp ?? { x: 0, y: 0 });
+ } else if (path.toLowerCase().endsWith('.esmesh')) {
+ e.preventDefault();
+ void ProjectStore.instantiateMeshFromPath(path, wp ?? { x: 0, y: 0 });
} else if (path.toLowerCase().endsWith('.estileset')) {
e.preventDefault();
// A tileset spawns a paintable TilemapLayer, which wires its own placement + painter.
diff --git a/desktop/src/project/ProjectStore.ts b/desktop/src/project/ProjectStore.ts
index caf1130a9..58595fed5 100644
--- a/desktop/src/project/ProjectStore.ts
+++ b/desktop/src/project/ProjectStore.ts
@@ -27,7 +27,8 @@ import { expandScenePrefabs, collapseScenePrefabs } from '@/engine/PrefabInstanc
import { discoverSceneAssets } from 'esengine';
import { SceneCommands } from '@/engine/SceneCommands';
import { Boxes } from 'lucide-react';
-import { spritePrefab, sourceById, type EntitySource } from '@/engine/entitySources';
+import { spritePrefab, meshPrefab, sourceById, type EntitySource } from '@/engine/entitySources';
+import { readMeshSummary } from '@/engine/meshSummary';
import { setCanvasDesignSeed, setProjectCameraFit, setProjectPrefabSources, setProjectSortingLayerModes } from '@/engine/projectSeams';
import { needsUIHost, hostPrefab, authoredEntities, type DocumentEntity } from '@/engine/prefabEnvironment';
import { setPrefabBaseResolver } from '@/engine/SceneQuery';
@@ -1230,6 +1231,23 @@ class ProjectStoreImpl {
* and add a Transform + Sprite at the drop point. Returns the source id, or null if
* the path isn't a tracked texture. One undoable step; the new entity is selected.
*/
+ /**
+ * Drop a `.esmesh` into the scene: a Transform + Mesh2D pointing at it, lit if
+ * the file carries normals. A mesh is a first-class asset — it has a slot, a
+ * thumbnail and an inspector — and this is the door the other four asset kinds
+ * already had.
+ */
+ async instantiateMeshFromPath(path: string, position: { x: number; y: number }): Promise<number | null> {
+ const ref = await AssetRegistry.assetRefForPath(path, 'mesh');
+ if (!ref) return null;
+ const summary = await readMeshSummary(path);
+ const name = (path.split('/').pop() ?? 'Mesh').replace(/\.[^.]+$/, '') || 'Mesh';
+ const id = SceneCommands.create(meshPrefab(name, ref, summary?.hasNormals ?? false),
+ { parent: null, position });
+ if (id != null) useSelection.getState().select(id);
+ return id;
+ }
+
async instantiateSpriteFromPath(path: string, position: { x: number; y: number }): Promise<number | null> {
const ref = await AssetRegistry.assetRefForPath(path, 'texture');
if (!ref) return null;
diff --git a/desktop/tests/add-sprite-entity.test.ts b/desktop/tests/add-sprite-entity.test.ts
index 84433f648..253840517 100644
--- a/desktop/tests/add-sprite-entity.test.ts
+++ b/desktop/tests/add-sprite-entity.test.ts
@@ -12,7 +12,7 @@ import type { SceneData } from 'esengine';
import { SceneModelImpl } from '@/engine/SceneModel';
import { EditorHistoryImpl } from '@/engine/EditorHistory';
import { SceneCommandsImpl } from '@/engine/SceneCommands';
-import { spritePrefab } from '@/engine/entitySources';
+import { spritePrefab, meshPrefab } from '@/engine/entitySources';
const emptyScene = (): SceneData =>
({ version: '1.0', name: 't', entities: [] } as unknown as SceneData);
@@ -53,3 +53,32 @@ describe('sprite creation (spritePrefab + SceneCommands.create)', () => {
expect(history.canUndo()).toBe(false);
});
});
+
+describe('mesh creation (meshPrefab + SceneCommands.create)', () => {
+ let model: SceneModelImpl;
+ let cmds: SceneCommandsImpl;
+
+ beforeEach(() => {
+ model = new SceneModelImpl();
+ cmds = new SceneCommandsImpl(model, new EditorHistoryImpl());
+ model.adopt(emptyScene(), new Map());
+ });
+
+ const mesh2d = (lit: boolean) => {
+ const id = cmds.create(meshPrefab('banner', '@uuid:m1', lit),
+ { parent: null, position: { x: 10, y: 20 } })!;
+ return model.entityBySource(id)!.components.find((c) => c.type === 'Mesh2D')!.data as
+ Record<string, unknown>;
+ };
+
+ it('points a Mesh2D at the dropped file', () => {
+ expect(mesh2d(false).mesh).toBe('@uuid:m1');
+ });
+
+ it('lights geometry that carries normals, and leaves the rest alone', () => {
+ // The same call the model import makes: normals mean it was authored to be
+ // shaded, and geometry without them lands unlit.
+ expect(mesh2d(true).lit).toBe(true);
+ expect(mesh2d(false).lit).toBe(false);
+ });
+});
diff --git a/desktop/tests/mesh-summary.test.ts b/desktop/tests/mesh-summary.test.ts
index 81d905abc..4b40cbf26 100644
--- a/desktop/tests/mesh-summary.test.ts
+++ b/desktop/tests/mesh-summary.test.ts
@@ -38,11 +38,15 @@ describe('summarizeMesh', () => {
triangles: 2,
extent: '200 × 100', // flat: the depth is not a dimension worth a column
channels: 'position, uv, color, normal',
+ hasNormals: true,
});
});
it('says which channels are absent by not naming them', () => {
- expect(summarizeMesh(quad(false))?.channels).toBe('position, uv, color');
+ const flat = summarizeMesh(quad(false));
+ expect(flat?.channels).toBe('position, uv, color');
+ // What a drop into the viewport reads to decide whether to light it.
+ expect(flat?.hasNormals).toBe(false);
});
it('reports depth when the geometry has some', () => {
diff --git a/docs/astro/src/content/docs/graphics/camera.mdx b/docs/astro/src/content/docs/graphics/camera.mdx
index 074186ba7..6a83a4b98 100644
--- a/docs/astro/src/content/docs/graphics/camera.mdx
+++ b/docs/astro/src/content/docs/graphics/camera.mdx
@@ -61,7 +61,7 @@ the camera by moving its entity's `Transform`.
| `viewport` | Vec4 | `{0,0,1,1}` | Screen rect `x, y, w, h` in 0–1 (split-screen / PiP). |
| `clearFlags` | `ClearFlags` | `ColorAndDepth` | What to clear first: `Nothing` / `Color` / `Depth` / `ColorAndDepth`. |
| `pixelPerfect` | boolean | `false` | Snap to the world pixel grid for crisp pixel art (Orthographic). |
-| `showFrustum` | boolean | `false` | Editor-only: draw the camera's frustum gizmo. |
+| `showFrustum` | boolean | `false` | Editor-only: draw this camera's whole view volume, near face to far. Off, its gizmo outlines what it frames on the content plane — which is empty for a camera aimed away from it. |
## Zoom & projection
diff --git a/docs/astro/src/content/docs/world/tilemaps.mdx b/docs/astro/src/content/docs/world/tilemaps.mdx
index c807f0502..7c4b6dd5d 100644
--- a/docs/astro/src/content/docs/world/tilemaps.mdx
+++ b/docs/astro/src/content/docs/world/tilemaps.mdx
@@ -133,7 +133,7 @@ renderer reads these live, so animating `tintColor` / `opacity` is lag-free.
| Property | Type | Default | Description |
|---|---|---|---|
| `cellSize` | Vec2 | `{32, 32}` | Tile size in world units. |
-| `originOffset` | Vec2 | `{0, 0}` | Layer origin offset. |
+| `originOffset` | Vec2 | `{0, 0}` | Shifts the layer's grid, in world units. Applied per frame beside the layer's parallax, so dragging it moves the tiles at once and rebuilds no chunk. |
| `tileset` | asset | none | Tileset texture (single-tileset layers). |
| `tilesetColumns` | number | `1` | Columns in the tileset atlas. |
| `tilesetRows` | number | `1` | Rows in the tileset atlas. |
diff --git a/docs/astro/src/content/docs/zh-cn/graphics/camera.mdx b/docs/astro/src/content/docs/zh-cn/graphics/camera.mdx
index acdfd8282..a2107756a 100644
--- a/docs/astro/src/content/docs/zh-cn/graphics/camera.mdx
+++ b/docs/astro/src/content/docs/zh-cn/graphics/camera.mdx
@@ -56,7 +56,7 @@ SDK 默认值为 2D 调好(正交、活动、`orthoSize` 540)。移动相机就
| `viewport` | Vec4 | `{0,0,1,1}` | 屏幕矩形 `x, y, w, h`(0–1,分屏/画中画)。 |
| `clearFlags` | `ClearFlags` | `ColorAndDepth` | 渲染前清什么:`Nothing` / `Color` / `Depth` / `ColorAndDepth`。 |
| `pixelPerfect` | boolean | `false` | 吸附到世界像素网格,让像素画清晰(正交)。 |
-| `showFrustum` | boolean | `false` | 仅编辑器:绘制相机的视锥 gizmo。 |
+| `showFrustum` | boolean | `false` | 仅编辑器:画出这台相机的整个视锥体(近面到远面)。关闭时 gizmo 只勾出它在内容平面上取景的范围——相机朝向别处时那里是空的。 |
## 缩放与投影
diff --git a/docs/astro/src/content/docs/zh-cn/world/tilemaps.mdx b/docs/astro/src/content/docs/zh-cn/world/tilemaps.mdx
index 646477b83..c8d909ed0 100644
--- a/docs/astro/src/content/docs/zh-cn/world/tilemaps.mdx
+++ b/docs/astro/src/content/docs/zh-cn/world/tilemaps.mdx
@@ -119,7 +119,7 @@ const loadLevel = defineSystem([Commands()], (cmds) => {
| 属性 | 类型 | 默认 | 说明 |
|---|---|---|---|
| `cellSize` | Vec2 | `{32, 32}` | 瓦片尺寸(世界单位)。 |
-| `originOffset` | Vec2 | `{0, 0}` | 图层原点偏移。 |
+| `originOffset` | Vec2 | `{0, 0}` | 图层网格的偏移(世界单位)。与图层视差在同一处逐帧应用,所以拖动它当场移动 tile,且不会重建任何 chunk。 |
| `tileset` | asset | 无 | 图集纹理(单图集图层)。 |
| `tilesetColumns` | number | `1` | 图集图册的列数。 |
| `tilesetRows` | number | `1` | 图集图册的行数。 |