3D Mesh Shaders

What it does

game.meshShaders.add(entity, 'lava') puts a recipe on an object, and define registers a shader of your own by name. A shader is the body of a fragment shader: it reads the object's own colour and texture, where it is in object and world space, which way it faces, the scene's light with the sun's shadow and the time, and leaves a premultiplied color. The engine then applies the scene's fog and tone map, the fade and a still dither against banding, so the shaded object sits in the same light as everything beside it.

A shader can also grow a shell: the mesh drawn again, pushed out along its smoothed normals, additively and from both sides, in one to eight layers. The snippet runs again on each layer and knows which one it is on, so a few soft layers of rising noise read as a volume of flame, and a single layer makes a force-field bubble round the object. Surfaces blend three ways: opaque (writing depth, with discard to cut holes), alpha (sorted with the transparent meshes) and additive.

It joins render-3d through that pack's mesh-shader hook, so the object keeps everything but its colour: its place among the transparent meshes, picking, its glow halo and the sun's shadow. Each shader comes back as a handle you set and tween live on the sim clock, show and hide, or scrub through its own time.

Features

• Nine recipes — lava, burning, ice, hologram, forceField, gold, chrome, dissolve and toon, each a definition in MESH_SHADER_RECIPES you can copy and change.
• What a surface needs to know — object and world position, the object's centre and size, normal, view, fresnel, the object's own colour and texture, and the sun and ambient light with the sun's shadow.
• Noise built in — 2D and 3D hash, value noise and four-octave fbm.
• Params and colours — up to sixteen params and four colours, by name and by slot, set or tweened live.
• Shells — one to eight layers pushed out along smoothed normals, for flames, glows and shields.
• Three blends — opaque with holes, alpha and additive, plus twoSided and shadow: false.
• Show and hide — the fade cross-fades the shader with the object's own look on the sim clock, and resolves when it arrives.
• Keeps the object's place — transparency sort, picking, the glow halo and the sun's shadow.
• Checked before it draws — checkMeshShader returns the problem in one sentence with no GPU, and failure(name) reports a device's compile error.
• Both renderers — WebGPU runs the WGSL as written and WebGL2 runs it translated; a snippet the translator refuses is refused up front, so it never draws on one backend only.

Good for

• Power-ups and transformations — a hero who catches fire with show and goes out with hide, back to their own look.
• Boss fights — a lava boss with glowing cracks, or a hexagon shield that pulses round it until it drops.
• Pickups and relics — a gold or chrome idol that reads as metal from every side, with no environment map.
• Sci-fi scenes — holograms with scanlines and a climbing band of light, additive and casting no shadow.
• Deaths and teleports — a dissolve with glowing edges, tweened on cue or cycling on its own.
• Stylised 3D — cel shading in a few flat bands with a rim light, on a character or a few key props.

Make it yours

Start from a recipe by name and override its params and colours when you add it, tween them in play, or copy its code into a define and change it. A definition chooses its blend, its shell, whether it casts a shadow and whether it is two-sided, and every recipe's params are named for what they do: heat and height on the fire, cells and pulse on the force field, bands and rim on the toon.

Two very different uses: a cel-shaded hero wearing toon all game, opaque, with its shade colour and band count set once; and a boss wrapped in forceField, added at fade 0, shown when its shield goes up, its pulse tweened as it takes damage, and hidden when the shield breaks.

A quick look

A gold relic, and a hero who catches fire and goes out again:

const relic = game.world3d.spawn({ mesh: 'torusKnot', y: 1, size: 2 });
game.meshShaders.add(relic, 'gold');

const hero = game.world3d.spawn({ mesh: 'capsule', size: 1.8 });
const fire = game.meshShaders.add(hero, 'burning', { fade: 0, params: { heat: 1.5 } });
void fire.show({ duration: 0.8, ease: 'sineOut' });   // catches fire
void fire.hide({ duration: 1.5 });                    // and goes out

Works with

• render-3d — required; the shader joins its draw. core-3d brings it, with world-3d and geometry-3d.
• world-3d and geometry-3d — the 3D world and the shapes a shader goes on.
• lighting-3d — its point and spot lamps light the rest of the scene but not a shaded surface.
• sprite-shaders — the same idea for a 2D sprite.
• backdrops — for a shader over the whole background.

Good to know

• One shader per object. Static batches and billboards cannot wear one.
• It replaces the material: material maps, metallic, rough, emissive and render-3d's surface effects are not applied, though the texture comes through base and the glow halo still shows.
• light is the sun and the ambient only; point and spot lights from lighting-3d do not reach a shaded surface.
• The shadow is the plain mesh's, so holes a dissolve cuts and flames a shell draws do not show in it.
• Each object costs a draw for its surface and one per shell layer every frame: for a handful of objects, not a crowd or a forest.