Not a native English speaker — corrections welcome!

▶ Open the full interactive playground Every demo in one place, full-screen — drag the sliders yourself.

Part 2 of the series. Part 1 was about the pipeline and quantization — floor(x*n)/n turning smooth values into pixel-art bands. This time it's toon lighting: how a surface decides how bright it is, and what happens when I quantize that brightness too.

I'm following David Holland's 3D Pixel Art Rendering in stock Godot 4.7, no engine patches. For the toon shading specifically I also leaned on CaptainProton42's Flexible Toon Shader as a reference.

The math — toon lighting

Brightness at a point on a surface comes down to one dot product: the surface normal N and the direction to the light L.

max(dot(N, L), 0.0)

dot(N, L) is largest when the surface faces the light straight-on, and it goes negative when the surface faces away — the back of the sphere, basically. Negative light doesn't mean anything, so it gets clamped to 0.

That alone gives a smooth gradient from dark to bright. Toon shading is just: take that gradient and run it through part 1's quantization. floor() turns the smooth ramp into hard steps — cel shading.

In Godot, this lives in the light() processor function, and it accumulates into DIFFUSE_LIGHT:

shader_type spatial;

uniform int bands : hint_range(2, 6) = 4;

void light() {
	float ndotl = max(dot(normalize(NORMAL), normalize(LIGHT)), 0.0);
	float toon = floor(ndotl * float(bands)) / float(bands);
	DIFFUSE_LIGHT += toon * ATTENUATION * LIGHT_COLOR * ALBEDO;
}

light() runs once per light in the scene, and each run adds this light's contribution to DIFFUSE_LIGHT — how bright this light makes this surface. Swap floor for round and the bright band gets wider (it rounds up into the top step sooner).

Where I actually got stuck — my shadows came out gray

light() only adds direct light. So the side of the sphere facing away from the light should get ndotl = 0 and stay black. Instead, mine came out gray.

Turned out the culprit wasn't my shader at all — it was the scene's ambient light. light() only handles direct contributions, but Godot's WorldEnvironment also feeds ambient light (and sky radiance) into the surface separately, and that's not something my floor() step ever touched. So the dark side of the sphere was dark from the light I wrote, but still lit from the environment.

What I actually did: tweaked the Ambient Light setting on the WorldEnvironment, and the gray shifted to a different tint (turning it off entirely gets you pure black). There's a more direct fix too — add render_mode ambient_light_disabled; to the top of the shader, which turns off ambient contribution for just this material, so its shadows go pure black regardless of scene settings. Pure black vs. a tinted dark shadow is really just a look you pick.

Dithering (Bayer)

Dithering is the trick of using only two colors (on/off) to fake more brightness steps than you actually have. A Bayer 4×4 matrix is a threshold table — it just says "if I only have room for N pixels turned on in this tile, which ones go first." Index it with screen coordinates (FRAGCOORD) instead of object UVs, and the dither pattern sticks to the screen, not to the object.

Going off the map — dithering the shading itself

Normally dithering gets applied to a smooth gradient — a color, a fog falloff, something continuous. What I tried instead: apply it inside light(), to the lighting strength itself, using the Bayer threshold as an on/off gate per pixel. So the shading itself gets dithered, not just a color afterward. That's what's in the header GIF.

Here's the shader as I actually wrote it:

shader_type spatial;

const float bayer4[16] = float[](
	 0.0,  8.0,  2.0, 10.0,
	12.0,  4.0, 14.0,  6.0,
	 3.0, 11.0,  1.0,  9.0,
	15.0,  7.0, 13.0,  5.0
);

uniform int bands : hint_range(2, 6) = 4;
uniform vec3 color = vec3(1.0, 1.0, 1.0);

