Shader composer

Turns a composed graph into the fields a material takes, in both languages.

The result spreads straight into createMaterial, and whichever backend draws it takes the half it speaks. Nothing at the call site names a backend, and that is the point: the values are typed, so the second language is a second walk over the graph rather than a translation, and the two halves cannot drift apart because nobody wrote either.

On the way it works out anything used twice only once, reads each leaf the way its stage offers it (and refuses one read where it does not exist), gathers every parameter into uniforms, and writes each noise function once.

The family comes back in the type, so the result spreads into a material for sprites or for models and the material knows which it is.

A sprite shader needs color and has no vertex stage. A model shader takes color, position or both, and a stage left out keeps the engine's own. color may be a vec3 (alpha 1) or a vec4; position is a vec3.

Compiles a .shader file into what a material needs: its hooks in both languages, its parameters and their types. The same shape reading a .wgsl gives, so nothing that uses a shader file can tell the two apart.

It writes no shader code of its own. It turns the file into the same values the composer functions build and hands them to compileShader, so a graph drawn on a canvas and the same graph written in code cannot drift, and every check the composer functions make applies to a wired graph too.

Only what reaches an output is built: a node nothing is wired to adds nothing, so a canvas with a few loose nodes on it still compiles. A loop is caught and named. An output left unwired keeps the engine's own for that stage, so a new file is valid and its material draws with the engine's shader until something is connected.

The value without its sign, lane by lane.

Adds lane by lane, a number spreading over a vector (composerAdd(color, 0.1) lightens every channel). Two vectors of different sizes are an error.

Cell noise (f32): the distance to the nearest of a scatter of random points, which gives cells, cracks or scales. Takes a vec2 or a vec3.

Cuts a gradient into steps flat bands, the cartoon look. Put the light through it for hard lighting, or any other gradient. Same type in as out; more steps is smoother.

Keeps value between lo and hi, lane by lane. Numbers as bounds spread over value.

Cosine of each lane, in radians.

A vector at right angles to two vec3s.

How far apart two points of the same size are (f32).

Divides lane by lane, a number spreading over a vector.

The dot product of two vectors of the same size (f32): how much they point the same way, and the heart of any lighting sum.

The light the material gives off by itself (vec3), so a graph can rebuild the engine's own look exactly. Models only, colour stage.

Layers of noise, each twice as fine and half as strong as the one before (f32): the detailed, natural kind, for terrain, smoke or lava. octaves is written into the shader, so it is a small fixed number (4 unless you say). Takes a vec2 or a vec3.

A constant number. The only kind of constant: vectors are made with composerVec2, composerVec3 and composerVec4, which wrap their plain numbers in this on their own.

The largest whole number not above each lane.

What is left after the whole part (x - floor(x)), lane by lane: the basis of anything that repeats or tiles.

The rim term, from 0 where the surface faces the camera to 1 where it turns away (f32): the start of a rim light, a hologram or a force field. A higher power pulls the rim in to the silhouette.

It reads which way the surface faces and where the camera is, so it only exists in a model's colour stage, and the compiler says so anywhere else.

How long a vector is (f32).

How much light reaches this point, and of what colour (vec3).

It is handed over on its own so a graph can light things its own way, in hard bands or with a rim. The engine's own look is the surface times this, plus composerEmissive. The light is worked out at the corners and blended in between, as the consoles of the era did. Models only, colour stage.

The larger of two values, lane by lane. A number spreads over a vector.

The smaller of two values, lane by lane. A number spreads over a vector.

Blends from a to b by t: 0 gives a, 1 gives b. a and b are the same size, and t is either a number or that size too.

The remainder the way shader authors expect it, x - y * floor(x / y), which always takes the sign of y. Built from the pieces above, because WGSL's own % keeps the sign of x instead and the two backends would disagree on negative numbers. A number as y spreads over x.

Multiplies lane by lane, a number spreading over a vector (composerMul(color, 2) doubles the brightness; two vectors multiply lane by lane).

The same direction, one unit long. Vectors only.

1 - x, lane by lane: the opposite of a mask or of a falloff, in one step of a pipe.

