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 can be dropped into a scene
esenginecde89149dd73
diff --git a/desktop/src/engine/entitySources.ts b/desktop/src/engine/entitySources.tsindex 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: numberreturn 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 UVdiff --git a/desktop/src/engine/meshSummary.ts b/desktop/src/engine/meshSummary.tsindex 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.tsxindex 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.tsindex caf1130a9..58595fed5 100644--- a/desktop/src/project/ProjectStore.ts+++ b/desktop/src/project/ProjectStore.ts@@ -27,7 +27,8 @@ import { expandScenePrefabs, collapseScenePrefabs } from '@/engine/PrefabInstancimport { 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.tsindex 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.tsindex 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 columnchannels: '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.mdxindex 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 & projectiondiff --git a/docs/astro/src/content/docs/world/tilemaps.mdx b/docs/astro/src/content/docs/world/tilemaps.mdxindex 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.mdxindex 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.mdxindex 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` | 图集图册的行数。 |