What the engine hands a shader

A material is a small function you write: the engine runs it for every pixel (and, on a model, for every corner) and hands it what it knows about that place. This page lists all of it. The names are a promise: a shader written against them keeps working in later versions, so none is ever renamed. The engine's tests check that every name on this page exists on both graphics backends.

To see each input at work, every one drawing something you can see, open the Shader inputs example.

The hooks are written in WGSL for WebGPU (fragment, vertex) and in GLSL for WebGL2 (fragmentGlsl, vertexGlsl). Every name is the same in both; only the types are written the GLSL way (vec4 for vec4<f32>). If you build the material with the shader composer, it writes both for you.

In every shader: mu

A material's parameters arrive in mu. The engine's come first and always in the same order, then yours, by the name you gave them: uniforms: { charge: 0 } is read as mu.charge.

Outside a scene change, progress and phase are both 0. Those four names are taken: a parameter of your own cannot use them.

A parameter is one of four types: f32, vec2<f32>, vec3<f32> or vec4<f32>. The whole block holds 64 numbers, the engine's included. A vec3 or a vec4 starts on a multiple of four, so a single number just before one leaves a small gap. A material that declares more than fits is drawn with the built-in look, and the console says why.

Sprites, text and map layers

A material with shader: 'sprite2d' (the default) has one hook:

fn effect(color: vec4<f32>, uv: vec2<f32>) -> vec4<f32> {
    return color;
}

• color is the picture already read and already tinted. return color; draws exactly what the engine would have drawn, so an effect is a change to that.
• On the letters of a vector font, color is the text's tint, with the letter's edge in its alpha.
• uv is the place on the sheet. It is not kept inside the sprite's frame: reading elsewhere on the sheet is allowed.
• sampleTexture(uv) reads the sheet at any place, also inside an if or a loop.

The same material works on a map layer without changing a word.

Models

A material with shader: 'mesh3d' has two hooks. Both are optional: the one you leave out does what the engine does.

fn vertex(pos: vec3<f32>, ctx: VertContext) -> vec3<f32> {
    return pos;
}
 
fn effect(surface: vec4<f32>, ctx: FragContext) -> vec4<f32> {
    return vec4<f32>(surface.rgb * ctx.light + ctx.shine + ctx.emissive, surface.a);
}

That effect is the engine's own, word for word: a good place to start from.

• vertex moves a corner, in the model's own space. Writing it costs a little: the surface is measured again after the move, which calls it two more times per corner.
• vertex can also hand four numbers to effect: carry = vec4<f32>(...). They arrive as ctx.carry, blended across the triangle. A wave's height for foam on its crests, a light worked out at the corners, or pos itself, so stripes stay on the model as it moves.
• surface is the picture times the tint times the colour painted on the corners.
• Fog goes over what effect returns, and alphaCutoff cuts by its alpha.

What the corner hook is told:

What the colour hook is told:

light and shine are worked out at the corners and blended across the triangle, not worked out again for every pixel. That is how the consoles of the era lit a model, and it is the look the engine is after.

Helpers a model's shader can call:

• sampleTexture(uv): the model's picture.
• sampleMap_<name>(uv): one of the material's maps, by its name (maps: { noise } is read with sampleMap_noise(ctx.uv)). A map the material does not have reads white.
• envUv(ctx): where a chrome reflection lands on a round picture of the surroundings. Read it with sampleMap_env(envUv(ctx)).

Screen effects

An effect over the whole screen (usePostProcess({ fragment })) has the same hook as a sprite. color is the frame already read at uv.

An effect reads one data picture: a palette or a colour table, never both.