Passes a value through a list of steps, left to right, so a long expression reads in the order it happens instead of from the inside out.

composerPipe(x, composerMul(2), composerAdd(1), composerSin) reads "take x, double it, add one, then the sine", and is exactly composerSin(composerAdd(composerMul(x, 2), 1)). Any one-operand function is a step as it is, and the two-operand ones that put the value on the left (composerAdd, composerMul, composerPow...) become one when given a single operand. For anything else, a small function (n) => ... is a step too.

base to the power of exp, lane by lane. A number as exp spreads over base.

Bounces the direction i off a surface facing n. Both vectors of the same size.

The game's size in pixels (vec2), which the engine writes for every material. For keeping a pattern square, or for effects measured in pixels.

Keeps each lane between 0 and 1, in one step of a pipe. Short for composerClamp(x, 0, 1).

The sign of each lane: -1, 0 or +1.

Smooth noise at a position (f32, 0 to 1): the usual source of anything organic, like clouds, flowing water or a dissolve mask. Takes a vec2 or a vec3. Scale the position to change how busy it is, and add composerTime() to move it.

Sine of each lane, in radians.

A soft cut: eases from 0 to 1 as value goes from edge0 to edge1. Numbers as edges spread over value.

Square root of each lane.

A hard cut: 0 where value is below edge, 1 from there on, lane by lane. A number as edge spreads over value.

Subtracts lane by lane, a number spreading over a vector.

