Toon Shader

A toon shader keeps the shape of the lighting but throws away its gradients. Instead of light fading smoothly from the lit side to the dark side, it jumps between a few flat levels. Godot lets a spatial shader replace its whole lighting model with a light() function, and that is where this shader does the work: it decides how much of each light reaches a pixel, cuts that amount into bands, and adds a rim and a highlight on top.

What light() is and when Godot calls it

The spatial shader docs say light() is called for every light in every pixel, inside a loop for each light type. Leave it out and Godot lights the material itself from what fragment() wrote. Write it and Godot hands you one light at a time: LIGHT is the direction to that light and NORMAL the surface normal, both in view space, VIEW points to the camera, LIGHT_COLOR is the light's colour times its energy times π, and ATTENUATION is how much of it survives the distance and the shadows. You add your result to DIFFUSE_LIGHT and SPECULAR_LIGHT. The docs say to use += so the lights add together; with =, each light overwrites the ones before it.

Godot does one more thing afterwards: it multiplies DIFFUSE_LIGHT by the ALBEDO from fragment(), but not SPECULAR_LIGHT. You can see both in the demo: the white sun gives each shape its own colour, while every highlight stays white. So DIFFUSE_LIGHT is "how lit is this pixel", not a colour.

Cutting light into bands

The shader first works out an amount of light from 0 to 1 (more on that below), then band() turns it into one of bands flat levels. It cuts 0 to 1 into equal slices and puts one step at each cut. With 3 bands the steps sit at 1/3 and 2/3, so the levels are 0, 0.5 and 1. Each step is a smoothstep over band_softness, which is only 0.02 wide. A hard step() would flip from one pixel to the next and show stair steps along every curved edge; the narrow blend gives the edge one or two in-between pixels, which reads as sharp but not jagged.

float band(float amount) {
	float slices = float(bands);
	float half_soft = max(band_softness, 0.0001) * 0.5;
	float level = 0.0;
	for (int i = 1; i < bands; i++) {
		float edge = float(i) / slices;
		level += smoothstep(edge - half_soft, edge + half_soft, amount);
	}
	// max() keeps a script that sets bands to 1 from dividing by zero.
	return level / max(slices - 1.0, 1.0);
}

The max(..., 0.0001) is there because smoothstep with both edges equal is undefined in GLSL, and band_softness can be set to 0. The Inspector keeps bands between 2 and 6, but a script can set any value with set_shader_parameter(), so the last line guards the division too.

Shadows, falloff and light strength in one number

The amount that gets banded is a product of three things. N·L, the plain Lambert term, is 1 where the surface faces the light and 0 at a right angle. ATTENUATION is 0 in shadow and, for omni and spot lights, falls off with distance. The strength is the light's brightest colour channel times its energy. Because LIGHT_COLOR already holds energy × π (the docs say the π is there because physically based lighting divides by π), dividing by π gives colour × energy. The shader splits that into the strength and a tint whose brightest channel is 1.

vec3 light_rgb = LIGHT_COLOR / PI;
float strength = max(max(light_rgb.r, light_rgb.g), light_rgb.b);
vec3 tint = light_rgb / max(strength, 0.0001);

float n_dot_l = clamp(dot(NORMAL, LIGHT), 0.0, 1.0);
float level = band(n_dot_l * ATTENUATION * max(strength, 1.0)) * min(strength, 1.0);

Banding the whole product is what makes it look drawn. A shadow is a drop in ATTENUATION, so its edge becomes a band edge. An omni light's falloff becomes rings: in the demo the orange lamp throws two nested ovals on the ground, a half-lit one and a fully lit one inside it. And because energy is in the product, a stronger lamp throws bigger pools. An early version banded only N·L × ATTENUATION, and a spot light 4 m above the scene lit nothing at all, because the distance falloff never got past the first step whatever its energy. The cost of the choice: a fully lit pixel shows the surface colour times the tint and no more, so raising a light's energy above 1 widens its lit area instead of brightening it.

Below 1 the shader splits the strength the other way, which is what the max() and min() in that line do. A strength above 1 goes into the banded amount; a strength below 1 multiplies the banded result. Put a weak light straight into the product and it would never reach the first step: at energy 0.3 with 3 bands, 0.3 never gets to 1/3, so the light would add nothing at all. With the split, a 0.3-energy light bands N·L × ATTENUATION as a light of energy 1 would and then gives 0.3 of that. In a test with only such a light and ambient off, the ball showed the same two lit bands and the highlight, just dimmer. At energy 1 and above both forms give the same result, and the demo's frames came out identical, pixel for pixel.

Why plain Lambert and not half-Lambert

Half-Lambert, dot(N, L) * 0.5 + 0.5, is a common toon trick because it wraps light round to the back of the object and keeps the dark side small. With real shadows it fights the shadow map. The shadow map says the far side of a ball is in its own shadow, while half-Lambert still lights it, so the dark band stops where the shadow map cuts it off, with a ragged, stair-stepped edge. That is exactly what a test with half-Lambert showed on the demo's ball. Plain Lambert reaches 0 at the same line where the shadow starts. With 3 bands and a light of energy 1, the first step is at 1/3, about 70° from the light, so the shadow's own edge falls inside the unlit band and does not show.

The rim light: in light() or in fragment()