void light() {
	float ndotl = max(dot(normalize(NORMAL), normalize(LIGHT)), 0.0);
	float toon = round(ndotl * float(bands)) / float(bands);

	ivec2 p = ivec2(FRAGCOORD.xy) % 4;
	float threshold = (bayer4[p.y * 4 + p.x] + 0.5) / 16.0;

	float lightStrength = toon * ATTENUATION;
	DIFFUSE_LIGHT += vec3(lightStrength > threshold ? 1.0 : 0.0) * LIGHT_COLOR * ALBEDO;
}

void fragment() {
	ALBEDO = color;
}

The key line: lightStrength > threshold ? 1.0 : 0.0. Every pixel checks its own lighting strength against its own spot in the Bayer table, and switches fully on or fully off. So instead of a clean stepped edge between bands, the boundary breaks up into a scatter of dots — dithered, not banded.

Wrap / next

So: one dot product for brightness, floor() (or round()) to band it into cel shading, and if the shadows look gray instead of black, it's not the toon math — it's ambient light from the environment sneaking in. Dithering fakes extra brightness levels with a threshold table, and applying that threshold inside the lighting function itself (instead of to a finished gradient) is what produced the header GIF.

Next up: depth textures.

Not a native English speaker — corrections welcome!

▶ Open the full interactive playground Every demo in one place, full-screen — drag the sliders yourself.

I'm teaching myself Godot 3D pixel-art shaders and building interactive explainers as I go. This is part 1.

What I'm building (series intro)

The goal, a few posts from now: a 3D pixel-art shader that works for both perspective and orthographic cameras, from one codebase. Outlines. Water. God rays. Bloom. The kind of look you see in games that render "real" 3D geometry but make it read as pixel art.

I don't know how to do most of that yet. That's the point of the series — I'm learning it from the ground up and writing down what actually happened, not a polished summary after the fact.

This first post is the boring-but-necessary part: what a shader even is, the pipeline that turns a 3D scene into a pixel-art image, and the one piece of math — quantization — that does most of the actual work.

