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(render): Mesh2D — scene-level mesh renderer on the unified command face

yhhdf09ccae1a1b
diff --git a/CMakeLists.txt b/CMakeLists.txt
index 9c9afc199..36d57f714 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -67,6 +67,7 @@ set(ESENGINE_SOURCES
src/esengine/renderer/plugins/UIElementPlugin.cpp
src/esengine/renderer/plugins/TextPlugin.cpp
src/esengine/renderer/plugins/ShapePlugin.cpp
+ src/esengine/renderer/plugins/MeshPlugin.cpp
src/esengine/platform/PathResolver.cpp
src/esengine/animation/TweenSystem.cpp
src/esengine/ecs/UILayoutSystem.cpp
diff --git a/desktop/package.json b/desktop/package.json
index 8a4960a04..444a6511a 100644
--- a/desktop/package.json
+++ b/desktop/package.json
@@ -54,6 +54,7 @@
"mcp": "electron electron/mcp/server.mjs",
"mcp:smoke": "vite build && node electron/mcp/smoke.mjs",
"verify:render:tilemap:hex": "vite build && ESTELLA_VERIFY_SCENE=/scenes/tilemap-hex.esscene ESTELLA_VERIFY_MANIFEST=/scenes/tilemap-hex.textures.json ESTELLA_VERIFY_W=256 ESTELLA_VERIFY_H=256 ESTELLA_VERIFY_STEPS=6 ESTELLA_VERIFY_EXPECT=\"[{\\\"x\\\":0.40,\\\"y\\\":0.40,\\\"rgb\\\":[255,0,0]},{\\\"x\\\":0.60,\\\"y\\\":0.40,\\\"rgb\\\":[0,255,0]},{\\\"x\\\":0.50,\\\"y\\\":0.55,\\\"rgb\\\":[0,0,255]},{\\\"x\\\":0.70,\\\"y\\\":0.55,\\\"rgb\\\":[255,255,0]}]\" electron scripts/headless-verify.mjs",
+ "verify:render:mesh2d": "vite build && ESTELLA_VERIFY_SCENE=/scenes/mesh2d.esscene ESTELLA_VERIFY_MANIFEST=/scenes/mesh2d.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,255,0],\"tol\":40},{\"x\":0.30,\"y\":0.40,\"rgb\":[255,0,0],\"tol\":40}]' electron scripts/headless-verify.mjs",
"verify:render:parallax:shape": "vite build && ESTELLA_VERIFY_SCENE=/scenes/parallax-shape.esscene ESTELLA_VERIFY_MANIFEST=/scenes/parallax-shape.textures.json ESTELLA_VERIFY_STEPS=4 ESTELLA_VERIFY_EXPECT=\"[{\\\"x\\\":0.5,\\\"y\\\":0.5,\\\"rgb\\\":[0,255,0],\\\"tol\\\":40},{\\\"x\\\":0.25,\\\"y\\\":0.5,\\\"rgb\\\":[255,0,0],\\\"tol\\\":40}]\" electron scripts/headless-verify.mjs",
"verify:render:postprocess:lut": "vite build && ESTELLA_VERIFY_PLAY=1 ESTELLA_VERIFY_SCENE=/scenes/lut-grade.esscene ESTELLA_VERIFY_MANIFEST=/scenes/lut-grade.textures.json ESTELLA_VERIFY_W=256 ESTELLA_VERIFY_H=256 ESTELLA_VERIFY_STEPS=10 ESTELLA_VERIFY_EXPECT=\"[{\\\"x\\\":0.292,\\\"y\\\":0.5,\\\"rgb\\\":[0,0,255],\\\"tol\\\":40},{\\\"x\\\":0.708,\\\"y\\\":0.5,\\\"rgb\\\":[255,0,0],\\\"tol\\\":40}]\" electron scripts/headless-verify.mjs"
},
diff --git a/desktop/public/scenes/mesh2d.esscene b/desktop/public/scenes/mesh2d.esscene
new file mode 100644
index 000000000..4ae54125a
--- /dev/null
+++ b/desktop/public/scenes/mesh2d.esscene
@@ -0,0 +1,40 @@
+{
+ "version": "1.0",
+ "name": "Mesh2D",
+ "entities": [
+ {
+ "id": 0,
+ "name": "Camera",
+ "parent": null,
+ "children": [],
+ "components": [
+ { "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": 10 } } },
+ { "type": "Camera", "data": { "projectionType": 1, "orthoSize": 300, "isActive": true, "priority": 0 } }
+ ],
+ "visible": true
+ },
+ {
+ "id": 1,
+ "name": "TwoTriangles",
+ "parent": null,
+ "children": [],
+ "components": [
+ { "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": 0 } } },
+ {
+ "type": "Mesh2D",
+ "data": {
+ "color": { "r": 1, "g": 1, "b": 1, "a": 1 },
+ "layer": 0,
+ "enabled": true,
+ "geometry": {
+ "positions": [-200, -100, -40, -100, -120, 100, 40, -100, 200, -100, 120, 100],
+ "colors": [1, 0, 0, 1, 1, 0, 0, 1, 1, 0, 0, 1, 0, 1, 0, 1, 0, 1, 0, 1, 0, 1, 0, 1],
+ "indices": [0, 1, 2, 3, 4, 5]
+ }
+ }
+ }
+ ],
+ "visible": true
+ }
+ ]
+}
diff --git a/desktop/public/scenes/mesh2d.textures.json b/desktop/public/scenes/mesh2d.textures.json
new file mode 100644
index 000000000..0967ef424
--- /dev/null
+++ b/desktop/public/scenes/mesh2d.textures.json
@@ -0,0 +1 @@
+{}
diff --git a/docs/REARCHITECTURE.md b/docs/REARCHITECTURE.md
index 89c593660..e985314fb 100644
--- a/docs/REARCHITECTURE.md
+++ b/docs/REARCHITECTURE.md
@@ -174,6 +174,7 @@ RC5"渲染唯一路径"的收官:所有 Renderer 只**生成命令**,Sort/Me
- **共享 collect 前奏**:`CameraWorldRect` 由 `RenderFrame::collectAll` 每次 collect 计算一次进 `RenderCollectContext`(此前 Sprite/Shape/Text/Tilemap 四个 plugin 各自求逆 VP 推相机中心/边界);`parallaxedWorldPosition()` helper(RenderTypePlugin.hpp)收拢 ensureDecomposed + 视差偏移 + "cull 于绘制处"约定。
- **刻意保留的两条即时模式边界**(非场景命令流,不进 DrawList 是语义选择而非欠账):`ImmediateDraw`(编辑器/调试叠加,自带 flush 时序)与 `draw_mesh` 自定义网格(在 TS 自定义绘制回调期内即时执行,依赖 pre-scene/post-flush 顺序语义)。
- 验证:新增 `tests/renderer/test_batch_builder.cpp`(8 用例 43 断言:各流 baseVertex 步长、纹理槽规则、实例化命令组装、多纹理合并 + texIndex 重写、跨流不合并、clip 盖章、execute 分发);六套 MockGfxDevice harness、web 构建、11 个 headless 像素场景(sprite / parallax-shape / text-sdf / 粒子×2 / tilemap×2 / ui-mask / lit×2 / postprocess)全 PASS;双 boundary guard 绿。
+- **承诺实测 — Mesh2D 场景级 renderer(2026-07-07 第二批)**:`RenderType::Mesh` 从"仅统计枚举"变成真渲染类型。`Mesh2D` 组件(EHT 注解字段 + **未注解的变长几何 payload 置尾**——变长数据无固定 ABI 偏移,天然不进指针布局/断言);几何经唯一入口 `mesh2d_setGeometry` 上传(索引越界整体拒绝 + AABB 计算);`MeshPlugin` 全部内容 = 共享前奏 + SpritePlugin 同款材质/lit 解析 + CPU 仿射变换 + `appendIndexedBatch`——**零底层改动**,网格自动获得排序/裁剪/clip/多纹理合并/Lit2D。SDK:`Mesh2DAPI`(withScratch 批量上传)+ 场景 out-of-band codec(`geometry` 字段随 .esscene 声明式携带,particle 渐变同模式)。刻意不做:GPU 驻留网格(2D 网格顶点量小,CPU 流式与 sprite/tilemap 同模型;大网格属未来 3D 议题)。验证:mesh2d headless 场景(双三角逐顶点色,3 像素断言)一次过 + 回归 5 场景 + SDK/desktop 双侧 tsc + 全套测试 + 24 examples + 双 guard 全绿。
### 地基收口(Foundation Consolidation)— 🟡 进行中,RC6 前置(设计文档)
见 [`REARCH_FOUNDATION_CONSOLIDATION.md`](./REARCH_FOUNDATION_CONSOLIDATION.md):
diff --git a/sdk/src/component.generated.ts b/sdk/src/component.generated.ts
index 60ff93368..e13690b6b 100644
--- a/sdk/src/component.generated.ts
+++ b/sdk/src/component.generated.ts
@@ -15,7 +15,7 @@ import type { Dimension, Padding, VisualState } from './wasm.generated';
* getAbiLayoutHash(); BuiltinBridge.connect() compares them and refuses to
* run on mismatch, because mismatched offsets read the wrong heap bytes.
*/
-export const ABI_LAYOUT_HASH = '4a0ed8f94ca2aed4';
+export const ABI_LAYOUT_HASH = '89e3ae10e24e8bc9';
export interface AssetFieldMeta {
field: string;
@@ -244,6 +244,28 @@ export const COMPONENT_META: Record<string, ComponentMetaEntry> = {
shadowDistance: { min: 0, tooltip: "Directional shadow distance; 0 = no directional shadow.", advanced: true },
},
},
+ Mesh2D: {
+ defaults: {
+ texture: 0,
+ color: { r: 1, g: 1, b: 1, a: 1 },
+ layer: 0,
+ lit: false,
+ parallax: { x: 1, y: 1 },
+ material: 0,
+ enabled: true,
+ },
+ assetFields: [{ field: 'texture', type: 'texture' as AssetFieldType }, { field: 'material', type: 'material' as AssetFieldType }],
+ entityFields: [],
+ colorFields: ['color'],
+ animatableFields: ['color.r', 'color.g', 'color.b', 'color.a'],
+ fields: {
+ color: { tooltip: "Tint multiplied into the vertex colors (white = unchanged)." },
+ layer: { step: 1, tooltip: "Sorting layer — controls draw order across renderables.", enumSource: "sortingLayers" },
+ lit: { tooltip: "Receive 2D lights: Light2D entities light this mesh (flat normal). A custom material overrides this." },
+ parallax: { tooltip: "Parallax scroll factor (1 = with world, <1 = slower, 0 = locked to camera).", advanced: true },
+ material: { advanced: true },
+ },
+ },
Parent: {
defaults: {
entity: 0,
@@ -745,6 +767,16 @@ export interface Light2DData {
enabled: boolean;
}
+export interface Mesh2DData {
+ texture: number;
+ color: Color;
+ layer: number;
+ lit: boolean;
+ parallax: Vec2;
+ material: number;
+ enabled: boolean;
+}
+
export interface ParentData {
entity: Entity;
}
diff --git a/sdk/src/component.ts b/sdk/src/component.ts
index 15bbe561e..1f3b7aa91 100644
--- a/sdk/src/component.ts
+++ b/sdk/src/component.ts
@@ -16,6 +16,7 @@ import type {
CanvasData, VelocityData, ParentData, ChildrenData, SpineAnimationData,
TilemapLayerData, BitmapTextData,
CameraData as CameraDataCpp, ParticleEmitterData as ParticleEmitterDataCpp,
+ Mesh2DData as Mesh2DDataCpp,
} from './component.generated';
// Builtin enums whose values come from C++ ES_ENUMs — imported from the generated
// module (single source) and re-exported below, so a TS const cannot drift from the
@@ -681,6 +682,31 @@ export const SpineAnimation = defineBuiltin<SpineAnimationData>('SpineAnimation'
metaDefaults<SpineAnimationData>('SpineAnimation')
);
+/**
+ * Local-space geometry of a Mesh2D renderable (triangle list, indexed).
+ * `positions` is x,y pairs; `uvs` is u,v pairs (default 0,0); `colors` is r,g,b,a
+ * floats (0-1) per vertex (default white). Uploaded via mesh2d_setGeometry, which
+ * validates indices engine-side.
+ */
+export interface Mesh2DGeometry {
+ positions: number[];
+ uvs?: number[];
+ colors?: number[];
+ indices: number[];
+}
+
+// Mesh2D = the generated C++ field shape + one out-of-band TS-only field: the
+// variable-size geometry payload has no fixed ABI offset, so it never crosses as a
+// component field — it is uploaded through mesh2d_setGeometry (see mesh2dPlugin's
+// scene codec).
+export interface Mesh2DData extends Mesh2DDataCpp {
+ geometry: Mesh2DGeometry;
+}
+
+export const Mesh2D = defineBuiltin<Mesh2DData>('Mesh2D',
+ metaDefaults<Mesh2DData>('Mesh2D', { geometry: { positions: [], indices: [] } })
+);
+
export const TilemapLayer = defineBuiltin<TilemapLayerData>('TilemapLayer',
metaDefaults<TilemapLayerData>('TilemapLayer'),
{
diff --git a/sdk/src/core-content.ts b/sdk/src/core-content.ts
index ee4a1760f..6f507b56a 100644
--- a/sdk/src/core-content.ts
+++ b/sdk/src/core-content.ts
@@ -303,6 +303,17 @@ export {
particlePlugin,
} from './particle';
+// =============================================================================
+// Mesh2D
+// =============================================================================
+
+export {
+ Mesh2DAPI,
+ Meshes2D,
+ Mesh2DPlugin,
+ mesh2dPlugin,
+} from './mesh2d';
+
// =============================================================================
// Tilemap
// =============================================================================
diff --git a/sdk/src/ecs/ptrAccessors.generated.ts b/sdk/src/ecs/ptrAccessors.generated.ts
index 4cf8b7a29..b8f2a03b3 100644
--- a/sdk/src/ecs/ptrAccessors.generated.ts
+++ b/sdk/src/ecs/ptrAccessors.generated.ts
@@ -473,6 +473,54 @@ export function createLight2DData(): Light2DPtrData {
};
}
+export interface Mesh2DPtrData {
+ texture: number;
+ color: Color;
+ layer: number;
+ lit: boolean;
+ parallax: Vec2;
+ material: number;
+ enabled: boolean;
+}
+
+export function fillMesh2D(
+ f32: Float32Array, u32: Uint32Array, u8: Uint8Array,
+ ptr: number, out: Mesh2DPtrData,
+): void {
+ out.texture = u32[ptr >> 2];
+ const color_ = out.color; color_.r = f32[(ptr + 4) >> 2]; color_.g = f32[((ptr + 4) >> 2) + 1]; color_.b = f32[((ptr + 4) >> 2) + 2]; color_.a = f32[((ptr + 4) >> 2) + 3];
+ out.layer = u32[(ptr + 20) >> 2] | 0;
+ out.lit = u8[ptr + 24] !== 0;
+ const parallax_ = out.parallax; parallax_.x = f32[(ptr + 28) >> 2]; parallax_.y = f32[((ptr + 28) >> 2) + 1];
+ out.material = u32[(ptr + 36) >> 2];
+ out.enabled = u8[ptr + 40] !== 0;
+}
+
+export function writeMesh2D(
+ f32: Float32Array, u32: Uint32Array, u8: Uint8Array,
+ ptr: number, data: Mesh2DPtrData,
+): void {
+ u32[ptr >> 2] = data.texture;
+ f32[(ptr + 4) >> 2] = data.color.r; f32[((ptr + 4) >> 2) + 1] = data.color.g; f32[((ptr + 4) >> 2) + 2] = data.color.b; f32[((ptr + 4) >> 2) + 3] = data.color.a;
+ u32[(ptr + 20) >> 2] = data.layer | 0;
+ u8[ptr + 24] = data.lit ? 1 : 0;
+ f32[(ptr + 28) >> 2] = data.parallax.x; f32[((ptr + 28) >> 2) + 1] = data.parallax.y;
+ u32[(ptr + 36) >> 2] = data.material;
+ u8[ptr + 40] = data.enabled ? 1 : 0;
+}
+
+export function createMesh2DData(): Mesh2DPtrData {
+ return {
+ texture: 0,
+ color: { r: 0, g: 0, b: 0, a: 0 },
+ layer: 0,
+ lit: false,
+ parallax: { x: 0, y: 0 },
+ material: 0,
+ enabled: false,
+ };
+}
+
export interface ParticleEmitterPtrData {
rate: number;
burstCount: number;
@@ -1293,6 +1341,7 @@ export const PTR_ACCESSORS: Record<string, PtrAccessor<any>> = {
FlexContainer: { fill: fillFlexContainer, write: writeFlexContainer, create: createFlexContainerData },
Interactable: { fill: fillInteractable, write: writeInteractable, create: createInteractableData },
Light2D: { fill: fillLight2D, write: writeLight2D, create: createLight2DData },
+ Mesh2D: { fill: fillMesh2D, write: writeMesh2D, create: createMesh2DData },
ParticleEmitter: { fill: fillParticleEmitter, write: writeParticleEmitter, create: createParticleEmitterData },
RigidBody: { fill: fillRigidBody, write: writeRigidBody, create: createRigidBodyData },
SegmentCollider: { fill: fillSegmentCollider, write: writeSegmentCollider, create: createSegmentColliderData },
diff --git a/sdk/src/mesh2d.ts b/sdk/src/mesh2d.ts
new file mode 100644
index 000000000..90859411f
--- /dev/null
+++ b/sdk/src/mesh2d.ts
@@ -0,0 +1,120 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * Mesh2D geometry API — uploads a Mesh2D component's local-space geometry to the
+ * engine (mesh2d_setGeometry) and carries it through scene save/load as an
+ * out-of-band field (variable-size payloads are not C++ component fields).
+ */
+import type { App, Plugin } from './app';
+import type { Entity } from './types';
+import type { ESEngineModule, CppRegistry } from './wasm';
+import type { Mesh2DGeometry } from './component';
+import { defineResource } from './resource';
+import { registerSceneComponentCodec } from './scene';
+import { withScratch } from './wasmScratch';
+
+function packRgba(colors: number[], v: number): number {
+ const clamp = (x: number) => Math.max(0, Math.min(255, Math.round(x * 255)));
+ return (clamp(colors[v * 4 + 0] ?? 1)
+ | (clamp(colors[v * 4 + 1] ?? 1) << 8)
+ | (clamp(colors[v * 4 + 2] ?? 1) << 16)
+ | (clamp(colors[v * 4 + 3] ?? 1) << 24)) >>> 0;
+}
+
+export class Mesh2DAPI {
+ /** Entity → authored geometry, so scene save round-trips what was uploaded. */
+ private readonly authored_ = new Map<number, Mesh2DGeometry>();
+
+ constructor(
+ private readonly module_: ESEngineModule,
+ private readonly registry_: CppRegistry,
+ ) {}
+
+ /**
+ * Upload geometry for an entity's Mesh2D component. Positions are x,y pairs in
+ * component-local space; uvs default to 0,0 (untextured meshes render vertex
+ * colors on the white texture); colors are r,g,b,a floats per vertex.
+ */
+ setGeometry(entity: Entity, geometry: Mesh2DGeometry): void {
+ const m = this.module_;
+ if (!m.mesh2d_setGeometry) return;
+ const vertexCount = Math.floor(geometry.positions.length / 2);
+ const indexCount = geometry.indices.length;
+ if (vertexCount === 0 || indexCount === 0) {
+ this.clearGeometry(entity);
+ return;
+ }
+
+ withScratch(m, alloc => {
+ const posUvPtr = alloc(vertexCount * 4 * 4);
+ const posUv = new Float32Array(m.HEAPU8.buffer, posUvPtr, vertexCount * 4);
+ const uvs = geometry.uvs;
+ for (let v = 0; v < vertexCount; v++) {
+ posUv[v * 4 + 0] = geometry.positions[v * 2 + 0] ?? 0;
+ posUv[v * 4 + 1] = geometry.positions[v * 2 + 1] ?? 0;
+ posUv[v * 4 + 2] = uvs?.[v * 2 + 0] ?? 0;
+ posUv[v * 4 + 3] = uvs?.[v * 2 + 1] ?? 0;
+ }
+
+ let colorsPtr = 0;
+ const colors = geometry.colors;
+ if (colors && colors.length > 0) {
+ colorsPtr = alloc(vertexCount * 4);
+ const packed = new Uint32Array(m.HEAPU8.buffer, colorsPtr, vertexCount);
+ for (let v = 0; v < vertexCount; v++) packed[v] = packRgba(colors, v);
+ }
+
+ const indicesPtr = alloc(indexCount * 4);
+ new Uint32Array(m.HEAPU8.buffer, indicesPtr, indexCount).set(geometry.indices);
+
+ m.mesh2d_setGeometry!(this.registry_, entity, posUvPtr, vertexCount,
+ colorsPtr, indicesPtr, indexCount);
+ });
+ this.authored_.set(entity, geometry);
+ }
+
+ /** Clear an entity's mesh geometry (a valid state: the mesh renders nothing). */
+ clearGeometry(entity: Entity): void {
+ this.module_.mesh2d_setGeometry?.(this.registry_, entity, 0, 0, 0, 0, 0);
+ this.authored_.delete(entity);
+ }
+
+ /** The last geometry uploaded for this entity (scene-export source). */
+ getGeometry(entity: Entity): Mesh2DGeometry | undefined {
+ return this.authored_.get(entity);
+ }
+}
+
+export const Meshes2D = defineResource<Mesh2DAPI>(null!, 'Meshes2D');
+
+export class Mesh2DPlugin implements Plugin {
+ name = 'mesh2d';
+
+ build(app: App): void {
+ const module = app.wasmModule as ESEngineModule;
+ const registry = app.world.getCppRegistry() as CppRegistry;
+ const api = new Mesh2DAPI(module, registry);
+ app.insertResource(Meshes2D, api);
+
+ // The geometry payload is authored in the component data but isn't a C++
+ // field — carry it out-of-band and upload it through the validated entry
+ // point on load (the same pattern as particle gradients / tilemap chunks).
+ registerSceneComponentCodec('Mesh2D', {
+ outOfBandFields: ['geometry'],
+ importData: (entity, outOfBand) => {
+ const g = outOfBand.geometry as Mesh2DGeometry | undefined;
+ if (g && g.positions?.length && g.indices?.length) {
+ api.setGeometry(entity, g);
+ } else {
+ api.clearGeometry(entity);
+ }
+ },
+ exportData: (entity, data) => {
+ const g = api.getGeometry(entity);
+ if (g) data.geometry = g;
+ },
+ });
+ }
+}
+
+export const mesh2dPlugin = new Mesh2DPlugin();
diff --git a/sdk/src/ptrLayouts.generated.ts b/sdk/src/ptrLayouts.generated.ts
index e5f889d59..7e4d88dbb 100644
--- a/sdk/src/ptrLayouts.generated.ts
+++ b/sdk/src/ptrLayouts.generated.ts
@@ -134,6 +134,18 @@ export const PTR_LAYOUTS: Record<string, PtrLayout> = {
{ name: 'enabled', type: 'bool', offset: 52 },
],
},
+ Mesh2D: {
+ ptrFn: 'getMesh2DPtr',
+ fields: [
+ { name: 'texture', type: 'u32', offset: 0 },
+ { name: 'color', type: 'color', offset: 4 },
+ { name: 'layer', type: 'i32', offset: 20 },
+ { name: 'lit', type: 'bool', offset: 24 },
+ { name: 'parallax', type: 'vec2', offset: 28 },
+ { name: 'material', type: 'u32', offset: 36 },
+ { name: 'enabled', type: 'bool', offset: 40 },
+ ],
+ },
ParticleEmitter: {
ptrFn: 'getParticleEmitterPtr',
fields: [
diff --git a/sdk/src/wasm.generated.ts b/sdk/src/wasm.generated.ts
index 663294f08..0730cb2a8 100644
--- a/sdk/src/wasm.generated.ts
+++ b/sdk/src/wasm.generated.ts
@@ -273,6 +273,16 @@ export interface Light2D {
enabled: boolean;
}
+export interface Mesh2D {
+ texture: number;
+ color: Vec4;
+ layer: number;
+ lit: boolean;
+ parallax: Vec2;
+ material: number;
+ enabled: boolean;
+}
+
export interface Parent {
entity: number;
}
@@ -528,6 +538,10 @@ export interface Registry {
getLight2D(entity: Entity): Light2D;
addLight2D(entity: Entity, component: Light2D): void;
removeLight2D(entity: Entity): void;
+ hasMesh2D(entity: Entity): boolean;
+ getMesh2D(entity: Entity): Mesh2D;
+ addMesh2D(entity: Entity, component: Mesh2D): void;
+ removeMesh2D(entity: Entity): void;
hasParent(entity: Entity): boolean;
getParent(entity: Entity): Parent;
addParent(entity: Entity, component: Parent): void;
@@ -620,6 +634,7 @@ export interface ESEngineModule {
FlexContainer: new () => FlexContainer;
Interactable: new () => Interactable;
Light2D: new () => Light2D;
+ Mesh2D: new () => Mesh2D;
Parent: new () => Parent;
ParticleEmitter: new () => ParticleEmitter;
RigidBody: new () => RigidBody;
diff --git a/sdk/src/wasm.ts b/sdk/src/wasm.ts
index b97f8405e..fdb0a124d 100644
--- a/sdk/src/wasm.ts
+++ b/sdk/src/wasm.ts
@@ -176,6 +176,17 @@ export interface ESEngineModule {
textureId: number, transformPtr: number,
entity: number, layer: number, depth: number, sdf: number
): void;
+ /**
+ * Upload a Mesh2D component's geometry: interleaved f32 [x,y,u,v] per vertex,
+ * optional RGBA8 colors (colorsPtr 0 = all white), u32 triangle-list indices.
+ * Validated engine-side: out-of-range indices reject the whole upload.
+ */
+ mesh2d_setGeometry?(
+ registry: CppRegistry, entity: number,
+ posUvPtr: number, vertexCount: number,
+ colorsPtr: number,
+ indicesPtr: number, indexCount: number
+ ): void;
// Material store (engine-side resolved render state, keyed by material handle).
// flags packs depthTest (bit 0), depthWrite (bit 1), CullMode (bits 2-3).
diff --git a/sdk/src/webAppFactory.ts b/sdk/src/webAppFactory.ts
index 6bf0c25c5..70211c251 100644
--- a/sdk/src/webAppFactory.ts
+++ b/sdk/src/webAppFactory.ts
@@ -7,6 +7,7 @@ import { uiPlugins } from './uiPlugins';
import { animationPlugin } from './animation';
import { audioPlugin } from './audio';
import { particlePlugin } from './particle';
+import { mesh2dPlugin } from './mesh2d';
import { tilemapPlugin } from './tilemap';
import { postProcessPlugin } from './postprocess';
import { timelinePlugin } from './timeline';
@@ -35,6 +36,7 @@ export { PhysicsPlugin, PhysicsEvents, Physics, loadPhysicsModule } from './phys
export { AnimationPlugin, animationPlugin } from './animation';
export { AudioPlugin, audioPlugin } from './audio';
export { ParticlePlugin, particlePlugin } from './particle';
+export { Mesh2DPlugin, mesh2dPlugin } from './mesh2d';
export { PostProcessPlugin, postProcessPlugin } from './postprocess';
export { TimelinePlugin, timelinePlugin, registerTimelineAsset, parseTimelineAsset, Timeline, TimelineApi, TimelinePlayer, type TimelinePlayerData } from './timeline';
// Authoring + pure-TS evaluation surface for the editor Sequencer.
@@ -58,7 +60,7 @@ export interface CreateWebAppOptions extends WebAppOptions {
wasmBaseUrl?: string;
}
-const basePlugins = [timerPlugin, lifecyclePlugin(), animationPlugin, audioPlugin, particlePlugin, tilemapPlugin, postProcessPlugin, timelinePlugin, perceptionPlugin, fsmPlugin, btPlugin, navPlugin];
+const basePlugins = [timerPlugin, lifecyclePlugin(), animationPlugin, audioPlugin, particlePlugin, mesh2dPlugin, tilemapPlugin, postProcessPlugin, timelinePlugin, perceptionPlugin, fsmPlugin, btPlugin, navPlugin];
export function createWebApp(module: ESEngineModule, options?: CreateWebAppOptions): App {
const sideModules: SideModuleHost | undefined = options?.sideModules
diff --git a/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap b/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap
index 553d7caa8..d75eb8500 100644
--- a/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap
+++ b/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap
@@ -182,6 +182,26 @@ exports[`builtin FieldMeta (RC9-1 equivalence gate) > matches the golden snapsho
"tooltip": "Point, Directional, Ambient, or Spot.",
},
},
+ "Mesh2D": {
+ "color": {
+ "tooltip": "Tint multiplied into the vertex colors (white = unchanged).",
+ },
+ "layer": {
+ "enumSource": "sortingLayers",
+ "step": 1,
+ "tooltip": "Sorting layer — controls draw order across renderables.",
+ },
+ "lit": {
+ "tooltip": "Receive 2D lights: Light2D entities light this mesh (flat normal). A custom material overrides this.",
+ },
+ "material": {
+ "advanced": true,
+ },
+ "parallax": {
+ "advanced": true,
+ "tooltip": "Parallax scroll factor (1 = with world, <1 = slower, 0 = locked to camera).",
+ },
+ },
"ParticleEmitter": {
"angleSpreadMax": {
"category": "Velocity",
diff --git a/src/esengine/bindings/EditorAPI.generated.cpp b/src/esengine/bindings/EditorAPI.generated.cpp
index 11c31e7eb..02e14fe14 100644
--- a/src/esengine/bindings/EditorAPI.generated.cpp
+++ b/src/esengine/bindings/EditorAPI.generated.cpp
@@ -2,10 +2,10 @@
* @file EditorAPI.generated.cpp
* @brief Auto-generated editor API with string-dispatched component access
* @details Generated by EHT - DO NOT EDIT
- * @schema_hash 09f40f18d6c7ea16
+ * @schema_hash f2224cd6bc00e0ff
*/
-#define ES_EDITOR_API_SCHEMA_HASH "09f40f18d6c7ea16"
+#define ES_EDITOR_API_SCHEMA_HASH "f2224cd6bc00e0ff"
#include <emscripten/bind.h>
#include <string>
@@ -19,6 +19,7 @@
#include "../ecs/components/Hierarchy.hpp"
#include "../ecs/components/Interactable.hpp"
#include "../ecs/components/Light2D.hpp"
+#include "../ecs/components/Mesh2D.hpp"
#include "../ecs/components/ParticleEmitter.hpp"
#include "../ecs/components/RigidBody.hpp"
#include "../ecs/components/ShadowCaster2D.hpp"
@@ -63,6 +64,7 @@ std::vector<std::string> editor_getComponentNames() {
"FlexContainer",
"Interactable",
"Light2D",
+ "Mesh2D",
"Parent",
"ParticleEmitter",
"RigidBody",
@@ -213,6 +215,20 @@ std::string editor_getComponentSchema(const std::string& name) {
{"key":"shadowDistance","type":"float","group":"Light2D"},
{"key":"enabled","type":"bool","group":"Light2D"}
])JSON";
+ } else if (name == "Mesh2D") {
+ return R"JSON([
+ {"key":"texture","type":"asset","group":"Mesh2D"},
+ {"key":"color.r","type":"color","group":"Mesh2D"},
+ {"key":"color.g","type":"color","group":"Mesh2D"},
+ {"key":"color.b","type":"color","group":"Mesh2D"},
+ {"key":"color.a","type":"color","group":"Mesh2D"},
+ {"key":"layer","type":"int","group":"Mesh2D"},
+ {"key":"lit","type":"bool","group":"Mesh2D"},
+ {"key":"parallax.x","type":"float","group":"Mesh2D"},
+ {"key":"parallax.y","type":"float","group":"Mesh2D"},
+ {"key":"material","type":"asset","group":"Mesh2D"},
+ {"key":"enabled","type":"bool","group":"Mesh2D"}
+ ])JSON";
} else if (name == "Parent") {
return R"JSON([
{"key":"entity","type":"entity","group":"Parent"}
@@ -525,6 +541,9 @@ bool editor_addComponent(Registry& reg, u32 e, const std::string& name) {
} else if (name == "Light2D") {
if (!reg.has<esengine::ecs::Light2D>(entity)) reg.emplace<esengine::ecs::Light2D>(entity);
return true;
+ } else if (name == "Mesh2D") {
+ if (!reg.has<esengine::ecs::Mesh2D>(entity)) reg.emplace<esengine::ecs::Mesh2D>(entity);
+ return true;
} else if (name == "Parent") {
if (!reg.has<esengine::ecs::Parent>(entity)) reg.emplace<esengine::ecs::Parent>(entity);
return true;
@@ -603,6 +622,8 @@ bool editor_removeComponent(Registry& reg, u32 e, const std::string& name) {
if (reg.has<esengine::ecs::Interactable>(entity)) { reg.remove<esengine::ecs::Interactable>(entity); return true; }
} else if (name == "Light2D") {
if (reg.has<esengine::ecs::Light2D>(entity)) { reg.remove<esengine::ecs::Light2D>(entity); return true; }
+ } else if (name == "Mesh2D") {
+ if (reg.has<esengine::ecs::Mesh2D>(entity)) { reg.remove<esengine::ecs::Mesh2D>(entity); return true; }
} else if (name == "Parent") {
if (reg.has<esengine::ecs::Parent>(entity)) { reg.remove<esengine::ecs::Parent>(entity); return true; }
} else if (name == "ParticleEmitter") {
@@ -654,6 +675,7 @@ bool editor_hasComponent(Registry& reg, u32 e, const std::string& name) {
if (name == "FlexContainer") return reg.has<esengine::ecs::FlexContainer>(entity);
if (name == "Interactable") return reg.has<esengine::ecs::Interactable>(entity);
if (name == "Light2D") return reg.has<esengine::ecs::Light2D>(entity);
+ if (name == "Mesh2D") return reg.has<esengine::ecs::Mesh2D>(entity);
if (name == "Parent") return reg.has<esengine::ecs::Parent>(entity);
if (name == "ParticleEmitter") return reg.has<esengine::ecs::ParticleEmitter>(entity);
if (name == "RigidBody") return reg.has<esengine::ecs::RigidBody>(entity);
@@ -690,6 +712,7 @@ std::vector<std::string> editor_getComponents(Registry& reg, u32 e) {
if (reg.has<esengine::ecs::FlexContainer>(entity)) result.push_back("FlexContainer");
if (reg.has<esengine::ecs::Interactable>(entity)) result.push_back("Interactable");
if (reg.has<esengine::ecs::Light2D>(entity)) result.push_back("Light2D");
+ if (reg.has<esengine::ecs::Mesh2D>(entity)) result.push_back("Mesh2D");
if (reg.has<esengine::ecs::Parent>(entity)) result.push_back("Parent");
if (reg.has<esengine::ecs::ParticleEmitter>(entity)) result.push_back("ParticleEmitter");
if (reg.has<esengine::ecs::RigidBody>(entity)) result.push_back("RigidBody");
@@ -816,6 +839,17 @@ bool editor_setFloat(Registry& reg, u32 e, const std::string& comp, const std::s
else if (field == "shadowDistance") { c.shadowDistance = value; }
else { return false; }
return true;
+ } else if (comp == "Mesh2D") {
+ if (!reg.has<esengine::ecs::Mesh2D>(entity)) return false;
+ auto& c = reg.get<esengine::ecs::Mesh2D>(entity);
+ if (field == "color.r") { c.color.r = value; }
+ else if (field == "color.g") { c.color.g = value; }
+ else if (field == "color.b") { c.color.b = value; }
+ else if (field == "color.a") { c.color.a = value; }
+ else if (field == "parallax.x") { c.parallax.x = value; }
+ else if (field == "parallax.y") { c.parallax.y = value; }
+ else { return false; }
+ return true;
} else if (comp == "ParticleEmitter") {
if (!reg.has<esengine::ecs::ParticleEmitter>(entity)) return false;
auto& c = reg.get<esengine::ecs::ParticleEmitter>(entity);
@@ -1139,6 +1173,15 @@ f32 editor_getFloat(Registry& reg, u32 e, const std::string& comp, const std::st
else if (field == "outerAngle") { return c.outerAngle; }
else if (field == "shadowSoftness") { return c.shadowSoftness; }
else if (field == "shadowDistance") { return c.shadowDistance; }
+ } else if (comp == "Mesh2D") {
+ if (!reg.has<esengine::ecs::Mesh2D>(entity)) return 0.0f;
+ const auto& c = reg.get<esengine::ecs::Mesh2D>(entity);
+ if (field == "color.r") { return c.color.r; }
+ else if (field == "color.g") { return c.color.g; }
+ else if (field == "color.b") { return c.color.b; }
+ else if (field == "color.a") { return c.color.a; }
+ else if (field == "parallax.x") { return c.parallax.x; }
+ else if (field == "parallax.y") { return c.parallax.y; }
} else if (comp == "ParticleEmitter") {
if (!reg.has<esengine::ecs::ParticleEmitter>(entity)) return 0.0f;
const auto& c = reg.get<esengine::ecs::ParticleEmitter>(entity);
@@ -1398,6 +1441,14 @@ bool editor_setInt(Registry& reg, u32 e, const std::string& comp, const std::str
if (field == "type") { c.type = static_cast<i32>(value); }
else { return false; }
return true;
+ } else if (comp == "Mesh2D") {
+ if (!reg.has<esengine::ecs::Mesh2D>(entity)) return false;
+ auto& c = reg.get<esengine::ecs::Mesh2D>(entity);
+ if (field == "texture") { c.texture = resource::TextureHandle(static_cast<u32>(value)); }
+ else if (field == "layer") { c.layer = static_cast<i32>(value); }
+ else if (field == "material") { c.material = static_cast<u32>(value); }
+ else { return false; }
+ return true;
} else if (comp == "Parent") {
if (!reg.has<esengine::ecs::Parent>(entity)) return false;
auto& c = reg.get<esengine::ecs::Parent>(entity);
@@ -1547,6 +1598,12 @@ i32 editor_getInt(Registry& reg, u32 e, const std::string& comp, const std::stri
if (!reg.has<esengine::ecs::Light2D>(entity)) return 0;
const auto& c = reg.get<esengine::ecs::Light2D>(entity);
if (field == "type") { return static_cast<i32>(c.type); }
+ } else if (comp == "Mesh2D") {
+ if (!reg.has<esengine::ecs::Mesh2D>(entity)) return 0;
+ const auto& c = reg.get<esengine::ecs::Mesh2D>(entity);
+ if (field == "texture") { return static_cast<i32>(c.texture.id()); }
+ else if (field == "layer") { return static_cast<i32>(c.layer); }
+ else if (field == "material") { return static_cast<i32>(c.material); }
} else if (comp == "Parent") {
if (!reg.has<esengine::ecs::Parent>(entity)) return 0;
const auto& c = reg.get<esengine::ecs::Parent>(entity);
@@ -1677,6 +1734,13 @@ bool editor_setBool(Registry& reg, u32 e, const std::string& comp, const std::st
if (field == "enabled") { c.enabled = value; }
else { return false; }
return true;
+ } else if (comp == "Mesh2D") {
+ if (!reg.has<esengine::ecs::Mesh2D>(entity)) return false;
+ auto& c = reg.get<esengine::ecs::Mesh2D>(entity);
+ if (field == "lit") { c.lit = value; }
+ else if (field == "enabled") { c.enabled = value; }
+ else { return false; }
+ return true;
} else if (comp == "ParticleEmitter") {
if (!reg.has<esengine::ecs::ParticleEmitter>(entity)) return false;
auto& c = reg.get<esengine::ecs::ParticleEmitter>(entity);
@@ -1802,6 +1866,11 @@ bool editor_getBool(Registry& reg, u32 e, const std::string& comp, const std::st
if (!reg.has<esengine::ecs::Light2D>(entity)) return false;
const auto& c = reg.get<esengine::ecs::Light2D>(entity);
if (field == "enabled") { return c.enabled; }
+ } else if (comp == "Mesh2D") {
+ if (!reg.has<esengine::ecs::Mesh2D>(entity)) return false;
+ const auto& c = reg.get<esengine::ecs::Mesh2D>(entity);
+ if (field == "lit") { return c.lit; }
+ else if (field == "enabled") { return c.enabled; }
} else if (comp == "ParticleEmitter") {
if (!reg.has<esengine::ecs::ParticleEmitter>(entity)) return false;
const auto& c = reg.get<esengine::ecs::ParticleEmitter>(entity);
diff --git a/src/esengine/bindings/RendererBindings.cpp b/src/esengine/bindings/RendererBindings.cpp
index 2fb0b8be7..1c9ab26ee 100644
--- a/src/esengine/bindings/RendererBindings.cpp
+++ b/src/esengine/bindings/RendererBindings.cpp
@@ -18,6 +18,7 @@
#include "../ecs/components/Canvas.hpp"
#include "../ecs/components/Transform.hpp"
#include "../ecs/components/Sprite.hpp"
+#include "../ecs/components/Mesh2D.hpp"
#include "../ecs/components/Light2D.hpp"
#include "../ecs/components/Hierarchy.hpp"
#include "../core/Log.hpp"
@@ -127,6 +128,61 @@ void renderer_submitTextBatch(
textureId, transform, Entity::fromRaw(entity), layer, depth, sdf != 0);
}
+// Mesh2D geometry upload: interleaved f32 [x,y,u,v] per vertex, optional RGBA8
+// colors (null = all white), u32 triangle-list indices. Validated here — the single
+// upload entry — so the render path can trust the payload: out-of-range indices or a
+// non-triangle count reject the whole upload instead of feeding the GPU garbage.
+void mesh2d_setGeometry(ecs::Registry& registry, u32 entity,
+ uintptr_t posUvPtr, u32 vertexCount,
+ uintptr_t colorsPtr,
+ uintptr_t indicesPtr, u32 indexCount) {
+ const Entity ent = Entity::fromRaw(entity);
+ auto* mesh = registry.tryGet<ecs::Mesh2D>(ent);
+ if (!mesh) {
+ ES_LOG_WARN("mesh2d_setGeometry: entity {} has no Mesh2D component", entity);
+ return;
+ }
+
+ // Empty upload = clear the geometry (a valid state: the mesh renders nothing).
+ if (posUvPtr == 0 || indicesPtr == 0 || vertexCount == 0 || indexCount == 0) {
+ mesh->vertices.clear();
+ mesh->indices.clear();
+ mesh->localMin = mesh->localMax = glm::vec2(0.0f);
+ return;
+ }
+ if (indexCount % 3 != 0) {
+ ES_LOG_WARN("mesh2d_setGeometry: indexCount {} is not a triangle list; rejected", indexCount);
+ return;
+ }
+
+ const f32* posUv = reinterpret_cast<const f32*>(posUvPtr);
+ const u32* colors = reinterpret_cast<const u32*>(colorsPtr);
+ const u32* indices = reinterpret_cast<const u32*>(indicesPtr);
+
+ for (u32 i = 0; i < indexCount; ++i) {
+ if (indices[i] >= vertexCount) {
+ ES_LOG_WARN("mesh2d_setGeometry: index {} out of range (vertexCount {}); rejected",
+ indices[i], vertexCount);
+ return;
+ }
+ }
+
+ mesh->vertices.resize(vertexCount);
+ glm::vec2 mn(posUv[0], posUv[1]);
+ glm::vec2 mx = mn;
+ for (u32 v = 0; v < vertexCount; ++v) {
+ auto& out = mesh->vertices[v];
+ out.position = { posUv[v * 4 + 0], posUv[v * 4 + 1] };
+ out.uv = { posUv[v * 4 + 2], posUv[v * 4 + 3] };
+ out.color = colorsPtr ? colors[v] : 0xFFFFFFFFu;
+ mn = glm::min(mn, out.position);
+ mx = glm::max(mx, out.position);
+ }
+ mesh->indices.assign(indices, indices + indexCount);
+ mesh->localMin = mn;
+ mesh->localMax = mx;
+}
+
void renderFrame(ecs::Registry& registry, i32 viewportWidth, i32 viewportHeight) {
if (!g_initialized || !g_renderFrame) return;
diff --git a/src/esengine/bindings/RendererBindings.hpp b/src/esengine/bindings/RendererBindings.hpp
index b6eb6a513..0e0552c17 100644
--- a/src/esengine/bindings/RendererBindings.hpp
+++ b/src/esengine/bindings/RendererBindings.hpp
@@ -78,6 +78,12 @@ void renderer_submitTextBatch(
u32 textureId, uintptr_t transformPtr,
u32 entity, i32 layer, f32 depth, i32 sdf
);
+void mesh2d_setGeometry(
+ ecs::Registry& registry, u32 entity,
+ uintptr_t posUvPtr, u32 vertexCount,
+ uintptr_t colorsPtr,
+ uintptr_t indicesPtr, u32 indexCount
+);
#ifdef ES_ENABLE_PARTICLES
void renderer_submitParticles(ecs::Registry& registry);
#endif
diff --git a/src/esengine/bindings/WebBindings.generated.cpp b/src/esengine/bindings/WebBindings.generated.cpp
index a6e07f740..8e5621598 100644
--- a/src/esengine/bindings/WebBindings.generated.cpp
+++ b/src/esengine/bindings/WebBindings.generated.cpp
@@ -19,6 +19,7 @@
#include "../ecs/components/Hierarchy.hpp"
#include "../ecs/components/Interactable.hpp"
#include "../ecs/components/Light2D.hpp"
+#include "../ecs/components/Mesh2D.hpp"
#include "../ecs/components/ParticleEmitter.hpp"
#include "../ecs/components/RigidBody.hpp"
#include "../ecs/components/ShadowCaster2D.hpp"
@@ -388,6 +389,40 @@ FlexContainerJS flexcontainerToJS(const esengine::ecs::FlexContainer& c) {
return js;
}
+struct Mesh2DJS {
+ u32 texture;
+ glm::vec4 color;
+ i32 layer;
+ bool lit;
+ glm::vec2 parallax;
+ u32 material;
+ bool enabled;
+};
+
+esengine::ecs::Mesh2D mesh2dFromJS(const Mesh2DJS& js) {
+ esengine::ecs::Mesh2D c;
+ c.texture = resource::TextureHandle(js.texture);
+ c.color = js.color;
+ c.layer = js.layer;
+ c.lit = js.lit;
+ c.parallax = js.parallax;
+ c.material = js.material;
+ c.enabled = js.enabled;
+ return c;
+}
+
+Mesh2DJS mesh2dToJS(const esengine::ecs::Mesh2D& c) {
+ Mesh2DJS js;
+ js.texture = c.texture.id();
+ js.color = c.color;
+ js.layer = c.layer;
+ js.lit = c.lit;
+ js.parallax = c.parallax;
+ js.material = c.material;
+ js.enabled = c.enabled;
+ return js;
+}
+
struct ParentJS {
u32 entity;
};
@@ -938,6 +973,15 @@ EMSCRIPTEN_BINDINGS(esengine_components) {
.field("shadowDistance", &esengine::ecs::Light2D::shadowDistance)
.field("enabled", &esengine::ecs::Light2D::enabled);
+ value_object<Mesh2DJS>("Mesh2D")
+ .field("texture", &Mesh2DJS::texture)
+ .field("color", &Mesh2DJS::color)
+ .field("layer", &Mesh2DJS::layer)
+ .field("lit", &Mesh2DJS::lit)
+ .field("parallax", &Mesh2DJS::parallax)
+ .field("material", &Mesh2DJS::material)
+ .field("enabled", &Mesh2DJS::enabled);
+
value_object<ParentJS>("Parent")
.field("entity", &ParentJS::entity);
@@ -1354,6 +1398,26 @@ EMSCRIPTEN_BINDINGS(esengine_registry) {
r.remove<esengine::ecs::Light2D>(entity);
}))
+ // Mesh2D
+ .function("hasMesh2D", optional_override([](Registry& r, u32 e) {
+ return r.has<esengine::ecs::Mesh2D>(static_cast<Entity>(e));
+ }))
+ .function("getMesh2D", optional_override([](Registry& r, u32 e) {
+ auto entity = static_cast<Entity>(e);
+ if (!r.valid(entity) || !r.has<esengine::ecs::Mesh2D>(entity)) return Mesh2DJS{};
+ return mesh2dToJS(r.get<esengine::ecs::Mesh2D>(entity));
+ }))
+ .function("addMesh2D", optional_override([](Registry& r, u32 e, const Mesh2DJS& js) {
+ auto entity = static_cast<Entity>(e);
+ if (!r.valid(entity)) return;
+ r.emplaceOrReplace<esengine::ecs::Mesh2D>(entity, mesh2dFromJS(js));
+ }))
+ .function("removeMesh2D", optional_override([](Registry& r, u32 e) {
+ auto entity = static_cast<Entity>(e);
+ if (!r.valid(entity) || !r.has<esengine::ecs::Mesh2D>(entity)) return;
+ r.remove<esengine::ecs::Mesh2D>(entity);
+ }))
+
// Parent
.function("hasParent", optional_override([](Registry& r, u32 e) {
return r.has<esengine::ecs::Parent>(static_cast<Entity>(e));
@@ -1730,6 +1794,7 @@ emscripten::val esengineGetBuiltinComponentNames() {
arr.set(i++, val(std::string("FlexContainer")));
arr.set(i++, val(std::string("Interactable")));
arr.set(i++, val(std::string("Light2D")));
+ arr.set(i++, val(std::string("Mesh2D")));
arr.set(i++, val(std::string("Parent")));
arr.set(i++, val(std::string("ParticleEmitter")));
arr.set(i++, val(std::string("RigidBody")));
@@ -1832,6 +1897,13 @@ static_assert(offsetof(esengine::ecs::Light2D, outerAngle) == 40, "ABI offset dr
static_assert(offsetof(esengine::ecs::Light2D, shadowSoftness) == 44, "ABI offset drift: esengine::ecs::Light2D.shadowSoftness (EHT expected 44)");
static_assert(offsetof(esengine::ecs::Light2D, shadowDistance) == 48, "ABI offset drift: esengine::ecs::Light2D.shadowDistance (EHT expected 48)");
static_assert(offsetof(esengine::ecs::Light2D, enabled) == 52, "ABI offset drift: esengine::ecs::Light2D.enabled (EHT expected 52)");
+static_assert(offsetof(esengine::ecs::Mesh2D, texture) == 0, "ABI offset drift: esengine::ecs::Mesh2D.texture (EHT expected 0)");
+static_assert(offsetof(esengine::ecs::Mesh2D, color) == 4, "ABI offset drift: esengine::ecs::Mesh2D.color (EHT expected 4)");
+static_assert(offsetof(esengine::ecs::Mesh2D, layer) == 20, "ABI offset drift: esengine::ecs::Mesh2D.layer (EHT expected 20)");
+static_assert(offsetof(esengine::ecs::Mesh2D, lit) == 24, "ABI offset drift: esengine::ecs::Mesh2D.lit (EHT expected 24)");
+static_assert(offsetof(esengine::ecs::Mesh2D, parallax) == 28, "ABI offset drift: esengine::ecs::Mesh2D.parallax (EHT expected 28)");
+static_assert(offsetof(esengine::ecs::Mesh2D, material) == 36, "ABI offset drift: esengine::ecs::Mesh2D.material (EHT expected 36)");
+static_assert(offsetof(esengine::ecs::Mesh2D, enabled) == 40, "ABI offset drift: esengine::ecs::Mesh2D.enabled (EHT expected 40)");
static_assert(offsetof(esengine::ecs::ParticleEmitter, rate) == 0, "ABI offset drift: esengine::ecs::ParticleEmitter.rate (EHT expected 0)");
static_assert(offsetof(esengine::ecs::ParticleEmitter, burstCount) == 4, "ABI offset drift: esengine::ecs::ParticleEmitter.burstCount (EHT expected 4)");
static_assert(offsetof(esengine::ecs::ParticleEmitter, burstInterval) == 8, "ABI offset drift: esengine::ecs::ParticleEmitter.burstInterval (EHT expected 8)");
@@ -1969,7 +2041,7 @@ static_assert(offsetof(esengine::ecs::Velocity, angular) == 12, "ABI offset drif
// ABI Hash -- runtime handshake against the SDK bundle
// =============================================================================
-static const char* kEsAbiLayoutHash = "4a0ed8f94ca2aed4";
+static const char* kEsAbiLayoutHash = "89e3ae10e24e8bc9";
std::string esengineGetAbiLayoutHash() {
return std::string(kEsAbiLayoutHash);
diff --git a/src/esengine/bindings/WebSDKEntry.cpp b/src/esengine/bindings/WebSDKEntry.cpp
index f50f750bf..6ce592b16 100644
--- a/src/esengine/bindings/WebSDKEntry.cpp
+++ b/src/esengine/bindings/WebSDKEntry.cpp
@@ -429,6 +429,7 @@ EMSCRIPTEN_BINDINGS(esengine_renderer) {
emscripten::function("renderer_submitSpineBatchByEntity", &esengine::renderer_submitSpineBatchByEntity);
#endif
emscripten::function("renderer_submitTextBatch", &esengine::renderer_submitTextBatch);
+ emscripten::function("mesh2d_setGeometry", &esengine::mesh2d_setGeometry);
emscripten::function("compileEsshader", &esengine::compileEsshader);
emscripten::function("defineMaterial", &esengine::defineMaterial);
diff --git a/src/esengine/core/EstellaContext.cpp b/src/esengine/core/EstellaContext.cpp
index 4e37c1963..1d8bc0f7b 100644
--- a/src/esengine/core/EstellaContext.cpp
+++ b/src/esengine/core/EstellaContext.cpp
@@ -20,6 +20,7 @@
#include "../renderer/plugins/UIElementPlugin.hpp"
#include "../renderer/plugins/TextPlugin.hpp"
#include "../renderer/plugins/ShapePlugin.hpp"
+#include "../renderer/plugins/MeshPlugin.hpp"
#ifdef ES_ENABLE_PARTICLES
#include "../renderer/plugins/ParticlePlugin.hpp"
#include "../particle/ParticleSystem.hpp"
@@ -137,6 +138,7 @@ void EstellaContext::initSubsystems() {
renderFrame->addPlugin(std::make_unique<UIElementPlugin>());
renderFrame->addPlugin(std::make_unique<TextPlugin>());
renderFrame->addPlugin(std::make_unique<ShapePlugin>());
+ renderFrame->addPlugin(std::make_unique<MeshPlugin>());
#ifdef ES_ENABLE_TILEMAP
{
diff --git a/src/esengine/ecs/components/Mesh2D.hpp b/src/esengine/ecs/components/Mesh2D.hpp
new file mode 100644
index 000000000..2ec7e1ab3
--- /dev/null
+++ b/src/esengine/ecs/components/Mesh2D.hpp
@@ -0,0 +1,97 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file Mesh2D.hpp
+ * @brief Arbitrary-geometry 2D mesh renderable (deformed sprites, polygons, water
+ * surfaces, procedural shapes).
+ * @details Vertices live in component-local space and stream through the unified
+ * Batch face each frame (CPU-transformed like every 2D renderable), so a
+ * mesh participates in sorting, clipping, and multi-texture merging exactly
+ * like a sprite. Geometry is set via mesh2d_setGeometry (bulk upload with
+ * index validation), not per-field reflection.
+ *
+ * @author ESEngine Team
+ * @date 2026
+ *
+ * @copyright Copyright (c) 2026 ESEngine Team
+ * Licensed under the Apache License, Version 2.0.
+ */
+#pragma once
+
+// =============================================================================
+// Includes
+// =============================================================================
+
+#include "../../core/Types.hpp"
+#include "../../core/Reflection.hpp"
+#include "../../math/Math.hpp"
+#include "../../resource/Handle.hpp"
+
+#include <vector>
+
+namespace esengine::ecs {
+
+/** @brief One local-space mesh vertex: position, texture coordinate, RGBA8 color. */
+struct MeshVertex2D {
+ glm::vec2 position{0.0f, 0.0f};
+ glm::vec2 uv{0.0f, 0.0f};
+ u32 color = 0xFFFFFFFFu;
+};
+
+// =============================================================================
+// Mesh2D Component
+// =============================================================================
+
+ES_COMPONENT()
+struct Mesh2D {
+ /** @brief Texture sampled by the mesh UVs (invalid = untextured, vertex colors only) */
+ ES_PROPERTY(asset = texture)
+ resource::TextureHandle texture;
+
+ /** @brief Color tint multiplied with per-vertex colors (white = unchanged) */
+ ES_PROPERTY(animatable, tooltip="Tint multiplied into the vertex colors (white = unchanged).")
+ glm::vec4 color{1.0f, 1.0f, 1.0f, 1.0f};
+
+ /** @brief Sorting layer (higher = rendered on top) */
+ ES_PROPERTY(step=1, enum_source=sortingLayers, tooltip="Sorting layer — controls draw order across renderables.")
+ i32 layer{0};
+
+ /** @brief Lit by the scene's 2D lights (Light2D). A custom material overrides this. */
+ ES_PROPERTY(tooltip="Receive 2D lights: Light2D entities light this mesh (flat normal). A custom material overrides this.")
+ bool lit{false};
+
+ /** @brief Parallax scroll factor per axis. 1 = moves with the world (default, no
+ * parallax); <1 = scrolls slower than the camera (appears farther, e.g. a
+ * background); 0 = locked to the camera (e.g. a sky). The renderer offsets
+ * the mesh by camera_center * (1 - factor). */
+ ES_PROPERTY(advanced, tooltip="Parallax scroll factor (1 = with world, <1 = slower, 0 = locked to camera).")
+ glm::vec2 parallax{1.0f, 1.0f};
+
+ /** @brief Custom material ID (0 = use default batch shader) */
+ ES_PROPERTY(asset = material, advanced)
+ u32 material{0};
+
+ ES_PROPERTY()
+ bool enabled{true};
+
+ // -------------------------------------------------------------------------
+ // Geometry payload — set via mesh2d_setGeometry, streamed by MeshPlugin.
+ // Deliberately un-annotated: variable-size data has no fixed ABI offset, so it
+ // stays out of the EHT reflection/pointer layout (all annotated fields above
+ // keep their asserted offsets because these members come last).
+ // -------------------------------------------------------------------------
+
+ /** @brief Local-space vertices (triangle list, indexed). */
+ std::vector<MeshVertex2D> vertices;
+
+ /** @brief Triangle-list indices into @ref vertices (validated on upload). */
+ std::vector<u32> indices;
+
+ /** @brief Local-space AABB of @ref vertices, recomputed on upload — cull source. */
+ glm::vec2 localMin{0.0f, 0.0f};
+ glm::vec2 localMax{0.0f, 0.0f};
+
+ Mesh2D() = default;
+};
+
+} // namespace esengine::ecs
diff --git a/src/esengine/renderer/plugins/MeshPlugin.cpp b/src/esengine/renderer/plugins/MeshPlugin.cpp
new file mode 100644
index 000000000..6ad569509
--- /dev/null
+++ b/src/esengine/renderer/plugins/MeshPlugin.cpp
@@ -0,0 +1,119 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+#include "MeshPlugin.hpp"
+#include "../BatchBuilder.hpp"
+#include "../MaterialStore.hpp"
+#include "../RenderFrame.hpp"
+#include "../Texture.hpp"
+#include "../../ecs/components/Transform.hpp"
+#include "../../ecs/components/Mesh2D.hpp"
+
+#include <cmath>
+
+namespace esengine {
+
+namespace {
+// Per-channel RGBA8 multiply, for tinting per-vertex colors.
+u32 mulColor(u32 a, u32 b) {
+ u32 r = (((a >> 0) & 0xFF) * ((b >> 0) & 0xFF)) / 255u;
+ u32 g = (((a >> 8) & 0xFF) * ((b >> 8) & 0xFF)) / 255u;
+ u32 bl = (((a >> 16) & 0xFF) * ((b >> 16) & 0xFF)) / 255u;
+ u32 al = (((a >> 24) & 0xFF) * ((b >> 24) & 0xFF)) / 255u;
+ return r | (g << 8) | (bl << 16) | (al << 24);
+}
+} // namespace
+
+void MeshPlugin::collect(RenderCollectContext& collect_ctx) {
+ auto& registry = collect_ctx.registry;
+ auto& frustum = collect_ctx.frustum;
+ auto& clips = collect_ctx.clip_state;
+ auto& buffers = collect_ctx.buffer_pool;
+ auto& draw_list = collect_ctx.draw_list;
+ auto& ctx = collect_ctx.frame_context;
+ auto meshView = registry.view<ecs::Transform, ecs::Mesh2D>();
+
+ u32 litProgram = 0;
+
+ for (auto entity : meshView) {
+ const auto& mesh = meshView.get<ecs::Mesh2D>(entity);
+ if (!mesh.enabled || mesh.indices.empty()) continue;
+
+ auto& transform = meshView.get<ecs::Transform>(entity);
+ glm::vec3 position = parallaxedWorldPosition(transform, mesh.parallax, collect_ctx.camera);
+ const auto& rotation = transform.worldRotation;
+ const auto& scale = transform.worldScale;
+
+ // Cull at the local AABB scaled into world space (rotation ignored — the
+ // same approximation the sprite path uses).
+ glm::vec2 localCenter = (mesh.localMin + mesh.localMax) * 0.5f;
+ glm::vec2 localHalf = (mesh.localMax - mesh.localMin) * 0.5f;
+ glm::vec3 aabbCenter = position
+ + glm::vec3(localCenter.x * scale.x, localCenter.y * scale.y, 0.0f);
+ glm::vec3 halfExtents(std::abs(localHalf.x * scale.x),
+ std::abs(localHalf.y * scale.y), 0.0f);
+ if (!frustum.intersectsAABB(aabbCenter, halfExtents)) continue;
+
+ u32 textureId = ctx.white_texture_id;
+ if (mesh.texture.isValid()) {
+ if (Texture* tex = ctx.resources.getTexture(mesh.texture)) {
+ textureId = tex->getId();
+ }
+ }
+
+ BatchDrawKey key{
+ .stage = ctx.current_stage,
+ .layer = mesh.layer,
+ .shaderId = ctx.batch_shader_id,
+ .blend = BlendMode::Normal,
+ .textureId = textureId,
+ .depth = position.z,
+ .entity = entity,
+ .type = RenderType::Mesh,
+ };
+
+ // Material resolve mirrors SpritePlugin: an unregistered handle falls back to
+ // the default batch shader; a material owns shading fully, so it takes
+ // precedence over the lit toggle.
+ if (mesh.material != 0) {
+ if (const MaterialRecord* m = ctx.materials ? ctx.materials->find(mesh.material) : nullptr) {
+ key.shaderId = (m->shader != 0) ? m->shader : ctx.batch_shader_id;
+ key.blend = m->blend;
+ key.materialId = mesh.material;
+ key.depthTest = m->depthTest;
+ key.depthWrite = m->depthWrite;
+ key.cull = static_cast<u8>(m->cull);
+ }
+ } else if (mesh.lit && ctx.frame) {
+ if (litProgram == 0) litProgram = ctx.frame->batchProgram({"LIT"});
+ if (litProgram != 0) key.shaderId = litProgram;
+ }
+
+ f32 angle = 2.0f * std::atan2(rotation.z, rotation.w);
+ bool rotated = std::abs(angle) > 0.001f;
+ f32 cosA = 1.0f, sinA = 0.0f;
+ if (rotated) {
+ cosA = std::cos(angle);
+ sinA = std::sin(angle);
+ }
+
+ u32 tint = packColor(mesh.color);
+ bool tinted = tint != 0xFFFFFFFFu;
+
+ scratch_.resize(mesh.vertices.size());
+ for (usize v = 0; v < mesh.vertices.size(); ++v) {
+ const auto& in = mesh.vertices[v];
+ glm::vec2 local(in.position.x * scale.x, in.position.y * scale.y);
+ glm::vec2 world = rotated
+ ? glm::vec2(position.x + local.x * cosA - local.y * sinA,
+ position.y + local.x * sinA + local.y * cosA)
+ : glm::vec2(position.x + local.x, position.y + local.y);
+ scratch_[v] = { world, tinted ? mulColor(in.color, tint) : in.color, in.uv };
+ }
+
+ appendIndexedBatch(buffers, draw_list, clips,
+ scratch_.data(), static_cast<u32>(scratch_.size()),
+ mesh.indices.data(), static_cast<u32>(mesh.indices.size()), key);
+ }
+}
+
+} // namespace esengine
diff --git a/src/esengine/renderer/plugins/MeshPlugin.hpp b/src/esengine/renderer/plugins/MeshPlugin.hpp
new file mode 100644
index 000000000..ad3883387
--- /dev/null
+++ b/src/esengine/renderer/plugins/MeshPlugin.hpp
@@ -0,0 +1,27 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+#pragma once
+
+#include "../RenderTypePlugin.hpp"
+#include "../BatchVertex.hpp"
+
+#include <vector>
+
+namespace esengine {
+
+/**
+ * @brief Scene-level 2D mesh renderer (Mesh2D component).
+ * @details Streams component-local geometry through the unified Batch face each
+ * frame — CPU-transformed like every 2D renderable — so meshes sort, clip,
+ * light, and multi-texture-merge exactly like sprites. The whole plugin is
+ * "vertices + BatchDrawKey + append": no bottom-layer changes.
+ */
+class MeshPlugin : public RenderTypePlugin {
+public:
+ void collect(RenderCollectContext& ctx) override;
+
+private:
+ std::vector<BatchVertex> scratch_; ///< Reused per mesh; amortizes the transform buffer.
+};
+
+} // namespace esengine