A rim light brightens the silhouette. N·V is 1 where the surface faces the camera and drops towards 0 at the outline, so 1.0 - N·V above 1.0 - rim_width picks out a thin outer ring. This shader computes it in light() and multiplies it by the band level, so the rim only appears where that light reaches, takes the light's tint, and goes away in shadow. In the demo it shows on the sun side of the ball, the figure and the torus, and the orange lamp adds a rim of its own where it lights an edge, such as the inside of the torus.

float n_dot_v = clamp(dot(NORMAL, VIEW), 0.0, 1.0);
float rim = smoothstep(1.0 - rim_width, 1.0 - rim_width + max(band_softness, 0.0001), 1.0 - n_dot_v);
DIFFUSE_LIGHT += tint * level * (1.0 + rim * rim_strength);

The other place is fragment(), writing the rim to EMISSION. That rim ignores the lights: it glows on the dark side and in total darkness too, which suits a hit flash or a ghost but not a lit edge. In a test with every light hidden, a fragment() rim still glowed round the ball and the torus.

A highlight with a hard edge

The highlight uses the Blinn-Phong half vector, the direction halfway between the light and the camera. Where the normal lines up with it, the surface reflects the light towards you. pow(N·H, glossiness) gives the usual soft blob, and a smoothstep at 0.5 cuts it into a flat disc. It is multiplied by the band level, so there is no glint in shadow, and by SPECULAR_AMOUNT, which the docs give as 1 for a DirectionalLight3D and 2 × Specular for omni and spot lights (1 at their default of 0.5). The fragment function also sets SPECULAR = 0.0, which the docs say turns off reflections, so the sky does not paint a soft reflection over the flat bands.

vec3 half_vector = normalize(LIGHT + VIEW);
float blinn = pow(clamp(dot(NORMAL, half_vector), 0.0, 1.0), glossiness);
float half_soft = max(band_softness, 0.0001) * 0.5;
float highlight = smoothstep(0.5 - half_soft, 0.5 + half_soft, blinn);
SPECULAR_LIGHT += tint * highlight * level * SPECULAR_AMOUNT;

Where ambient light fits

light() only runs for lights. Ambient light from the WorldEnvironment is added by Godot outside it, times the albedo, under every band. That is why the unlit band is not black. How it looks depends on Ambient Light > Source. With Sky, the ambient is read from the sky in the direction of each normal, so normals that face up get more than normals that face down. On the demo's ball the unlit band measured 55 at the top and 43 at the bottom (average brightness out of 255), so the dark side still shows it is round. With Color it measured 63 at both ends: one flat colour. With ambient off it was black.

Ambient also lifts the lit bands, which narrows the gap between them: the ball's lit band measured 133 with sky ambient and 122 without. To get a darker shadow side and keep the shape, lower Sky Contribution. At 0.5, with the default black ambient colour, the unlit band dropped to 38 at the top and 29 at the bottom.

diffuse_toon, specular_toon and why this shader skips them

Godot has toon lighting built in. The spatial shader docs list diffuse_toon ("Toon shading for diffuse") and specular_toon ("Toon for direct light specular lobes") as render modes, and a StandardMaterial3D has the same choices under Shading. They give one step from dark to lit, and its softness follows ROUGHNESS. In a test on the demo's ball with a StandardMaterial3D set to both, Roughness 1 gave an almost smooth gradient with no visible band, and Roughness 0.3 gave one soft step and a blurred highlight. There is no setting for the number of bands, no rim tied to each light, and the edge softness cannot be set apart from the highlight size. A custom light() gives you all of that, and it is the only way to change how shadows and falloff are banded. The price is that the diffuse_* and specular_* render modes no longer do anything, because they only pick Godot's own lighting function, which yours replaces.

A ramp texture instead of bands

The other common approach looks the light amount up in a gradient texture, often called a ramp. It is not in this shader, but swapping it in takes three lines: a sampler2D uniform, and in light() a texture read in place of band(), with the same split of the strength.

uniform sampler2D ramp : repeat_disable, filter_nearest;

// in light(), instead of band():
float amount = n_dot_l * ATTENUATION * max(strength, 1.0);
float level = texture(ramp, vec2(clamp(amount, 0.0, 1.0), 0.5)).r * min(strength, 1.0);

In a test with a GradientTexture1D set to Constant interpolation and stops at 0, 0.2 and 0.75, the ball showed three bands with the edges where the stops were. A ramp is better when an artist wants to draw the bands: uneven widths, a lit band that is wider than the others, or a soft gradient in one place and a hard edge in another. repeat_disable stops the fully lit end wrapping round to the dark end, and filter_nearest keeps Constant stops hard. Bands from code are better when you want to change the count from a script or the Inspector without making a new texture, and they skip the texture read.

How it builds on the lighting lesson

The lighting and materials guide builds a room with a sun at a rotation of (-55, -25, 0), compares ambient light from a Color at Energy 0 and 0.3, then switches to a sky, and warns about shadow acne and bias. This shader reacts to all of those settings, just more sharply. The demo's sun uses the same -55° pitch, which lights flat ground at N·L 0.82, well inside the top band. The guide's ambient comparison is the one in the section above: Color ambient flattens the dark side of a toon object even more than a smooth one, because the bands remove the last gradient. And shadow acne is far easier to see on hard bands, as the pitfalls below measure.