Where this comes from (credit where it's due)

I didn't invent any of this. I fell down this rabbit hole after reading David Holland's 3D Pixel Art Rendering — the idea that you can render real 3D geometry and still make it read as pixel art kind of broke my brain. I didn't want to just copy a finished shader; I wanted to rebuild each piece from scratch until I actually understood why it works. That's what this series is.

People and work this stands on:

• David Holland — 3D Pixel Art Rendering — the article that started it all: outlines, camera snapping, water, volumetrics, the whole map. He built this in Godot itself — a custom 4.3 build with a handful of engine-source patches for the trickiest parts (a custom camera projection, sampling the shadow map inside shaders). I'm redoing it in stock Godot 4.7 with no engine patches, which is exactly where most of my "wait, how do I do this part?" moments come from.
• t3ssel8r — pretty much defined this look for a lot of us: orthographic + low resolution + camera snapping, and shell-based volumetrics.
• Roystan — clear, patient outline and toon-water tutorials. Unity, but the ideas carry straight over.
• godotshaders.com outline shader — a concrete Godot reference for the outline pass.

If you're new to this, honestly go read and watch their stuff first — they're the real teachers here. This series is just me working through it out loud, in vanilla Godot, writing down what actually happened (mistakes included). Corrections welcome.

The mental model: a shader is a per-pixel function

A shader has (at least) two stages. The vertex stage takes a mesh vertex and decides where it lands on screen. The fragment stage takes a pixel and decides what color it is.

Both are tiny functions. The part that took me a while to really internalize: the GPU runs the fragment function on thousands of pixels at the same time, and each run knows nothing about the others.

So the mental model I keep coming back to is:

I am one pixel. I don't know what color my neighbor is. I can only read my own coordinate and sample textures.

No loops over "all pixels," no shared state between pixels (within a single pass, at least). If I want a pixel to react to its neighbors — for an outline, for example — I have to bring that information in some other way (usually by sampling a texture at nearby coordinates, which is its own topic for a later post).

This is also why a lot of shader code looks weirdly restrictive compared to normal programming. You can't just say "loop over the image and find the edges." You have to ask: what can this one pixel figure out using only its own coordinate and whatever textures it's allowed to sample? Everything downstream gets built out of that constraint.

Coordinates: UV vs SCREEN_UV

A coordinate is only ever meaningful relative to an origin and a set of axes — that's an agreement, not a fact about the universe. Godot's shaders hand you a few different ones, and mixing them up was my first real point of confusion.

• UV is a 0..1 coordinate glued to the surface of the mesh. If the object moves or rotates, the UV-based pattern moves and rotates with it — like a texture printed on the object.
• SCREEN_UV is a 0..1 coordinate glued to the screen. If the object moves, a SCREEN_UV-based pattern stays put — the object is more like a window you're looking at the screen-space pattern through.

Here's the shader I used to see this for myself. Two spheres, the same shader on both — the only thing I flip is whether it reads UV or SCREEN_UV:

shader_type spatial;
render_mode unshaded;

uniform bool use_screen_uv = false;

void fragment() {
    vec2 uv = use_screen_uv ? SCREEN_UV : UV;
    ALBEDO = vec3(uv.x, uv.y, 0.0);
}

Two new keywords here compared to the 2D shader further down. shader_type spatial marks this as a 3D material (the 2D one is canvas_item). render_mode unshaded tells Godot to skip all lighting math and draw ALBEDO straight to the screen — I want to see the raw coordinate as a color, not a lit surface. And in a 3D shader the output color goes into ALBEDO, not COLOR.

With UV, the gradient is printed onto each sphere's surface. Both spheres look identical, and if I rotated one the colors would ride along with it:

Flip to SCREEN_UV and the gradient belongs to the screen instead. Now the left sphere reads greener and the right one oranger, purely because of where they sit in the window — each sphere is just a window onto one shared screen-space gradient:

This distinction matters more than it sounds like it should, because SCREEN_UV is the seed for basically all post-processing — outlines, screen-space effects, anything that needs to know "where am I on the final image" instead of "where am I on this specific object."

The one bit of math: quantization

If pixel art has a mathematical heart, it's this one line:

floor(x * n) / n

Read it left to right: multiply x up by n, floor it (drop everything after the decimal point), divide back down by n. In plain words: force a lower resolution onto a value that was smooth.

There's an identity that goes with it, and it's the thing that made quantization click for me:

x = floor(x) + fract(x)

Any number is exactly its floor (the "staircase" part) plus its fract (the "sawtooth" part, always between 0 and 1). This is always true, not an approximation — floor throws information away, fract holds exactly what floor threw away, and adding them back gives you the original value with zero error.

Here's what that looks like plotted. Top: a smooth ramp against the quantized staircase for n = 8. Bottom: the floor and fract pieces separately, and their sum landing exactly back on the original line.

My first shader (Godot 4.x)

Small enough to paste into a new .gdshader file and run:

shader_type canvas_item;

uniform int steps : hint_range(2, 32) = 8;

void fragment() {
    // UV goes 0..1 across the surface.
    // Each pixel only knows its own UV — nothing about its neighbors.
    float q = floor(UV.x * float(steps)) / float(steps);
    COLOR = vec4(vec3(q), 1.0);
}

The : hint_range(2, 32) part just tells Godot's inspector to show steps as a slider from 2 to 32 instead of a plain number field — pure editor convenience, it doesn't touch the math.

Attach it to a ColorRect or a Sprite2D and you get a horizontal grayscale gradient — except it's banded, not smooth. Bump steps up and the bands get thinner; push it high enough and it looks smooth again (you've just made n large enough that the human eye can't tell the difference). That one floor() call is the heart of the pixel-art look.

Here it is running in Godot — as steps drops, the smooth ramp collapses into fewer and fewer bands:

Where I actually got stuck (the pipeline in practice)

The math above is one line. Getting an actual 3D scene to look pixel-art in Godot is a separate job, and it's mostly plumbing, not shader code.

The approach: render the 3D scene into a SubViewport at a low internal resolution, then display that render on a full-screen TextureRect with the Nearest texture filter, scaled up to fill the window.

The one thing that actually tripped me up: Full Rect did nothing.

I started from a 2D Scene, dropped in a TextureRect, and set its anchor preset to Full Rect expecting it to fill the window. Instead its size stayed 0 — the node was there, but it had no area, so nothing showed up. I stared at the inspector for a while before the cause clicked: my scene root was a Node2D, and Full Rect anchoring only means something inside a Control-based layout tree. The fix was almost silly — make the root a plain Node (or just start the scene with a Node root in the first place). The moment I did that, Full Rect filled the window like I'd expected all along.

Every shader in this post worked as-is once the layout was right — the bug was never in the shader, it was in the scene setup around it. That seems to be the theme with this kind of work: the code compiles, nothing crashes, and the "bug" is a UI element quietly doing nothing, with no stack trace to follow.

Nearest vs Linear — the one setting that makes or breaks the look.

The last piece is the TextureRect's Texture Filter. On the default, Linear, the low-res render gets smoothed as it scales up, so you end up with a blurry image instead of pixel art:

Switch it to Nearest and each low-res pixel is held as a hard-edged block. Same render, same resolution — the only thing that changed is the filter, and that one setting is the whole difference between "blurry 3D" and "pixel art":

Wrap-up / next

So: a shader is a tiny per-pixel function running in parallel with no memory of its neighbors, UV vs SCREEN_UV is about what the coordinate is glued to, and floor(x*n)/n is the one line of math that turns "smooth" into "pixel art." The rest of this post was really just the practical plumbing to get that math onto a real 3D scene.

Next up: toon lighting — dot products, Lambertian shading, and dithering to fake more color depth than the quantized palette actually has. If any of the math or the Godot specifics above is wrong or could be explained better, corrections welcome — I'm still figuring this out.

Not a native English speaker — corrections welcome!

The symptom

I was setting up an auto-publish pipeline for this blog: push a markdown file to posts/, and a GitHub Action publishes it to Hashnode. The workflow triggers like this:

on:
  push:
    branches: [main]
    paths:
      - "posts/**"

I force-pushed a commit that definitely changed files under posts/. Then... nothing.

No workflow run. Not a failed run. Not a skipped run. gh run list showed nothing for that commit, and the Actions tab was empty too.

I checked the usual suspects:

• Actions enabled for the repo — yes
• Workflow file state active — yes
• main actually pointing at my new commit — yes

Everything looked correct. Still silence. This was the confusing part: a failed run gives you a log to read. No run gives you nothing.

The cause

The force push was the problem — combined with the paths filter.

I was consolidating two repositories, so my force push replaced main with a completely unrelated history (no common ancestor between the old and new commits).

To apply a paths filter, GitHub has to answer "which files changed in this push?" by diffing the before/after commits. My best understanding: when the push is a force push to an unrelated history, that diff can't be computed in a meaningful way — and in my case, GitHub silently skipped the workflow instead of running it.

(The docs say that with very large pushes or diff timeouts the workflow "always runs", which is the opposite behavior — so the unrelated-history case seems to be its own thing. If you know the exact rule, please correct me in the comments.)

The fix

One normal commit that touches a path matching the filter:

# any real change under posts/ works
echo "" >> posts/my-post.md
git add posts/my-post.md
git commit -m "Kick CI after force push"
git push origin main

This triggered the workflow immediately, because now GitHub can diff against the previous commit like normal.

Two details that matter:

• git commit --allow-empty does not work here. An empty commit changes no files, so the paths filter matches nothing.
• The kick commit must touch a file that matches your filter (posts/** in my case).

What I learned

• Avoid force-pushing to a branch that has paths-filtered workflows.
• If you must force-push, follow it with a normal commit touching a filtered path to "restart" the trigger.
• When a push produces no run at all (not even a failed one), suspect the trigger filters before suspecting the workflow itself.

Keywords for fellow searchers: github actions workflow not running after force push · on push paths not triggering · workflow silently skipped · no workflow run created after push