Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

feat(render): material graphs gain a vertex offset output that bends the mesh and the shadow it casts

yhh56b1ef68f828
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 30e081f99..5524f5ffd 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,7 +16,7 @@ published separately; it ships inside the editor.
### Changed
-- **Gizmos are redrawn.** The transform handles are larger and clearer: arrows have filled heads, rings dim on their far side, the scale handles are solid cubes, and the part under the cursor turns yellow while the others fall back as you drag. A chip beside the cursor reads the offset, angle or factor being applied (`X +120.0`, `Y 42.5°`, `X ×1.35`), a rotate drag fills the swept angle, a move leaves a ghost where it started and, with snapping on, ticks at each increment. The entity under the cursor is outlined faintly before you click it, and a selected entity's outline is a little heavier. A selected mesh shows corner brackets with the length of three edges and its triangle and vertex count in the readout, the Show menu can draw its wireframe and normals, and a skinned mesh or one of its bones shows the skeleton as bones with the chosen joint in yellow. A decal projector shows its box and the line it projects along, a light probe volume the grid of probes a bake would lay, a LOD group the level it is showing and the share of the screen it takes, and the Gizmo menu has a handle-size slider. A selected UI node shows its margin and padding as bands, the pinned insets of an absolutely placed node as dashed lines with their values, and a flex container's direction and the gaps between its children. The six faces of a light probe volume, reflection probe or decal projector are handles: drag one and that half of the box follows the cursor. A selected mesh is outlined along its own silhouette rather than a box, up to 80,000 triangles. The Show menu can draw wireframe on every mesh at once, and choosing a bone paints the surface it moves from blue to red, the rest left grey; convex colliders now draw with the other 3D colliders. A Hunter's attack range is drawn as a red ball, a Perceiver's sight as the cone it actually tests (a ball when its field of view is all round), and a ThirdPersonCamera's boom as a line from the point it looks at to where it ends up, with the probe swept along it as a ball at the end. A UI element drawn as 9-slice shows its picture under its Slice Border field with four guides to drag, as the texture inspector does; while the texture carries a border of its own, which the renderer prefers, it says so instead. A selected Spine or DragonBones entity shows its bones over the artwork as the 3D rigs do, laid where the runtime posed them this frame, with the entity's scale and flips applied; the Spine and DragonBones modules gained a call that lists the bone tree, so a module built before it still draws the skeleton and only the bones are absent. A selected tilemap layer reports its tile count and the size of the area its tiles cover in the viewport readout (`172 tiles · 32×17`), and on a square grid outlines that area, so an infinite layer's edge can be seen. The profiler is laid out as a module rail (Frame, CPU / GPU, Render, Counters, Memory, Systems, Spine) beside the module chosen: its timeline plots what the CPU was busy with and no longer the wait for the next frame, so a healthy window is no longer one flat block and a hitch is a tall column; clicking a column pins that frame and the strip beneath says in a sentence how far over budget it ran and where; the cost tree is a table of total, own cost and share of the frame, in columns; the toolbar is icon buttons with the live state as a pill. The frame debugger's draw list has column headers, a header per pass with its draw count, a swatch for each draw's type, a break-reason filter that starts with All, and the position of the selected draw in the capture. The sequencer's keyframes take the shape of how the curve leaves them (round smooth, diamond linear, square held, round with an arc eased) in the colour of their track, a group's row sums up the keys beneath it, each channel row shows its value at the playhead beside a swatch that is its curve's colour, the ruler marks seconds as well as frames, the playhead's flag carries the frame, the record button is red and the snap toggle says what it is; the curve view marks its grid and names the selected key's frame, value and interpolation. The sound event editor lists its variants as a table with each clip's waveform and the share of the draw its weight takes, groups its settings (playback, level and pitch, voices, space), draws volume and rate as ranges, plots the attenuation curve with the function the runtime uses, and leads its preview bar with the Trigger action. The Show menu also picks how the viewport shades meshes: as authored, as neutral clay (shape, without anyone's colours) or as flat albedo (base colour, no light); the engine takes it as per-view state, so a camera preview in the same frame keeps the authored look. A fourth shading, wireframe, draws every triangle edge on a dark surface with the hidden ones hidden; the engine's pipelines now carry a primitive topology, WebGL2 and WebGPU alike, and each mesh the editor loads keeps a line list of its distinct edges. Script graphs, material graphs and behavior trees share one node look: a header in the colour of what the node is for, an icon and a plain name with the stored id small beside it, round pins that are solid when wired and hollow when not (control pins are triangles), and wires coloured by the type they carry. A graph with no saved positions is laid out left to right when it opens and opens no smaller than half size, and an Arrange button lays any graph out again. A script graph's inputs, outputs and variables are a searchable list beside the canvas that shows how often each variable is read and written, lights the nodes that use the selected one, and lets you drag a variable onto the canvas to get or set it. The Lighting panel folds into groups with a short state beside each title, shows its warnings as a plain row with an amber edge rather than an amber box, and keeps the bake state, counts and the Bake button pinned at the bottom. The History panel draws a rule at the present, with undone steps below it. The scatter brush draws one real sample of itself to scale. The Plugins panel is a list grouped by origin, with search, beside the details of the plugin picked: its actions, declared capabilities, what it contributes and its health. The string table numbers its rows, marks a missing translation with an amber edge and totals its problems in a status bar. The Spine preview in the asset inspector uses the editor's own dropdowns and icon buttons, shows the time against the animation's length, and names the bounds drawn over it (fixed, unsaved, last scan). While a running game is inspected, the selected entity's outline carries its name, the move handles have arrowheads, and a chip beside the handle reads the position, turn or scale being applied. The Game panel says it is idle, starting or failed with an icon, and a failure shows its reason in a block that can be selected. The World panel is a short panel beside the Content Browser: a toolbar with the cell count and size, the persistent entities as a count that opens their list, and — while the game runs — what is in each residency state, the hit rate and the last demand-to-resident time; below it a table of cells with their entity count and, at runtime, state, prefetch result and demand-to-resident time, and the entities of the picked cell beside it. Picking a cell frames its entities in the viewport. The UI Widgets palette is a searchable list in groups (layout, display, input, popup, touch controls) with the Chinese name and the widget's own name on each row, instead of a grid of tiles. The UI debugger's four views are laid out alike: the Elements tree shows each element's main component and its picked element's size and components sit beside it; Text and Focus order are tables with a state dot per row and select on a click of the row; Events draws each dispatch's bubbling path as a chain from its target. Project Health's three counts filter the list, its findings are grouped by severity under folding headings, and the checks that could not run are listed with their reasons instead of in a tooltip. In the Agent panel each run's header carries a dot for how it came out (running, held, not held, stopped early, never checked), a run's steps hang on a rail with a dot each, the acceptance line is ruled off like the change set instead of boxed, and the key hints under the input show while you are typing. The Plugins panel lists the ids a plugin and another owner both claimed and who got them, filters the list to failed, awaiting-trust, incompatible or shadowed plugins, no longer offers a built-in plugin a trust withdrawal that cannot hold, and says what a plugin contributes before disabling it. A material graph can now use another graph as one node: a `.esmatsub` material subgraph has inputs (a name, a type and a default each) and one result, a graph that uses it fills the inputs by wire or by typing a number on the node, and the compiler inlines it, so one subgraph used twice makes two independent copies and saving a subgraph recompiles the shaders of the graphs that use it. New ones come from the Content Browser's New menu; the subgraph's own header says how many graphs use it. A material graph's output node takes the standard material's surface: normal, metallic, roughness, occlusion and emission ports (and an alpha port that also works on an unlit graph), with a typed number for any left unwired. Connecting any of them compiles the graph to the same lit mesh shading the built-in Model material uses — metal read from blue and roughness from green, occlusion on the ambient light only, emission added after lighting — and a graph with none of them compiles exactly as before. New nodes: Normal Map, which reads its texture as data and unpacks it the way the standard material does, and Channel, which takes one of R, G, B or A as a number; a texture node can be set to read its map as data.
+- **Gizmos are redrawn.** The transform handles are larger and clearer: arrows have filled heads, rings dim on their far side, the scale handles are solid cubes, and the part under the cursor turns yellow while the others fall back as you drag. A chip beside the cursor reads the offset, angle or factor being applied (`X +120.0`, `Y 42.5°`, `X ×1.35`), a rotate drag fills the swept angle, a move leaves a ghost where it started and, with snapping on, ticks at each increment. The entity under the cursor is outlined faintly before you click it, and a selected entity's outline is a little heavier. A selected mesh shows corner brackets with the length of three edges and its triangle and vertex count in the readout, the Show menu can draw its wireframe and normals, and a skinned mesh or one of its bones shows the skeleton as bones with the chosen joint in yellow. A decal projector shows its box and the line it projects along, a light probe volume the grid of probes a bake would lay, a LOD group the level it is showing and the share of the screen it takes, and the Gizmo menu has a handle-size slider. A selected UI node shows its margin and padding as bands, the pinned insets of an absolutely placed node as dashed lines with their values, and a flex container's direction and the gaps between its children. The six faces of a light probe volume, reflection probe or decal projector are handles: drag one and that half of the box follows the cursor. A selected mesh is outlined along its own silhouette rather than a box, up to 80,000 triangles. The Show menu can draw wireframe on every mesh at once, and choosing a bone paints the surface it moves from blue to red, the rest left grey; convex colliders now draw with the other 3D colliders. A Hunter's attack range is drawn as a red ball, a Perceiver's sight as the cone it actually tests (a ball when its field of view is all round), and a ThirdPersonCamera's boom as a line from the point it looks at to where it ends up, with the probe swept along it as a ball at the end. A UI element drawn as 9-slice shows its picture under its Slice Border field with four guides to drag, as the texture inspector does; while the texture carries a border of its own, which the renderer prefers, it says so instead. A selected Spine or DragonBones entity shows its bones over the artwork as the 3D rigs do, laid where the runtime posed them this frame, with the entity's scale and flips applied; the Spine and DragonBones modules gained a call that lists the bone tree, so a module built before it still draws the skeleton and only the bones are absent. A selected tilemap layer reports its tile count and the size of the area its tiles cover in the viewport readout (`172 tiles · 32×17`), and on a square grid outlines that area, so an infinite layer's edge can be seen. The profiler is laid out as a module rail (Frame, CPU / GPU, Render, Counters, Memory, Systems, Spine) beside the module chosen: its timeline plots what the CPU was busy with and no longer the wait for the next frame, so a healthy window is no longer one flat block and a hitch is a tall column; clicking a column pins that frame and the strip beneath says in a sentence how far over budget it ran and where; the cost tree is a table of total, own cost and share of the frame, in columns; the toolbar is icon buttons with the live state as a pill. The frame debugger's draw list has column headers, a header per pass with its draw count, a swatch for each draw's type, a break-reason filter that starts with All, and the position of the selected draw in the capture. The sequencer's keyframes take the shape of how the curve leaves them (round smooth, diamond linear, square held, round with an arc eased) in the colour of their track, a group's row sums up the keys beneath it, each channel row shows its value at the playhead beside a swatch that is its curve's colour, the ruler marks seconds as well as frames, the playhead's flag carries the frame, the record button is red and the snap toggle says what it is; the curve view marks its grid and names the selected key's frame, value and interpolation. The sound event editor lists its variants as a table with each clip's waveform and the share of the draw its weight takes, groups its settings (playback, level and pitch, voices, space), draws volume and rate as ranges, plots the attenuation curve with the function the runtime uses, and leads its preview bar with the Trigger action. The Show menu also picks how the viewport shades meshes: as authored, as neutral clay (shape, without anyone's colours) or as flat albedo (base colour, no light); the engine takes it as per-view state, so a camera preview in the same frame keeps the authored look. A fourth shading, wireframe, draws every triangle edge on a dark surface with the hidden ones hidden; the engine's pipelines now carry a primitive topology, WebGL2 and WebGPU alike, and each mesh the editor loads keeps a line list of its distinct edges. Script graphs, material graphs and behavior trees share one node look: a header in the colour of what the node is for, an icon and a plain name with the stored id small beside it, round pins that are solid when wired and hollow when not (control pins are triangles), and wires coloured by the type they carry. A graph with no saved positions is laid out left to right when it opens and opens no smaller than half size, and an Arrange button lays any graph out again. A script graph's inputs, outputs and variables are a searchable list beside the canvas that shows how often each variable is read and written, lights the nodes that use the selected one, and lets you drag a variable onto the canvas to get or set it. The Lighting panel folds into groups with a short state beside each title, shows its warnings as a plain row with an amber edge rather than an amber box, and keeps the bake state, counts and the Bake button pinned at the bottom. The History panel draws a rule at the present, with undone steps below it. The scatter brush draws one real sample of itself to scale. The Plugins panel is a list grouped by origin, with search, beside the details of the plugin picked: its actions, declared capabilities, what it contributes and its health. The string table numbers its rows, marks a missing translation with an amber edge and totals its problems in a status bar. The Spine preview in the asset inspector uses the editor's own dropdowns and icon buttons, shows the time against the animation's length, and names the bounds drawn over it (fixed, unsaved, last scan). While a running game is inspected, the selected entity's outline carries its name, the move handles have arrowheads, and a chip beside the handle reads the position, turn or scale being applied. The Game panel says it is idle, starting or failed with an icon, and a failure shows its reason in a block that can be selected. The World panel is a short panel beside the Content Browser: a toolbar with the cell count and size, the persistent entities as a count that opens their list, and — while the game runs — what is in each residency state, the hit rate and the last demand-to-resident time; below it a table of cells with their entity count and, at runtime, state, prefetch result and demand-to-resident time, and the entities of the picked cell beside it. Picking a cell frames its entities in the viewport. The UI Widgets palette is a searchable list in groups (layout, display, input, popup, touch controls) with the Chinese name and the widget's own name on each row, instead of a grid of tiles. The UI debugger's four views are laid out alike: the Elements tree shows each element's main component and its picked element's size and components sit beside it; Text and Focus order are tables with a state dot per row and select on a click of the row; Events draws each dispatch's bubbling path as a chain from its target. Project Health's three counts filter the list, its findings are grouped by severity under folding headings, and the checks that could not run are listed with their reasons instead of in a tooltip. In the Agent panel each run's header carries a dot for how it came out (running, held, not held, stopped early, never checked), a run's steps hang on a rail with a dot each, the acceptance line is ruled off like the change set instead of boxed, and the key hints under the input show while you are typing. The Plugins panel lists the ids a plugin and another owner both claimed and who got them, filters the list to failed, awaiting-trust, incompatible or shadowed plugins, no longer offers a built-in plugin a trust withdrawal that cannot hold, and says what a plugin contributes before disabling it. A material graph can now use another graph as one node: a `.esmatsub` material subgraph has inputs (a name, a type and a default each) and one result, a graph that uses it fills the inputs by wire or by typing a number on the node, and the compiler inlines it, so one subgraph used twice makes two independent copies and saving a subgraph recompiles the shaders of the graphs that use it. New ones come from the Content Browser's New menu; the subgraph's own header says how many graphs use it. A material graph's output node takes the standard material's surface: normal, metallic, roughness, occlusion and emission ports (and an alpha port that also works on an unlit graph), with a typed number for any left unwired. Connecting any of them compiles the graph to the same lit mesh shading the built-in Model material uses — metal read from blue and roughness from green, occlusion on the ambient light only, emission added after lighting — and a graph with none of them compiles exactly as before. New nodes: Normal Map, which reads its texture as data and unpacks it the way the standard material does, and Channel, which takes one of R, G, B or A as a number; a texture node can be set to read its map as data. The output node also has a vertex offset port: a number moves each vertex along its normal, a vec2 or vec3 moves it by that displacement, so a graph can sway foliage or ripple water; the mesh's shadow bends the same way, and a Vertex bounds field on the node says how far the offset can reach so culling keeps a bent mesh that is still on screen. The offset runs on lit 3D meshes only, and its graph cannot sample textures or read the screen.
- **A material's preview is a real shape.** Selecting a material shows it on a sphere, cube or plane (lit materials open on the sphere, sprite shaders on the plane), over a dark, checker or light background, with a sample image for shaders that sample a texture; the choice is remembered per kind. The header carries the ball as its icon and the name with a faint extension, the shader is a plain section with a link to make it unique, and the Content Browser's material thumbnails use the same preview. The engine's offscreen preview target now has a depth buffer, so a mesh drawn there is no longer drawn inside out.
- **The 2D animation editors are redrawn.** In the sprite animation editor the view's tools float over its corner, playback and the timeline are one panel, frame events are flags on an event track (click one to rename, move or remove it), the frame source folds into a strip that opens on an empty clip, and frame rate, loop and Save no longer appear a second time in the inspector. The animator controller shows states as cards with their clip and speed, wires between a pair of states run side by side with a pill for the condition (dashed when it waits for the exit time), and its inspector puts the selected state or transition first, with the controller's layers, typed parameters and a folded constraints section below.
- **The tile editor matches its design.** The layer and tileset menus sit on the raised surface, a picked tile has a 2px frame and shows its id on hover, the brush column shows the tile id, the replace dialog's button says Replace, and the tileset inspector shows one-way and trigger as switches, the layer opacity is a slim slider, and a collision layer's friction and bounce fields are flat with their own heading.
diff --git a/desktop b/desktop
index b236c99d5..5e35d68b0 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit b236c99d59b87aa684e81e7c8b95e8e6f832672a
+Subproject commit 5e35d68b090a9ca686642d16e623f9487fc21768
diff --git a/sdk/src/render/materialGraph.ts b/sdk/src/render/materialGraph.ts
index 7111979c8..3057a888c 100644
--- a/sdk/src/render/materialGraph.ts
+++ b/sdk/src/render/materialGraph.ts
@@ -116,13 +116,22 @@ export function compileMaterialGraph(source: MaterialGraph, resolve?: SubgraphRe
const graph = resolve ? flattenSubgraphs(source, resolve) : source;
if (graph.nodes.some((n) => n.type === 'subgraph')) throw new Error('material graph: a subgraph node needs a resolver to compile');
const nodes = new Map(graph.nodes.map((n) => [n.id, n] as const));
- const memo = new Map<string, Emitted>();
- const visiting = new Set<string>();
+ let memo = new Map<string, Emitted>();
+ let visiting = new Set<string>();
const params: string[] = [];
- const helpers = new Set<string>();
- const whelpers = new Set<string>();
- const body: string[] = [];
- const wbody: string[] = [];
+ let helpers = new Set<string>();
+ let whelpers = new Set<string>();
+ let body: string[] = [];
+ let wbody: string[] = [];
+ // The vertex offset is compiled in a second pass over the same nodes, into its own body, where the
+ // fragment's inputs (the interpolated UV, a texture sample, the screen) do not exist.
+ let vertexMode = false;
+ const fragUv = (): Emitted => (vertexMode
+ ? { expr: 'uv', wexpr: 'uv', type: 'vec2' }
+ : { expr: 'v_texCoord', wexpr: 'v.v_texCoord', type: 'vec2' });
+ const needsFragment = (n: MaterialGraphNode, what: string): void => {
+ if (vertexMode) throw new Error(`material graph: node "${n.id}" (${n.type}) ${what}, which the vertex offset cannot`);
+ };
let tmp = 0;
const numParam = (n: MaterialGraphNode, key: string, fallback: number): string => {
@@ -159,15 +168,17 @@ export function compileMaterialGraph(source: MaterialGraph, resolve?: SubgraphRe
let out: Emitted;
switch (n.type) {
case 'uv':
- out = { expr: 'v_texCoord', wexpr: 'v.v_texCoord', type: 'vec2' };
+ out = fragUv();
break;
case 'vertexColor':
+ needsFragment(n, 'reads the vertex colour');
out = { expr: 'v_color', wexpr: 'v.v_color', type: 'vec4' };
break;
case 'time':
out = { expr: 'u_time.x', wexpr: 'tc.u_time.x', type: 'float' };
break;
case 'screenUV': {
+ needsFragment(n, 'reads the screen position');
// 0..1, y-up on both backends: gl_FragCoord has a bottom-left origin,
// the WGSL position builtin a top-left one — flip y before normalizing.
out = line('vec2',
@@ -178,23 +189,24 @@ export function compileMaterialGraph(source: MaterialGraph, resolve?: SubgraphRe
case 'constFloat': {
const name = paramName(n);
const v = typeof n.params?.value === 'number' ? n.params.value : 0;
- params.push(`#pragma param ${name} float default(${v})`);
+ if (!params.includes(`#pragma param ${name} float default(${v})`)) params.push(`#pragma param ${name} float default(${v})`);
out = { expr: name, wexpr: `mc.${name}`, type: 'float' };
break;
}
case 'constColor': {
const name = paramName(n);
const c = Array.isArray(n.params?.value) ? (n.params!.value as number[]) : [1, 1, 1, 1];
- params.push(`#pragma param ${name} color default(${c.slice(0, 4).join(',')})`);
+ if (!params.includes(`#pragma param ${name} color default(${c.slice(0, 4).join(',')})`)) params.push(`#pragma param ${name} color default(${c.slice(0, 4).join(',')})`);
out = { expr: name, wexpr: `mc.${name}`, type: 'vec4' };
break;
}
case 'textureSample': {
+ needsFragment(n, 'samples a texture');
const name = paramName(n);
const def = typeof n.params?.default === 'string' ? n.params.default : 'white';
// A map that holds numbers (metal / rough / occlusion) must not be decoded as a colour.
params.push(`#pragma param ${name} texture default(${def})${n.params?.data === true ? ' texel(data)' : ''}`);
- const uv = n.inputs?.uv ? input('uv') : { expr: 'v_texCoord', wexpr: 'v.v_texCoord', type: 'vec2' as GraphType };
+ const uv = n.inputs?.uv ? input('uv') : fragUv();
out = line('vec4',
`texture(${name}, ${uv.expr})`,
`textureSampleLevel(${name}, ${name}_s, ${uv.wexpr}, 0.0)`);
@@ -250,7 +262,7 @@ export function compileMaterialGraph(source: MaterialGraph, resolve?: SubgraphRe
case 'noise': {
helpers.add(NOISE_HELPER);
whelpers.add(NOISE_HELPER_WGSL);
- const uv = n.inputs?.uv ? input('uv') : { expr: 'v_texCoord', wexpr: 'v.v_texCoord', type: 'vec2' as GraphType };
+ const uv = n.inputs?.uv ? input('uv') : fragUv();
const scale = numParam(n, 'scale', 12);
out = line('float',
`noise2d(${uv.expr} * ${scale})`,
@@ -258,7 +270,7 @@ export function compileMaterialGraph(source: MaterialGraph, resolve?: SubgraphRe
break;
}
case 'panner': {
- const uv = n.inputs?.uv ? input('uv') : { expr: 'v_texCoord', wexpr: 'v.v_texCoord', type: 'vec2' as GraphType };
+ const uv = n.inputs?.uv ? input('uv') : fragUv();
const sx = numParam(n, 'speedX', 0.1);
const sy = numParam(n, 'speedY', 0);
out = line('vec2',
@@ -267,6 +279,7 @@ export function compileMaterialGraph(source: MaterialGraph, resolve?: SubgraphRe
break;
}
case 'normalMap': {
+ needsFragment(n, 'samples a texture');
const name = paramName(n);
params.push(`#pragma param ${name} texture default(flatnormal) texel(data)`);
const uv = n.inputs?.uv ? input('uv') : { expr: 'v_texCoord', wexpr: 'v.v_texCoord', type: 'vec2' as GraphType };
@@ -384,6 +397,37 @@ ${nrmWg ? ` sN = perturbNormal(sN, v.v_worldXYZ, v.v_texCoord, ${nrmWg});\n`
}
const alphaOnly = !pbr && outNode.inputs?.alpha ? alphaE : null;
+ // The vertex offset: its own DAG, compiled into `esMaterialVertex`, which the engine's mesh vertex stage
+ // calls on each local-space vertex. A float moves the vertex along its normal; a vec2 / vec3 / vec4 is
+ // a displacement (vec2 in x and y).
+ let vertexHook = '';
+ let wgslVertexHook = '';
+ let vertexBounds = 0;
+ const offsetSrc = outNode.inputs?.vertexOffset;
+ if (offsetSrc) {
+ const fragMemo = { memo, visiting, helpers, whelpers, body, wbody };
+ memo = new Map(); visiting = new Set(); helpers = new Set(); whelpers = new Set(); body = []; wbody = [];
+ vertexMode = true;
+ const o = emit(offsetSrc);
+ const disp = o.type === 'float' ? { gl: `localNormal * ${o.expr}`, wg: `(*localNormal) * ${o.wexpr}` }
+ : o.type === 'vec2' ? { gl: `vec3(${o.expr}, 0.0)`, wg: `vec3f(${o.wexpr}, 0.0)` }
+ : o.type === 'vec3' ? { gl: o.expr, wg: o.wexpr }
+ : { gl: `${o.expr}.xyz`, wg: `${o.wexpr}.xyz` };
+ const indent = (lines: string[]): string => lines.map((l) => ' ' + l).join('\n');
+ vertexHook = `${helpers.size ? [...helpers].join('\n') + '\n' : ''}void esMaterialVertex(inout vec3 local, inout vec3 localNormal, in vec2 uv) {
+${indent(body)}
+ local += ${disp.gl};
+}`;
+ wgslVertexHook = `${whelpers.size ? [...whelpers].join('\n') + '\n' : ''}fn esMaterialVertex(local : ptr<function, vec3f>, localNormal : ptr<function, vec3f>, uv : vec2f) {
+${indent(wbody)}
+ *local = *local + ${disp.wg};
+}`;
+ ({ memo, visiting, helpers, whelpers, body, wbody } = fragMemo);
+ vertexMode = false;
+ const b = outNode.params?.lit_vertexBounds;
+ vertexBounds = typeof b === 'number' && Number.isFinite(b) && b > 0 ? b : 0;
+ }
+
const name = graph.name ?? 'Graph';
const domain = pbr ? 'Lit' : (RENAMED_DOMAINS[graph.domain ?? ''] ?? graph.domain ?? 'Unlit');
const paramBlock = params.length ? params.join('\n') + '\n' : '';
@@ -397,7 +441,7 @@ ${nrmWg ? ` sN = perturbNormal(sN, v.v_worldXYZ, v.v_texCoord, ${nrmWg});\n`
return `#pragma shader "${name}"
#pragma version 300 es
#pragma domain ${domain}
-${paramBlock}
+${paramBlock}${vertexHook ? `${vertexBounds > 0 ? `#pragma vertexbounds ${vertexBounds}\n` : ''}\n#pragma vertexoffset\n${vertexHook}\n#pragma end\n\n#pragma vertexoffset wgsl\n${wgslVertexHook}\n#pragma end\n` : ''}
#pragma fragment
precision mediump float;
@@ -488,6 +532,7 @@ export const NODE_SPECS: Record<GraphNodeType, NodeSpec> = {
inputs: [
{ name: 'color', type: 'vec4' }, { name: 'normal', type: 'vec3' }, { name: 'metallic', type: 'float' }, { name: 'roughness', type: 'float' },
{ name: 'occlusion', type: 'float' }, { name: 'emission', type: 'vec3' }, { name: 'alpha', type: 'float' },
+ { name: 'vertexOffset', type: 'vec3' },
],
output: null, params: [], addable: false,
},
diff --git a/sdk/tests/materialPbr.test.ts b/sdk/tests/materialPbr.test.ts
index fc190e194..16b40eba8 100644
--- a/sdk/tests/materialPbr.test.ts
+++ b/sdk/tests/materialPbr.test.ts
@@ -76,3 +76,77 @@ describe('standard-material surface', () => {
expect(() => compileMaterialGraph(g)).toThrow(/takes \.b of a vec2/);
});
});
+
+describe('vertex offset', () => {
+ const wind = (extra: Partial<MaterialGraph['nodes'][number]> = {}): MaterialGraph => ({
+ name: 'Wind', output: 'out',
+ nodes: [
+ { id: 'c', type: 'constColor', params: { name: 'u_c', value: [1, 1, 1, 1] } },
+ { id: 'time', type: 'time' },
+ { id: 'amt', type: 'constFloat', params: { name: 'u_bend', value: 0.5 } },
+ { id: 's', type: 'sin', inputs: { x: 'time' } },
+ { id: 'm', type: 'multiply', inputs: { a: 's', b: 'amt' } },
+ { id: 'out', type: 'output', inputs: { color: 'c', vertexOffset: 'm' }, ...extra },
+ ],
+ });
+
+ it('compiles the offset into a hook in both languages, ahead of the fragment', () => {
+ const src = compileMaterialGraph(wind());
+ expect(src).toContain('#pragma vertexoffset\n');
+ expect(src).toContain('#pragma vertexoffset wgsl\n');
+ expect(src).toContain('void esMaterialVertex(inout vec3 local, inout vec3 localNormal, in vec2 uv) {');
+ expect(src).toContain('fn esMaterialVertex(local : ptr<function, vec3f>, localNormal : ptr<function, vec3f>, uv : vec2f) {');
+ expect(src.indexOf('#pragma vertexoffset')).toBeLessThan(src.indexOf('#pragma fragment'));
+ });
+
+ it('moves a scalar along the normal, and a vec2 / vec3 as a displacement', () => {
+ const along = compileMaterialGraph(wind());
+ expect(along).toContain('local += localNormal * n');
+ expect(along).toContain('*local = *local + (*localNormal) * n');
+ const g = wind();
+ g.nodes.push({ id: 'uv', type: 'uv' });
+ g.nodes.find((n) => n.id === 'out')!.inputs!.vertexOffset = 'uv';
+ expect(compileMaterialGraph(g)).toContain('local += vec3(uv, 0.0);');
+ });
+
+ it('shares the material\'s params with the fragment, declaring each once', () => {
+ const src = compileMaterialGraph(wind());
+ expect(src.match(/#pragma param u_bend/g)).toHaveLength(1);
+ expect(src).toContain('u_bend');
+ expect(src).toContain('mc.u_bend');
+ expect(src).toContain('u_time.x');
+ });
+
+ it('writes the bounds expansion only when one is typed', () => {
+ expect(compileMaterialGraph(wind())).not.toContain('#pragma vertexbounds');
+ expect(compileMaterialGraph(wind({ params: { lit_vertexBounds: 12.5 } }))).toContain('#pragma vertexbounds 12.5\n');
+ });
+
+ it('leaves a graph with no offset exactly as before', () => {
+ const g = wind();
+ delete g.nodes.find((n) => n.id === 'out')!.inputs!.vertexOffset;
+ const src = compileMaterialGraph(g);
+ expect(src).not.toContain('vertexoffset');
+ expect(src).not.toContain('esMaterialVertex');
+ });
+
+ it('refuses what only a fragment has: a texture, the screen, the vertex colour', () => {
+ for (const bad of [
+ { id: 'x', type: 'textureSample' as const, params: { name: 'u_t', default: 'white' } },
+ { id: 'x', type: 'screenUV' as const },
+ { id: 'x', type: 'vertexColor' as const },
+ ]) {
+ const g = wind();
+ g.nodes.push(bad);
+ g.nodes.find((n) => n.id === 'out')!.inputs!.vertexOffset = 'x';
+ expect(() => compileMaterialGraph(g)).toThrow(/vertex offset cannot/);
+ }
+ });
+
+ it('lets the fragment keep sampling textures while the vertex pass runs', () => {
+ const g = wind();
+ g.nodes.push({ id: 'tex', type: 'textureSample', params: { name: 'u_albedo', default: 'white' } });
+ g.nodes.find((n) => n.id === 'out')!.inputs!.color = 'tex';
+ expect(compileMaterialGraph(g)).toContain('texture(u_albedo, v_texCoord)');
+ });
+});
diff --git a/src/esengine/bindings/MaterialBindings.cpp b/src/esengine/bindings/MaterialBindings.cpp
index 314643f0c..6f1477d07 100644
--- a/src/esengine/bindings/MaterialBindings.cpp
+++ b/src/esengine/bindings/MaterialBindings.cpp
@@ -47,6 +47,8 @@ static MaterialUniformLayout buildMaterialLayout(const resource::ParsedShader& p
MaterialUniformLayout layout;
layout.blockSize = parsed.materialBlockSize;
layout.coverageParam = parsed.coverageParam;
+ layout.vertexBounds = parsed.vertexBounds;
+ layout.vertexHook = !parsed.vertexHook.empty();
for (const auto& p : parsed.properties) {
if (!p.fromParam) continue;
if (p.type == resource::ShaderPropertyType::Texture) {
diff --git a/src/esengine/data/shaders/mesh.esshader b/src/esengine/data/shaders/mesh.esshader
index 98492fee0..e5b8cc3b7 100644
--- a/src/esengine/data/shaders/mesh.esshader
+++ b/src/esengine/data/shaders/mesh.esshader
@@ -138,6 +138,13 @@ out highp vec3 v_worldPos;
out highp vec4 v_shadowClip;
#endif
+// A material's own vertex offset, for the shadow program built from this source on its behalf: the
+// caster has to bend where the lit surface does, or its shadow stands still. The assembler puts the
+// material's hook where the marker is; without ES_MATERIAL_VERTEX none of it exists.
+#ifdef ES_MATERIAL_VERTEX
+@@ES_VERTEX_HOOK@@
+#endif
+
void main() {
vec3 local = a_position;
#ifdef MESH_NORMALS
@@ -146,6 +153,9 @@ void main() {
vec3 localNormal = vec3(0.0, 0.0, 1.0);
#endif
applyMorph(local, localNormal);
+#ifdef ES_MATERIAL_VERTEX
+ esMaterialVertex(local, localNormal, a_texCoord);
+#endif
#ifdef SKINNED
// The four bones this vertex is bound to, blended by their weights. The
// result is world-space, so no model matrix follows it.
@@ -310,6 +320,10 @@ struct VSOut {
@location(6) @interpolate(flat) v_probeSlot : f32,
};
+#ifdef ES_MATERIAL_VERTEX
+@@ES_VERTEX_HOOK@@
+#endif
+
@vertex fn vs_main(v : VSIn, @builtin(instance_index) inst : u32) -> VSOut {
g_instanceId = i32(inst);
var local = v.a_position;
@@ -329,6 +343,9 @@ struct VSOut {
localNormal = localNormal + morph.shape[i].y * morphDelta(at + 1.0);
}
}
+#ifdef ES_MATERIAL_VERTEX
+ esMaterialVertex(&local, &localNormal, v.a_texCoord);
+#endif
#ifdef SKINNED
// The four bones this vertex is bound to, blended by their weights. The
// result is world-space, so no model matrix follows it.
diff --git a/src/esengine/renderer/plugins/MeshPlugin.cpp b/src/esengine/renderer/plugins/MeshPlugin.cpp
index a1542e0b6..dc64b3d67 100644
--- a/src/esengine/renderer/plugins/MeshPlugin.cpp
+++ b/src/esengine/renderer/plugins/MeshPlugin.cpp
@@ -599,10 +599,14 @@ void MeshPlugin::collect(RenderCollectContext& collect_ctx) {
// Reused by the draw key below: two lookups is how the two come to differ.
const MaterialRecord* material = (mesh.material != 0 && ctx.materials)
? ctx.materials->find(mesh.material) : nullptr;
+ // A material that bends its vertices can put them outside the mesh's own box; culling the
+ // box would drop a bent mesh that is still on screen, so it grows by what the material says.
+ const f32 bend = material ? ctx.materials->vertexBounds(mesh.material) : 0.0f;
const bool depthTested = material ? material->depthTest : mesh.opaque;
glm::vec3 aabbCenter(0.0f), halfExtents(0.0f);
- orientedWorldAabb(position, rotation, scale, localMin, localMax, aabbCenter, halfExtents);
+ orientedWorldAabb(position, rotation, scale, localMin - glm::vec3(bend), localMax + glm::vec3(bend),
+ aabbCenter, halfExtents);
// The collect's own predicate, not a frustum test of this plugin's: it
// answers "outside the view" AND "behind something solid", and a mesh is
// what both were built for.
@@ -809,6 +813,16 @@ void MeshPlugin::collect(RenderCollectContext& collect_ctx) {
}
}
key.shaderId = materialProgram != 0 ? materialProgram : residentShader;
+ // A caster whose material bends it casts the bent shape: the depth program gets the
+ // material's hook, and the draw keeps the material so its params are bound.
+ if (shadowDepth && material && ctx.materials && ctx.materials->hasVertexHook(mesh.material)) {
+ const u32 bentDepth = ctx.materials->shadowProgram(mesh.material, ctx.resources,
+ resident->hasNormals, skinned);
+ if (bentDepth != 0) {
+ key.shaderId = bentDepth;
+ key.materialId = mesh.material;
+ }
+ }
key.layoutId = LayoutId::MeshInstance;
key.instanceCount = 1;
key.instanceStride = MESH_INSTANCE_STRIDE;
diff --git a/src/esengine/renderer/rhi/ShaderEmbeds.generated.hpp b/src/esengine/renderer/rhi/ShaderEmbeds.generated.hpp
index 7efb4de01..5580b654b 100644
--- a/src/esengine/renderer/rhi/ShaderEmbeds.generated.hpp
+++ b/src/esengine/renderer/rhi/ShaderEmbeds.generated.hpp
@@ -502,6 +502,13 @@ out highp vec3 v_worldPos;
out highp vec4 v_shadowClip;
#endif
+
+
+
+#ifdef ES_MATERIAL_VERTEX
+@@ES_VERTEX_HOOK@@
+#endif
+
void main() {
vec3 local = a_position;
#ifdef MESH_NORMALS
@@ -510,6 +517,9 @@ void main() {
vec3 localNormal = vec3(0.0, 0.0, 1.0);
#endif
applyMorph(local, localNormal);
+#ifdef ES_MATERIAL_VERTEX
+ esMaterialVertex(local, localNormal, a_texCoord);
+#endif
#ifdef SKINNED
@@ -674,6 +684,10 @@ struct VSOut {
@location(6) @interpolate(flat) v_probeSlot : f32,
};
+#ifdef ES_MATERIAL_VERTEX
+@@ES_VERTEX_HOOK@@
+#endif
+
@vertex fn vs_main(v : VSIn, @builtin(instance_index) inst : u32) -> VSOut {
g_instanceId = i32(inst);
var local = v.a_position;
@@ -693,6 +707,9 @@ struct VSOut {
localNormal = localNormal + morph.shape[i].y * morphDelta(at + 1.0);
}
}
+#ifdef ES_MATERIAL_VERTEX
+ esMaterialVertex(&local, &localNormal, v.a_texCoord);
+#endif
#ifdef SKINNED
diff --git a/src/esengine/renderer/store/MaterialStore.cpp b/src/esengine/renderer/store/MaterialStore.cpp
index e8038a477..cbbe4f348 100644
--- a/src/esengine/renderer/store/MaterialStore.cpp
+++ b/src/esengine/renderer/store/MaterialStore.cpp
@@ -14,6 +14,7 @@
#include "../../resource/ShaderParser.hpp"
#include "../rhi/Shader.hpp"
#include "../../core/Log.hpp"
+#include "../rhi/ShaderEmbeds.generated.hpp"
namespace esengine {
@@ -88,6 +89,61 @@ u32 MaterialStore::meshProgram(u32 materialId, resource::ResourceManager& resour
return variantProgram(materialId, resources, shape, features, "resident geometry");
}
+u32 MaterialStore::shadowProgram(u32 materialId, resource::ResourceManager& resources,
+ bool withNormals, bool skinned) const {
+ const MaterialRecord* rec = find(materialId);
+ if (!rec || !rec->shaderRef.isValid()) return 0;
+ const u64 shape = (1ull << 37) | (withNormals ? (1ull << 32) : 0ull) | (skinned ? (1ull << 33) : 0ull);
+ auto& variants = mesh_programs_[rec->shaderRef.id()];
+ auto cached = variants.find(shape);
+ if (cached != variants.end()) {
+ const Shader* shader = resources.getShader(cached->second);
+ return shader ? shader->getProgramId() : 0;
+ }
+ auto src = sources_.find(rec->shaderRef.id());
+ if (src == sources_.end()) {
+ variants[shape] = {};
+ return 0;
+ }
+
+ // The engine's mesh depth shader, handed the material's hook and the block it reads. The
+ // material's own fragment is not used: a shadow map wants depth, not colour.
+ const resource::ParsedShader material = resource::ShaderParser::parse(src->second.source);
+ resource::ParsedShader depth = resource::ShaderParser::parse(ShaderEmbeds::MESH);
+ if (!material.valid || !depth.valid || material.vertexHook.empty()) {
+ variants[shape] = {};
+ return 0;
+ }
+ depth.properties = material.properties;
+ depth.materialBlockSize = material.materialBlockSize;
+ depth.vertexHook = material.vertexHook;
+ depth.wgslVertexHook = material.wgslVertexHook;
+
+ std::vector<std::string> features;
+ if (withNormals) features.emplace_back("MESH_NORMALS");
+ if (skinned) features.emplace_back("SKINNED");
+ features.emplace_back("SHADOW_DEPTH");
+ features.emplace_back("ES_MATERIAL_VERTEX");
+ const auto target = resources.preferredShaderTarget();
+ const std::string vert = resource::ShaderParser::assembleStage(depth, resource::ShaderStage::Vertex, "", features, target);
+ const std::string frag = resource::ShaderParser::assembleStage(depth, resource::ShaderStage::Fragment, "", features, target);
+ if (vert.empty() || frag.empty()) {
+ ES_LOG_WARN("MaterialStore: no shadow program for material {} (stage assembly failed)", materialId);
+ variants[shape] = {};
+ return 0;
+ }
+ resource::ShaderHandle handle = resources.createShaderWithBindings(vert, frag, {}, resources.preferredShaderLanguage());
+ Shader* shader = resources.getShader(handle);
+ if (!shader || !shader->isValid()) {
+ resources.releaseShader(handle);
+ variants[shape] = {};
+ return 0;
+ }
+ const u32 program = shader->getProgramId();
+ variants[shape] = handle;
+ return program;
+}
+
u32 MaterialStore::particleProgram(u32 materialId, resource::ResourceManager& resources) const {
return variantProgram(materialId, resources, 1ull << 35, { "PARTICLE" }, "particles");
}
diff --git a/src/esengine/renderer/store/MaterialStore.hpp b/src/esengine/renderer/store/MaterialStore.hpp
index 41ca78edd..c7cde7d2b 100644
--- a/src/esengine/renderer/store/MaterialStore.hpp
+++ b/src/esengine/renderer/store/MaterialStore.hpp
@@ -91,6 +91,11 @@ struct MaterialUniformLayout {
/// The param whose value above zero makes output alpha coverage (see
/// ParsedShader::coverageParam); empty when the shader declares none.
std::string coverageParam;
+ /// What the shader's vertex hook can move a vertex by (ParsedShader::vertexBounds), and whether it
+ /// has a hook at all — culling grows a mesh's box by the first, and the shadow pass builds a
+ /// program of its own for the second.
+ float vertexBounds = 0.0f;
+ bool vertexHook = false;
std::vector<MaterialParamSlot> params;
std::vector<MaterialTextureSlot> textures;
@@ -185,6 +190,28 @@ public:
bool withNormals = false, bool skinned = false,
bool envMapped = false, bool lightmapped = false) const;
+ /// How far @p materialId's vertex hook can move a vertex from the mesh's own bounds, in the
+ /// mesh's local units; 0 for a material without one.
+ float vertexBounds(u32 materialId) const {
+ const MaterialRecord* m = find(materialId);
+ const MaterialUniformLayout* layout = m ? layoutFor(m->shaderRef) : nullptr;
+ return layout ? layout->vertexBounds : 0.0f;
+ }
+
+ /// Whether @p materialId bends its vertices (so its shadow has to bend too).
+ bool hasVertexHook(u32 materialId) const {
+ const MaterialRecord* m = find(materialId);
+ const MaterialUniformLayout* layout = m ? layoutFor(m->shaderRef) : nullptr;
+ return layout && layout->vertexHook;
+ }
+
+ /// The program that draws @p materialId's CASTER into a shadow map: the engine's depth shader for
+ /// resident meshes with the material's vertex hook and params grafted on, so a bent mesh casts the
+ /// shadow of the bent shape. 0 when the source was never kept or the variant fails — the caller
+ /// then casts the unbent shape, which is the old behaviour.
+ u32 shadowProgram(u32 materialId, resource::ResourceManager& resources,
+ bool withNormals, bool skinned) const;
+
/// The program that draws @p materialId on PARTICLE geometry — the instanced
/// quad an emitter streams. Same source, same author's fragment, a different
/// engine vertex stage; 0 on the same terms as {@link meshProgram}.
diff --git a/src/esengine/resource/ShaderParser.cpp b/src/esengine/resource/ShaderParser.cpp
index 982b5bbd6..ab249406a 100644
--- a/src/esengine/resource/ShaderParser.cpp
+++ b/src/esengine/resource/ShaderParser.cpp
@@ -184,6 +184,14 @@ bool expandIncludes(const std::string& source,
return true;
}
+// Swap a placeholder that a canonical stage's literal text carries for the material's hook (or
+// nothing, which is what keeps a stage without one byte-for-byte what it was).
+void fillHook(std::string& src, const std::string& token, const std::string& text) {
+ for (usize at = src.find(token); at != std::string::npos; at = src.find(token, at + text.size())) {
+ src.replace(at, token.size(), text);
+ }
+}
+
// The WGSL varying interface of the canonical 2D vertex stage. Injected into
// BOTH canonical stages (vertex emits it, fragment consumes it), so
// fragment-only twins write `fs_main(v : VSOut)` against an engine-owned
@@ -223,7 +231,7 @@ std::string wgslCanonicalVSOut(bool lit) {
// WGSL twin of canonicalVertexStage: same attribute locations, GLSL names
// kept behind struct fields (a_position -> v.a_position) so the two stages diff
// cleanly. FrameConstants arrives with the injected headers.
-std::string canonicalVertexStageWGSL(bool lit) {
+std::string canonicalVertexStageWGSL(bool lit, const std::string& hook = {}) {
std::string src = wgslCanonicalVSOut(lit);
src +=
"\n"
@@ -276,6 +284,8 @@ std::string canonicalVertexStageWGSL(bool lit) {
"#endif\n"
"};\n"
"\n"
+ "\n"
+ "@@WGSL_HOOK@@"
"@vertex fn vs_main(v : VSIn, @builtin(instance_index) instanceId : u32) -> VSOut {\n"
" var out : VSOut;\n"
" g_instanceId = i32(instanceId);\n"
@@ -296,6 +306,7 @@ std::string canonicalVertexStageWGSL(bool lit) {
" localNormal = localNormal + morph.shape[i].y * morphDelta(at + 1.0);\n"
" }\n"
" }\n"
+ "@@WGSL_CALL@@"
"#endif\n"
// A particle faces the viewer wherever it is seen from; head-on and
// orthographic the axes come out (1,0,0) and (0,1,0), the flat quad a 2D
@@ -359,6 +370,10 @@ std::string canonicalVertexStageWGSL(bool lit) {
src +=
" return out;\n"
"}\n";
+ fillHook(src, "@@WGSL_HOOK@@", hook.empty() ? std::string() :
+ "#ifdef MESH\n" + hook + "\n#endif\n");
+ fillHook(src, "@@WGSL_CALL@@", hook.empty() ? std::string() :
+ " esMaterialVertex(&local, &localNormal, v.a_texCoord);\n");
return src;
}
@@ -412,7 +427,7 @@ std::string canonicalPPVertexStage() {
// Canonical 2D vertex stage for fragment-only .esshaders, in its three VERTEX
// SOURCES: batch (already world space), resident mesh (local + a per-object
// transform), skinned (posed by bones). One material serves all three.
-std::string canonicalVertexStage(bool lit) {
+std::string canonicalVertexStage(bool lit, const std::string& hook = {}) {
std::string src =
// A particle's quad corner is the vertex; where that corner lands is on the
// instance. The layout differs from every other source, so it replaces the
@@ -488,6 +503,7 @@ std::string canonicalVertexStage(bool lit) {
}
src +=
"\n"
+ "@@GLSL_HOOK@@"
"void main() {\n"
"#ifdef MESH\n"
" vec3 local = a_position;\n"
@@ -498,6 +514,7 @@ std::string canonicalVertexStage(bool lit) {
"#endif\n"
// Before the pose: a target was authored against the mesh at rest.
" applyMorph(local, localNormal);\n"
+ "@@GLSL_CALL@@"
"#endif\n"
// A particle faces the viewer wherever it is seen from; head-on and
// orthographic the axes come out (1,0,0) and (0,1,0), the flat quad a 2D
@@ -558,6 +575,10 @@ std::string canonicalVertexStage(bool lit) {
src += " v_probeSlot = float(ES_INSTANCE_ID);\n";
}
src += "}\n";
+ fillHook(src, "@@GLSL_HOOK@@", hook.empty() ? std::string() :
+ "#ifdef MESH\n" + hook + "\n#endif\n");
+ fillHook(src, "@@GLSL_CALL@@", hook.empty() ? std::string() :
+ " esMaterialVertex(local, localNormal, a_texCoord);\n");
return src;
}
@@ -584,7 +605,8 @@ enum class ParseState {
Properties,
Vertex,
Fragment,
- Variant
+ Variant,
+ VertexHook
};
// =============================================================================
@@ -672,6 +694,32 @@ ParsedShader ShaderParser::parse(const std::string& source, const ShaderIncludeR
continue;
}
+ if (directive == "vertexbounds") {
+ // How far the vertex hook may move a vertex, in the mesh's local units.
+ result.vertexBounds = std::strtof(argument.c_str(), nullptr);
+ if (!(result.vertexBounds >= 0.0f)) result.vertexBounds = 0.0f;
+ continue;
+ }
+
+ if (directive == "vertexoffset") {
+ if (state != ParseState::Global) {
+ result.errorMessage = "Unexpected #pragma vertexoffset at line " + std::to_string(lineNumber);
+ return result;
+ }
+ if (!argument.empty() && argument != "wgsl") {
+ result.errorMessage = "Unknown vertexoffset language '" + argument + "' at line " +
+ std::to_string(lineNumber) + " (expected no tag for GLSL, or 'wgsl')";
+ return result;
+ }
+ state = ParseState::VertexHook;
+ currentSectionIsWGSL = !argument.empty();
+ currentSectionIsFullWGSL = false;
+ currentSection.str("");
+ currentSection.clear();
+ currentSectionMap.clear();
+ continue;
+ }
+
if (directive == "domain") {
if (!argument.empty()) result.domain = normalizeDomain(argument);
continue;
@@ -764,6 +812,11 @@ ParsedShader ShaderParser::parse(const std::string& source, const ShaderIncludeR
currentSectionIsFullWGSL = false;
break;
}
+ case ParseState::VertexHook:
+ (currentSectionIsWGSL ? result.wgslVertexHook : result.vertexHook) = currentSection.str();
+ currentSectionMap.clear();
+ currentSectionIsWGSL = false;
+ break;
case ParseState::Variant:
result.variants[currentVariantName] = currentSection.str();
currentVariantName.clear();
@@ -796,6 +849,7 @@ ParsedShader ShaderParser::parse(const std::string& source, const ShaderIncludeR
case ParseState::Vertex:
case ParseState::Fragment:
+ case ParseState::VertexHook:
case ParseState::Variant: {
currentSection << line << "\n";
const SourceLine src = (lineNumber >= 1 && lineNumber <= result.expandedLineMap.size())
@@ -816,7 +870,7 @@ ParsedShader ShaderParser::parse(const std::string& source, const ShaderIncludeR
// Fragment-only authoring: 2D domains get the canonical batch-space
// pass-through, PostProcess the canonical fullscreen pass-through.
if (result.domain == "Unlit" || result.domain == "Lit") {
- result.stages[ShaderStage::Vertex] = canonicalVertexStage(result.domain == "Lit");
+ result.stages[ShaderStage::Vertex] = canonicalVertexStage(result.domain == "Lit", result.vertexHook);
result.vertexIsCanonical = true;
} else if (result.domain == "PostProcess") {
result.stages[ShaderStage::Vertex] = canonicalPPVertexStage();
@@ -837,7 +891,7 @@ ParsedShader ShaderParser::parse(const std::string& source, const ShaderIncludeR
if (result.wgslStages.count(ShaderStage::Fragment) != 0 &&
result.wgslStages.count(ShaderStage::Vertex) == 0) {
if (result.domain == "Unlit" || result.domain == "Lit") {
- result.wgslStages[ShaderStage::Vertex] = canonicalVertexStageWGSL(result.domain == "Lit");
+ result.wgslStages[ShaderStage::Vertex] = canonicalVertexStageWGSL(result.domain == "Lit", result.wgslVertexHook);
result.wgslVertexIsCanonical = true;
} else if (result.domain == "PostProcess") {
result.wgslStages[ShaderStage::Vertex] = canonicalPPVertexStageWGSL();
@@ -1689,7 +1743,11 @@ ShaderParser::AssembledStage assembleWGSLStage(const ParsedShader& parsed,
inject(wgslReachedTextureDecls(assembled.str() + bodyIt->second,
parsed.domain == "PostProcess"));
- assembled << bodyIt->second;
+ std::string bodyText = bodyIt->second;
+ if (stage == ShaderStage::Vertex && !parsed.wgslVertexHook.empty()) {
+ fillHook(bodyText, "@@ES_VERTEX_HOOK@@", parsed.wgslVertexHook);
+ }
+ assembled << bodyText;
result.source = preprocessConditionals(assembled.str(), features);
result.headerLineCount = headerLines;
@@ -2451,7 +2509,13 @@ ShaderParser::AssembledStage ShaderParser::assembleStageEx(const ParsedShader& p
headerLines += countNewlines(parsed.sharedCode);
}
- assembled << blankUniformBlock(stageIt->second, "FrameConstants");
+ // A shader that writes its own vertex stage can take a material's hook too: it says where with a marker,
+ // and the material that borrows the stage supplies the text (see MaterialStore::shadowProgram).
+ std::string bodyText = stageIt->second;
+ if (stage == ShaderStage::Vertex && !parsed.vertexHook.empty()) {
+ fillHook(bodyText, "@@ES_VERTEX_HOOK@@", parsed.vertexHook);
+ }
+ assembled << blankUniformBlock(bodyText, "FrameConstants");
if (stage == ShaderStage::Vertex && stageIt->second.find("esInstance") != std::string::npos) {
assembled << instanceRecordGLSLBodies();
}
diff --git a/src/esengine/resource/ShaderParser.hpp b/src/esengine/resource/ShaderParser.hpp
index f16df414a..63f9227fb 100644
--- a/src/esengine/resource/ShaderParser.hpp
+++ b/src/esengine/resource/ShaderParser.hpp
@@ -152,6 +152,16 @@ struct ParsedShader {
/// output alpha is coverage (a cutout sharpened to one texel), so an opaque draw
/// may turn it into multisample coverage instead of a hard edge.
std::string coverageParam;
+ /// `#pragma vertexoffset`: the body of `esMaterialVertex(inout local, inout localNormal, uv)`,
+ /// run on a resident mesh's local-space vertex before it is posed and placed. It is the
+ /// material's own, so the canonical mesh vertex stage calls it and a material without one
+ /// assembles exactly as before. The WGSL twin takes pointers instead of `inout`.
+ std::string vertexHook;
+ std::string wgslVertexHook;
+ /// `#pragma vertexbounds <units>`: how far the hook can move a vertex from the mesh's own
+ /// bounds, in the mesh's local units — what culling must grow its box by so a bent mesh is not
+ /// dropped while still visible. Zero when the material has no hook.
+ float vertexBounds = 0.0f;
/// std140 byte size of the generated MaterialConstants block (16-aligned), 0 if no
/// non-texture params. The render path sizes the per-material UBO to this.
u32 materialBlockSize = 0;
diff --git a/tests/renderer/test_shader_variant.cpp b/tests/renderer/test_shader_variant.cpp
index 5e0c562c0..aecb7b616 100644
--- a/tests/renderer/test_shader_variant.cpp
+++ b/tests/renderer/test_shader_variant.cpp
@@ -541,6 +541,106 @@ static void testSystemValuesTrailAttributes() {
CHECK(canonicalTrails, "the canonical material vertex names no system value before its attributes");
}
+// A material's own vertex hook: the canonical MESH vertex stage calls it on the local-space
+// vertex (after the morph, before the pose); a material without one assembles as it always has.
+static const char* HOOKED_LIT = R"(#pragma shader "Hooked"
+#pragma version 300 es
+#pragma domain Lit
+#pragma param u_bend float default(0.5)
+#pragma vertexbounds 12.5
+
+#pragma vertexoffset
+void esMaterialVertex(inout vec3 local, inout vec3 localNormal, in vec2 uv) {
+ local.x += sin(u_time.x) * u_bend;
+}
+#pragma end
+
+#pragma vertexoffset wgsl
+fn esMaterialVertex(local : ptr<function, vec3f>, localNormal : ptr<function, vec3f>, uv : vec2f) {
+ (*local).x = (*local).x + sin(tc.u_time.x) * mc.u_bend;
+}
+#pragma end
+
+#pragma fragment
+precision mediump float;
+in vec4 v_color;
+in highp vec2 v_worldPos;
+out vec4 fragColor;
+void main() { fragColor = v_color; }
+#pragma end
+
+#pragma fragment wgsl
+@fragment fn fs_main(v : VSOut) -> @location(0) vec4f { return v.v_color; }
+#pragma end
+)";
+
+static void testVertexHook() {
+ ParsedShader p = ShaderParser::parse(HOOKED_LIT);
+ CHECK(p.valid, "a shader with a vertex hook parses");
+ CHECK(p.vertexHook.find("esMaterialVertex") != std::string::npos, "the GLSL hook is captured");
+ CHECK(p.wgslVertexHook.find("esMaterialVertex") != std::string::npos, "the WGSL hook is captured");
+ CHECK(p.vertexBounds > 12.4f && p.vertexBounds < 12.6f, "#pragma vertexbounds is captured");
+ CHECK(p.vertexIsCanonical, "a hooked shader still takes the engine's vertex stage");
+
+ const std::string vs = ShaderParser::assembleStage(p, ShaderStage::Vertex, "", {"MESH", "MESH_NORMALS"});
+ CHECK(vs.find("void esMaterialVertex(") != std::string::npos, "GLSL: the hook is defined in the vertex stage");
+ CHECK(vs.find("esMaterialVertex(local, localNormal, a_texCoord);") != std::string::npos, "GLSL: the hook is called");
+ CHECK(vs.find("applyMorph(local, localNormal);") < vs.find("esMaterialVertex(local, localNormal, a_texCoord);"),
+ "GLSL: the hook runs after the morph target");
+ CHECK(vs.find("esMaterialVertex(local, localNormal, a_texCoord);") < vs.find("vec4 world = esInstanceModel()"),
+ "GLSL: the hook runs before the vertex is placed in the world");
+ CHECK(vs.find("uniform MaterialConstants") != std::string::npos, "GLSL: the hook can read the material's params");
+
+ const std::string ws = ShaderParser::assembleStage(p, ShaderStage::Vertex, "", {"MESH", "MESH_NORMALS"}, ShaderTargetLanguage::WGSL);
+ CHECK(ws.find("fn esMaterialVertex(") != std::string::npos, "WGSL: the hook is defined in the vertex stage");
+ CHECK(ws.find("esMaterialVertex(&local, &localNormal, v.a_texCoord);") != std::string::npos, "WGSL: the hook is called");
+ CHECK(ws.find("var<uniform> mc : MaterialConstants") != std::string::npos, "WGSL: the hook can read the material's params");
+
+ // The hook is for resident meshes. Without MESH the call is compiled out, 2D batches draw as before.
+ const std::string batch = ShaderParser::assembleStage(p, ShaderStage::Vertex, "", {});
+ CHECK(batch.find("#define MESH") == std::string::npos
+ && batch.find("#ifdef MESH\nvoid esMaterialVertex(") != std::string::npos
+ && batch.find("#ifdef MESH\n vec3 local = a_position;") != std::string::npos,
+ "GLSL: the hook and its call sit under MESH, so a 2D batch variant compiles them out");
+
+ // A shader with no hook assembles with no trace of one.
+ ParsedShader plain = ShaderParser::parse(FRAG_ONLY_LIT);
+ const std::string pv = ShaderParser::assembleStage(plain, ShaderStage::Vertex, "", {"MESH"});
+ CHECK(pv.find("esMaterialVertex") == std::string::npos && pv.find("@@") == std::string::npos,
+ "a shader without a hook has no hook, and no leftover placeholder");
+ CHECK(plain.vertexBounds == 0.0f, "no bounds expansion without a hook");
+}
+
+// The shadow program a bent material gets: the engine's mesh depth shader with the material's hook and
+// params grafted on, so the caster bends where the lit surface does.
+static void testShadowGraft() {
+ ParsedShader material = ShaderParser::parse(HOOKED_LIT);
+ ParsedShader depth = ShaderParser::parse(esengine::ShaderEmbeds::MESH);
+ CHECK(material.valid && depth.valid, "the material and the mesh depth shader both parse");
+ depth.properties = material.properties;
+ depth.materialBlockSize = material.materialBlockSize;
+ depth.vertexHook = material.vertexHook;
+ depth.wgslVertexHook = material.wgslVertexHook;
+ const std::vector<std::string> features{"MESH_NORMALS", "SHADOW_DEPTH", "ES_MATERIAL_VERTEX"};
+
+ const std::string vs = ShaderParser::assembleStage(depth, ShaderStage::Vertex, "", features);
+ CHECK(vs.find("void esMaterialVertex(") != std::string::npos, "depth GLSL: the material's hook is defined");
+ CHECK(vs.find("esMaterialVertex(local, localNormal, a_texCoord);") != std::string::npos, "depth GLSL: the hook is called");
+ CHECK(vs.find("@@ES_VERTEX_HOOK@@") == std::string::npos, "depth GLSL: the marker is replaced");
+ CHECK(vs.find("uniform MaterialConstants") != std::string::npos, "depth GLSL: the material's block is declared for the hook");
+
+ const std::string ws = ShaderParser::assembleStage(depth, ShaderStage::Vertex, "", features, ShaderTargetLanguage::WGSL);
+ CHECK(ws.find("fn esMaterialVertex(") != std::string::npos, "depth WGSL: the material's hook is defined");
+ CHECK(ws.find("esMaterialVertex(&local, &localNormal, v.a_texCoord);") != std::string::npos, "depth WGSL: the hook is called");
+ CHECK(ws.find("var<uniform> mc : MaterialConstants") != std::string::npos, "depth WGSL: the material's block is declared");
+
+ // Without the feature the stock depth shader is untouched, hook or no hook.
+ ParsedShader stock = ShaderParser::parse(esengine::ShaderEmbeds::MESH);
+ const std::string plain = ShaderParser::assembleStage(stock, ShaderStage::Vertex, "", {"SHADOW_DEPTH"});
+ CHECK(plain.find("esMaterialVertex(local") == std::string::npos || plain.find("#ifdef ES_MATERIAL_VERTEX") != std::string::npos,
+ "the stock depth shader's call sits under ES_MATERIAL_VERTEX");
+}
+
int main() {
ParsedShader p = ShaderParser::parse(SRC);
CHECK(p.valid, "shader parses");
@@ -563,6 +663,8 @@ int main() {
testHandWrittenFrameBlock();
testWGSLEmission();
testSystemValuesTrailAttributes();
+ testVertexHook();
+ testShadowGraft();
if (g_failures == 0) {
std::printf("\nALL SHADER-VARIANT TESTS PASSED\n");
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 83d798381..adda2dae1 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -152,6 +152,8 @@ export const NOTED = {
{ note: 'Material graphs can use other graphs as nodes.' },
'feat(render): material graphs gain the standard material surface — normal, metallic, roughness, occlusion, emission and alpha ports':
{ note: 'Material graphs can output a standard PBR surface.' },
+ 'feat(render): material graphs gain a vertex offset output that bends the mesh and the shadow it casts':
+ { note: 'Material graphs can bend a mesh and its shadow.' },
'feat(editor): an asset header names its kind and size, and a segmented switch is used only when its words fit':
{ note: "An asset's header names its kind and size." },
"feat(editor): asset inspectors take the board's finish — a card preview, ruled key-value rows, tinted actions, a kind icon in the header":