The colour the engine would have drawn here (vec4): the picture, already read and already tinted (and on a model, painted by its corners' colour), before any light. Where most colour effects start. Colour stage only.

Picks components of a vector by their letters ('bgr', 'xy'). The number of letters, one to four, is the size of the result, and a single letter gives a plain number.

The letters come from one set, xyzw or rgba, never both in one mask, and each must exist in the value it reads: both are checked here rather than left to the card.

Reads the material's own picture, tinted, at any coordinate (vec4). What waves, pixelation, a colour split or a blur are made of: composerSurface() is this read at the fragment's own coordinate. Colour stage only.

Seconds since the game started (f32), which the engine writes for every material. Anything that moves on its own is driven by this, with no code per frame.

A parameter with a name, which the game can change while it runs.

What value looks like sets its type (a number, or a list of two, three or four) and is what it starts at. compileShader gathers every parameter of the graph into the material's uniforms, so writing material.uniforms.<name> moves it on the next frame. time and resolution are taken: the engine writes those, and they are read with composerTime and composerResolution.

The texture coordinate (vec2). There in every stage; in a model's vertex graph it is the corner's own.

A vector of two. Two numbers, one vec2, or one number copied into both.

A vector of three, the everyday one for colours and directions. Three numbers, a vec2 and a number, one vec3, or one number copied into all three.

A vector of four, usually a colour with its alpha. Four numbers, a vec3 and a number (colour and alpha), one vec4, or one number copied into all four.

The colour painted on the model's corners (vec4), smeared across each triangle. Models only, in either stage.

It is already part of composerSurface. On its own it is for using the paint as something other than colour: how much a corner sways in the wind, or how much of a second picture shows through, which is how the era blended grass into a dirt path without a second texture pass.

Which way the corner faces, in the model's own space (vec3). Moving a corner along it swells the model. Models only, vertex stage.

Where the corner is, in the model's own space (vec3): the value a position graph moves, to make it wobble, swell or jitter. Models only, vertex stage.

The direction from this point towards the camera, one unit long (vec3). What a rim or a shine is worked out from. Models only, colour stage.

The fourth component of a vector, as a number. Short for composerSwizzle(v, 'w').

Which way the surface faces, in the world (vec3). Models only, colour stage; in a vertex graph use composerVertexNormal.

Where this point of the surface is, in the world (vec3). Models only, colour stage.

The first component of a vector, as a number. Short for composerSwizzle(v, 'x').

The second component of a vector, as a number. Short for composerSwizzle(v, 'y').

The third component of a vector, as a number. Short for composerSwizzle(v, 'z').

Reads a .shader file and checks its shape.

It takes the text of the file or JSON already parsed, because both callers exist: a game loading it has text in hand, and an editor holds a graph it has just changed and wants checked before it writes it. A broken shape (a node with no id, a place that is not two numbers, an unknown family) is refused here, naming the node. What the graph means (a kind of node nobody knows, a wire into an input that does not exist, a loop) is compileShaderGraph's, which knows the catalogue.

The version of the .shader format. It only goes up for a change an older reader could not survive; a new optional field does not move it.

What compileShader gives back: exactly the fields createMaterial takes, so it is spread straight in, createMaterial({ ...compiled }).

A stage left at the engine's own is missing, the same as not writing it in createMaterial. uniforms holds every parameter found in the graph, ready to be changed while the game runs.

The two ways to call a two-operand node: both operands give a value, one gives a step for composerPipe, with the value coming down the pipe as the first operand.

What an operand of a composer function may be: another value, or a plain number, which becomes a constant. So composerAdd(composerX(composerUv()), 0.5) needs no composerFloat(0.5).

One value in a composed shader: what kind of value it is, and how to build it from the values it depends on.

It is plain data, never a closure. kind picks how it is written out, params carries its literal operands and deps the values it is made from. That is what lets a graph be written to JSON and read back, the same rule every other piece of state in the engine follows.

Never built by hand: the composer* functions fill these fields consistently and check their operands as they go.

One stage of composerPipe: it takes the value flowing through and returns the next.

Every one-operand function already is one, and the two-operand ones become one when given a single operand (composerMul(2)), so they chain without wrapping.

A note on the canvas: a titled rectangle behind the nodes, for grouping part of a graph and saying what it is for.

It has an array of its own rather than being a kind of node, because it is not one: no wires, no value, no place in the graph. As a node, the compiler, the type check and the previews would each need an exception for the one entry that is not part of the shader.

A wire: output out of node from feeds input in of node to.

By name rather than by position, so adding an input to a kind of node cannot quietly rewire every file that uses it.

One node in a saved graph: which kind of node it is, where it sits on the canvas, and its literals.

It does not describe itself. Its inputs, outputs and code all come from the catalogue, looked up by type, so a file stays small and a node learns something new when the catalogue changes rather than when every file is rewritten.

pos belongs to the editor and is in the file on purpose, like a box's place in a scene: how a graph is laid out is part of what it says to whoever reads it.

The families a graph file can be for: the two that draw things, deliberately not every family a material has.

'post' is missing because no node writes a screen-wide effect, so a graph claiming it would compile to nothing. Spelling it as its own type makes that gap a compile error in the one place that could open it, and the reader refuses the same value, so the two cannot disagree.

A function a node needs written once at the top of the shader (the noise functions, for instance), kept only once however many nodes ask for it.

Both languages ride on the node rather than living in a table per language looked up by name. A helper exists because a node needs it, and keeping the two apart would let a graph ask for a helper one language never defined: a failure that shows up as a shader that does not compile in somebody's browser, rather than as a missing entry while writing it.

A value a leaf reads from the running shader: a function argument (uv, pos), one of the values the engine writes for every material (time), or what the model's colour hook is told about the place it is colouring (worldNormal, light).

Each one is only there in some stages, and the compiler refuses a leaf read where it does not exist (light in a vertex graph, say) instead of emitting code the card then rejects.

A literal a node keeps in its own body instead of receiving through a wire: a swizzle mask, a number of octaves, a colour. Only what JSON keeps intact and an inspector can show a control for.

What compileShader is handed: the family the shader is for, and up to two results.

color is what the colour hook returns and position is where the vertex hook moves a corner to (models only). Leave one out and that stage keeps the engine's own.

The family is kept in the type, so what comes out is known to be a sprite's or a model's.

A .shader file: a shader drawn as nodes on a canvas.

It sits next to a hand-written .wgsl and next to a graph composed in code, and all three end up as the same thing, so a material cannot tell which one it was given. The file holds no shader source in any language, only nodes and wires as plain JSON.

target means what @shader means at the top of a .wgsl: it picks the hooks, so it is not a preference but part of what gets compiled.