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 the standard material surface — normal, metallic, roughness, occlusion, emission and alpha ports

yhhe0ea3db15be1
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 86f85d3d2..30e081f99 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.
+- **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.
- **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 efa604a29..b236c99d5 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit efa604a290fe0552fd7e102d135dd06282c8b3dc
+Subproject commit b236c99d59b87aa684e81e7c8b95e8e6f832672a
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 711395d58..ca4e38670 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -4233,6 +4233,8 @@ PlatformImage | PlatformCanvas | ImageBitmap
| 'subgraph' // another graph used as one node (inlined before compile)
| 'subInput' // inside a subgraph: one of its inputs, read by the nodes that use it
| 'subOutput' // inside a subgraph: its result
+ | 'normalMap' // sample a tangent-space normal map (read as data, unpacked like the standard material)
+ | 'channel' // one component (r/g/b/a) of a value, as a scalar
| 'literal' // a constant the compiler makes when a subgraph input is left unconnected
| 'uv' // v_texCoord
| 'vertexColor' // v_color (the sprite's per-instance tint)
@@ -5523,7 +5525,7 @@ send: (data: string | ArrayBuffer) => void
## NodeParamSpec — interface @beta
```
key: string
-kind: "texture" | "float" | "color"
+kind: "texture" | "bool" | "float" | "channel" | "color"
label: string
```
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 54c32eb44..5584d3eda 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -4241,6 +4241,8 @@ PlatformImage | PlatformCanvas | ImageBitmap
| 'subgraph' // another graph used as one node (inlined before compile)
| 'subInput' // inside a subgraph: one of its inputs, read by the nodes that use it
| 'subOutput' // inside a subgraph: its result
+ | 'normalMap' // sample a tangent-space normal map (read as data, unpacked like the standard material)
+ | 'channel' // one component (r/g/b/a) of a value, as a scalar
| 'literal' // a constant the compiler makes when a subgraph input is left unconnected
| 'uv' // v_texCoord
| 'vertexColor' // v_color (the sprite's per-instance tint)
@@ -5721,7 +5723,7 @@ send: (data: string | ArrayBuffer) => void
## NodeParamSpec — interface @beta
```
key: string
-kind: "texture" | "float" | "color"
+kind: "texture" | "bool" | "float" | "channel" | "color"
label: string
```
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index d6d005b4e..18671124e 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -4228,6 +4228,8 @@ PlatformImage | PlatformCanvas | ImageBitmap
| 'subgraph' // another graph used as one node (inlined before compile)
| 'subInput' // inside a subgraph: one of its inputs, read by the nodes that use it
| 'subOutput' // inside a subgraph: its result
+ | 'normalMap' // sample a tangent-space normal map (read as data, unpacked like the standard material)
+ | 'channel' // one component (r/g/b/a) of a value, as a scalar
| 'literal' // a constant the compiler makes when a subgraph input is left unconnected
| 'uv' // v_texCoord
| 'vertexColor' // v_color (the sprite's per-instance tint)
@@ -5518,7 +5520,7 @@ send: (data: string | ArrayBuffer) => void
## NodeParamSpec — interface @beta
```
key: string
-kind: "texture" | "float" | "color"
+kind: "texture" | "bool" | "float" | "channel" | "color"
label: string
```
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 542d2428a..edb7dd6eb 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -4228,6 +4228,8 @@ PlatformImage | PlatformCanvas | ImageBitmap
| 'subgraph' // another graph used as one node (inlined before compile)
| 'subInput' // inside a subgraph: one of its inputs, read by the nodes that use it
| 'subOutput' // inside a subgraph: its result
+ | 'normalMap' // sample a tangent-space normal map (read as data, unpacked like the standard material)
+ | 'channel' // one component (r/g/b/a) of a value, as a scalar
| 'literal' // a constant the compiler makes when a subgraph input is left unconnected
| 'uv' // v_texCoord
| 'vertexColor' // v_color (the sprite's per-instance tint)
@@ -5811,7 +5813,7 @@ send: (data: string | ArrayBuffer) => void
## NodeParamSpec — interface @beta
```
key: string
-kind: "texture" | "float" | "color"
+kind: "texture" | "bool" | "float" | "channel" | "color"
label: string
```
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index f1ce33415..59e86b875 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -4228,6 +4228,8 @@ PlatformImage | PlatformCanvas | ImageBitmap
| 'subgraph' // another graph used as one node (inlined before compile)
| 'subInput' // inside a subgraph: one of its inputs, read by the nodes that use it
| 'subOutput' // inside a subgraph: its result
+ | 'normalMap' // sample a tangent-space normal map (read as data, unpacked like the standard material)
+ | 'channel' // one component (r/g/b/a) of a value, as a scalar
| 'literal' // a constant the compiler makes when a subgraph input is left unconnected
| 'uv' // v_texCoord
| 'vertexColor' // v_color (the sprite's per-instance tint)
@@ -5525,7 +5527,7 @@ send: (data: string | ArrayBuffer) => void
## NodeParamSpec — interface @beta
```
key: string
-kind: "texture" | "float" | "color"
+kind: "texture" | "bool" | "float" | "channel" | "color"
label: string
```
diff --git a/sdk/src/render/materialGraph.ts b/sdk/src/render/materialGraph.ts
index 3104b401c..7111979c8 100644
--- a/sdk/src/render/materialGraph.ts
+++ b/sdk/src/render/materialGraph.ts
@@ -25,6 +25,8 @@ export type GraphNodeType =
| 'subgraph' // another graph used as one node (inlined before compile)
| 'subInput' // inside a subgraph: one of its inputs, read by the nodes that use it
| 'subOutput' // inside a subgraph: its result
+ | 'normalMap' // sample a tangent-space normal map (read as data, unpacked like the standard material)
+ | 'channel' // one component (r/g/b/a) of a value, as a scalar
| 'literal' // a constant the compiler makes when a subgraph input is left unconnected
| 'uv' // v_texCoord
| 'vertexColor' // v_color (the sprite's per-instance tint)
@@ -190,7 +192,8 @@ export function compileMaterialGraph(source: MaterialGraph, resolve?: SubgraphRe
case 'textureSample': {
const name = paramName(n);
const def = typeof n.params?.default === 'string' ? n.params.default : 'white';
- params.push(`#pragma param ${name} texture default(${def})`);
+ // 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 };
out = line('vec4',
`texture(${name}, ${uv.expr})`,
@@ -263,6 +266,23 @@ export function compileMaterialGraph(source: MaterialGraph, resolve?: SubgraphRe
`fract(${uv.wexpr} + tc.u_time.x * vec2f(${sx}, ${sy}))`);
break;
}
+ case 'normalMap': {
+ 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 };
+ out = line('vec3', `sampleNormal(${name}, ${uv.expr})`, `sampleNormal(${name}, ${name}_s, ${uv.wexpr})`);
+ break;
+ }
+ case 'channel': {
+ const a = input('v');
+ const ch = (['r', 'g', 'b', 'a'] as const).find((c) => c === n.params?.channel) ?? 'r';
+ const idx = 'rgba'.indexOf(ch);
+ if (a.type === 'float') { out = a; break; }
+ // A vec2 has no b / a, and a vec3 has no a: say so rather than emit a swizzle neither language accepts.
+ if (idx >= TYPE_RANK[a.type]) throw new Error(`material graph: node "${id}" takes .${ch} of a ${a.type}`);
+ out = line('float', `${a.expr}.${ch}`, `${a.wexpr}.${ch}`);
+ break;
+ }
case 'literal': {
const v = typeof n.params?.value === 'number' && Number.isFinite(n.params.value) ? n.params.value : 0;
const ty = (['float', 'vec2', 'vec3', 'vec4'] as const).find((t) => t === n.params?.type) ?? 'float';
@@ -301,8 +321,71 @@ export function compileMaterialGraph(source: MaterialGraph, resolve?: SubgraphRe
}
const result = emit(graph.output);
+
+ // Standard-material surface: the `output` node's PBR ports (or a literal typed on one) turn this
+ // graph into the Lit mesh shading the built-in `Model` shader uses — the same normal unpack, the
+ // same metal-in-B / rough-in-G packing, occlusion on the ambient term only, emission after light.
+ const outNode = nodes.get(graph.output)!;
+ const PBR_SLOTS = ['normal', 'metallic', 'roughness', 'occlusion', 'emission'] as const;
+ const hasLiteral = (slot: string): boolean => typeof outNode.params?.[`lit_${slot}`] === 'number';
+ const pbr = PBR_SLOTS.some((s) => outNode.inputs?.[s] || hasLiteral(s));
+
+ // The scalar / vec3 an optional port or its typed literal says; null when neither is there.
+ const scalarOf = (slot: string, fallback: number): Emitted => {
+ const src = outNode.inputs?.[slot];
+ if (src) {
+ const e = emit(src);
+ return e.type === 'float' ? e : { expr: `${e.expr}.x`, wexpr: `${e.wexpr}.x`, type: 'float' };
+ }
+ const v = typeof outNode.params?.[`lit_${slot}`] === 'number' ? (outNode.params![`lit_${slot}`] as number) : fallback;
+ return { expr: v.toFixed(4), wexpr: v.toFixed(4), type: 'float' };
+ };
+ const alphaE = scalarOf('alpha', 1);
+ let surface: { glsl: string; wgsl: string } | null = null;
+ if (pbr) {
+ const base = emit(outNode.inputs!.color!);
+ const baseGl = `${toVec4(base.expr, base.type)}.rgb`;
+ const baseWg = `${toVec4W(base.wexpr, base.type)}.rgb`;
+ const nrm = outNode.inputs?.normal ? emit(outNode.inputs.normal) : null;
+ const nrmGl = nrm ? (nrm.type === 'vec3' ? nrm.expr : `${toVec4(nrm.expr, nrm.type)}.xyz`) : null;
+ const nrmWg = nrm ? (nrm.type === 'vec3' ? nrm.wexpr : `${toVec4W(nrm.wexpr, nrm.type)}.xyz`) : null;
+ const metal = scalarOf('metallic', 0);
+ const rough = scalarOf('roughness', 1);
+ const occ = scalarOf('occlusion', 1);
+ let emisGl = 'vec3(0.0)';
+ let emisWg = 'vec3f(0.0)';
+ if (outNode.inputs?.emission) {
+ const e = emit(outNode.inputs.emission);
+ emisGl = `${toVec4(e.expr, e.type)}.rgb`;
+ emisWg = `${toVec4W(e.wexpr, e.type)}.rgb`;
+ }
+ surface = {
+ glsl: `#ifdef MESH_NORMALS
+ highp vec3 sN = normalize(v_worldNormal);
+${nrmGl ? ` sN = perturbNormal(sN, v_worldXYZ, v_texCoord, ${nrmGl});\n` : ''} if (!gl_FrontFacing) sN = -sN;
+ highp vec3 sP = v_worldXYZ;
+#else
+ vec3 sN = ${nrmGl ?? 'vec3(0.0, 0.0, 1.0)'};
+ highp vec3 sP = vec3(v_worldPos, 0.0);
+#endif
+ vec3 lit = applyLightingPBR(${baseGl}, sN, sP, viewDirection(sP), ${metal.expr}, ${rough.expr}, 1.0, ${occ.expr});
+ fragColor = vec4(lit + ${emisGl}, ${alphaE.expr});`,
+ wgsl: `#ifdef MESH_NORMALS
+ var sN = normalize(v.v_worldNormal);
+${nrmWg ? ` sN = perturbNormal(sN, v.v_worldXYZ, v.v_texCoord, ${nrmWg});\n` : ''} if (!front) { sN = -sN; }
+ let sP = v.v_worldXYZ;
+#else
+ let sN = ${nrmWg ?? 'vec3f(0.0, 0.0, 1.0)'};
+ let sP = vec3f(v.v_worldPos, 0.0);
+#endif
+ let lit = applyLightingPBR(${baseWg}, sN, sP, viewDirection(sP), ${metal.wexpr}, ${rough.wexpr}, 1.0, ${occ.wexpr});
+ return vec4f(lit + ${emisWg}, ${alphaE.wexpr});`,
+ };
+ }
+ const alphaOnly = !pbr && outNode.inputs?.alpha ? alphaE : null;
+
const name = graph.name ?? 'Graph';
- const domain = RENAMED_DOMAINS[graph.domain ?? ''] ?? graph.domain ?? 'Unlit';
+ const domain = pbr ? 'Lit' : (RENAMED_DOMAINS[graph.domain ?? ''] ?? graph.domain ?? 'Unlit');
const paramBlock = params.length ? params.join('\n') + '\n' : '';
const helperBlock = helpers.size ? [...helpers].join('\n') + '\n\n' : '';
const whelperBlock = whelpers.size ? [...whelpers].join('\n') + '\n\n' : '';
@@ -320,19 +403,28 @@ precision mediump float;
in vec4 v_color;
in vec2 v_texCoord;
-
+${pbr ? `in highp vec2 v_worldPos;
+#ifdef MESH_NORMALS
+in highp vec3 v_worldNormal;
+in highp vec3 v_worldXYZ;
+#endif
+` : ''}
${helperBlock}out vec4 fragColor;
void main() {
${bodyBlock}
- fragColor = ${result.expr};
+${surface ? surface.glsl : ` fragColor = ${alphaOnly ? `vec4((${result.expr}).rgb, ${alphaOnly.expr})` : result.expr};`}
}
#pragma end
#pragma fragment wgsl
-${whelperBlock}@fragment fn fs_main(v : VSOut) -> @location(0) vec4f {
-${wbodyBlock}
- return ${result.wexpr};
+${whelperBlock}@fragment fn fs_main(v : VSOut${pbr ? ', @builtin(front_facing) front : bool' : ''}) -> @location(0) vec4f {
+${pbr ? ` g_probeSlot = v.v_probeSlot;
+#ifdef MESH_LIGHTMAP
+ g_lightmap = v.v_lightmap;
+#endif
+` : ''}${wbodyBlock}
+${surface ? surface.wgsl : ` return ${alphaOnly ? `vec4f((${result.wexpr}).rgb, ${alphaOnly.wexpr})` : result.wexpr};`}
}
#pragma end
`;
@@ -370,7 +462,7 @@ export interface NodePort {
export interface NodeParamSpec {
key: string;
label: string;
- kind: 'color' | 'float' | 'texture';
+ kind: 'color' | 'float' | 'texture' | 'bool' | 'channel';
}
/** Static schema for a node type — the single source the palette, ports, and node inspector
@@ -391,14 +483,23 @@ export const NODE_SPECS: Record<GraphNodeType, NodeSpec> = {
subInput: { label: 'Subgraph Input', inputs: [], output: 'float', params: [], addable: false },
subOutput: { label: 'Subgraph Output', inputs: [{ name: 'value', type: 'float' }], output: null, params: [], addable: false },
literal: { label: 'Literal', inputs: [], output: 'float', params: [], addable: false },
- output: { label: 'Output', inputs: [{ name: 'color', type: 'vec4' }], output: null, params: [], addable: false },
+ output: {
+ label: 'Output',
+ 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' },
+ ],
+ output: null, params: [], addable: false,
+ },
+ normalMap: { label: 'Normal Map', inputs: [{ name: 'uv', type: 'vec2' }], output: 'vec3', params: [{ key: 'name', label: 'Param', kind: 'texture' }], addable: true },
+ channel: { label: 'Channel', inputs: [{ name: 'v', type: 'vec4' }], output: 'float', params: [{ key: 'channel', label: 'Channel', kind: 'channel' }], addable: true },
uv: { label: 'UV', inputs: [], output: 'vec2', params: [], addable: true },
vertexColor: { label: 'Vertex Color', inputs: [], output: 'vec4', params: [], addable: true },
time: { label: 'Time', inputs: [], output: 'float', params: [], addable: true },
screenUV: { label: 'Screen UV', inputs: [], output: 'vec2', params: [], addable: true },
constFloat: { label: 'Float', inputs: [], output: 'float', params: [{ key: 'value', label: 'Value', kind: 'float' }], addable: true },
constColor: { label: 'Color', inputs: [], output: 'vec4', params: [{ key: 'value', label: 'Color', kind: 'color' }], addable: true },
- textureSample: { label: 'Texture', inputs: [{ name: 'uv', type: 'vec2' }], output: 'vec4', params: [{ key: 'name', label: 'Param', kind: 'texture' }], addable: true },
+ textureSample: { label: 'Texture', inputs: [{ name: 'uv', type: 'vec2' }], output: 'vec4', params: [{ key: 'name', label: 'Param', kind: 'texture' }, { key: 'data', label: 'Data', kind: 'bool' }], addable: true },
multiply: { label: 'Multiply', inputs: [{ name: 'a', type: 'vec4' }, { name: 'b', type: 'vec4' }], output: 'vec4', params: [], addable: true },
add: { label: 'Add', inputs: [{ name: 'a', type: 'vec4' }, { name: 'b', type: 'vec4' }], output: 'vec4', params: [], addable: true },
lerp: { label: 'Lerp', inputs: [{ name: 'a', type: 'vec4' }, { name: 'b', type: 'vec4' }, { name: 't', type: 'float' }], output: 'vec4', params: [], addable: true },
@@ -439,6 +540,8 @@ function defaultParams(type: GraphNodeType, id: string): Record<string, unknown>
case 'constFloat': return { name: `u_${id}`, value: 1 };
case 'constColor': return { name: `u_${id}`, value: [1, 1, 1, 1] };
case 'textureSample': return { name: `u_${id}`, default: 'white' };
+ case 'normalMap': return { name: `u_${id}` };
+ case 'channel': return { channel: 'r' };
case 'smoothstep': return { edge0: 0, edge1: 1 };
case 'noise': return { scale: 12 };
case 'panner': return { speedX: 0.1, speedY: 0 };
diff --git a/sdk/tests/materialPbr.test.ts b/sdk/tests/materialPbr.test.ts
new file mode 100644
index 000000000..fc190e194
--- /dev/null
+++ b/sdk/tests/materialPbr.test.ts
@@ -0,0 +1,78 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+import { describe, it, expect } from 'vitest';
+import { compileMaterialGraph, type MaterialGraph } from '../src/render/materialGraph';
+
+const pbrGraph = (extra: Record<string, string> = {}, outParams?: Record<string, unknown>): MaterialGraph => ({
+ name: 'Metal',
+ output: 'out',
+ nodes: [
+ { id: 'alb', type: 'textureSample', params: { name: 'u_albedo', default: 'white' } },
+ { id: 'nrm', type: 'normalMap', params: { name: 'u_normal' } },
+ { id: 'mr', type: 'textureSample', params: { name: 'u_mr', default: 'white', data: true } },
+ { id: 'm', type: 'channel', params: { channel: 'b' }, inputs: { v: 'mr' } },
+ { id: 'r', type: 'channel', params: { channel: 'g' }, inputs: { v: 'mr' } },
+ { id: 'out', type: 'output', params: outParams, inputs: { color: 'alb', normal: 'nrm', metallic: 'm', roughness: 'r', ...extra } },
+ ],
+});
+
+describe('standard-material surface', () => {
+ const src = compileMaterialGraph(pbrGraph());
+
+ it('compiles in the Lit domain and lights through applyLightingPBR in both languages', () => {
+ expect(src).toContain('#pragma domain Lit');
+ expect(src.match(/applyLightingPBR\(/g)).toHaveLength(2);
+ expect(src).toContain('perturbNormal(sN, v_worldXYZ, v_texCoord,');
+ expect(src).toContain('perturbNormal(sN, v.v_worldXYZ, v.v_texCoord,');
+ expect(src).toContain('@builtin(front_facing) front : bool');
+ });
+
+ it('reads the normal map and the packed metal / rough map as data, not colour', () => {
+ expect(src).toContain('#pragma param u_normal texture default(flatnormal) texel(data)');
+ expect(src).toContain('#pragma param u_mr texture default(white) texel(data)');
+ expect(src).toContain('#pragma param u_albedo texture default(white)\n');
+ expect(src).toContain('sampleNormal(u_normal, v_texCoord)');
+ });
+
+ it('takes metal from B and roughness from G, and defaults the rest like the standard material', () => {
+ expect(src).toMatch(/float n\d = n\d\.b;/);
+ expect(src).toMatch(/float n\d = n\d\.g;/);
+ expect(src).toContain(', 1.0, 1.0000);'); // specular 1, occlusion 1
+ expect(src).toContain('vec3(0.0), 1.0000)'); // no emission, opaque
+ });
+
+ it('adds emission after the light and takes alpha from its port', () => {
+ const g = pbrGraph({ emission: 'alb', alpha: 'm' });
+ const out = compileMaterialGraph(g);
+ expect(out).toMatch(/fragColor = vec4\(lit \+ n\d\.rgb, n\d\);/);
+ });
+
+ it('turns on from a literal alone, and leaves a graph with no PBR port exactly as it was', () => {
+ const legacy: MaterialGraph = { name: 'L', output: 'out', nodes: [{ id: 'c', type: 'constColor', params: { name: 'u_c', value: [1, 0, 0, 1] } }, { id: 'out', type: 'output', inputs: { color: 'c' } }] };
+ const plain = compileMaterialGraph(legacy);
+ expect(plain).toContain('#pragma domain Unlit');
+ expect(plain).not.toContain('applyLightingPBR');
+ expect(plain).toContain('fragColor = u_c;');
+ const lit = compileMaterialGraph({ ...legacy, nodes: legacy.nodes.map((n) => (n.id === 'out' ? { ...n, params: { lit_roughness: 0.3 } } : n)) });
+ expect(lit).toContain('#pragma domain Lit');
+ expect(lit).toContain('0.3000');
+ });
+
+ it('keeps an unlit graph\'s alpha port working without the lighting path', () => {
+ const g: MaterialGraph = { name: 'A', output: 'out', nodes: [
+ { id: 'c', type: 'constColor', params: { name: 'u_c', value: [1, 1, 1, 1] } },
+ { id: 'a', type: 'constFloat', params: { name: 'u_a', value: 0.5 } },
+ { id: 'out', type: 'output', inputs: { color: 'c', alpha: 'a' } },
+ ] };
+ const out = compileMaterialGraph(g);
+ expect(out).toContain('#pragma domain Unlit');
+ expect(out).toContain('fragColor = vec4((u_c).rgb, u_a);');
+ });
+
+ it('refuses a channel the value does not have', () => {
+ const g = pbrGraph();
+ g.nodes.push({ id: 'uv', type: 'uv' }, { id: 'bad', type: 'channel', params: { channel: 'b' }, inputs: { v: 'uv' } });
+ g.nodes.find((n) => n.id === 'out')!.inputs!.occlusion = 'bad';
+ expect(() => compileMaterialGraph(g)).toThrow(/takes \.b of a vec2/);
+ });
+});
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index b583e9167..83d798381 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -150,6 +150,8 @@ export const NOTED = {
{ note: 'The Plugins panel shows conflicts and what disabling removes.' },
'feat(render): material subgraphs — a graph used as one node of another, inlined at compile time':
{ 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(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":