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(native): materials and .esshader compile on a device

esengine327d2f75d5a8
diff --git a/CMakeLists.txt b/CMakeLists.txt
index 05e88e8dd..cbb90ce24 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -265,6 +265,7 @@ if(ES_BUILD_WEB OR ES_BUILD_WXGAME)
src/esengine/bindings/ImmediateDrawBindings.cpp
src/esengine/bindings/GeometryBindings.cpp
src/esengine/bindings/AnimationBindings.cpp
+ src/esengine/bindings/MaterialBindings.cpp
${GENERATED_WEB_BINDINGS}
${GENERATED_EDITOR_API}
)
diff --git a/build-tools/tasks/native.js b/build-tools/tasks/native.js
index 09dd0e1cd..6fe7e09f1 100644
--- a/build-tools/tasks/native.js
+++ b/build-tools/tasks/native.js
@@ -54,6 +54,7 @@ export const ENGINE_BINDING_HEADERS = [
'GeometryBindings.hpp',
'ImmediateDrawBindings.hpp',
'AnimationBindings.hpp',
+ 'MaterialBindings.hpp',
];
export const MODULE_BINDING_HEADERS = [
diff --git a/cmake/ESEngineSources.cmake b/cmake/ESEngineSources.cmake
index a70d54afc..1be810e92 100644
--- a/cmake/ESEngineSources.cmake
+++ b/cmake/ESEngineSources.cmake
@@ -69,6 +69,9 @@ if(NOT ES_BUILD_WEB AND NOT ES_BUILD_WXGAME)
${ESENGINE_ROOT}/src/esengine/bindings/ImmediateDrawBindings.cpp
# Tweens: portable C++ that used to live in the emscripten entry TU.
${ESENGINE_ROOT}/src/esengine/bindings/AnimationBindings.cpp
+ # Materials and .esshader compilation — the surface every custom material
+ # and every post-process pass gets its shader from.
+ ${ESENGINE_ROOT}/src/esengine/bindings/MaterialBindings.cpp
# activeCtx()'s unset fallback. A host that installs its own context (the
# native one does, at boot) never reaches it, but the inline accessor
# references it, so the definition has to link.
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 9fd1a7c29..f161b2f81 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -2232,8 +2232,6 @@ anim_resumeTween: (registry: CppRegistry, tweenEntity: number) => void
anim_setSequenceNext: (registry: CppRegistry, tweenEntity: number, nextEntity: number) => void
anim_setTweenBezier: (registry: CppRegistry, tweenEntity: number, p1x: number, p1y: number, p2x: number, p2y: number) => void
anim_updateTweens: (registry: CppRegistry, deltaTime: number) => void
-compileEsshader: (source: string, featuresCsv: string) => number
-defineMaterial: (materialId: number, shader: number, blendMode: number, flags: number) => void
draw_begin: (matrixPtr: number) => void
draw_circle: (centerX: number, centerY: number, radius: number, r: number, g: number, b: number, a: number, filled: boolean, segments: number) => void
draw_circleOutline: (centerX: number, centerY: number, radius: number, r: number, g: number, b: number, a: number, thickness: number, segments: number) => void
@@ -2282,6 +2280,11 @@ initRenderer: () => void
initRendererWebGPU: (canvasSelector: string, width: number, height: number) => boolean
initRendererWithCanvas: (canvasSelector: string) => boolean
initRendererWithContext: (contextHandle: number) => boolean
+material_compileEsshader: (source: string, featuresCsv: string) => number
+material_define: (materialId: number, shaderHandle: number, blendMode: number, flags: number) => void
+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_setGeometry: ((registry: CppRegistry, entity: number, posUvPtr: number, vertexCount: number, colorsPtr: number, indicesPtr: number, indexCount: number) => void) | undefined
particle_getAliveCount: ((entity: number) => number) | undefined
particle_play: ((registry: CppRegistry, entity: number) => void) | undefined
@@ -2387,8 +2390,6 @@ renderer_submitUIElements: (registry: CppRegistry) => void
renderer_updateTransforms: (registry: CppRegistry) => void
sdfFromAlpha: ((alphaPtr: number, outPtr: number, width: number, height: number, spread: number) => void) | undefined
setActiveContext: (ctx: CppEngineContext | null) => void
-setMaterialTexture: (materialId: number, name: string, textureHandle: number) => void
-setMaterialUniform: (materialId: number, name: string, arity: number, v0: number, v1: number, v2: number, v3: number) => void
shutdownRenderer: () => void
tilemap_destroyLayer: ((entity: number) => void) | undefined
tilemap_exportChunks: ((entity: number) => string) | undefined
@@ -2419,7 +2420,6 @@ uiTree_markAllDirty: () => void
uiTree_markDirty: (entity: number) => void
uiTree_markStructureDirty: () => void
ui_getRenderOrder: ((registry: CppRegistry, entity: number) => number) | undefined
-undefineMaterial: (materialId: number) => void
```
## EasingType — type
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index c352ddefc..de0f93384 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -2240,8 +2240,6 @@ anim_resumeTween: (registry: CppRegistry, tweenEntity: number) => void
anim_setSequenceNext: (registry: CppRegistry, tweenEntity: number, nextEntity: number) => void
anim_setTweenBezier: (registry: CppRegistry, tweenEntity: number, p1x: number, p1y: number, p2x: number, p2y: number) => void
anim_updateTweens: (registry: CppRegistry, deltaTime: number) => void
-compileEsshader: (source: string, featuresCsv: string) => number
-defineMaterial: (materialId: number, shader: number, blendMode: number, flags: number) => void
draw_begin: (matrixPtr: number) => void
draw_circle: (centerX: number, centerY: number, radius: number, r: number, g: number, b: number, a: number, filled: boolean, segments: number) => void
draw_circleOutline: (centerX: number, centerY: number, radius: number, r: number, g: number, b: number, a: number, thickness: number, segments: number) => void
@@ -2290,6 +2288,11 @@ initRenderer: () => void
initRendererWebGPU: (canvasSelector: string, width: number, height: number) => boolean
initRendererWithCanvas: (canvasSelector: string) => boolean
initRendererWithContext: (contextHandle: number) => boolean
+material_compileEsshader: (source: string, featuresCsv: string) => number
+material_define: (materialId: number, shaderHandle: number, blendMode: number, flags: number) => void
+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_setGeometry: ((registry: CppRegistry, entity: number, posUvPtr: number, vertexCount: number, colorsPtr: number, indicesPtr: number, indexCount: number) => void) | undefined
particle_getAliveCount: ((entity: number) => number) | undefined
particle_play: ((registry: CppRegistry, entity: number) => void) | undefined
@@ -2395,8 +2398,6 @@ renderer_submitUIElements: (registry: CppRegistry) => void
renderer_updateTransforms: (registry: CppRegistry) => void
sdfFromAlpha: ((alphaPtr: number, outPtr: number, width: number, height: number, spread: number) => void) | undefined
setActiveContext: (ctx: CppEngineContext | null) => void
-setMaterialTexture: (materialId: number, name: string, textureHandle: number) => void
-setMaterialUniform: (materialId: number, name: string, arity: number, v0: number, v1: number, v2: number, v3: number) => void
shutdownRenderer: () => void
tilemap_destroyLayer: ((entity: number) => void) | undefined
tilemap_exportChunks: ((entity: number) => string) | undefined
@@ -2427,7 +2428,6 @@ uiTree_markAllDirty: () => void
uiTree_markDirty: (entity: number) => void
uiTree_markStructureDirty: () => void
ui_getRenderOrder: ((registry: CppRegistry, entity: number) => number) | undefined
-undefineMaterial: (materialId: number) => void
```
## EasingType — type
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 5afbda51c..dee18a8d2 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -2227,8 +2227,6 @@ anim_resumeTween: (registry: CppRegistry, tweenEntity: number) => void
anim_setSequenceNext: (registry: CppRegistry, tweenEntity: number, nextEntity: number) => void
anim_setTweenBezier: (registry: CppRegistry, tweenEntity: number, p1x: number, p1y: number, p2x: number, p2y: number) => void
anim_updateTweens: (registry: CppRegistry, deltaTime: number) => void
-compileEsshader: (source: string, featuresCsv: string) => number
-defineMaterial: (materialId: number, shader: number, blendMode: number, flags: number) => void
draw_begin: (matrixPtr: number) => void
draw_circle: (centerX: number, centerY: number, radius: number, r: number, g: number, b: number, a: number, filled: boolean, segments: number) => void
draw_circleOutline: (centerX: number, centerY: number, radius: number, r: number, g: number, b: number, a: number, thickness: number, segments: number) => void
@@ -2277,6 +2275,11 @@ initRenderer: () => void
initRendererWebGPU: (canvasSelector: string, width: number, height: number) => boolean
initRendererWithCanvas: (canvasSelector: string) => boolean
initRendererWithContext: (contextHandle: number) => boolean
+material_compileEsshader: (source: string, featuresCsv: string) => number
+material_define: (materialId: number, shaderHandle: number, blendMode: number, flags: number) => void
+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_setGeometry: ((registry: CppRegistry, entity: number, posUvPtr: number, vertexCount: number, colorsPtr: number, indicesPtr: number, indexCount: number) => void) | undefined
particle_getAliveCount: ((entity: number) => number) | undefined
particle_play: ((registry: CppRegistry, entity: number) => void) | undefined
@@ -2382,8 +2385,6 @@ renderer_submitUIElements: (registry: CppRegistry) => void
renderer_updateTransforms: (registry: CppRegistry) => void
sdfFromAlpha: ((alphaPtr: number, outPtr: number, width: number, height: number, spread: number) => void) | undefined
setActiveContext: (ctx: CppEngineContext | null) => void
-setMaterialTexture: (materialId: number, name: string, textureHandle: number) => void
-setMaterialUniform: (materialId: number, name: string, arity: number, v0: number, v1: number, v2: number, v3: number) => void
shutdownRenderer: () => void
tilemap_destroyLayer: ((entity: number) => void) | undefined
tilemap_exportChunks: ((entity: number) => string) | undefined
@@ -2414,7 +2415,6 @@ uiTree_markAllDirty: () => void
uiTree_markDirty: (entity: number) => void
uiTree_markStructureDirty: () => void
ui_getRenderOrder: ((registry: CppRegistry, entity: number) => number) | undefined
-undefineMaterial: (materialId: number) => void
```
## EasingType — type
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 03a12969c..692903dcb 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -2227,8 +2227,6 @@ anim_resumeTween: (registry: CppRegistry, tweenEntity: number) => void
anim_setSequenceNext: (registry: CppRegistry, tweenEntity: number, nextEntity: number) => void
anim_setTweenBezier: (registry: CppRegistry, tweenEntity: number, p1x: number, p1y: number, p2x: number, p2y: number) => void
anim_updateTweens: (registry: CppRegistry, deltaTime: number) => void
-compileEsshader: (source: string, featuresCsv: string) => number
-defineMaterial: (materialId: number, shader: number, blendMode: number, flags: number) => void
draw_begin: (matrixPtr: number) => void
draw_circle: (centerX: number, centerY: number, radius: number, r: number, g: number, b: number, a: number, filled: boolean, segments: number) => void
draw_circleOutline: (centerX: number, centerY: number, radius: number, r: number, g: number, b: number, a: number, thickness: number, segments: number) => void
@@ -2277,6 +2275,11 @@ initRenderer: () => void
initRendererWebGPU: (canvasSelector: string, width: number, height: number) => boolean
initRendererWithCanvas: (canvasSelector: string) => boolean
initRendererWithContext: (contextHandle: number) => boolean
+material_compileEsshader: (source: string, featuresCsv: string) => number
+material_define: (materialId: number, shaderHandle: number, blendMode: number, flags: number) => void
+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_setGeometry: ((registry: CppRegistry, entity: number, posUvPtr: number, vertexCount: number, colorsPtr: number, indicesPtr: number, indexCount: number) => void) | undefined
particle_getAliveCount: ((entity: number) => number) | undefined
particle_play: ((registry: CppRegistry, entity: number) => void) | undefined
@@ -2382,8 +2385,6 @@ renderer_submitUIElements: (registry: CppRegistry) => void
renderer_updateTransforms: (registry: CppRegistry) => void
sdfFromAlpha: ((alphaPtr: number, outPtr: number, width: number, height: number, spread: number) => void) | undefined
setActiveContext: (ctx: CppEngineContext | null) => void
-setMaterialTexture: (materialId: number, name: string, textureHandle: number) => void
-setMaterialUniform: (materialId: number, name: string, arity: number, v0: number, v1: number, v2: number, v3: number) => void
shutdownRenderer: () => void
tilemap_destroyLayer: ((entity: number) => void) | undefined
tilemap_exportChunks: ((entity: number) => string) | undefined
@@ -2414,7 +2415,6 @@ uiTree_markAllDirty: () => void
uiTree_markDirty: (entity: number) => void
uiTree_markStructureDirty: () => void
ui_getRenderOrder: ((registry: CppRegistry, entity: number) => number) | undefined
-undefineMaterial: (materialId: number) => void
```
## EasingType — type
diff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.md
index a84a21d80..d46fdd88b 100644
--- a/sdk/etc/wasm.api.md
+++ b/sdk/etc/wasm.api.md
@@ -184,8 +184,6 @@ anim_resumeTween: (registry: CppRegistry, tweenEntity: number) => void
anim_setSequenceNext: (registry: CppRegistry, tweenEntity: number, nextEntity: number) => void
anim_setTweenBezier: (registry: CppRegistry, tweenEntity: number, p1x: number, p1y: number, p2x: number, p2y: number) => void
anim_updateTweens: (registry: CppRegistry, deltaTime: number) => void
-compileEsshader: (source: string, featuresCsv: string) => number
-defineMaterial: (materialId: number, shader: number, blendMode: number, flags: number) => void
draw_begin: (matrixPtr: number) => void
draw_circle: (centerX: number, centerY: number, radius: number, r: number, g: number, b: number, a: number, filled: boolean, segments: number) => void
draw_circleOutline: (centerX: number, centerY: number, radius: number, r: number, g: number, b: number, a: number, thickness: number, segments: number) => void
@@ -234,6 +232,11 @@ initRenderer: () => void
initRendererWebGPU: (canvasSelector: string, width: number, height: number) => boolean
initRendererWithCanvas: (canvasSelector: string) => boolean
initRendererWithContext: (contextHandle: number) => boolean
+material_compileEsshader: (source: string, featuresCsv: string) => number
+material_define: (materialId: number, shaderHandle: number, blendMode: number, flags: number) => void
+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_setGeometry: ((registry: CppRegistry, entity: number, posUvPtr: number, vertexCount: number, colorsPtr: number, indicesPtr: number, indexCount: number) => void) | undefined
particle_getAliveCount: ((entity: number) => number) | undefined
particle_play: ((registry: CppRegistry, entity: number) => void) | undefined
@@ -339,8 +342,6 @@ renderer_submitUIElements: (registry: CppRegistry) => void
renderer_updateTransforms: (registry: CppRegistry) => void
sdfFromAlpha: ((alphaPtr: number, outPtr: number, width: number, height: number, spread: number) => void) | undefined
setActiveContext: (ctx: CppEngineContext | null) => void
-setMaterialTexture: (materialId: number, name: string, textureHandle: number) => void
-setMaterialUniform: (materialId: number, name: string, arity: number, v0: number, v1: number, v2: number, v3: number) => void
shutdownRenderer: () => void
tilemap_destroyLayer: ((entity: number) => void) | undefined
tilemap_exportChunks: ((entity: number) => string) | undefined
@@ -371,7 +372,6 @@ uiTree_markAllDirty: () => void
uiTree_markDirty: (entity: number) => void
uiTree_markStructureDirty: () => void
ui_getRenderOrder: ((registry: CppRegistry, entity: number) => number) | undefined
-undefineMaterial: (materialId: number) => void
```
## EmscriptenFS — interface
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 9a741033f..f86a4bc58 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -2227,8 +2227,6 @@ anim_resumeTween: (registry: CppRegistry, tweenEntity: number) => void
anim_setSequenceNext: (registry: CppRegistry, tweenEntity: number, nextEntity: number) => void
anim_setTweenBezier: (registry: CppRegistry, tweenEntity: number, p1x: number, p1y: number, p2x: number, p2y: number) => void
anim_updateTweens: (registry: CppRegistry, deltaTime: number) => void
-compileEsshader: (source: string, featuresCsv: string) => number
-defineMaterial: (materialId: number, shader: number, blendMode: number, flags: number) => void
draw_begin: (matrixPtr: number) => void
draw_circle: (centerX: number, centerY: number, radius: number, r: number, g: number, b: number, a: number, filled: boolean, segments: number) => void
draw_circleOutline: (centerX: number, centerY: number, radius: number, r: number, g: number, b: number, a: number, thickness: number, segments: number) => void
@@ -2277,6 +2275,11 @@ initRenderer: () => void
initRendererWebGPU: (canvasSelector: string, width: number, height: number) => boolean
initRendererWithCanvas: (canvasSelector: string) => boolean
initRendererWithContext: (contextHandle: number) => boolean
+material_compileEsshader: (source: string, featuresCsv: string) => number
+material_define: (materialId: number, shaderHandle: number, blendMode: number, flags: number) => void
+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_setGeometry: ((registry: CppRegistry, entity: number, posUvPtr: number, vertexCount: number, colorsPtr: number, indicesPtr: number, indexCount: number) => void) | undefined
particle_getAliveCount: ((entity: number) => number) | undefined
particle_play: ((registry: CppRegistry, entity: number) => void) | undefined
@@ -2382,8 +2385,6 @@ renderer_submitUIElements: (registry: CppRegistry) => void
renderer_updateTransforms: (registry: CppRegistry) => void
sdfFromAlpha: ((alphaPtr: number, outPtr: number, width: number, height: number, spread: number) => void) | undefined
setActiveContext: (ctx: CppEngineContext | null) => void
-setMaterialTexture: (materialId: number, name: string, textureHandle: number) => void
-setMaterialUniform: (materialId: number, name: string, arity: number, v0: number, v1: number, v2: number, v3: number) => void
shutdownRenderer: () => void
tilemap_destroyLayer: ((entity: number) => void) | undefined
tilemap_exportChunks: ((entity: number) => string) | undefined
@@ -2414,7 +2415,6 @@ uiTree_markAllDirty: () => void
uiTree_markDirty: (entity: number) => void
uiTree_markStructureDirty: () => void
ui_getRenderOrder: ((registry: CppRegistry, entity: number) => number) | undefined
-undefineMaterial: (materialId: number) => void
```
## EasingType — type
diff --git a/sdk/src/corePlugin.ts b/sdk/src/corePlugin.ts
index c4d7c290c..0d9c5362b 100644
--- a/sdk/src/corePlugin.ts
+++ b/sdk/src/corePlugin.ts
@@ -32,8 +32,8 @@ export const corePlugin: Plugin = {
});
initDrawAPI(module);
initGeometryAPI(module);
- initMaterialAPI(module);
- initPostProcessAPI(module); // the module IS the core here (see engineApi)
+ initMaterialAPI(module); // the module IS the core here (see engineApi)
+ initPostProcessAPI(module);
initRendererAPI(module);
initGLDebugAPI(module);
app.insertResource(CameraView, new CameraViewAPI(app));
diff --git a/sdk/src/ecs/nativeEngineApi.generated.ts b/sdk/src/ecs/nativeEngineApi.generated.ts
index b0cbeae52..7b14d1ea9 100644
--- a/sdk/src/ecs/nativeEngineApi.generated.ts
+++ b/sdk/src/ecs/nativeEngineApi.generated.ts
@@ -57,6 +57,11 @@ export interface NativeEngineApi {
getUINodeHiddenInTree?(registry: unknown, entity: number): boolean;
gl_checkErrors?(context: string): number;
gl_enableErrorCheck?(enabled: boolean): void;
+ material_compileEsshader?(source: string, featuresCsv: string): number;
+ material_define?(materialId: number, shaderHandle: number, blendMode: number, flags: number): void;
+ 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_setGeometry?(registry: unknown, entity: number, posUvPtr: number, vertexCount: number, colorsPtr: number, indicesPtr: number, indexCount: number): void;
particle_getAliveCount?(entity: number): number;
particle_play?(registry: unknown, entity: number): void;
@@ -282,6 +287,11 @@ export function createNativeEngineApi(
bind('getUINodeHiddenInTree', 'es_getUINodeHiddenInTree', true);
bind('gl_checkErrors', 'es_gl_checkErrors', false);
bind('gl_enableErrorCheck', 'es_gl_enableErrorCheck', false);
+ bind('material_compileEsshader', 'es_material_compileEsshader', false);
+ bind('material_define', 'es_material_define', false);
+ bind('material_setTexture', 'es_material_setTexture', false);
+ bind('material_setUniform', 'es_material_setUniform', false);
+ bind('material_undefine', 'es_material_undefine', false);
bind('mesh2d_setGeometry', 'es_mesh2d_setGeometry', true);
bind('particle_getAliveCount', 'es_particle_getAliveCount', false);
bind('particle_play', 'es_particle_play', true);
diff --git a/sdk/src/ecs/nativeRuntime.ts b/sdk/src/ecs/nativeRuntime.ts
index beded2bdb..d668692e5 100644
--- a/sdk/src/ecs/nativeRuntime.ts
+++ b/sdk/src/ecs/nativeRuntime.ts
@@ -31,6 +31,7 @@ import { createNativeSideModules } from './nativeSideModules';
import { initPostProcessAPI } from '../postprocess';
import { initDrawAPI } from '../draw';
import { initGeometryAPI } from '../geometry';
+import { initMaterialAPI } from '../material';
import type { ESEngineModule } from '../wasm';
import { log } from '../logger';
import { setRendererBackend } from '../renderer';
@@ -125,8 +126,9 @@ export function createNativeApp(
}
/**
- * The core-API facets `corePlugin` binds on the web — draw, geometry, post-process
- * — need the API connected to the core before the plugins that use them build. A
+ * The core-API facets `corePlugin` binds on the web — draw, geometry, material,
+ * post-process — need the API connected to the core before the plugins that use
+ * them build. A
* native app does not run corePlugin, so wire the ones this core compiles here,
* each guarded by an entry point it defines so a core built without one is skipped
* rather than half-connected. draw/geometry malloc their scratch buffers through
@@ -139,6 +141,14 @@ function installNativeCoreApis(app: App): void {
const module = engine as unknown as ESEngineModule;
if (typeof engine.draw_begin === 'function') initDrawAPI(module);
if (typeof engine.geometry_create === 'function') initGeometryAPI(module);
+ // Materials feed both custom .esshader assets and every post-process pass
+ // (its effect shaders compile through material_compileEsshader), so this
+ // precedes the post-process wiring below.
+ if (typeof engine.material_compileEsshader === 'function') {
+ initMaterialAPI(engine);
+ } else {
+ log.info('material', 'not available — this engine core was built without it');
+ }
if (typeof engine.postprocess_init === 'function') {
initPostProcessAPI(engine);
} else {
diff --git a/sdk/src/material.ts b/sdk/src/material.ts
index e8d4100eb..7589c00f6 100644
--- a/sdk/src/material.ts
+++ b/sdk/src/material.ts
@@ -6,8 +6,9 @@
* @details Provides shader creation and material management for custom visual effects.
*/
+import type { EngineApi } from './ecs/engineApi';
import type { ESEngineModule } from './wasm';
-import { CoreApiBridge } from './CoreApiBridge';
+import { WasmBridge } from './WasmBridge';
import { requireResourceManager } from './resourceManager';
import { awaitReadback, READBACK_READY } from './readback';
import type { Vec2, Vec3, Vec4 } from './types';
@@ -136,8 +137,40 @@ export interface MaterialData {
// Internal State
// =============================================================================
-const bridge = new CoreApiBridge('material');
-let module: ESEngineModule | null = null;
+/**
+ * The material entry points as a core that HAS them answers them. Named, not
+ * re-declared: the signatures come from the generated engine surface, so this
+ * cannot drift from the C++ (MaterialBindings.hpp) that produced it.
+ */
+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>> {
+ protected readonly label = 'material';
+}
+
+const bridge = new MaterialBridge();
+let module: MaterialCore | null = null;
let nextMaterialId = 1;
const materials = new Map<MaterialHandle, MaterialData>();
// Reverse index parent -> instances, so editing a base material re-flushes its instances.
@@ -147,10 +180,15 @@ const childrenOf = new Map<MaterialHandle, Set<MaterialHandle>>();
// Initialization
// =============================================================================
-/** @internal Wired by the engine plugins — not part of the public API. */
-export function initMaterialAPI(wasmModule: ESEngineModule): void {
- bridge.connect(wasmModule);
- module = bridge.module;
+/**
+ * @internal Wired by the engine plugins — not part of the public API.
+ * Takes whichever core is present (see ecs/engineApi.ts). A core that compiles
+ * materials out answers none of these entry points; the caller checks that before
+ * connecting, which is what makes the narrowing here sound.
+ */
+export function initMaterialAPI(engine: NonNullable<EngineApi>): void {
+ bridge.connect(engine);
+ module = bridge.module as MaterialCore;
}
export function shutdownMaterialAPI(): void {
@@ -183,11 +221,11 @@ function unregisterChild(parent: MaterialHandle, child: MaterialHandle): void {
function pushUniform(handle: MaterialHandle, name: string, value: UniformValue): void {
if (!module) return;
if (isTextureRef(value)) {
- module.setMaterialTexture(handle, name, value.textureId);
+ module.material_setTexture(handle, name, value.textureId);
return;
}
const { arity, values } = classifyUniformArity(value);
- module.setMaterialUniform(handle, name, arity, values[0], values[1], values[2], values[3]);
+ module.material_setUniform(handle, name, arity, values[0], values[1], values[2], values[3]);
}
interface ResolvedMaterial {
@@ -229,7 +267,7 @@ function resolveMaterial(handle: MaterialHandle): ResolvedMaterial | null {
function flushMaterial(handle: MaterialHandle): void {
const resolved = resolveMaterial(handle);
if (resolved && module) {
- module.defineMaterial(handle, resolved.shader, resolved.blendMode,
+ module.material_define(handle, resolved.shader, resolved.blendMode,
materialFlags(resolved.depthTest, resolved.depthWrite, resolved.cull));
for (const [name, value] of resolved.uniforms) pushUniform(handle, name, value);
}
@@ -321,7 +359,7 @@ export const Material = {
* should reach the GPU. Returns a shader handle, or 0 on failure.
*/
compileShader(esshaderSource: string, features: string[] = []): ShaderHandle {
- return module?.compileEsshader(esshaderSource, features.join(',')) ?? 0;
+ return module?.material_compileEsshader(esshaderSource, features.join(',')) ?? 0;
},
/** Gets an enabled static switch (false when unset). */
@@ -447,7 +485,7 @@ export const Material = {
if (data?.parent !== undefined) unregisterChild(data.parent, material);
childrenOf.delete(material); // orphaned instances fall back to their own values (resolve is defensive)
materials.delete(material);
- module?.undefineMaterial(material);
+ module?.material_undefine(material);
},
/**
@@ -468,7 +506,7 @@ export const Material = {
* readback fails.
*/
async renderPreview(material: MaterialHandle, w: number, h: number): Promise<ImageData | null> {
- const m = module;
+ const m = previewCore(module);
if (!m) return null;
m.renderer_renderMaterialPreview(material, w, h);
if (await awaitReadback(() => m.renderer_pollPreviewReadback()) !== READBACK_READY) {
@@ -490,7 +528,7 @@ export const Material = {
releaseAll(): void {
if (module) {
- for (const handle of materials.keys()) module.undefineMaterial(handle);
+ for (const handle of materials.keys()) module.material_undefine(handle);
}
materials.clear();
childrenOf.clear();
diff --git a/sdk/src/wasm.ts b/sdk/src/wasm.ts
index 60c5d0d74..52c0b9223 100644
--- a/sdk/src/wasm.ts
+++ b/sdk/src/wasm.ts
@@ -205,19 +205,18 @@ export interface ESEngineModule {
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).
- // Compiles a .esshader through ShaderParser (auto-generating the MaterialConstants block +
- // the enabled #pragma switch / feature permutation from featuresCsv) and registers its param
- // layout; returns the shader resource handle (0 on failure).
- compileEsshader(source: string, featuresCsv: string): number;
- defineMaterial(materialId: number, shader: number, blendMode: number, flags: number): void;
- // Packs a named param's components into the material's std140 UBO by reflected offset.
- setMaterialUniform(materialId: number, name: string, arity: number,
- v0: number, v1: number, v2: number, v3: number): void;
- // Binds a texture param to its sampler unit; textureHandle is a texture resource handle.
- setMaterialTexture(materialId: number, name: string, textureHandle: number): void;
- undefineMaterial(materialId: number): void;
+ // Material API. Materials are engine-side data: the SDK compiles a shader
+ // here, then pushes the resolved render state (flags pack depthTest bit 0,
+ // depthWrite bit 1, CullMode bits 2-3) and the param values. Reached through
+ // the generated engine surface rather than this interface (see material.ts),
+ // which is what makes them work on a device too; declared here because embind
+ // registers them by hand for the web.
+ material_compileEsshader(source: string, featuresCsv: string): number;
+ material_define(materialId: number, shaderHandle: number, blendMode: number, flags: number): void;
+ material_setUniform(materialId: number, name: string, arity: number,
+ v0: number, v1: number, v2: number, v3: number): void;
+ material_setTexture(materialId: number, name: string, textureHandle: number): void;
+ material_undefine(materialId: number): void;
// ImmediateDraw API
draw_begin(matrixPtr: number): void;
diff --git a/sdk/tests/binding-surface.test.ts b/sdk/tests/binding-surface.test.ts
index 0417ebf7b..7ba0c4fe9 100644
--- a/sdk/tests/binding-surface.test.ts
+++ b/sdk/tests/binding-surface.test.ts
@@ -460,6 +460,8 @@ const pooledModuleCpp = [
'bindings/TilemapBindings.hpp',
'bindings/AnimationBindings.hpp',
'bindings/AnimationBindings.cpp',
+ 'bindings/MaterialBindings.hpp',
+ 'bindings/MaterialBindings.cpp',
].map((f) => stripComments(read(resolve(CPP, f)))).join('\n');
function expectArities(label: string, tsSigs: Map<string, number>, cppSigs: Map<string, number>): void {
diff --git a/sdk/tests/material.test.ts b/sdk/tests/material.test.ts
index 7303c8ea1..38b0457db 100644
--- a/sdk/tests/material.test.ts
+++ b/sdk/tests/material.test.ts
@@ -33,11 +33,11 @@ function createMaterialMockModule() {
getResourceManager: vi.fn(() => resourceManager),
resourceManager,
// The engine-side material store push (replaces the old pull callback + cache).
- compileEsshader: vi.fn().mockReturnValue(7),
- defineMaterial: vi.fn(),
- setMaterialUniform: vi.fn(),
- setMaterialTexture: vi.fn(),
- undefineMaterial: vi.fn(),
+ material_compileEsshader: vi.fn().mockReturnValue(7),
+ material_define: vi.fn(),
+ material_setUniform: vi.fn(),
+ material_setTexture: vi.fn(),
+ material_undefine: vi.fn(),
};
return mock;
@@ -45,7 +45,7 @@ function createMaterialMockModule() {
type MockModule = ReturnType<typeof createMaterialMockModule>;
-// Render-state flags the SDK packs for defineMaterial: depthTest (bit 0),
+// Render-state flags the SDK packs for material_define: depthTest (bit 0),
// depthWrite (bit 1), CullMode (bits 2-3).
function flags(depthTest: boolean, depthWrite: boolean, cull: CullMode): number {
return (depthTest ? 0x1 : 0) | (depthWrite ? 0x2 : 0) | ((cull & 0x3) << 2);
@@ -161,7 +161,7 @@ describe('Material API', () => {
depthTest: true,
cull: CullMode.Back,
});
- expect(mock.defineMaterial).toHaveBeenCalledWith(
+ expect(mock.material_define).toHaveBeenCalledWith(
h, 42, BlendMode.Additive, flags(true, true, CullMode.Back),
);
});
@@ -221,7 +221,7 @@ describe('Material API', () => {
const h = Material.create({ shader: 1 as ShaderHandle });
Material.release(h);
expect(Material.isValid(h)).toBe(false);
- expect(mock.undefineMaterial).toHaveBeenCalledWith(h);
+ expect(mock.material_undefine).toHaveBeenCalledWith(h);
});
});
@@ -232,8 +232,8 @@ describe('Material API', () => {
Material.releaseAll();
expect(Material.isValid(h1)).toBe(false);
expect(Material.isValid(h2)).toBe(false);
- expect(mock.undefineMaterial).toHaveBeenCalledWith(h1);
- expect(mock.undefineMaterial).toHaveBeenCalledWith(h2);
+ expect(mock.material_undefine).toHaveBeenCalledWith(h1);
+ expect(mock.material_undefine).toHaveBeenCalledWith(h2);
});
});
@@ -296,9 +296,9 @@ describe('Material API', () => {
it('should push the new state on setBlendMode', () => {
const h = Material.create({ shader: 1 as ShaderHandle });
- mock.defineMaterial.mockClear();
+ mock.material_define.mockClear();
Material.setBlendMode(h, BlendMode.Additive);
- expect(mock.defineMaterial).toHaveBeenCalledWith(
+ expect(mock.material_define).toHaveBeenCalledWith(
h, 1, BlendMode.Additive, flags(false, true, CullMode.None),
);
});
@@ -311,30 +311,30 @@ describe('Material API', () => {
describe('DepthTest / DepthWrite / Cull', () => {
it('should set depth test and push state', () => {
const h = Material.create({ shader: 1 as ShaderHandle });
- mock.defineMaterial.mockClear();
+ mock.material_define.mockClear();
Material.setDepthTest(h, true);
expect(Material.get(h)!.depthTest).toBe(true);
- expect(mock.defineMaterial).toHaveBeenCalledWith(
+ expect(mock.material_define).toHaveBeenCalledWith(
h, 1, BlendMode.Normal, flags(true, true, CullMode.None),
);
});
it('should set depth write and push state', () => {
const h = Material.create({ shader: 1 as ShaderHandle });
- mock.defineMaterial.mockClear();
+ mock.material_define.mockClear();
Material.setDepthWrite(h, false);
expect(Material.get(h)!.depthWrite).toBe(false);
- expect(mock.defineMaterial).toHaveBeenCalledWith(
+ expect(mock.material_define).toHaveBeenCalledWith(
h, 1, BlendMode.Normal, flags(false, false, CullMode.None),
);
});
it('should set cull mode and push state', () => {
const h = Material.create({ shader: 1 as ShaderHandle });
- mock.defineMaterial.mockClear();
+ mock.material_define.mockClear();
Material.setCull(h, CullMode.Front);
expect(Material.get(h)!.cull).toBe(CullMode.Front);
- expect(mock.defineMaterial).toHaveBeenCalledWith(
+ expect(mock.material_define).toHaveBeenCalledWith(
h, 1, BlendMode.Normal, flags(false, true, CullMode.Front),
);
});
@@ -444,9 +444,9 @@ describe('Material API', () => {
it('should push the flattened (inherited) instance to the engine store', () => {
const src = Material.create({ shader: 5 as ShaderHandle, blendMode: BlendMode.Multiply });
- mock.defineMaterial.mockClear();
+ mock.material_define.mockClear();
const inst = Material.createInstance(src);
- expect(mock.defineMaterial).toHaveBeenCalledWith(
+ expect(mock.material_define).toHaveBeenCalledWith(
inst, 5, BlendMode.Multiply, flags(false, true, CullMode.None),
);
});
@@ -489,11 +489,11 @@ describe('Material API', () => {
it('a parent edit re-pushes the instance to the engine (propagation)', () => {
const src = Material.create({ shader: 1 as ShaderHandle, uniforms: { u_val: 10 } });
const inst = Material.createInstance(src);
- mock.setMaterialUniform.mockClear();
+ mock.material_setUniform.mockClear();
Material.setUniform(src, 'u_val', 99);
// Both the parent and the inheriting instance are re-pushed with the new value.
- expect(mock.setMaterialUniform).toHaveBeenCalledWith(src, 'u_val', 1, 99, 0, 0, 0);
- expect(mock.setMaterialUniform).toHaveBeenCalledWith(inst, 'u_val', 1, 99, 0, 0, 0);
+ expect(mock.material_setUniform).toHaveBeenCalledWith(src, 'u_val', 1, 99, 0, 0, 0);
+ expect(mock.material_setUniform).toHaveBeenCalledWith(inst, 'u_val', 1, 99, 0, 0, 0);
});
it('should throw for invalid source', () => {
@@ -648,16 +648,16 @@ describe('Material API', () => {
// =========================================================================
describe('material parameter push', () => {
- it('compileShader proxies to module.compileEsshader (no switches => empty features)', () => {
+ it('compileShader proxies to module.material_compileEsshader (no switches => empty features)', () => {
const h = Material.compileShader('#pragma shader "x"');
expect(h).toBe(7);
- expect(mock.compileEsshader).toHaveBeenCalledWith('#pragma shader "x"', '');
+ expect(mock.material_compileEsshader).toHaveBeenCalledWith('#pragma shader "x"', '');
});
it('compileShader passes enabled switches as a CSV feature set', () => {
- mock.compileEsshader.mockClear();
+ mock.material_compileEsshader.mockClear();
Material.compileShader('src', ['USE_A', 'USE_B']);
- expect(mock.compileEsshader).toHaveBeenCalledWith('src', 'USE_A,USE_B');
+ expect(mock.material_compileEsshader).toHaveBeenCalledWith('src', 'USE_A,USE_B');
});
it('stores static switches and round-trips them through toAssetData', () => {
@@ -673,23 +673,23 @@ describe('Material API', () => {
shader: 1 as ShaderHandle,
uniforms: { u_tint: { x: 1, y: 0, z: 0, w: 1 } },
});
- expect(mock.setMaterialUniform).toHaveBeenCalledWith(h, 'u_tint', 4, 1, 0, 0, 1);
+ expect(mock.material_setUniform).toHaveBeenCalledWith(h, 'u_tint', 4, 1, 0, 0, 1);
});
it('pushes the value on setUniform', () => {
const h = Material.create({ shader: 1 as ShaderHandle });
- mock.setMaterialUniform.mockClear();
+ mock.material_setUniform.mockClear();
Material.setUniform(h, 'u_strength', 2.5);
- expect(mock.setMaterialUniform).toHaveBeenCalledWith(h, 'u_strength', 1, 2.5, 0, 0, 0);
+ expect(mock.material_setUniform).toHaveBeenCalledWith(h, 'u_strength', 1, 2.5, 0, 0, 0);
});
- it('routes texture refs to setMaterialTexture (not the std140 uniform path)', () => {
+ it('routes texture refs to material_setTexture (not the std140 uniform path)', () => {
const h = Material.create({ shader: 1 as ShaderHandle });
- mock.setMaterialUniform.mockClear();
- mock.setMaterialTexture.mockClear();
+ mock.material_setUniform.mockClear();
+ mock.material_setTexture.mockClear();
Material.setUniform(h, 'u_tex', Material.tex(5));
- expect(mock.setMaterialUniform).not.toHaveBeenCalled();
- expect(mock.setMaterialTexture).toHaveBeenCalledWith(h, 'u_tex', 5);
+ expect(mock.material_setUniform).not.toHaveBeenCalled();
+ expect(mock.material_setTexture).toHaveBeenCalledWith(h, 'u_tex', 5);
});
});
diff --git a/src/esengine/bindings/MaterialBindings.cpp b/src/esengine/bindings/MaterialBindings.cpp
new file mode 100644
index 000000000..c47166424
--- /dev/null
+++ b/src/esengine/bindings/MaterialBindings.cpp
@@ -0,0 +1,161 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file MaterialBindings.cpp
+ * @brief Implementation of the material / `.esshader` entry points.
+ */
+
+#include "MaterialBindings.hpp"
+#include "ActiveContext.hpp"
+
+#include "../core/Log.hpp"
+#include "../renderer/MaterialStore.hpp"
+#include "../renderer/RenderContext.hpp"
+#include "../renderer/Shader.hpp"
+#include "../renderer/Texture.hpp"
+#include "../resource/ResourceManager.hpp"
+#include "../resource/ShaderParser.hpp"
+
+#include <cstdlib>
+#include <sstream>
+
+namespace esengine {
+
+static EstellaContext& ctx() { return activeCtx(); }
+
+#define g_renderContext (ctx().tryGet<RenderContext>())
+#define g_resourceManager (ctx().tryGet<resource::ResourceManager>())
+
+// Float component count for a std140 param type (textures have no block slot).
+static u32 materialParamArity(resource::ShaderPropertyType t) {
+ using PT = resource::ShaderPropertyType;
+ switch (t) {
+ case PT::Float: case PT::Int: return 1;
+ case PT::Vec2: return 2;
+ case PT::Vec3: return 3;
+ case PT::Vec4: case PT::Color: return 4;
+ default: return 0;
+ }
+}
+
+// Build the engine-side layout from a parsed shader's #pragma param reflection: non-texture
+// params into the std140 block (declared order == offset order), texture params into sampler
+// slots (their reflected units, >= MATERIAL_TEXTURE_UNIT_BASE).
+static MaterialUniformLayout buildMaterialLayout(const resource::ParsedShader& parsed,
+ const RenderContext& rc) {
+ MaterialUniformLayout layout;
+ layout.blockSize = parsed.materialBlockSize;
+ for (const auto& p : parsed.properties) {
+ if (!p.fromParam) continue;
+ if (p.type == resource::ShaderPropertyType::Texture) {
+ if (p.textureUnit >= 0) {
+ // Resolve the param's `default(<name>)` to a built-in default texture, bound when
+ // a material leaves the param unset.
+ layout.textures.push_back({ p.name, static_cast<u32>(p.textureUnit),
+ rc.defaultTextureByName(p.defaultValue) });
+ }
+ } else if (p.std140Offset >= 0) {
+ MaterialParamSlot slot{ p.name, static_cast<u32>(p.std140Offset), materialParamArity(p.type) };
+ // default(a,b,c,d) csv → the slot's initial block value.
+ std::istringstream csv(p.defaultValue);
+ std::string tok;
+ for (u32 i = 0; i < slot.arity && std::getline(csv, tok, ','); ++i) {
+ slot.defaults[i] = std::strtof(tok.c_str(), nullptr);
+ }
+ layout.params.push_back(slot);
+ }
+ }
+ return layout;
+}
+
+u32 material_compileEsshader(const std::string& source, const std::string& featuresCsv) {
+ auto* rm = g_resourceManager;
+ if (!rm) return 0;
+ resource::ParsedShader parsed = resource::ShaderParser::parse(source);
+ if (!parsed.valid) {
+ ES_LOG_ERROR("material_compileEsshader: parse failed: {}", parsed.errorMessage);
+ return 0;
+ }
+ const std::vector<std::string> features = resource::ShaderParser::splitFeatures(featuresCsv);
+ // Assemble both stages for the backend's language — a material .esshader
+ // carries its WGSL twin in-file, and a missing twin surfaces here as a
+ // descriptive assembly error rather than a backend compile failure.
+ const auto target = rm->preferredShaderTarget();
+ const std::string vert = resource::ShaderParser::assembleStage(parsed, resource::ShaderStage::Vertex, "", features, target);
+ const std::string frag = resource::ShaderParser::assembleStage(parsed, resource::ShaderStage::Fragment, "", features, target);
+ if (vert.empty() || frag.empty()) {
+ ES_LOG_ERROR("material_compileEsshader: stage assembly failed for '{}'", parsed.name);
+ return 0;
+ }
+ // No DrawParams rewrite: assembled material sources already carry their
+ // params in MaterialConstants; only sampler uniforms remain loose.
+ resource::ShaderHandle handle = rm->createShader(vert, frag, /*rewriteLoose=*/false,
+ rm->preferredShaderLanguage());
+ if (!handle.isValid()) return 0;
+ if (auto* rc = g_renderContext) {
+ if (Shader* s = rm->getShader(handle)) {
+ rc->materials().registerLayout(s->getProgramId(), buildMaterialLayout(parsed, *rc));
+ // Point each texture param's sampler at its unit, once per program (GLSL ES 300 has
+ // no layout(binding=); mirrors the batch path's u_textures setup in RenderFrame).
+ // Sampler seeding is a GLSL concept; on WGSL the unit rides the bind group.
+ if (s->language() == GfxShaderLanguage::GLSL_ES300) {
+ s->bind();
+ for (const auto& p : parsed.properties) {
+ if (p.fromParam && p.type == resource::ShaderPropertyType::Texture && p.textureUnit >= 0) {
+ s->setUniform(p.name, static_cast<i32>(p.textureUnit));
+ }
+ }
+ s->unbind();
+ }
+ }
+ }
+ return handle.id();
+}
+
+void material_define(u32 materialId, u32 shaderHandle, u32 blendMode, u32 flags) {
+ auto* rc = g_renderContext;
+ if (!rc) return;
+ u32 programId = 0;
+ if (shaderHandle != 0) {
+ if (auto* rm = g_resourceManager) {
+ if (Shader* s = rm->getShader(resource::ShaderHandle(shaderHandle))) {
+ programId = s->getProgramId();
+ }
+ }
+ }
+ MaterialRecord rec;
+ rec.shader = programId;
+ rec.blend = static_cast<BlendMode>(blendMode);
+ rec.depthTest = (flags & 0x1u) != 0;
+ rec.depthWrite = (flags & 0x2u) != 0;
+ rec.cull = static_cast<CullMode>((flags >> 2) & 0x3u);
+ rc->materials().define(materialId, rec);
+}
+
+void material_setUniform(u32 materialId, const std::string& name, u32 arity,
+ f32 v0, f32 v1, f32 v2, f32 v3) {
+ auto* rc = g_renderContext;
+ if (!rc) return;
+ const f32 vals[4] = { v0, v1, v2, v3 };
+ rc->materials().setUniform(materialId, name, vals, arity);
+}
+
+void material_setTexture(u32 materialId, const std::string& name, u32 textureHandle) {
+ auto* rc = g_renderContext;
+ if (!rc) return;
+ u32 gpuTexture = 0;
+ if (textureHandle != 0) {
+ if (auto* rm = g_resourceManager) {
+ if (Texture* t = rm->getTexture(resource::TextureHandle(textureHandle))) {
+ gpuTexture = t->getId();
+ }
+ }
+ }
+ rc->materials().setTexture(materialId, name, gpuTexture);
+}
+
+void material_undefine(u32 materialId) {
+ if (auto* rc = g_renderContext) rc->materials().undefine(materialId);
+}
+
+} // namespace esengine
diff --git a/src/esengine/bindings/MaterialBindings.hpp b/src/esengine/bindings/MaterialBindings.hpp
new file mode 100644
index 000000000..8fd186020
--- /dev/null
+++ b/src/esengine/bindings/MaterialBindings.hpp
@@ -0,0 +1,53 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file MaterialBindings.hpp
+ * @brief Material + `.esshader` entry points, for whichever core is embedded.
+ *
+ * @details A material is engine-side data: the SDK compiles its shader here, then
+ * pushes the resolved render state and param values, and the render path
+ * reads them by the handle a component carries. These used to live in the
+ * web entry point as hand-written embind, which made every material — and
+ * every post-process pass, whose shader compiles through the same
+ * `material_compileEsshader` — web-only by construction. Declared here,
+ * EHT generates the native wrappers from the same source embind registers.
+ */
+#pragma once
+
+
+#include "../core/Types.hpp"
+#include <string>
+
+namespace esengine {
+
+/**
+ * Compile a `.esshader` through the full ShaderParser path — assembling the
+ * auto-generated MaterialConstants block plus the requested feature/switch
+ * permutation (each feature -> `#define NAME 1`) — and register its param layout.
+ * @p featuresCsv is the enabled `#pragma switch` set, comma-separated, so a
+ * material's static switches select a permutation; the SDK loader caches one
+ * compiled program per (shader, switch-set). Returns the shader resource handle,
+ * or 0 on failure.
+ */
+u32 material_compileEsshader(const std::string& source, const std::string& featuresCsv);
+
+/**
+ * Publish a material's resolved render state. @p shaderHandle is the SDK shader
+ * resource handle, translated here to the program id the render path binds;
+ * @p flags packs depthTest (bit 0), depthWrite (bit 1) and CullMode (bits 2-3).
+ * Param values arrive separately, via material_setUniform / material_setTexture.
+ */
+void material_define(u32 materialId, u32 shaderHandle, u32 blendMode, u32 flags);
+
+/** Pack a named param's float components into the material's std140 block, by
+ * reflected offset. A no-op when the shader declares no matching `#pragma param`. */
+void material_setUniform(u32 materialId, const std::string& name, u32 arity,
+ f32 v0, f32 v1, f32 v2, f32 v3);
+
+/** Bind a texture param to its reflected sampler unit. @p textureHandle is an SDK
+ * texture resource handle; 0 clears the binding back to the param's default. */
+void material_setTexture(u32 materialId, const std::string& name, u32 textureHandle);
+
+void material_undefine(u32 materialId);
+
+} // namespace esengine
diff --git a/src/esengine/bindings/WebSDKEntry.cpp b/src/esengine/bindings/WebSDKEntry.cpp
index ceef0ffcd..0b9d0333a 100644
--- a/src/esengine/bindings/WebSDKEntry.cpp
+++ b/src/esengine/bindings/WebSDKEntry.cpp
@@ -25,6 +25,7 @@
#include "ImmediateDrawBindings.hpp"
#include "GeometryBindings.hpp"
#include "AnimationBindings.hpp"
+#include "MaterialBindings.hpp"
#ifdef ES_ENABLE_POSTPROCESS
#include "PostProcessBindings.hpp"
#endif
@@ -87,115 +88,6 @@ static EstellaContext& ctx() { return activeCtx(); }
#define g_particleSystem (ctx().tryGet<particle::ParticleSystem>())
#endif
-// Float component count for a std140 param type (textures have no block slot).
-static u32 materialParamArity(resource::ShaderPropertyType t) {
- using PT = resource::ShaderPropertyType;
- switch (t) {
- case PT::Float: case PT::Int: return 1;
- case PT::Vec2: return 2;
- case PT::Vec3: return 3;
- case PT::Vec4: case PT::Color: return 4;
- default: return 0;
- }
-}
-
-// Build the engine-side layout from a parsed shader's #pragma param reflection: non-texture
-// params into the std140 block (declared order == offset order), texture params into sampler
-// slots (their reflected units, >= MATERIAL_TEXTURE_UNIT_BASE).
-static MaterialUniformLayout buildMaterialLayout(const resource::ParsedShader& parsed,
- const RenderContext& rc) {
- MaterialUniformLayout layout;
- layout.blockSize = parsed.materialBlockSize;
- for (const auto& p : parsed.properties) {
- if (!p.fromParam) continue;
- if (p.type == resource::ShaderPropertyType::Texture) {
- if (p.textureUnit >= 0) {
- // Resolve the param's `default(<name>)` to a built-in default texture, bound when
- // a material leaves the param unset.
- layout.textures.push_back({ p.name, static_cast<u32>(p.textureUnit),
- rc.defaultTextureByName(p.defaultValue) });
- }
- } else if (p.std140Offset >= 0) {
- MaterialParamSlot slot{ p.name, static_cast<u32>(p.std140Offset), materialParamArity(p.type) };
- // default(a,b,c,d) csv → the slot's initial block value.
- std::istringstream csv(p.defaultValue);
- std::string tok;
- for (u32 i = 0; i < slot.arity && std::getline(csv, tok, ','); ++i) {
- slot.defaults[i] = std::strtof(tok.c_str(), nullptr);
- }
- layout.params.push_back(slot);
- }
- }
- return layout;
-}
-
-// Compiles a .esshader (material shader) through the full ShaderParser path — assembling the
-// auto-generated MaterialConstants block + the requested feature/switch permutation (each
-// feature -> `#define NAME 1`) — and registers its param layout. @p featuresCsv is the enabled
-// `#pragma switch` set (comma-separated), so a material's static switches select a permutation;
-// the SDK loader caches one compiled program per (shader, switch-set). Returns the shader
-// resource handle (0 on failure). Reflection-aware replacement for the loader's old regex.
-// Split a comma-separated feature list into trimmed, non-empty entries.
-static std::vector<std::string> splitFeaturesCsv(const std::string& featuresCsv) {
- std::vector<std::string> features;
- for (usize start = 0; start <= featuresCsv.size();) {
- const usize comma = featuresCsv.find(',', start);
- const usize end = comma == std::string::npos ? featuresCsv.size() : comma;
- std::string f = featuresCsv.substr(start, end - start);
- // trim
- const usize a = f.find_first_not_of(" \t");
- const usize b = f.find_last_not_of(" \t");
- if (a != std::string::npos) features.push_back(f.substr(a, b - a + 1));
- if (comma == std::string::npos) break;
- start = comma + 1;
- }
- return features;
-}
-
-u32 compileEsshader(const std::string& source, const std::string& featuresCsv) {
- auto* rm = g_resourceManager;
- if (!rm) return 0;
- resource::ParsedShader parsed = resource::ShaderParser::parse(source);
- if (!parsed.valid) {
- ES_LOG_ERROR("compileEsshader: parse failed: {}", parsed.errorMessage);
- return 0;
- }
- std::vector<std::string> features = splitFeaturesCsv(featuresCsv);
- // Assemble both stages for the backend's language — a material .esshader
- // carries its WGSL twin in-file, and a missing twin surfaces here as a
- // descriptive assembly error rather than a backend compile failure.
- const auto target = rm->preferredShaderTarget();
- const std::string vert = resource::ShaderParser::assembleStage(parsed, resource::ShaderStage::Vertex, "", features, target);
- const std::string frag = resource::ShaderParser::assembleStage(parsed, resource::ShaderStage::Fragment, "", features, target);
- if (vert.empty() || frag.empty()) {
- ES_LOG_ERROR("compileEsshader: stage assembly failed for '{}'", parsed.name);
- return 0;
- }
- // No DrawParams rewrite: assembled material sources already carry their
- // params in MaterialConstants; only sampler uniforms remain loose.
- resource::ShaderHandle handle = rm->createShader(vert, frag, /*rewriteLoose=*/false,
- rm->preferredShaderLanguage());
- if (!handle.isValid()) return 0;
- if (auto* rc = g_renderContext) {
- if (Shader* s = rm->getShader(handle)) {
- rc->materials().registerLayout(s->getProgramId(), buildMaterialLayout(parsed, *rc));
- // Point each texture param's sampler at its unit, once per program (GLSL ES 300 has
- // no layout(binding=); mirrors the batch path's u_textures setup in RenderFrame).
- // Sampler seeding is a GLSL concept; on WGSL the unit rides the bind group.
- if (s->language() == GfxShaderLanguage::GLSL_ES300) {
- s->bind();
- for (const auto& p : parsed.properties) {
- if (p.fromParam && p.type == resource::ShaderPropertyType::Texture && p.textureUnit >= 0) {
- s->setUniform(p.name, static_cast<i32>(p.textureUnit));
- }
- }
- s->unbind();
- }
- }
- }
- return handle.id();
-}
-
// Cook-time introspection: assembles both GLSL stages exactly as the runtime would
// (same parser + injected headers), plus the reflection a GLSL→WGSL converter needs
// (texture params → sampler units). The export cook feeds the assembled stages through
@@ -210,7 +102,7 @@ emscripten::val esshader_cookInfo(const std::string& source, const std::string&
out.set("error", parsed.errorMessage);
return out;
}
- const std::vector<std::string> features = splitFeaturesCsv(featuresCsv);
+ const std::vector<std::string> features = resource::ShaderParser::splitFeatures(featuresCsv);
const std::string vert = resource::ShaderParser::assembleStage(
parsed, resource::ShaderStage::Vertex, "", features,
resource::ShaderTargetLanguage::GLSL_ES300);
@@ -238,61 +130,6 @@ emscripten::val esshader_cookInfo(const std::string& source, const std::string&
return out;
}
-// Materials are engine-side data: the SDK pushes a material's resolved render state here when
-// it is created or edited, and the render path reads it by the handle a component carries
-// (Sprite::material, etc.). `shaderHandle` is the SDK shader resource handle, translated here
-// to the GL program id the render path binds. flags packs depthTest (bit 0), depthWrite
-// (bit 1) and CullMode (bits 2-3). Per-material uniform values arrive via setMaterialUniform.
-void defineMaterial(u32 materialId, u32 shaderHandle, u32 blendMode, u32 flags) {
- auto* rc = g_renderContext;
- if (!rc) return;
- u32 programId = 0;
- if (shaderHandle != 0) {
- if (auto* rm = g_resourceManager) {
- if (Shader* s = rm->getShader(resource::ShaderHandle(shaderHandle))) {
- programId = s->getProgramId();
- }
- }
- }
- MaterialRecord rec;
- rec.shader = programId;
- rec.blend = static_cast<BlendMode>(blendMode);
- rec.depthTest = (flags & 0x1u) != 0;
- rec.depthWrite = (flags & 0x2u) != 0;
- rec.cull = static_cast<CullMode>((flags >> 2) & 0x3u);
- rc->materials().define(materialId, rec);
-}
-
-// Packs a named param's float components into the material's std140 buffer (by reflected
-// offset). A no-op for materials whose shader declares no matching #pragma param.
-void setMaterialUniform(u32 materialId, const std::string& name, u32 arity,
- f32 v0, f32 v1, f32 v2, f32 v3) {
- auto* rc = g_renderContext;
- if (!rc) return;
- const f32 vals[4] = { v0, v1, v2, v3 };
- rc->materials().setUniform(materialId, name, vals, arity);
-}
-
-// Binds a texture param to its sampler unit. `textureHandle` is the SDK texture resource
-// handle, resolved here to the GL texture id the render path binds. No-op for an unknown param.
-void setMaterialTexture(u32 materialId, const std::string& name, u32 textureHandle) {
- auto* rc = g_renderContext;
- if (!rc) return;
- u32 glTex = 0;
- if (textureHandle != 0) {
- if (auto* rm = g_resourceManager) {
- if (Texture* t = rm->getTexture(resource::TextureHandle(textureHandle))) {
- glTex = t->getId();
- }
- }
- }
- rc->materials().setTexture(materialId, name, glTex);
-}
-
-void undefineMaterial(u32 materialId) {
- if (auto* rc = g_renderContext) rc->materials().undefine(materialId);
-}
-
// Build provenance signature — kept self-contained (not via the umbrella
// header) so the literal is guaranteed to land in this translation unit and
// survive in the shipped binary. Emitted once at init as an origin marker.
@@ -541,12 +378,12 @@ EMSCRIPTEN_BINDINGS(esengine_renderer) {
emscripten::function("renderer_submitTextBatch", &esengine::renderer_submitTextBatch);
emscripten::function("mesh2d_setGeometry", &esengine::mesh2d_setGeometry);
- emscripten::function("compileEsshader", &esengine::compileEsshader);
+ emscripten::function("material_compileEsshader", &esengine::material_compileEsshader);
emscripten::function("esshader_cookInfo", &esengine::esshader_cookInfo);
- emscripten::function("defineMaterial", &esengine::defineMaterial);
- emscripten::function("setMaterialUniform", &esengine::setMaterialUniform);
- emscripten::function("setMaterialTexture", &esengine::setMaterialTexture);
- emscripten::function("undefineMaterial", &esengine::undefineMaterial);
+ emscripten::function("material_define", &esengine::material_define);
+ emscripten::function("material_setUniform", &esengine::material_setUniform);
+ emscripten::function("material_setTexture", &esengine::material_setTexture);
+ emscripten::function("material_undefine", &esengine::material_undefine);
emscripten::function("draw_begin", &esengine::draw_begin);
emscripten::function("draw_end", &esengine::draw_end);
diff --git a/src/esengine/resource/ShaderParser.cpp b/src/esengine/resource/ShaderParser.cpp
index 0359089bc..f0bab1c31 100644
--- a/src/esengine/resource/ShaderParser.cpp
+++ b/src/esengine/resource/ShaderParser.cpp
@@ -506,6 +506,19 @@ std::string ShaderParser::variantKey(const std::vector<std::string>& features) {
return key;
}
+std::vector<std::string> ShaderParser::splitFeatures(const std::string& csv) {
+ std::vector<std::string> features;
+ for (usize start = 0; start <= csv.size();) {
+ const usize comma = csv.find(',', start);
+ const usize end = comma == std::string::npos ? csv.size() : comma;
+ const std::string f = trim(csv.substr(start, end - start));
+ if (!f.empty()) features.push_back(f);
+ if (comma == std::string::npos) break;
+ start = comma + 1;
+ }
+ return features;
+}
+
namespace {
u32 countNewlines(const std::string& s) {
diff --git a/src/esengine/resource/ShaderParser.hpp b/src/esengine/resource/ShaderParser.hpp
index 7cead5f29..f653cf8b1 100644
--- a/src/esengine/resource/ShaderParser.hpp
+++ b/src/esengine/resource/ShaderParser.hpp
@@ -278,6 +278,12 @@ public:
*/
static std::string variantKey(const std::vector<std::string>& features);
+ /**
+ * @brief Split a comma-separated feature/switch list into trimmed, non-empty
+ * entries — the form the boundary carries a permutation in.
+ */
+ static std::vector<std::string> splitFeatures(const std::string& csv);
+
/**
* @brief Process-global color-space mode. When linear, every assembled
* stage compiles with ES_LINEAR defined (GLSL #define / WGSL