A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
feat(native): materials and .esshader compile on a device
esengine327d2f75d5a8
diff --git a/CMakeLists.txt b/CMakeLists.txtindex 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.cppsrc/esengine/bindings/GeometryBindings.cppsrc/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.jsindex 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.cmakeindex 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.mdindex 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) => voidanim_setSequenceNext: (registry: CppRegistry, tweenEntity: number, nextEntity: number) => voidanim_setTweenBezier: (registry: CppRegistry, tweenEntity: number, p1x: number, p1y: number, p2x: number, p2y: number) => voidanim_updateTweens: (registry: CppRegistry, deltaTime: number) => void-compileEsshader: (source: string, featuresCsv: string) => number-defineMaterial: (materialId: number, shader: number, blendMode: number, flags: number) => voiddraw_begin: (matrixPtr: number) => voiddraw_circle: (centerX: number, centerY: number, radius: number, r: number, g: number, b: number, a: number, filled: boolean, segments: number) => voiddraw_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: () => voidinitRendererWebGPU: (canvasSelector: string, width: number, height: number) => booleaninitRendererWithCanvas: (canvasSelector: string) => booleaninitRendererWithContext: (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) => voidmesh2d_setGeometry: ((registry: CppRegistry, entity: number, posUvPtr: number, vertexCount: number, colorsPtr: number, indicesPtr: number, indexCount: number) => void) | undefinedparticle_getAliveCount: ((entity: number) => number) | undefinedparticle_play: ((registry: CppRegistry, entity: number) => void) | undefined@@ -2387,8 +2390,6 @@ renderer_submitUIElements: (registry: CppRegistry) => voidrenderer_updateTransforms: (registry: CppRegistry) => voidsdfFromAlpha: ((alphaPtr: number, outPtr: number, width: number, height: number, spread: number) => void) | undefinedsetActiveContext: (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) => voidshutdownRenderer: () => voidtilemap_destroyLayer: ((entity: number) => void) | undefinedtilemap_exportChunks: ((entity: number) => string) | undefined@@ -2419,7 +2420,6 @@ uiTree_markAllDirty: () => voiduiTree_markDirty: (entity: number) => voiduiTree_markStructureDirty: () => voidui_getRenderOrder: ((registry: CppRegistry, entity: number) => number) | undefined-undefineMaterial: (materialId: number) => void```## EasingType — typediff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 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) => voidanim_setSequenceNext: (registry: CppRegistry, tweenEntity: number, nextEntity: number) => voidanim_setTweenBezier: (registry: CppRegistry, tweenEntity: number, p1x: number, p1y: number, p2x: number, p2y: number) => voidanim_updateTweens: (registry: CppRegistry, deltaTime: number) => void-compileEsshader: (source: string, featuresCsv: string) => number-defineMaterial: (materialId: number, shader: number, blendMode: number, flags: number) => voiddraw_begin: (matrixPtr: number) => voiddraw_circle: (centerX: number, centerY: number, radius: number, r: number, g: number, b: number, a: number, filled: boolean, segments: number) => voiddraw_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: () => voidinitRendererWebGPU: (canvasSelector: string, width: number, height: number) => booleaninitRendererWithCanvas: (canvasSelector: string) => booleaninitRendererWithContext: (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) => voidmesh2d_setGeometry: ((registry: CppRegistry, entity: number, posUvPtr: number, vertexCount: number, colorsPtr: number, indicesPtr: number, indexCount: number) => void) | undefinedparticle_getAliveCount: ((entity: number) => number) | undefinedparticle_play: ((registry: CppRegistry, entity: number) => void) | undefined@@ -2395,8 +2398,6 @@ renderer_submitUIElements: (registry: CppRegistry) => voidrenderer_updateTransforms: (registry: CppRegistry) => voidsdfFromAlpha: ((alphaPtr: number, outPtr: number, width: number, height: number, spread: number) => void) | undefinedsetActiveContext: (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) => voidshutdownRenderer: () => voidtilemap_destroyLayer: ((entity: number) => void) | undefinedtilemap_exportChunks: ((entity: number) => string) | undefined@@ -2427,7 +2428,6 @@ uiTree_markAllDirty: () => voiduiTree_markDirty: (entity: number) => voiduiTree_markStructureDirty: () => voidui_getRenderOrder: ((registry: CppRegistry, entity: number) => number) | undefined-undefineMaterial: (materialId: number) => void```## EasingType — typediff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 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) => voidanim_setSequenceNext: (registry: CppRegistry, tweenEntity: number, nextEntity: number) => voidanim_setTweenBezier: (registry: CppRegistry, tweenEntity: number, p1x: number, p1y: number, p2x: number, p2y: number) => voidanim_updateTweens: (registry: CppRegistry, deltaTime: number) => void-compileEsshader: (source: string, featuresCsv: string) => number-defineMaterial: (materialId: number, shader: number, blendMode: number, flags: number) => voiddraw_begin: (matrixPtr: number) => voiddraw_circle: (centerX: number, centerY: number, radius: number, r: number, g: number, b: number, a: number, filled: boolean, segments: number) => voiddraw_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: () => voidinitRendererWebGPU: (canvasSelector: string, width: number, height: number) => booleaninitRendererWithCanvas: (canvasSelector: string) => booleaninitRendererWithContext: (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) => voidmesh2d_setGeometry: ((registry: CppRegistry, entity: number, posUvPtr: number, vertexCount: number, colorsPtr: number, indicesPtr: number, indexCount: number) => void) | undefinedparticle_getAliveCount: ((entity: number) => number) | undefinedparticle_play: ((registry: CppRegistry, entity: number) => void) | undefined@@ -2382,8 +2385,6 @@ renderer_submitUIElements: (registry: CppRegistry) => voidrenderer_updateTransforms: (registry: CppRegistry) => voidsdfFromAlpha: ((alphaPtr: number, outPtr: number, width: number, height: number, spread: number) => void) | undefinedsetActiveContext: (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) => voidshutdownRenderer: () => voidtilemap_destroyLayer: ((entity: number) => void) | undefinedtilemap_exportChunks: ((entity: number) => string) | undefined@@ -2414,7 +2415,6 @@ uiTree_markAllDirty: () => voiduiTree_markDirty: (entity: number) => voiduiTree_markStructureDirty: () => voidui_getRenderOrder: ((registry: CppRegistry, entity: number) => number) | undefined-undefineMaterial: (materialId: number) => void```## EasingType — typediff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 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) => voidanim_setSequenceNext: (registry: CppRegistry, tweenEntity: number, nextEntity: number) => voidanim_setTweenBezier: (registry: CppRegistry, tweenEntity: number, p1x: number, p1y: number, p2x: number, p2y: number) => voidanim_updateTweens: (registry: CppRegistry, deltaTime: number) => void-compileEsshader: (source: string, featuresCsv: string) => number-defineMaterial: (materialId: number, shader: number, blendMode: number, flags: number) => voiddraw_begin: (matrixPtr: number) => voiddraw_circle: (centerX: number, centerY: number, radius: number, r: number, g: number, b: number, a: number, filled: boolean, segments: number) => voiddraw_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: () => voidinitRendererWebGPU: (canvasSelector: string, width: number, height: number) => booleaninitRendererWithCanvas: (canvasSelector: string) => booleaninitRendererWithContext: (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) => voidmesh2d_setGeometry: ((registry: CppRegistry, entity: number, posUvPtr: number, vertexCount: number, colorsPtr: number, indicesPtr: number, indexCount: number) => void) | undefinedparticle_getAliveCount: ((entity: number) => number) | undefinedparticle_play: ((registry: CppRegistry, entity: number) => void) | undefined@@ -2382,8 +2385,6 @@ renderer_submitUIElements: (registry: CppRegistry) => voidrenderer_updateTransforms: (registry: CppRegistry) => voidsdfFromAlpha: ((alphaPtr: number, outPtr: number, width: number, height: number, spread: number) => void) | undefinedsetActiveContext: (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) => voidshutdownRenderer: () => voidtilemap_destroyLayer: ((entity: number) => void) | undefinedtilemap_exportChunks: ((entity: number) => string) | undefined@@ -2414,7 +2415,6 @@ uiTree_markAllDirty: () => voiduiTree_markDirty: (entity: number) => voiduiTree_markStructureDirty: () => voidui_getRenderOrder: ((registry: CppRegistry, entity: number) => number) | undefined-undefineMaterial: (materialId: number) => void```## EasingType — typediff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.mdindex 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) => voidanim_setSequenceNext: (registry: CppRegistry, tweenEntity: number, nextEntity: number) => voidanim_setTweenBezier: (registry: CppRegistry, tweenEntity: number, p1x: number, p1y: number, p2x: number, p2y: number) => voidanim_updateTweens: (registry: CppRegistry, deltaTime: number) => void-compileEsshader: (source: string, featuresCsv: string) => number-defineMaterial: (materialId: number, shader: number, blendMode: number, flags: number) => voiddraw_begin: (matrixPtr: number) => voiddraw_circle: (centerX: number, centerY: number, radius: number, r: number, g: number, b: number, a: number, filled: boolean, segments: number) => voiddraw_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: () => voidinitRendererWebGPU: (canvasSelector: string, width: number, height: number) => booleaninitRendererWithCanvas: (canvasSelector: string) => booleaninitRendererWithContext: (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) => voidmesh2d_setGeometry: ((registry: CppRegistry, entity: number, posUvPtr: number, vertexCount: number, colorsPtr: number, indicesPtr: number, indexCount: number) => void) | undefinedparticle_getAliveCount: ((entity: number) => number) | undefinedparticle_play: ((registry: CppRegistry, entity: number) => void) | undefined@@ -339,8 +342,6 @@ renderer_submitUIElements: (registry: CppRegistry) => voidrenderer_updateTransforms: (registry: CppRegistry) => voidsdfFromAlpha: ((alphaPtr: number, outPtr: number, width: number, height: number, spread: number) => void) | undefinedsetActiveContext: (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) => voidshutdownRenderer: () => voidtilemap_destroyLayer: ((entity: number) => void) | undefinedtilemap_exportChunks: ((entity: number) => string) | undefined@@ -371,7 +372,6 @@ uiTree_markAllDirty: () => voiduiTree_markDirty: (entity: number) => voiduiTree_markStructureDirty: () => voidui_getRenderOrder: ((registry: CppRegistry, entity: number) => number) | undefined-undefineMaterial: (materialId: number) => void```## EmscriptenFS — interfacediff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 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) => voidanim_setSequenceNext: (registry: CppRegistry, tweenEntity: number, nextEntity: number) => voidanim_setTweenBezier: (registry: CppRegistry, tweenEntity: number, p1x: number, p1y: number, p2x: number, p2y: number) => voidanim_updateTweens: (registry: CppRegistry, deltaTime: number) => void-compileEsshader: (source: string, featuresCsv: string) => number-defineMaterial: (materialId: number, shader: number, blendMode: number, flags: number) => voiddraw_begin: (matrixPtr: number) => voiddraw_circle: (centerX: number, centerY: number, radius: number, r: number, g: number, b: number, a: number, filled: boolean, segments: number) => voiddraw_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: () => voidinitRendererWebGPU: (canvasSelector: string, width: number, height: number) => booleaninitRendererWithCanvas: (canvasSelector: string) => booleaninitRendererWithContext: (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) => voidmesh2d_setGeometry: ((registry: CppRegistry, entity: number, posUvPtr: number, vertexCount: number, colorsPtr: number, indicesPtr: number, indexCount: number) => void) | undefinedparticle_getAliveCount: ((entity: number) => number) | undefinedparticle_play: ((registry: CppRegistry, entity: number) => void) | undefined@@ -2382,8 +2385,6 @@ renderer_submitUIElements: (registry: CppRegistry) => voidrenderer_updateTransforms: (registry: CppRegistry) => voidsdfFromAlpha: ((alphaPtr: number, outPtr: number, width: number, height: number, spread: number) => void) | undefinedsetActiveContext: (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) => voidshutdownRenderer: () => voidtilemap_destroyLayer: ((entity: number) => void) | undefinedtilemap_exportChunks: ((entity: number) => string) | undefined@@ -2414,7 +2415,6 @@ uiTree_markAllDirty: () => voiduiTree_markDirty: (entity: number) => voiduiTree_markStructureDirty: () => voidui_getRenderOrder: ((registry: CppRegistry, entity: number) => number) | undefined-undefineMaterial: (materialId: number) => void```## EasingType — typediff --git a/sdk/src/corePlugin.ts b/sdk/src/corePlugin.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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 APIdraw_begin(matrixPtr: number): void;diff --git a/sdk/tests/binding-surface.test.ts b/sdk/tests/binding-surface.test.tsindex 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.tsindex 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.cppnew file mode 100644index 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 esenginediff --git a/src/esengine/bindings/MaterialBindings.hpp b/src/esengine/bindings/MaterialBindings.hppnew file mode 100644index 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 esenginediff --git a/src/esengine/bindings/WebSDKEntry.cpp b/src/esengine/bindings/WebSDKEntry.cppindex 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.cppindex 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.hppindex 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