A GPU is a second processor with its own memory, called VRAM. Your data has to live in VRAM before the GPU can use it. Getting it there costs time.

A CPU has a few smart cores. A GPU has thousands of simple ones, and they work in lockstep. Lockstep means they move together. Cores are grouped in sets of 64 to 128, and every core in a group runs the same line of code at the same tick. They only differ in the data they work on.

Here is the part to remember. If your shader has an if statement and half the cores take one path and half take the other, the group runs both paths one after the other. Double the time, same result. Splitting paths is slow. Doing the same work across all cores is fast.

Memory matters too. Each group has a small pool of fast memory right next to it. VRAM is the big pool but it is far away and slow. How you read memory decides how fast your shader runs.

Fixed Hardware

Some parts of the GPU are not programmable. They are wired in. They just run when you draw. Three worth knowing.

Rasterizer: Turns triangles into pixels.

Texture units: Read images from memory.

ROPs: Write the final pixel to the screen. They also handle depth checks and blending for see-through things.

The catch is overdraw. If you stack lots of see-through things on top of each other, like smoke or particles, every layer goes through the ROPs. Read, mix, write back. This can slow your game down even when your shaders are simple.

How Games Actually Use The GPU

Every frame, work flows through the GPU in stages. Five of them matter.

Before anything starts, the CPU hands the GPU a list of triangles. Often millions per frame. Each triangle has three corners, called vertices. Each vertex carries some data. Position in 3D space. Color. UV, which is where to read from a texture. A normal, which is the direction the surface faces.

Now the pipeline runs.

Stage 1. Vertex shader. A small program you write. It runs once per vertex, in parallel across the GPU's cores. Its job is to take the vertex from the model's own coordinate space and move it into screen space. The vertex knows where it sits inside the model. The vertex shader figures out where it sits on your screen.

Stage 2. Rasterizer. Fixed hardware. Takes a triangle. Figures out which pixels on the screen are inside it. One triangle in. Many pixels out.

Stage 3. Fragment shader. Another small program you write. It runs once per pixel. It reads textures, applies lighting, factors in shadows, and picks the final color for that pixel.

Stage 4. Depth test. Is this pixel closer to the camera than whatever is already there? If yes, keep it. If no, throw it away. This is how the GPU knows a wall hides what is behind it.

Stage 5. ROPs. Write the final pixel to the framebuffer, which is the image that becomes your screen. Mix with the existing pixel if needed, for things like glass or smoke.

Millions of vertices and pixels flowing through thousands of cores, every frame.

For the pipeline to keep running, the GPU needs to be told what to draw. That is where the trouble starts.

The Draw Call Problem

The GPU cannot draw anything on its own. The CPU has to tell it what to do. "Use this shader. Use this texture. Draw 1200 triangles." That instruction is called a draw call.

Each draw call takes the CPU a tiny bit of time. Just a few microseconds. Sounds like nothing.

Now draw 5000 different objects. That is 5000 draw calls. Suddenly the CPU has spent 5 to 15 milliseconds just talking to the GPU. Your whole frame budget at 60 fps is 16 milliseconds. You blew it before drawing anything.

This is why the CPU is usually the bottleneck in games with lots of objects, not the GPU. The GPU sits there waiting. The CPU cannot send instructions fast enough.

Almost every big trick in game engines, going back decades, is about sending fewer draw calls, or making each one do more work.

Instancing. The First Big Trick.

You often draw the same mesh many times. A forest with thousands of trees all from the same model. An army with hundreds of soldiers from the same character. A particle system with ten thousand identical quads.

Instancing lets you draw the same mesh many times in one draw call. You upload the mesh once. You upload a second buffer of per instance data (positions, rotations, colors, scales).

You tell the GPU "draw this mesh 10 000 times, here is the list." The vertex shader reads its instance index and pulls the right data from the buffer.

One draw call instead of ten thousand. The CPU gets its time back. The GPU runs at full speed.

When you hear people say GPU instancing, this is what they're talking about.

Compute Shaders. GPU As General Parallel Processor.

A compute shader is a program that runs on the GPU but is not tied to the rendering pipeline. It does not care about triangles. It does not output pixels. It just reads and writes arbitrary buffers in parallel across thousands of threads.

You dispatch a grid of threads. Thousands at a time. Each thread has an index. Each thread runs the same program on different data.

This turned the GPU into a general purpose parallel processor. Physics simulation. Particle updates. Image processing. Neural networks. Cloth. Water. Fluid dynamics. Audio effects. Anything that fits "do the same thing to a lot of data" now lives on the GPU.

Indirect Draws. The GPU Drives Its Own Work.

One more trick that mattered.

When you draw things on screen, the CPU normally tells the GPU what to draw and how many. Something like "draw 1000 trees." That number, 1000, is baked into the instruction before the GPU ever sees it.

Indirect draws flip this. The CPU says "draw however many trees this buffer tells you to." The actual count lives in GPU memory. The CPU does not know it. The CPU does not care.

Now here is where it clicks. A compute shader can write to that buffer. So a compute shader can decide the count, and the draw call just reads whatever the compute shader wrote. The CPU is cut out of the loop.

This unlocks real things.

A compute pass can cull objects hidden behind walls, then write the count of visible ones. It can count how many grass blades are close enough to matter. It can pick LOD levels. It can kill dead particles and report how many are still alive. The draw call consumes whatever number comes out. No CPU round trip. No waiting.

The GPU is driving its own work. It's so fucking smart. This took me a second to understand. Compute shaders are fucking cool, but with this, it's really sick.

To make it click for you: The compute shader runs on the GPU. It writes a number into a buffer that lives in GPU memory. Say the number is 347. That buffer never leaves the GPU. Then the draw call happens. The CPU sent this draw call earlier, but the draw call is basically a note that says "hey GPU, when you get to this, look at buffer X and draw that many things."

The GPU reaches that instruction. The GPU itself reads buffer X. Sees 347. Draws 347 things.

WebGL days

The web got WebGL in 2011, based on an older mobile graphics standard from the mid 2000s. It could run vertex and fragment shaders, do basic instancing, and render textures. It was enough to put 3D on the web for the first time.

But it was missing the big stuff. No compute shaders. No indirect draws. No flexible storage buffers.

So if you wanted 10000 animated grass blades, the wind math had to run in JavaScript on the CPU. Update every blade. Upload the buffer to the GPU. Draw. The CPU was doing work the GPU should have been doing.

What WebGPU Actually Changes

WebGPU is a new browser API that exposes modern GPU capabilities.

Real compute shaders. Arbitrary GPU programs that read and write buffers. Physics, AI, particles, image effects, all of it.

Storage buffers. Generic read write GPU memory. You lay data out however you want.

Indirect draws. The GPU decides what gets rendered.

Where This Shines

Instancing scaled up. A million grass blades drawn in one call, with per blade position, height, wind sample, and color all generated in a compute pass.

Particle systems. Fire, smoke, sparks, magic. Every particle advanced in parallel on the GPU. Tens of thousands of particles at 144 fps with the CPU doing nothing per frame.

Simulation. Cloth, water, fluid, flocking, crowds. Each element updated in a compute pass. The browser can do what Unity does.

Terrain and worlds. Streaming LOD, procedural detail, real game scenes. Not the scaled down browser version. The native version, running in a tab.

A CPU core has a clock. It ticks about 3 to 4 billion times per second. Each tick, the core tries to do one unit of work. That is where your frames come from.

Inside one core there are four parts that matter. The Control Unit reads the next instruction. The ALU (Arithmetic Logic Unit) is the calculator that does the math. Registers are tiny slots right next to the ALU holding the numbers being worked on. Caches are fast memory nearby that feed the registers.

All math happens in the ALU. The ALU only touches registers. So every number has to travel from RAM through the caches into a register and out. The math is fast. The travel is slow.

When your data is not in the cache at the moment the ALU needs it, the core stalls. A stalled core still ticks. It just does not do anything on those ticks. Wasted work. That is where most slow code actually loses.

The Memory Hierarchy

Modern CPUs can run about a hundred math operations in the time it takes to fetch one value from RAM. So the thing that makes code fast is not the math. It is keeping your data close to the ALU.

Caches work in chunks called cache lines, usually 64 bytes. When you touch one byte, the CPU pulls 64 bytes around it into the cache. Touch the next 63 bytes right after. Free.

Touch memory randomly across the heap and every access is a new cache miss. Every miss is tens of wasted ticks while the ALU waits.

Sequential access is fast. Random access is slow. Most of this post is about making your JavaScript sequential.

SIMD. One Instruction, Many Numbers.

Your CPU has special instructions called SIMD, Single Instruction Multiple Data. They do the same math on a chunk of numbers in a single tick. Usually 4 or 8 at a time on a mainstream CPU.

Adding two arrays of 8 floats without SIMD takes 8 ticks, one pair per tick. The same work with SIMD takes 1 tick for all 8.

A lane is one parallel slot inside a SIMD register. A modern CPU can pack 8 floats side by side in one register. Each float slot is a lane. One SIMD add touches all 8 lanes at once. Scalar JS math uses only lane 0. The other 7 are physically there but sitting idle.

Same CPU. Same clock. Same silicon. The SIMD lanes are there either way. Without SIMD you leave 7 of the 8 lanes idle. You pay for the whole chip and use one eighth of it.

JavaScript does not expose SIMD directly. Modern engines auto vectorize tight loops over typed arrays sometimes.

Branch Prediction

Modern CPUs run a pipeline. The next instruction starts before the previous one finishes. Several are always in flight at the same time.

The problem comes with if statements. The CPU does not know which branch to take until the condition is evaluated. Rather than stall, it guesses. This is branch prediction. Guess right, free. Guess wrong, the CPU throws away the work it did on the wrong path and restarts. A mispredict costs around 15 ticks.

A condition that takes the same path almost every time is basically free. The predictor learns it. A condition that flips 50/50 every iteration forces a mispredict half the time and turns a tight loop into a stumble.

Fix it by removing data dependent branches from inner loops, or by sorting your data so the branches become predictable.

The Big Trick. Structure of Arrays.

This is the one that matters most. Every serious JS game engine, physics library, and particle system does it. Most regular JS does not. The gap in speed is an order of magnitude.

You have an array of objects. Each object has many fields. You loop over them doing math on a few fields.

type Particle = { x, y, vx, vy, color, age, life }
const particles: Array<Particle> = [...]

for (let i = 0; i < particles.length; i++) {
  particles[i].x += particles[i].vx
  particles[i].y += particles[i].vy
}

This looks clean. It is also cache hostile. Each particle is a scattered object on the JS heap. When you read particles[i].x, the cache line you get contains x, y, vx, vy, color, age, life, and chunks of V8 metadata. You use two of those. The other 60 bytes of the cache line are dead weight for this loop.

Flip the layout. Same data, different memory arrangement.

const x = new Float32Array(count)
const y = new Float32Array(count)
const vx = new Float32Array(count)
const vy = new Float32Array(count)

for (let i = 0; i < count; i++) {
  x[i] += vx[i]
  y[i] += vy[i]
}

Now every cache line is full of numbers you actually read. No metadata. No waste. You blaze through memory in order and the prefetcher pulls the next 64 bytes before you need them.

This pattern has a name. Structure of Arrays, or SoA. The opposite is Array of Structures, AoS. AoS is how most JavaScript is written. SoA is how fast JavaScript is written.

Every serious engine does this. Unity DOTS and ECS. Bevy. Unreal Mass. Box2D and Rapier physics. Three.js instanced meshes. They all store components in parallel typed arrays under the hood.

The Entity Component System pattern game engines ship with is largely a way to enforce SoA automatically. You write code that looks like "for every entity with a Position and Velocity," and the engine guarantees those components live in parallel arrays you never see. You think in terms of "the data I read together should live together," and the engine does the layout for you.

When people say data oriented design, this is what they mean.

JavaScript Specifics

Two things V8 cares about on top of the CPU rules.

Typed arrays hold raw numbers. A regular Array stores values as tagged pointers. Every element could be anything, so every read checks the type first. A Float32Array or Int32Array is a raw packed block of numbers. No type checks. Cache friendly. Use them for every hot numeric buffer.

Stable object shapes. V8 watches every object. If you always set the same fields in the same order at construction, V8 assigns a fast hidden class and field access becomes a direct memory read. Add fields later or delete them and you drop to the slow path.

// slow. Shape changes.
const p = { x: 0, y: 0 }
p.vx = 0
p.vy = 0

// fast. Shape is final at birth.
const p = { x: 0, y: 0, vx: 0, vy: 0 }

For hot code, combine these two. SoA layout, typed arrays for the numeric columns.

Before And After

Add two vectors of 100 000 3D positions per frame.

Naive AoS version.

type Vec3 = { x: number, y: number, z: number }
const a: Array<Vec3> = [...]
const b: Array<Vec3> = [...]
const out: Array<Vec3> = a.map(() => ({ x: 0, y: 0, z: 0 }))

for (let i = 0; i < a.length; i++) {
  out[i].x = a[i].x + b[i].x
  out[i].y = a[i].y + b[i].y
  out[i].z = a[i].z + b[i].z
}

300 000 object allocations. Random cache misses every iteration. 8 to 15 ms per frame on a modern laptop.

SoA version with typed arrays.

const ax = new Float32Array(100_000)
const ay = new Float32Array(100_000)
const az = new Float32Array(100_000)
const bx = new Float32Array(100_000)
const by = new Float32Array(100_000)
const bz = new Float32Array(100_000)
const ox = new Float32Array(100_000)
const oy = new Float32Array(100_000)
const oz = new Float32Array(100_000)

for (let i = 0; i < 100_000; i++) {
  ox[i] = ax[i] + bx[i]
  oy[i] = ay[i] + by[i]
  oz[i] = az[i] + bz[i]
}

Zero allocation in the hot loop. Nine sequential reads and three sequential writes. 0.3 to 0.8 ms. More than ten times faster for the same math.

Particle systems drive fire, smoke, sparks, rain, dust, magic. They look complex. They are not. A particle system is a flat image drawn over and over with small variations. That is it.

What A Particle Actually Is

A particle is a quad. Quad means a rectangle made of two triangles.

The quad has a texture on it. Usually small. Usually with transparent edges.

The quad always faces the camera. So when you move the camera around, the quad rotates to face you. This is called a billboard. Like a highway billboard that turns to stay readable from the road.

That is the whole thing. A particle is one textured billboard.

Now imagine 10 000 of them. Different positions. Different sizes. Different colors. Some fading out. Some rotating. That is a particle system.

What A Particle System Is

A particle system does three jobs. Emit. Simulate. Render.

Three jobs. That is the whole system.

Emit

You pick a shape for the emitter. Point. Box. Sphere. Cone. Mesh surface. New particles spawn from that shape.

You pick a rate. 100 per second. Bursts of 50 at a time. Whatever fits the effect.

Initial state is usually random within bounds. Velocity random in a cone. Size random in a range. Color maybe random. Life random.

Random with bounds is what makes particles look organic instead of robotic. Pure random is noise. Pure fixed values are robotic. The middle is life.

Simulate

Every frame you loop over every living particle. You update.

• Position. Add velocity times deltaTime. DeltaTime means the time since the last frame, so your particle moves the same distance regardless of frame rate.

• Velocity. Apply gravity, drag, wind, any force you want.

• Age. Increase by deltaTime.

• If age exceeds lifetime, kill the particle.

• Attributes over lifetime. Size, color, opacity often follow a curve across the particle's life.

That last part is where the magic lives. A fire particle is yellow at birth. Red in the middle. Black smoke at death. Driven by a curve with three key points.

Render

Each living particle becomes a quad. Each quad gets the texture. Each quad gets tinted by the particle's color. Each quad scales to the particle's size.

Draw them all. Move on to the next frame.

Blend Modes. The Most Important Choice

A particle is transparent where its texture is transparent. How the transparent parts combine with what is behind them matters a lot. This is the blend mode.

Two blend modes matter for games. Additive and alpha.

Additive Blending

Additive means the particle's color is added to whatever is behind it. The math is final = src + dst. Source is the particle color. Destination is what is already there.

Black plus anything is that anything. So black reads as fully transparent with no alpha channel needed.

Bright colors stacked on bright colors push toward white. Fire looks like fire because the overlaps get brighter, not darker.

Use additive for fire. Sparks. Magic. Lightning. Lasers. Anything that emits light.

Alpha Blending

Alpha means the particle has an alpha channel. Alpha is a fourth value per pixel that says how opaque that pixel is. 0 is fully transparent. 1 is fully opaque.

The math is final = src.rgb * src.a + dst.rgb * (1 - src.a). Mix between particle color and scene color, weighted by alpha.

Alpha blended particles can be any color including black. Overlaps look like overlaps. No brightness push.

Use alpha for smoke. Fog. Dust. Clouds. Rain. Anything solid-ish that does not emit light.

Why This Matters

Pick the wrong blend mode and your fire looks like grey paper. Your smoke looks like fire. Particle feel lives in the blend mode.

The Sorting Problem

Alpha blended particles have a painful trick.

If you draw a near particle first, then a far particle behind it, the far one either fails the depth test and disappears, or draws on top incorrectly because it writes wrong depth. Either way looks broken.

Solution. Sort particles by distance to the camera every frame. Draw furthest first. Nearest last. This is called back to front sorting.

Additive particles do not need sorting. The math is commutative. a + b + c = c + b + a. Order does not change the pile of brightness.

In a game with tens of thousands of alpha particles the sort has to happen every frame. On the CPU that chokes above a few thousand particles. On the GPU you use a bitonic sort, a parallel sort algorithm that fits GPU threads well, and the cost stays flat.

The Intersection Problem

Here is where particle systems win or lose.

A particle quad moves through the world. Sometimes the quad passes through solid geometry. A smoke quad crosses the floor. A fire quad crosses a wall.

The depth test of the GPU cuts the quad at the intersection. You see a hard straight line where the quad meets the surface. Looks like a flat sticker pressed into the wall. Reveals that the quad is flat. Kills the effect.

This is the single biggest tell that particles are fake.

Soft Particles. The Fix.

Soft particles solve the intersection problem. You fade the particle's alpha toward zero as it gets close to the geometry behind it. No more hard cut. Smooth fade instead.

The illusion. A particle cannot pass through a wall anymore because it fades out before it touches the wall.

How It Works

In the particle's fragment shader you need two values.

1. Particle depth. The distance from the camera to this particle pixel.

2. Scene depth. The distance from the camera to whatever solid geometry is behind this same pixel, read from the depth buffer.

Subtract the two. The result is how far the particle sits in front of the wall.

If the distance is big, keep full alpha. If the distance is small, fade the alpha toward zero. A smoothstep function handles the curve. Smoothstep is a function that smoothly ramps from 0 to 1 between two edges with an S shape, no sharp transition.

delta = sceneDepth - particleDepth
softAlpha = smoothstep(0, falloffRange, delta)
finalAlpha = particle.alpha * softAlpha

falloffRange is a tunable number. Small values mean the fade happens right at the wall. Big values mean particles fade out even when kind of far from the wall. You tune per effect.

The Depth Buffer Catch

Reading from the depth buffer does not give you real world distance. It gives you a non-linear value between 0 and 1 optimized for precision near the camera. You have to linearize it. Convert back to actual view space distance using the camera's near and far planes.

The formula is algebra. Not scary. Three.js has a helper, in raw WebGPU you do it yourself.

Once you have linear depth, the math above just works.

Particles In Three.js

Three.js gives you two paths.

THREE.Points

A built in. Each particle is a point primitive, a GPU feature where one vertex becomes a square sprite in screen space automatically.

Fast. Simple. No quad geometry to manage. You set positions in a buffer and Three.js draws them.

The downsides. Size is in pixel units, not world units, which is awkward for 3D effects that need to feel scaled. You get one size per particle. And you cannot use arbitrary geometry, only square sprites.

Instanced Quad Meshes

You build a quad geometry once. You instance it, drawing the same quad thousands of times with per instance data for position, size, color, rotation. Each instance is a real quad in world space.

More work to set up. More control. Works for arbitrary shapes, ribbons, trails, mesh particles. Better for real VFX systems.

WebGPU Changes Everything

Traditional Three.js particle code was CPU driven. JavaScript looped over every particle every frame, updated its position, uploaded fresh data to the GPU. Fine below 1000 particles. Painful above 2000. Dead above 5000.

WebGPU compute shaders change the story. Compute shaders are GPU programs that run in parallel over buffers of data. Move the particle simulation into a compute shader and JavaScript never touches per particle state again. The GPU advances 100 000 particles each frame in one dispatch with no perf drop.

The bottleneck shifts from simulation to sorting. And sorting moves to a bitonic compute pass too.

This is the path a real WebGPU VFX library takes. Compute shader simulation. Instanced quad rendering. GPU sort for alpha blending. Soft particles via depth buffer fade.

Ghost of Tsushima renders huge fields of grass that sway in the wind. Each blade animates on its own. Roughly 83,000 blades on screen at once. In about 2.5 milliseconds per frame.

This post is not about copying their exact code. It is about the core ideas behind how they did it. Principles you can steal and reuse whenever you need to render a lot of something.

Here's the original talk: Procedural Grass in Ghost of Tsushima.

The First Big Decision. No Grass Cards.

Most games use grass cards for grass. A grass card is a flat rectangle with a grass texture painted on it. Like a photo of grass taped to cardboard. You place thousands of these around the world.

Grass cards have two big problems.

One. The wind animation is stuck to the whole card. The whole card wiggles as one piece. Individual blades cannot sway independently. It looks fake up close.

Two. Overdraw. Overdraw is when the GPU paints the same pixel more than once in a frame. Cards overlap a lot. Most of each card is transparent. The GPU still has to process all those transparent pixels. Wasted work.

Sucker Punch threw cards out. Instead. They build each blade of grass from scratch using math. Every frame. On the GPU.

Principle One. Build It From Math. Not From Assets.

Each blade in Ghost of Tsushima is a cubic bezier curve. A cubic bezier curve is a math curve defined by 4 control points. You move those points. The curve changes shape.

• Point 1. Base of the blade. Where it meets the ground.

• Point 4. Tip of the blade.

• Points 2 and 3. In the middle. They control how the blade bends.

Move the tip. The blade leans. Push the middle points up. The blade arches. That is it. Whole blade shape controlled by 4 positions.

Why this is a huge deal.

Cards are static. You made them once. You are stuck with them.

Bezier curves are live. You build the blade fresh every frame from 4 points. So.

• Want the blade to sway. Move the tip a little.

• Want the player to push it. Push a control point.

• Want wind to curve it. Move the middle points.

• Want 50 different blade shapes. Just change the point positions.

You are not animating a model. You are rebuilding the blade every frame with slightly different numbers.

Principle Two. The CPU Is the Bottleneck. Talk to the GPU Less.

Say you have 83,000 blades of grass. If the CPU tells the GPU "draw this blade" 83,000 separate times. The CPU dies. Not because drawing is slow. Because talking is slow.

Each instruction to the GPU is called a draw call. Draw calls are expensive on the CPU side. Setting up state. Sending data. Validation. All that overhead adds up fast.

The fix is GPU instancing. You tell the GPU once. "Draw this blade shape 83,000 times. Here is the list of positions. Go." One draw call. GPU handles the rest in parallel.

Wait. Is this not just parallelism.

No. GPUs are parallel by default. That is just what they do. The thing instancing fixes is different. It cuts down draw call overhead. The CPU saying the same thing 83,000 times vs saying it once.

Take away principle. When you have many copies of something. One mesh. Many positions. Instance it. Particles. Trees. Rocks. Crowds. Bullets. Tiles. All the same pattern.

Principle Three. Do Not Compute What You Cannot See.

Even with instancing. You do not want to render a million blades when only 83,000 are visible. That is 12x more work than needed.

Ghost of Tsushima throws blades away in stages. Before they ever reach the vertex shader.

• Distance culling. Too far from the camera. Drop it.

• Frustum culling. Outside what the camera can see. Drop it. The frustum is the pyramid shape of what the camera is looking at.

• Occlusion culling. Hidden behind a hill or a wall. Drop it.

• Type culling. This spot has no grass type assigned. Drop it.

• Height culling. This spot has zero-height grass. Drop it.

Each stage is cheaper than the next. Cheap tests first. Expensive tests only on survivors. By the time you start actually building blades. You have the real working set.

Take away principle. Culling is layered. Cheap tests kill most of the work. Expensive tests only run on what survives. This pattern applies everywhere. Physics. AI. Rendering. Audio. Pathfinding.

Principle Four. Clumps. Controlled Randomness Beats Pure Randomness.

Their first grass looked boring. Like a golf course. They tried adding more randomness. It just looked messy. Not natural.

Real fields are not random. They are clumpy. This patch got more sunlight so the grass is taller here. That spot has different soil so the grass is darker there. The variation has structure.

To fake this. They use a voronoi algorithm. Voronoi means dividing space into regions around points. Each blade checks which clump point it is closest to. That clump controls the blade's height. Direction. Color. Bend.

So instead of each blade being random by itself. Blades in the same clump share traits. The field has patches of tall grass. Patches of short grass. Patches pointing slightly different directions. It looks alive.

Take away principle. Randomness alone looks fake. Structured variation looks real. If you need something to feel organic. Group it into clusters first. Then vary within and between clusters.

Principle Five. Two Levels of Detail. Far Stuff Gets Cheaper.

Close grass has 15 vertices per blade. Far grass has 7. That is less than half.

A vertex is a corner point on a piece of geometry. More vertices means smoother curves but more work. Far away you cannot see the difference. So use less.

Transitioning between the two is tricky. If you just snap from 15 to 7 verts. The blade shape pops. Visible. Ugly. So the high-detail version slowly blends toward the low-detail shape as it gets close to the transition distance. By the time the swap happens. Both versions look nearly identical. No pop.

Also. Far away tiles are twice as big but have the same number of blades. So far grass is spread out twice as far apart. To hide this. Near grass drops 3 out of every 4 blades as it gets close to the far distance. Thins out gradually. So when you cross the line. The density already matches.

Take away principle. Not everything deserves full detail. Pay for quality where the player will see it. Skimp where they will not. And always blend between detail levels. Never snap.

Principle Six. One Trick For Short Grass. Fold The Verts.

Here is a clever one. If the grass is short. The blade does not need all 15 vertices. A short blade looks fine with 7. So they reuse the other 8 vertices to build a second blade right next to the first one.

Same draw call. Same vertex budget. Twice the blades. Free density.

You only get this trick because the geometry is procedural. If you were using cards or premade meshes. You could not do this. The vertices are flexible. So you use them however is most useful.

Take away principle. When you have a fixed budget. Ask if you can split it. Sometimes the thing you are building does not need the whole budget. So the leftover becomes another thing.

Your JavaScript does not run directly. The engine transforms it first. V8. SpiderMonkey. JavaScriptCore. They all follow roughly the same steps.

Parse. The engine reads your source code and builds an AST. AST means Abstract Syntax Tree. A tree structure that represents the code.

Bytecode. The AST gets compiled to bytecode. Bytecode is a simpler instruction set that the engine can execute quickly. Not machine code yet. Just a middle step.

Interpret. The engine runs the bytecode in an interpreter. This is fast to start but slow to execute long-term.

Optimize. If a piece of code runs often. The engine compiles it to real machine code using a JIT compiler. Machine code is the actual instructions your CPU runs. Fast.

JIT means Just-In-Time. The compiler runs while the program is running. Not ahead of time.

Hidden Classes. Why Object Shape Matters.

JavaScript lets you add properties to objects whenever you want. Convenient. But it makes objects hard to optimize.

Engines solve this with hidden classes. Also called shapes or maps.

A hidden class is an internal structure that tracks what properties an object has and in what order. Every object gets one.

Same properties in the same order. Engine reuses the hidden class. Fast. Different orders. Different hidden classes. Slow.

Example.

const a = { x: 1, y: 2 };
const b = { x: 1, y: 2 };
// Same hidden class. Engine can optimize both together.

const c = { x: 1 };
c.y = 2;
const d = { y: 2 };
d.x = 1;
// Different hidden classes. Even though they end up with same properties.

The lesson. Initialize objects with the same shape in the same order. Every time.

Inline Caches. Remembering Shapes.

The hidden class lets the engine skip property lookups.

First time you access obj.name. The engine finds where name lives inside that hidden class. Then caches that location right next to the instruction.

Next time that instruction runs. If the object has the same hidden class. The engine reads directly from the cached location. No lookup.

This cache is called an inline cache or IC. It is one of the biggest reasons modern JavaScript is fast.

Every spot in your code where you access a property has its own inline cache. The cache tracks which hidden classes have shown up at that exact spot. Three possible states.

Monomorphic. Only one hidden class has ever been seen there. The engine just checks "same shape as before? yes. grab from the known location." One check. Fastest.

Polymorphic. A handful of different hidden classes have been seen. Usually 2 to 4. The engine now has to check each one in turn. "Is it shape A? No. Shape B? Yes. Grab from there." More checks. Slower.

Megamorphic. Too many different hidden classes have shown up. Past the engine's limit. The cache gives up and falls back to a full generic property lookup every time. Slowest.

JIT Compilation. From Warm To Hot.

The engine does not optimize everything. It watches your code and tracks which functions run often. A function that runs many times is called hot.

When a function gets hot. The engine sends it to the optimizing compiler. The compiler makes assumptions based on what it has seen.

"This function always receives two numbers." "This object always has these properties in this order." "This array always contains integers."

Under those assumptions. It generates fast machine code. Much faster than bytecode.

The key thing. The optimized code is not general. It is specialized for the patterns observed.

Deoptimization. When Assumptions Break.

Assumptions can be wrong. You pass a string where you used to pass a number. You add a new property to an object. You mix types in an array.

When that happens. The optimized code is no longer valid. The engine throws it away and falls back to the bytecode interpreter. This is called deoptimization.

Deoptimization is expensive. The optimization work is wasted. Your code runs slower until the engine decides to reoptimize. If it does.

Common causes.

• Passing different types to a function that used to be consistent.

• Adding or deleting properties on hot objects.

• Mixing integers and floats in an array.

• Using constructs the optimizer does not handle well.

Garbage Collection. How The Engine Frees Memory.

You do not manually free memory in JavaScript. The engine handles it. The system that does this is the garbage collector. Or GC.

The GC walks a graph. It starts from things called roots and follows every reference it finds. Anything reachable from a root is live. Anything it cannot reach is garbage.

What Counts As A Root

Roots are the anchor points. Things the engine always treats as live.

• Global and module-level variables. Things on window, globalThis, or declared at the top level of a module. Live for the lifetime of the program.

• Active stack variables. Local variables inside functions currently running on the call stack. Live only while their function is executing.

• Closure-captured variables. Values an outer scope captured that a still-reachable closure holds on to.

Roots themselves are not collected. But what they point to can still become garbage. Set a global variable to null. The old value it used to point to is now unreachable. Free to collect. The root slot itself is untouched.

A local variable stops being a root the moment its function returns. Whatever it pointed to becomes garbage unless something else still holds a reference.

Generational Collection

Modern engines use generational garbage collection. Based on one observation. Most objects die young. A function creates objects. Uses them. Returns. Those objects are garbage almost immediately.

The GC splits memory into two zones.

Young generation. Small. Where new objects are born. Most die here.

Old generation. Larger. Where objects that survived a few young collections get promoted.

Minor GC vs Major GC

Minor GC. Collects only the young generation. Happens often. Fast. Pauses are usually a few milliseconds or less.

Major GC. Collects the old generation. Sometimes scans both generations together. Happens rarely. Slower because there is more memory to scan and more references to trace.

The split keeps most pauses short. You pay the long pause only when the old generation gets full.

Tips For Writing Performant JavaScript

You do not need to hand-tune everything. But these habits help the engine help you.

Keep Object Shapes Consistent

Same properties. Same order. Every time.

// Good
const user1 = { name: "Alice", age: 30, role: "admin" };
const user2 = { name: "Bob", age: 25, role: "user" };

// Bad
const user1 = { name: "Alice", age: 30 };
user1.role = "admin"; // new hidden class

Declare All Properties Upfront

If a property might be missing at first. Initialize it to null. Do not add it later.

// Good
const user = { name: "Alice", age: null };
user.age = 30; // same hidden class. just a value change.

// Bad
const user = { name: "Alice" };
user.age = 30; // new hidden class

Do Not Delete Properties

Set them to null instead. Delete changes the hidden class. Setting to null does not.

// Good
user.age = null;

// Bad
delete user.age;

Keep Argument Types Consistent

If a function takes a number. Always pass a number. Mixing types causes deoptimization.

function add(a, b) {
  return a + b;
}

add(5, 10); // engine optimizes for numbers
add("hi", "bye"); // deopt. now reoptimizes for strings

Do Not Mix Integers And Floats In Arrays

The engine uses a different internal format for integer arrays vs float arrays. Mixing them forces a slower general format.

// Good
const ints = [1, 2, 3, 4];
const floats = [1.5, 2.5, 3.5];

// Bad
const mixed = [1, 2.5, 3, 4.5];

Use Set For Membership Checks

includes on an array is O(n). has on a Set is O(1). Huge difference when checking membership often.

// Slow. O(n * m)
const result = list1.filter((x) => list2.includes(x));

// Fast. O(n + m)
const set = new Set(list2);
const result = list1.filter((x) => set.has(x));

Use Map For Dynamic Keys

If you are adding and removing keys at runtime. Use a Map. Regular objects end up with constant hidden class changes. Maps do not.

// Bad
const cache = {};
cache[userId] = data;

// Good
const cache = new Map();
cache.set(userId, data);

Use === Not ==

== does type coercion behind the scenes. === compares directly. Faster and more predictable. There is no reason to use ==.

Watch Out For Closures Holding Large Data

A closure keeps alive everything it captures. Even if you only use a small piece. The GC cannot free the rest.

// Bad. keeps all of hugeData alive
function makeHandler() {
  const hugeData = loadHugeData();
  return () => console.log(hugeData.name);
}

// Good. only keeps the name
function makeHandler() {
  const hugeData = loadHugeData();
  const name = hugeData.name;
  return () => console.log(name);
}

Linear algebra is the math of vectors and matrices. That is it. The whole field.

Vectors describe things like position and direction and movement. Matrices describe transformations. Like moving things. Rotating things. Scaling things.

Games are made of 3D points that need to be positioned and moved and rotated and projected onto your screen. All of that is vectors and matrices. That is why this matters.

Part 1. Vectors.

A vector is a list of numbers. That is the simplest definition.

A 2D vector has two numbers. Like (3, 4). A 3D vector has three numbers. Like (2, 5, 7). You can have 4D vectors and beyond but games mostly use 2D and 3D and sometimes 4D.

But what do those numbers mean? It depends on what you are using the vector for.

Position Vectors

A position vector tells you where something is in space. If your player is at (10, 0, 5) that means they are 10 units along the X axis. 0 units on the Y axis. And 5 units on the Z axis.

Direction Vectors

A direction vector tells you which way something is pointing. Not where it is. Just which way.

If your character is facing forward. Their direction vector might be (0, 0, 1). That means zero on X. Zero on Y. One on Z. So they are pointing down the Z axis.

The same numbers can be a position or a direction depending on how you use them. That is important to remember.

Part 2. Basic Vector Operations.

Vectors are useful because you can do math with them. Here are the operations you will use constantly.

Adding Vectors

You add vectors by adding each of their numbers together.

(1, 2, 3) + (4, 5, 6) = (5, 7, 9)

Why is this useful? Because adding a direction vector to a position vector moves the position in that direction.

If your player is at (10, 0, 5) and they move forward by (0, 0, 1) their new position is (10, 0, 6). That is literally how movement works in games.

Scaling Vectors

You can multiply a vector by a single number. This is called scalar multiplication. A scalar is just a regular number. Not a vector.

2 × (1, 2, 3) = (2, 4, 6)

This makes the vector bigger or smaller while keeping its direction the same. Multiply by 2 and it is twice as long. Multiply by 0.5 and it is half as long. Multiply by -1 and it flips around pointing the opposite way.

This is useful for things like speed. A direction vector tells you where you are going. Multiply it by how fast you want to go. Now you have velocity.

Part 3. Magnitude and Normalization.

Magnitude

The magnitude of a vector is its length. How long is the arrow.

For a 2D vector (3, 4) the magnitude is 5. For a 3D vector you use the same idea. Square each number. Add them up. Take the square root. You do not need to memorize the formula. Just know that magnitude means length.

If a vector represents velocity. Its magnitude is the speed. If it represents a distance from A to B. Its magnitude is how far apart they are.

Normalization

A normalized vector is one whose length is exactly 1. Also called a unit vector.

You normalize a vector by dividing it by its own magnitude. The direction stays the same. Only the length changes to 1.

Why do this? Because when you only care about direction not distance. You want length 1. It makes math cleaner and faster.

Every time a game needs "which way is this thing facing" or "which direction is the light coming from" it uses normalized vectors.

Part 4. The Dot Product.

This one is huge. The dot product shows up everywhere in games.

The dot product takes two vectors and gives you back a single number. Not a vector. Just a number.

Here is what matters. That number tells you how aligned the two vectors are.

• If they point in the exact same direction. The dot product is 1.

• If they are perpendicular. Ninety degrees apart. The dot product is 0.

• If they point in opposite directions. The dot product is -1.

• Anything in between gives you a value between -1 and 1.

This only works cleanly when both vectors are normalized. Remember normalization from before? This is one of the reasons it matters.

Why You Care About The Dot Product

Lighting. To figure out how bright a surface is. You take the dot product of the surface normal and the light direction. A surface normal is a vector that points straight out from a surface. If it faces the light the dot is close to 1. Bright. If it faces away the dot is close to 0 or negative. Dark. That is literally how games calculate basic lighting.

Is something in front of you? Take the dot product of your forward direction and the direction to the other object. If it is positive. They are in front of you. If negative. They are behind you. Super useful for AI and camera logic.

What angle are two things at? The dot product tells you how aligned two vectors are. You can use it to check if two objects are roughly facing the same way. Or for a guard that should only see you if you are in their cone of vision.

Part 5. The Cross Product.

The cross product takes two vectors and gives you back a new vector. Not a number like the dot product. An actual vector.

The new vector is perpendicular to both of the input vectors. Ninety degrees from both.

Why You Care About The Cross Product

Calculating normal vectors. A normal vector points straight out from a surface. Games need them for lighting and physics. If you have a triangle with three corners. You can take two of its edges as vectors. Cross product them. The result is the normal vector for that triangle. Every single 3D model uses this.

Defining a 3D coordinate system. If you know which way is forward and which way is up for a character. You can cross product them to find which way is right. This is how character controllers and cameras work.

Part 6. Matrices.

A matrix is a grid of numbers. Rows and columns.

A 4x4 matrix has 16 numbers arranged in 4 rows and 4 columns. That is the most common one in games.

Matrices look scary but they do one main thing. They transform vectors.

Transform means change. Move. Rotate. Scale. Any of that.

When you multiply a matrix by a vector you get a new vector. The matrix is the transformation. The original vector is the input. The result is the transformed vector.

The Three Transformations You Need

There are three main kinds of transformations in games. Each one is just a specific matrix.

Translation. Moves a point from one place to another. Adds some offset to the position. If you want to move something 5 units to the right. There is a translation matrix for that.

Rotation. Spins a point around an axis. Rotating around the Y axis spins things like they are on a turntable. Rotating around the X axis tilts things up and down. Each rotation is its own matrix.

Scale. Makes things bigger or smaller. A scale of 2 doubles the size. A scale of 0.5 halves it. You can even scale differently on each axis. Make something twice as tall without changing its width.

Part 7. Combining Transformations.

Here is the really cool part. You can multiply matrices together to combine transformations.

If you have a rotation matrix and a translation matrix. Multiply them together. Now you have a single matrix that rotates AND translates in one step.

This is how every 3D object in a game gets placed into the world. The game has a matrix for each object that contains all the position and rotation and scale info combined. One matrix holds everything.

Order Matters

One thing to watch out for. The order you multiply matrices in changes the result. Rotating then moving is different from moving then rotating.

Think of it like directions. Walk 10 steps forward then turn right. You end up in a different place than if you turn right first and then walk 10 steps forward. Same operations. Different order. Different result.

Part 8. The Big Picture. How It All Fits In A 3D Engine.

Every 3D point you see on screen goes through a chain of matrix transformations before it gets drawn. This chain is called the MVP transformation. Model. View. Projection.

Model Matrix. Takes a 3D object and places it in the world. Position. Rotation. Scale. All in one matrix per object.

View Matrix. Takes the world and positions it relative to the camera. Like moving the whole world so the camera is at the origin looking forward.

Projection Matrix. Takes the 3D world and squishes it down onto your 2D screen. This is where perspective happens. Things farther away look smaller.

Every vertex of every 3D model gets multiplied by these three matrices. Millions of times per frame. The GPU does this incredibly fast. That is why modern games can render huge detailed worlds.

Every ocean you have sailed. Every river you crossed. Every pool you dove into. None of it was real water. It was all a trick. A very clever trick built from math and textures and a lot of creative cheating.

Why Not Just Simulate Real Water?

Real water consists of billions of molecules interacting. Simulating even a small portion in real time is too costly. Games must achieve 30 to 60 frames per second, and a true fluid simulation would exceed the frame budget.

So instead of simulating water. Games fake it. And they have gotten incredibly good at faking it.

The Surface. It Starts With Waves.

The foundation of almost all game water is a flat plane. A simple grid of triangles. To make it look like water you need to make it move. You do that with waves.

Sine Waves

A sine wave is a smooth curve that goes up and down forever. It has two properties you care about.

Amplitude is how tall the wave is. A bigger amplitude means taller peaks and deeper valleys.

Wavelength is the distance between two peaks. A shorter wavelength means the wave repeats more often. Which means more detail.

You feed a position on your plane into a sine function and it gives you back a height. That height moves the surface up or down. Add time to the equation and the wave starts moving.

One sine wave looks boring. But if you add multiple sine waves together. Each with different amplitudes and wavelengths and directions. You start getting something that looks like water. This technique is called Sum of Sines.

Sharper Peaks

Basic sine waves are too smooth and round. Real ocean waves have sharper peaks and wider flat areas between them. There are modified wave equations that give you this sharper shape. One famous one is called the Gerstner wave. Another simpler approach uses an exponential function to sharpen the peaks. The idea is the same. You take your basic sine wave and reshape it so the tops are pointy and the bottoms are wide.

Fractional Brownian Motion (FBM)

This is a big one. FBM is a technique where you layer waves on top of each other in a structured way. Here is how it works.

You start with one big wave. Low frequency. High amplitude. This is your base shape. Then you add another wave on top. This one has higher frequency but lower amplitude. So it adds smaller detail on top of the big shape. Then you do it again. Even higher frequency. Even smaller amplitude. Finer detail.

You keep doing this. Each layer is called an octave. Each octave adds finer and finer detail but with less and less impact. The result is a surface that has large rolling shapes AND tiny ripples at the same time. Just like real water.

FBM is not just used for water. It is one of the most important algorithms in graphics. It is used to generate clouds. Terrain. Fire. Anything that needs natural-looking layered detail.

Vertex Displacement

All of these waves need to actually move the surface. The technique for this is called vertex displacement. Your water plane is a grid made of many vertices. Points in 3D space. A shader runs on the GPU and moves each vertex up or down based on the wave math. The GPU does this for every vertex every frame. It is extremely fast.

Vertex means a corner point of a triangle in your 3D mesh. Shader means a small program that runs on the GPU. It controls how geometry is positioned and how pixels are colored. GPU means Graphics Processing Unit. The chip in your computer that is designed to do millions of small math operations at the same time.

The wave math runs inside a vertex shader. That is the part of the rendering pipeline where you can change the position of each vertex before it gets drawn on screen.

Making It Look Like Water. Lighting and Shading.

Moving geometry alone looks like a white blob. The magic that makes it look like water is all in the lighting.

Normal Vectors

To calculate how light hits a surface you need to know which direction the surface is facing at every point. That direction is called a normal vector. On a flat floor every normal points straight up. On a wavy water surface the normals tilt in all sorts of directions following the bumps and dips.

The cool thing about the wave math approach is that you can calculate the exact normals using calculus. You take the derivative of your wave function. That gives you precise normals without any guessing. This matters because accurate normals mean accurate lighting.

Diffuse Lighting

The most basic lighting calculation. You compare the normal vector to the direction of the light. If they face each other. The surface is bright. If they face away. The surface is dark. This is called Lambertian diffuse. It gives the water its basic form and shading.

Specular Highlights

These are the bright sparkly spots you see where sunlight bounces off the water directly into your eyes. The calculation checks if your viewing angle lines up with the reflected light direction. If it does. You get a bright spot. This is what makes water look shiny and alive.

Reflections

Water without reflections does not look like water. There are three main approaches games use.

Ray Tracing traces light rays to calculate perfect reflections. Looks amazing. Very expensive. Only works on modern hardware.

Screen Space Reflections (SSR) only reflects what is already visible on your screen. Cheap and common. But if the thing being reflected moves off screen the reflection just disappears. Easy to break. Most games use this anyway because it is fast.

Cube Map Reflections use a pre-captured image of the environment stored on the six faces of a cube. You calculate the reflection direction from the camera and sample the cube map. This gives decent reflections cheaply. Most skybox reflections work this way.

The Fresnel Effect

This is one of the most important visual tricks for water. Fresnel describes how the reflection strength changes based on your viewing angle.

Look straight down into water. You see through it clearly. Look across a lake at a shallow angle. It looks like a mirror.

Games blend between showing the reflection and showing what is under the water based on this angle. This single effect makes a huge difference in how real the water looks.

Normal Maps. Faking the Small Stuff.

You cannot add infinite wave detail through vertex displacement. At some point the triangles in your mesh are too big to show tiny ripples. This is where normal maps come in.

A normal map is a texture. But instead of storing color it stores direction information. Each pixel tells the shader "pretend the surface is tilted this way." This lets you add fine surface detail like small ripples and distortions without adding any actual geometry.

The classic water trick is to take two normal map textures and scroll them across the surface in different directions. They overlap and blend. Your brain sees complex moving ripples. In reality it is just two images sliding over a flat surface. This technique is everywhere. From Half-Life 2 to Cyberpunk 2077.

Caustics. Light Patterns Underwater.

Caustics are those dancing bright patterns you see on the bottom of a swimming pool. They happen because the wavy water surface bends light like a bunch of tiny magnifying glasses. Some spots on the floor get extra light focused on them. Other spots get less. This creates the signature wiggly web of bright lines.

In games the cheapest approach is just a scrolling texture. An animated image of caustic patterns projected onto surfaces under the water. Add some distortion and it looks convincing. Subnautica uses this approach heavily across its entire ocean floor.

More advanced methods actually trace where the light goes after hitting the water surface and calculate where the bright spots should be. This matches the wave shapes but costs more.

Interaction. Making It Feel Real.

What really sells water is how it reacts to the world.

Ripples from objects. When a character walks into water or a bullet hits the surface the game uses vertex displacement at that spot to create a ripple that spreads outward and fades.

Splash particles. Sprite-based particle effects for splashes. Combined with ripples this gives you something like the bullet impacts in Red Dead Redemption 2.

Foam. White foam that appears on wave crests and near shorelines. Usually a texture that is blended in based on wave height or proximity to objects.

Buoyancy. Objects floating. The simplest version just pushes objects up when they are below the water line. More advanced versions calculate how much of the object is submerged and apply force proportionally. This gives natural bobbing behavior.

Underwater effects. When the camera goes below the surface everything changes. Colors shift blue. Sound gets muffled. A fog effect limits visibility. The surface looks different from below. Each of these is a separate system.

The Recipe. Putting It All Together.

Here is the full stack of what makes game water work.

A flat plane mesh with enough vertices to deform. Wave math using sum of sines or FBM to displace those vertices. Normal calculation for accurate lighting. Scrolling normal maps for fine surface detail. Diffuse and specular lighting. Fresnel-based blending between reflection and refraction. Reflections via cube maps or SSR or ray tracing. Caustic textures projected on underwater surfaces. Particle effects for splashes and foam. Interaction systems for ripples and buoyancy.

Every game picks and chooses from this list based on their budget and hardware targets. A mobile game might only use scrolling normal maps on a flat plane. A game like Sea of Thieves uses almost everything on this list and then some.

Before anything else. You need to understand one thing. Distance.

You have two dots on a piece of paper. The distance between them is just how far apart they are. You could measure it with a ruler. That is it. Nothing fancy.

A computer can calculate this distance with a simple formula. You do not need to understand the formula. Just know that the computer can take any two points and instantly tell you how far apart they are.

What Is a Distance Field.

Now imagine this. You have a circle sitting in the middle of a blank space. Pick any random point in that space. The computer can tell you how far that point is from the edge of the circle. Not the center. The edge.

Now imagine doing that for every single point in the space. Every point gets a number. That number is its distance to the nearest surface.

If you color those numbers. Close to the surface is dark. Far from the surface is bright. You get something that looks like a glowing ring. Bright far away. Dark near the circle.

That is a distance field. Every point in space knows how far it is from the nearest thing.

What Does Signed Mean.

Here is where people get confused. But it is simple.

Signed just means the number can be positive or negative. Like a bank account. Positive means you have money. Negative means you owe money. The sign tells you which side you are on.

For a distance field it works the same way.

If you are outside the circle. The distance is positive. You are away from the surface.

If you are inside the circle. The distance is negative. You have gone past the surface.

If you are exactly on the edge. The distance is zero. You are right on the surface.

That is it. That is what signed means. Positive is outside. Negative is inside. Zero is the surface. The sign tells you which side you are on.

This is called a Signed Distance Function. SDF for short. A function that tells you how far you are from the nearest surface and whether you are inside or outside.

The Key Idea. You Only Know Distance. Nothing Else.

Here is the weird part. The signed distance function only tells you one thing. How far away is the nearest surface.

It does not tell you where the surface is. It does not tell you what direction it is in. It does not tell you what shape it is.

Just the distance. That is all.

How Ray Marching Works.

Imagine you are standing in a dark room. You cannot see anything. But you have a special device. When you press a button it tells you how far away the nearest wall is. It does not tell you which direction the wall is. Just the distance.

You want to walk forward without hitting anything. Here is what you do.

Step 1. Press the button. It says "the nearest wall is 5 meters away." Great. You know it is safe to take 5 steps forward. No matter what direction the wall is in. You cannot hit anything within 5 meters.

Step 2. You walk 5 meters forward. Press the button again. Now it says "the nearest wall is 2 meters away." So you walk 2 meters forward.

Step 3. Press again. "0.3 meters." Walk 0.3 meters.

Step 4. Press again. "0.01 meters." You are basically touching the wall. You found a surface.

That is ray marching. You keep checking the distance. You keep stepping forward by exactly that distance. Each step is guaranteed to be safe because you cannot overshoot. The steps get smaller and smaller as you get closer. Until you hit something.

Why the Steps Are Circles.

The distance is the same in every direction. So the safe zone at each step is a circle. Each circle gets smaller as you get closer to the surface.

Now Do That for Every Pixel.

One ray finds one surface point. That gives you one pixel on your screen.

To render a full image. You shoot one ray for every pixel. A screen might have over two million pixels. So you shoot over two million rays. Each one marches forward step by step until it hits something or gives up.

The computer does all of these at the same time. GPUs are built for this. Millions of tiny tasks running in parallel.

When a ray hits a surface. You color that pixel. When a ray hits nothing. You color it as background. Do this for every pixel and you get a full image.

Building a Scene. Combining Shapes.

You know how to render one shape now. But what about a scene with many shapes.

Here is the beautiful part. Remember. The distance function tells you how far the nearest surface is. If you have two shapes. You just check the distance to both. And take the smaller number. The smaller number is the nearest surface. That's the one which matters. It's the one you would hit first.

In code this is just the min function. Take the minimum of two distances. Done. You now have two shapes in your scene.

Want 10 shapes. Take the min of all 10 distances.

We wanted procedural trees. We kept getting trunks with leaf puffs. Pine looked acceptable. Oak. Birch. Maple. And sakura did not. They read like poles with crowns.

The important lesson is simple. The problem was not bark. The problem was not leaf textures. The problem was grammar.

The Real Problem

Our broadleaf presets were barely creating side branches in world space. We measured the generated segments instead of guessing.

oak    { segments: 568, maxRadius: 0.29, branchishSegments: 0 }
pine   { segments: 54,  maxRadius: 0.76, branchishSegments: 40 }
birch  { segments: 406, maxRadius: 0.48, branchishSegments: 0 }
maple  { segments: 460, maxRadius: 0.48, branchishSegments: 0 }
sakura { segments: 414, maxRadius: 0.09, branchishSegments: 0 }

This told us the truth fast. The broadleaf trees were almost entirely vertical. They had leaves. They had bark. They did not have a real branch scaffold.

Pine looked better because it already had actual lateral structure. The other species were mostly pretending.

The Broken Idea

The old oak preset looked tree like on paper.

export const OAK = {
  axiom: 'FA',
  rules: [
    { predecessor: 'A', successor: '!F[&FL!A]////[&FL!A]////[&FL!A]' },
    { predecessor: 'F', successor: 'S//F' },
    { predecessor: 'S', successor: 'F' },
    { predecessor: 'L', successor: '[^^-F+F+F-|-F+F+F]' },
  ],
}

It feels expressive. It is not structurally honest. The same symbols were trying to be trunk growth. branch growth. recursive continuation. and leaf volume at the same time. The result was vertical motion with decorative foliage.

The renderer could not reveal branches that were never really generated.

The Fix

We split responsibilities. We introduced a real trunk symbol T. We introduced a real branch symbol B. Then we made trunk growth continue while branch growth peeled off to the sides.

export const OAK = {
  axiom: 'T',
  rules: [
    { predecessor: 'T', successor: 'FF[+!B][-!B][//+!B][//-!B]T' },
    { predecessor: 'B', successor: 'F[+!B][-!B]F' },
  ],
}

This did three important things.

First. T keeps the main scaffold alive.

Second. B creates side limbs that can recurse without collapsing back into the trunk.

Third. The extra FF at the start gives each branch system some travel distance before more splitting. That makes limbs readable instead of glued into one top puff.

We applied the same idea to birch. maple. and sakura with different angles and decay values.

The Supporting Fixes

We also kept real taper per segment instead of faking radius only at major rule points.

const nextRadius = state.radius * config.segmentTaper
segments.push({
  startRadius: state.radius,
  endRadius: nextRadius,
})
state.radius = nextRadius

That made branches feel more branch like once the scaffold existed.

We also added a test that checks broadleaf trees actually spread outward.

expect(maxRadius).toBeGreaterThan(1.5)
expect(branchCount).toBeGreaterThan(30)

That matters because the bug was visual but the cause was structural. We wanted a test that protects structure.

The Result

After the rewrite the numbers changed hard.

oak    { segments: 218, maxRadius: 2.73, branchCount: 149 }
pine   { segments: 54,  maxRadius: 0.76, branchCount: 27 }
birch  { segments: 114, maxRadius: 1.90, branchCount: 48 }
maple  { segments: 218, maxRadius: 2.72, branchCount: 152 }
sakura { segments: 218, maxRadius: 2.66, branchCount: 171 }

That is why the trees finally started reading like trees with branches instead of sticks with toppings.

Oak got scaffold limbs.

Maple got a real canopy.

Sakura got visible structure under the blossom mass.

Birch stayed lighter and more delicate.

Pine stayed good because it was already the closest to a real branching grammar.

What I Want To Remember

If a procedural tree looks fake then do not start by tuning leaf textures or bark maps.

Measure branch spread first.

If horizontal spread is near zero then the grammar is lying to you.

Fix the scaffold first.

Then style it.

I went into a bit of a rabbithole studying how Nanite works. Here are some of the things I learned and the write-up I wish existed.

The Four Problems

Every triangle you render costs something. When you have millions of them four problems start screaming at you.

Draw Calls

A draw call is a command. The CPU tells the GPU "draw this object". One object. One draw call. Sounds simple.

The problem is the coordination. Every draw call requires the CPU and GPU to sync up. The CPU prepares the command. The GPU receives it. They handshake. This takes time. Not because the drawing is slow. But because the communication is slow.

1000 objects means 1000 draw calls. The CPU spends all its time just talking to the GPU instead of doing useful work. The GPU sits there waiting. This is a bottleneck. The slowest part that holds everything else back.

Overhead

Overhead is everything that is NOT drawing pixels. Setting up shaders. Binding textures. Switching materials. State changes. Every time the GPU switches from one material to another there is a cost. All this extra work adds up.

More objects with different materials means more overhead. The GPU spends time preparing instead of rendering.

Memory

Triangles take space. A single vertex needs about 32 to 44 bytes. That includes its position in 3D space. Its normal direction. Its texture coordinates. Each triangle also needs 12 bytes for index data.

A 1 million triangle mesh uses roughly 30 to 140 megabytes depending on how it is structured. That lives in VRAM. "VRAM" is the GPU's own memory. It is fast but limited. Fill it up and performance falls off a cliff.

Computation

Every triangle goes through a pipeline. The vertex shader transforms it into screen space. The rasterizer figures out which pixels it covers. The fragment shader colors those pixels. Multiply that by millions of triangles and you have an enormous amount of math every single frame.

If you want 60 frames per second you have about 16 milliseconds to do ALL of this. For the entire scene. Every object. Every triangle. Every pixel. 16 milliseconds. That is not a lot.

The Techniques We Had Before Nanite

People have been fighting these four problems for decades. Here are the main tools they built.

Normal Baking

You start with two models. A high detail version with millions of triangles. And a low detail version with a few thousand. You "bake" the surface detail from the high model into a texture called a normal map. This texture stores the direction each tiny surface patch faces. When light hits the low model it reads the normal map and PRETENDS the surface has all that detail.

The result looks almost the same. But the GPU only processes a few thousand triangles instead of millions.

The good: Huge geometry reduction. Low computation. Low overhead.

The bad: Medium memory cost because you need to store the normal map textures. Medium manual labor because an artist has to create both the high and low poly versions and bake the map carefully. Also the silhouette of the object is still simple. The edges of the shape look low poly because normal maps only fake surface detail. They cannot change the actual outline.

LOD. Level of Detail

You create multiple versions of the same model. LOD 0 is the full detail version. LOD 1 has fewer triangles. LOD 2 even fewer. LOD 3 is very simple. The engine swaps between them based on distance from the camera.

Close up you see LOD 0. Far away you see LOD 3. The player never notices.

The good: High geometry reduction. Saves a lot of GPU work for distant objects.

The bad: HIGH manual labor. Someone has to create 3 or 4 versions of every single model. That is a lot of work across hundreds of assets. Also "popping". When the engine swaps LOD levels the model visibly changes for a frame. Players can see it. It breaks immersion. And you need to store all versions in memory.

Subdivision Modeling

The opposite approach. You start with a simple low poly cage. The computer subdivides it. "Subdivide" means split each face into smaller faces and smooth the result. You control how many times it subdivides. More subdivisions means more detail -> more triangles!

The good. Low manual labor. You build one simple model and the computer generates the detail.

The bad. Low geometry reduction. It ADDS triangles. It does not remove them. High computation because subdividing at runtime is expensive. It can only add detail. It cannot reduce it based on distance.

Voxels

Instead of triangles you represent the world as a 3D grid of cubes. Like Minecraft. Each cell in the grid is either filled or empty. You can vary the grid resolution. Coarse grid for far away. Fine grid for close up.

The good: Low manual labor. Voxel worlds can be generated by code. Dynamic detail adjustment by changing grid resolution.

The bad: High memory because you store a big 3D grid. High computation to convert voxels into something renderable. Blocky look. Sharp edges are hard to represent. Texturing is problematic because voxels do not naturally support UV coordinates.

The Summary

The first two techniques handle most problems but require a lot of manual work. The second two are more automatic but have other costs. None of them solve everything.

What if there was a system that handled all four problems. Automatically. No manual LOD creation. No popping. No wasted triangles.

The Fastest Triangle to Render

Before diving into Nanite there is one idea you need to accept.

The fastest triangle to render is the one you never send to the GPU.

Not "the smallest triangle". Not "the simplest triangle". The one you skip entirely. If you can figure out which triangles the player will never see and throw them away before the GPU even touches them you win. Every triangle you skip saves draw call time. Overhead. Memory. Computation. All four problems at once.

Think about a statue with 33 million triangles. Now put 500 of those statues in a room. That is over 16 billion triangles. You cannot render all of them. But you do not need to. Most of those triangles are either too far away to matter. Or facing away from the camera. Or hidden behind other objects.

The entire job is figuring out which ones to skip.

Clustering. Organizing the Chaos

Checking 33 million triangles one by one is way too slow. You need to group them.

A cluster is a small group of triangles. Usually around 128 of them. Instead of asking "should I render this triangle" 33 million times you ask "should I render this cluster" about 250,000 times. Much better.

Bounding Volumes

Each cluster gets wrapped in a simple shape. A sphere or a box. This is called a bounding volume. It is a quick approximation of where the cluster is in space.

Testing "does this simple box intersect the camera view" is way faster than testing 128 individual triangles. If the box is not visible you skip all 128 triangles inside it in one check.

Bounding Volume Hierarchy. BVH

You can nest these bounding volumes. Wrap two clusters in a bigger box. Wrap two of those bigger boxes in an even bigger box. Keep going until you have one box that contains the whole object.

This creates a tree structure. At the top is the whole object. At the bottom are individual clusters.

To check visibility you start at the top. If the big box is not visible you skip EVERYTHING inside it. One check eliminates thousands of clusters. If it IS visible you go one level deeper and check the two medium boxes. And so on.

This reduces the number of checks from N to log(N). In a scene with 1000 clusters that means roughly 10 checks instead of 1000. Massive speedup.

Automated LOD With Clusters

Take your clusters of 128 triangles. That is LOD 0. Full detail.

Now take two neighboring clusters. 256 triangles total. Merge them into one group. Simplify down to 128 triangles. Split into two new clusters.

You went from 256 to 128. Half the detail. One LOD level up. No artist involved. Fully automatic.

Repeat at every level. Each level roughly halves the triangle count until you have a very coarse version of the whole mesh at the top.

The order matters. Merge first. Then simplify. If you simplify each cluster alone the shared edges between neighbors change independently. They no longer line up. You get cracks. Visible gaps in the mesh.

By merging first the shared edge is no longer a boundary. It is in the middle of the merged group. Just regular geometry. The simplification cleans it up like any other edge. No cracks.

But here is the problem. Two clusters can only be merged if something can reach both of them. In a tree each cluster has one parent. If two clusters have different parents nobody can merge them. Their shared boundary is stuck forever. Level after level these stuck edges pile up. The mesh fills with dense geometry that cannot be simplified. That is mesh cruft.

The fix is simple. Let a cluster have two parents. Both sides of any boundary can reach the shared cluster. Both sides can merge across it. Every boundary gets cleaned up. Nothing is stuck.

That is a DAG. A Directed Acyclic Graph. "Directed" means connections flow one way. Parent to child. "Acyclic" means no loops. The only difference from a tree is that one child can have two parents.

Nanite does not use a DAG because it is fancy. Merging clusters naturally creates shared children. The DAG is just what you end up with when you allow that.

Screen Space Error

Every simplified mesh is slightly different from the original. That difference is the error. A fixed number measured in world units. It never changes.

What changes is how big that error looks on screen. 0.5 centimeters of error up close might cover 8 pixels. The player sees it. 200 meters away the same 0.5 centimeters covers less than one pixel. The player cannot see it. The monitor cannot even display it.

The rule. If the error is smaller than one pixel use the cheaper version.

Each cluster has multiple LOD levels. Each level has a known error. The engine picks the cheapest level where the error is below one pixel. Done.

This happens per cluster. Not per object. Front of a rock might be at LOD 0. Back of the same rock at LOD 3. Each cluster picks independently every frame. Changes are always smaller than one pixel. That is why there is no popping. The switches are invisible by definition.

One Giant Draw Call

Traditional rendering. The CPU tells the GPU "draw this rock". Then "draw this wall". Then "draw this floor". One command per object. 1000 objects means 1000 commands. The CPU spends all its time talking.

Nanite packs all surviving cluster triangles into one big block of data in VRAM. Sends one command. "Draw all of this". Done.

The GPU does the rest. It runs the culling. Picks the LOD levels. Decides what to render. All on its own. The CPU barely participates. This works because GPUs have thousands of cores that run in parallel. Checking 250,000 clusters is 250,000 tiny tasks. Perfect GPU work. A CPU with 16 cores would choke on that. A GPU with thousands of cores eats it.

The only split is materials. Metal needs different shader code than wood. So triangles with different materials still need separate commands. But all the triangles within one material get batched together. Way fewer commands than one per object.

Culling. Throwing Away What You Cannot See

Even with automated LODs and batching you still have too many clusters. The next step is figuring out which ones to skip entirely. This is culling.

Culling means removing. Deciding what NOT to render. Three types. Each one catches different things.

Frustum Culling

The frustum is the shape of what your camera can see. It looks like a pyramid with the tip cut off. The near end is small and close to the camera. The far end is wide and far away.

Anything outside this shape is off screen. Do not render it. A building behind you. Gone. A tree far to the left. Gone.

You test each cluster's bounding volume against the frustum. If the bounding box does not intersect the frustum the whole cluster is skipped. Fast and simple.

But frustum culling has a blind spot. It keeps everything INSIDE the frustum. Even objects hidden behind a wall. You can see the wall but not the building behind it. Yet both pass the frustum test.

Backface Culling

Every triangle has two sides. A front face and a back face. If a triangle faces away from the camera you are looking at its back. You cannot see it. Skip it.

How does the GPU know which side faces you. Triangle vertices are listed in a specific order. If they appear clockwise on screen the triangle faces you. Counter clockwise means it faces away. The GPU checks this with very fast math.

The other way to check is using the dot product. Each triangle has a normal vector pointing outward. If the dot product of the view direction and the normal is positive the triangle faces away. "Dot product" is a math operation that tells you how much two directions agree. Positive means same direction. Negative means opposite directions.

About half of all triangles in any scene face away from you at any given time. So backface culling alone removes roughly 50 percent of the work.

Occlusion Culling

The hardest one. A cluster passes the frustum test. Its triangles face the camera. But there is a wall in front of it. The player cannot see the cluster because something else blocks it. That is occlusion.

To figure this out you need to know what is in front of what. That requires the depth buffer.

The Depth Buffer

The depth buffer is an image the GPU creates while rendering. Every pixel stores how far away the closest surface is. It is a grayscale image. Close things are dark. Far things are bright.

If you want to check whether a cluster is hidden you compare its depth against the depth buffer. If every pixel where the cluster would appear already has something closer then the cluster is fully hidden. Skip it.

But here is a problem. You need the depth buffer to decide what to cull. But you need to render things to build the depth buffer. Chicken and egg.

Hierarchical Z Buffer. Hi-Z

This is the trick that makes occlusion culling fast.

First a quick reminder. The depth buffer is an image the GPU builds while rendering. Every pixel stores how far away the closest visible surface is at that spot on screen. Keyword is visible. Only things that were actually drawn get recorded. If something was culled it is not in there. -> This took me a while to grasp. This is the key thing. Visible!

Now the problem. Say you want to check if a cluster is hidden behind something. That cluster might cover 10,000 pixels on screen. To check properly you would have to read 10,000 depth values and compare each one. That is slow.

Hi-Z fixes this. You take the depth buffer and build a mipmap chain. A mipmap is a series of smaller copies of the image. Full resolution. Half. Quarter. Eighth. All the way down to one pixel.

But here is the key difference from normal mipmaps. Normal texture mipmaps average the pixels together. Hi-Z takes the MAXIMUM depth value. The furthest point.

Why maximum. This is the part that matters for occlusion.

Say four pixels in the depth buffer have values 5. 8. 3. 10. Those numbers are distances. Something visible was rendered at distance 5 at one pixel. Something at distance 8 at another. And so on. The max is 10. That means the FURTHEST visible thing in that group of four pixels is at distance 10. Everything else there is even closer.

Now you have a cluster at distance 12. It is further away than 10. That means it is further away than EVERYTHING rendered in that group. Even the furthest thing there is still closer than the cluster. So the cluster is behind all of it. Fully hidden. That is occlusion. One check covered four pixels.

Go up another mipmap level. One pixel now covers 16 original pixels. Same logic. One check covers 16 pixels. Next level. 64 pixels. Then 256. Then 1024. A cluster that covers a large area on screen can be tested with just one or two reads at a coarse mipmap level instead of thousands of reads.

To test a cluster you figure out how big it would be on screen. Pick the mipmap level where one pixel roughly covers that area. Read the max depth value. Compare it to the cluster's distance. Cluster is further away. It is behind everything there. Hidden. Cut it. Cluster is closer. It might be visible. Keep it.

This is conservative. It plays it safe. Sometimes it says "maybe visible" when the cluster is actually hidden. That is fine. You render a little extra. But it NEVER says "hidden" when the cluster is actually visible. That would mean missing objects on screen. That would be a bug. So it errs on the side of doing a little extra work rather than skipping something it should not.

Nanite's Two Pass Occlusion

Nanite takes this further with two passes.

Pass 1: Use last frame's depth buffer. Test all clusters against it. Most things that were hidden last frame are still hidden this frame. This catches the majority of occluded clusters immediately.

Pass 2: Render the clusters that survived pass 1. Build a new depth buffer. Now test any remaining uncertain clusters against this fresh depth buffer. This catches things that just moved into view or edge cases the old depth buffer missed.

Two passes sounds like more work. But it means almost nothing gets rendered unnecessarily. The total work is less than doing it in one pass with guesswork.

The Small Triangle Problem

There is one more thing Nanite had to solve.

The GPU processes pixels in groups of 2x2. These groups are called quads. When a triangle is so small it only covers one pixel in that quad the GPU still runs the fragment shader for all four pixels. Three of those four pixels are wasted work. Up to 75 percent waste.

With millions of small triangles this waste adds up fast.

Nanite's solution. For clusters where triangle edges are smaller than 32 pixels it uses a software rasterizer. "Software rasterizer" means custom code running on the GPU that replaces the normal hardware rasterization pipeline. This custom code knows how to handle tiny triangles efficiently. No wasted quads.

For larger triangles the normal hardware rasterizer runs as usual. It is already fast for big triangles.

This split made Nanite's rasterization three times faster.

The Full Picture

Nanite is not the GPU. Nanite is software built by Epic Games. A system of code that runs on the GPU and tells it exactly what to do. The GPU is the muscle. Nanite is the brain.

It works in two phases.

Phase 1. Before The Game Runs

This happens once. When the artist imports a mesh into Unreal Engine.

Clustering

An artist imports a 33 million triangle statue. Nanite splits it into clusters. Small groups of 128 triangles each.

Building The DAG

It builds the DAG. The structure where clusters can share boundaries with multiple parents. This is what allows clean simplification without cracks.

Creating The LOD Levels

Merge neighboring clusters. Simplify. Split into new clusters. Repeat. Each level has roughly half the triangles of the level below it. Old boundaries get cleaned up because they become interior edges after merging. No manual work. Fully automatic.

Calculating The Error

For each LOD level it measures how many centimeters the simplified version differs from the original. This number is baked in. It never changes.

Storing The Data

Two things get stored. The metadata. Bounding boxes. Error values. Facing directions. DAG connections. This is lightweight. A few megabytes. And the actual triangle data for every LOD level. This is heavy. Sits on disk.

Done. Never repeated.

Phase 2. Every Frame

The metadata sits in RAM. Always available. The GPU runs through it and filters the clusters down step by step.

Frustum Culling

Is this cluster on screen. Test the bounding box against the camera frustum. Off screen. Cut it.

Backface Culling

Is this cluster facing the camera. Check the stored normal direction against the view direction. Facing away. Cut it.

Screen Space Error

Which LOD level does this cluster need. Convert the error value to pixels based on distance from camera. Pick the cheapest level where the error is below one pixel. Invisible to the player.

Occlusion Culling Pass 1

Was this cluster hidden last frame. Check against last frame's Hi-Z depth buffer. Further away than everything at that spot. Cut it.

Occlusion Culling Pass 2

Render everything that made it this far. Build a fresh depth buffer. Test uncertain clusters again. Still hidden. Cut it.

Streaming

Now the GPU has a small list of clusters that passed every check. Only their triangle data gets streamed from disk into VRAM. Everything else stays on disk untouched.

Rasterization

Clusters with tiny triangles where edges are smaller than 32 pixels go through the software rasterizer. Custom code. No wasted pixels. Bigger triangles go through the normal hardware rasterizer.

The Draw Call

Here is the important part. By the time the draw call happens the GPU already threw away most of the scene. The culling. The LOD selection. All of that happened before this step. The buffer only contains the clusters that passed every single check.

So the CPU sends one command per material. "Draw this". But "this" is not 33 million triangles. It is maybe 50,000. The GPU is not drawing everything. It is drawing the tiny fraction that actually matters. One command. Small amount of real work.

Frame done. 16 milliseconds. Next frame. Do it all again.

When to Use Nanite. And When Not To

Nanite is not the answer to everything.

Use it for: Scenes with extremely high poly static assets. Photogrammetry scans. Rocks. Walls. Architectural models. Anything that is large. Opaque. And does not move.

Do not use it for: Dynamic or animated objects like characters. Transparent materials. Masked materials like foliage and leaves. Very small detailed objects. In these cases traditional LOD and culling techniques still work better.

I discovered this while digging through the Vercel docs and the Next.js cache components skill. I was trying to understand how caching actually works when you deploy to Vercel. What I found is one of the most powerful features in Next.js 16 that not enough people are talking about.

You can write 'use cache: remote' inside any async function and get a shared distributed cache across all your serverless instances. No Redis. No config. No infrastructure. Just a directive.

What Cache Components Are

Next.js 16 introduced Cache Components. You enable them with one line in your config:

// next.config.ts
const nextConfig = {
  cacheComponents: true,
};

This unlocks three directives:

• 'use cache': in-memory cache on the server

• 'use cache: remote': shared remote cache across all instances

• 'use cache: private': per-user browser cache

You put these directives inside async functions. Next.js caches the return value. That is it.

The Problem with Plain use cache

Plain 'use cache' stores data in memory. On Vercel, your app runs as serverless functions. Each function instance has its own memory. When the instance shuts down, the cache is gone.

So this happens:

1. User A hits your site. Instance A spins up. Fetches data. Caches it in memory.

2. User B hits your site. Instance B spins up. It has no idea about Instance A's cache. Fetches data again.

3. Instance A gets recycled. Cache gone.

For build-time prerendered content this is fine. The cached result is baked into the static shell and served from the CDN. But for runtime data, anything that runs at request time, the in-memory cache is basically useless in a serverless environment.

What use cache: remote Does Differently

'use cache: remote' stores the cached data in a shared key-value store that all serverless instances can access. On Vercel, this is called Runtime Cache. It lives in the same region as your function. You do not set it up. Vercel provides it automatically.

Now:

1. User A hits your site. Instance A fetches data. Stores it in the remote cache.

2. User B hits your site. Instance B checks the remote cache. Finds the data. Skips the database.

3. Instance A gets recycled. Does not matter. The cache is in the remote store, not in memory.

Every user. Every serverless instance. Same region. Same cache.

How It Works in Practice

Say you have a homepage with featured products from Supabase.

import { createClient } from "@/utils/supabase/server";
import { cacheTag, cacheLife } from "next/cache";

export async function getFeaturedProducts() {
  "use cache: remote";
  cacheTag("products");
  cacheLife("max");

  const supabase = await createClient();
  const { data } = await supabase
    .from("products")
    .select("*")
    .eq("featured", true);

  return data;
}

First request hits Supabase. Result goes into the remote cache. Every request after that skips Supabase entirely. Your database sees one request instead of thousands.

Use it in your page like any normal function:

export default async function HomePage() {
  const products = await getFeaturedProducts();
  return (
    <section>
      {products.map((p) => (
        <ProductCard key={p.id} product={p} />
      ))}
    </section>
  );
}

It does not matter what data source you use. Supabase. Prisma. Drizzle. Raw fetch. A GraphQL client. 'use cache: remote' caches the return value of the function. It does not care how the data was fetched.

Cache Forever Until You Invalidate

You can cache data indefinitely. Use cacheLife('max') or set a custom long expiration:

cacheLife({
  stale: 31536000,
  revalidate: 31536000,
  expire: 31536000,
});

That is roughly one year. The cache stays until you explicitly kill it. Which brings us to the best part.

Invalidation with Tags

Every cached function can be tagged with cacheTag(). When your data changes, call revalidateTag() to drop the cache.

// Tag your cached functions
async function getHeroContent() {
  "use cache: remote";
  cacheTag("homepage", "hero");
  cacheLife("max");
  return db.hero.findFirst();
}

async function getFeaturedProducts() {
  "use cache: remote";
  cacheTag("homepage", "products");
  cacheLife("max");
  return db.products.findMany({ where: { featured: true } });
}

async function getTestimonials() {
  "use cache: remote";
  cacheTag("homepage", "testimonials");
  cacheLife("max");
  return db.testimonials.findMany();
}

Notice the trick. Each function has a shared 'homepage' tag and a specific tag. So you can invalidate just products. Or nuke the entire homepage cache at once.

"use server";

import { revalidateTag } from "next/cache";

// Invalidate just products
export async function onProductUpdate() {
  revalidateTag("products");
}

// Invalidate the entire homepage
export async function refreshHomepage() {
  revalidateTag("homepage");
}

Call these from a server action, a webhook, an admin panel. The cache entry drops across every region. Next request rebuilds it fresh.

There are two invalidation functions:

• revalidateTag(): background revalidation. Current request might still see stale data. Next request sees fresh data.

• updateTag(): immediate. Same request sees fresh data.

Time-Based Invalidation

If you do not want to manage tags manually, use time-based expiration:

async function getTrendingPosts() {
  "use cache: remote";
  cacheLife("hours"); // revalidates every few hours
  return db.posts.findMany({ orderBy: { views: "desc" } });
}

Built-in profiles: 'minutes', 'hours', 'days', 'weeks', 'max'.

Or go custom:

cacheLife({
  stale: 300, // 5 min. serve old data while refreshing
  revalidate: 600, // 10 min. background refresh interval
  expire: 3600, // 1 hour. hard expiration
});

stale means the data is old but still served while fresh data is fetched in the background. revalidate is how often Next.js checks for new data behind the scenes. expire is the hard cutoff where the cache is completely gone.

Where the Cache Actually Lives

On Vercel, use cache: remote uses Vercel's Runtime Cache. It is a key-value store in each region where your functions run. You do not configure it.

• Shared across all users in the same region. Yes.

• Shared across all serverless instances. Yes.

• Shared across regions. No. Each region has its own cache.

• Survives new deployments. Yes.

• Shared between preview and production. No. Separate environments.

The word "non-durable" in the docs means Vercel can evict entries under memory pressure. It is a cache, not a database. Your database is still the source of truth. If the cache misses, your function just re-fetches and caches again.

If you are self-hosting (not on Vercel), you need to configure your own cache handler via cacheHandlers in next.config.ts. You can use Redis, Memcached, DynamoDB, whatever. But on Vercel it is zero config.

One Rule: No Runtime APIs Inside

You cannot call cookies(), headers(), or read searchParams inside a 'use cache: remote' function. These change per request. Caching them makes no sense.

The fix: read them outside, pass the value in as an argument.

async function ProductPrice({ productId }: { productId: string }) {
  const currency = (await cookies()).get("currency")?.value ?? "USD";
  const price = await getPrice(productId, currency);
  return (
    <span>
      {price} {currency}
    </span>
  );
}

async function getPrice(productId: string, currency: string) {
  "use cache: remote";
  cacheTag(`price-${productId}`);
  cacheLife({ expire: 3600 });

  // Cache key = productId + currency
  // All users with same currency share this entry
  return db.products.getPrice(productId, currency);
}

The arguments automatically become part of the cache key. Different arguments create different cache entries. So all USD users share one entry. All EUR users share another.

Smart Cache Key Design

Cache on dimensions with few unique values. Filter the rest in memory.

// BAD: caching per price filter creates thousands of entries
async function getProducts(category: string, minPrice: number) {
  "use cache: remote";
  return db.products.find({ category, minPrice });
}

// GOOD: cache per category, filter price in memory
async function getProducts(category: string) {
  "use cache: remote";
  return db.products.findByCategory(category);
}

// Then in your component
const products = await getProducts("electronics");
const filtered = products.filter((p) => p.price >= minPrice);

Same idea with user data. Do not cache per user ID. Cache per language or role or region. Fewer entries. Higher hit rate.

The Three Directives Compared

Why This Matters

Before this, if you wanted a distributed cache in front of your database, you had to set up Redis or Memcached, write cache keys manually, handle invalidation yourself, and manage infrastructure.

Now you write 'use cache: remote' and cacheTag('products') inside a function. Call revalidateTag('products') when data changes. Done. A distributed cache with declarative invalidation built into your component tree.

Your database goes from handling every single request to handling one request per cache lifetime per region. That is a massive reduction in load, cost, and latency.

It is one of the most practical features in modern web development and I think more people should know about it.

A good level and XP system should do three things well. It should be easy to reason about. It should be hard to exploit. It should be flexible enough to support more than one reward source. That means the math should be pure, and the write path should be centralized.

What to store

Keep the long lived progression state on the profile.

profiles: defineTable({
  xp: v.number(),
  level: v.number(),
  streakCount: v.number(),
})

xp is the real source of truth for progression. level is a cached convenience field. streakCount matters if your XP system includes a streak multiplier.

Keep level math pure

Do not calculate level progression ad hoc inside mutations. Keep the math in one pure module. This is the pattern.

function getXpForNextLevel({ currentLevel }: { currentLevel: number }): number {
  return Math.floor(100 * Math.pow(1.3, currentLevel - 1))
}

function getLevelFromXp({ totalXp }: { totalXp: number }): number {
  let level = 1
  let cumulativeXp = 0

  while (true) {
    const xpForNextLevel = getXpForNextLevel({ currentLevel: level })
    if (cumulativeXp + xpForNextLevel > totalXp) {
      return level
    }

    cumulativeXp += xpForNextLevel
    level += 1
  }
}

function getCurrentLevelProgress({ totalXp }: { totalXp: number }) {
  const currentLevel = getLevelFromXp({ totalXp })
  let cumulativeXpToCurrentLevel = 0

  for (let level = 1; level < currentLevel; level += 1) {
    cumulativeXpToCurrentLevel += getXpForNextLevel({ currentLevel: level })
  }

  const xpIntoLevel = totalXp - cumulativeXpToCurrentLevel
  const xpForNextLevel = getXpForNextLevel({ currentLevel })

  return {
    currentLevel,
    xpIntoLevel,
    xpForNextLevel,
    percentComplete: xpForNextLevel === 0 ? 0 : xpIntoLevel / xpForNextLevel,
  }
}

This gives you one clear level curve and one clear progress calculation.

Decide your reward sources explicitly

Do not just sprinkle XP everywhere. Name the reward sources. That makes analytics, balancing, and future refactors much easier. This is the pattern.

type XpAwardSource = 'word' | 'world' | 'chapter'

type XpAward = {
  source: XpAwardSource
  baseXp: number
}

const LEVEL_COMPLETION_XP = 10
const WORLD_COMPLETION_BONUS_XP = 50
const CHAPTER_COMPLETION_BONUS_XP = 150

Now your system is not a pile of anonymous numbers. It is a list of named rewards.

Add the streak multiplier as a pure function

If you want streaks to matter, keep that logic pure too.

function getStreakMultiplier({ streakDays }: { streakDays: number }): number {
  if (streakDays <= 2) return 1
  if (streakDays <= 6) return 1.2
  if (streakDays <= 29) return 1.5
  if (streakDays <= 99) return 2
  if (streakDays <= 364) return 2.5

  const yearsAfterFirst = Math.floor((streakDays - 365) / 365)
  return 3 + yearsAfterFirst * 0.5
}

function calculateXpEarned({
  baseXp,
  streakMultiplier,
}: {
  baseXp: number
  streakMultiplier: number
}) {
  return Math.floor(baseXp * streakMultiplier)
}

This makes the multiplier easy to test and easy to rebalance later.

Support multiple XP awards in one completion

This is the part many systems get wrong. A single completion can trigger more than one reward. For example. A level completion reward. A world completion bonus. A chapter completion bonus. If you model XP as one number only, the logic becomes messy fast. Instead, accept an array of award items.

function getXpBatchAwardOutcome({
  awards,
  currentXp,
  streakMultiplier,
}: {
  awards: ReadonlyArray<XpAward>
  currentXp: number
  streakMultiplier: number
}) {
  const awardsBreakdown = awards.map((award) => ({
    ...award,
    xpEarned: calculateXpEarned({
      baseXp: award.baseXp,
      streakMultiplier,
    }),
  }))

  const totalXpEarned = awardsBreakdown.reduce(
    (total, award) => total + award.xpEarned,
    0
  )

  const newXp = currentXp + totalXpEarned
  const previousLevel = getLevelFromXp({ totalXp: currentXp })
  const newLevel = getLevelFromXp({ totalXp: newXp })

  return {
    awardsBreakdown,
    previousXp: currentXp,
    newXp,
    previousLevel,
    newLevel,
    didLevelUp: newLevel > previousLevel,
    levelsGained: newLevel - previousLevel,
    totalXpEarned,
  }
}

This is much easier to understand. It also gives the frontend a clean payload for XP animations.

Centralize the write path in one internal mutation

This is the most important implementation detail. Do not let every gameplay mutation patch XP by itself. Create one internal XP mutation that applies awards. This is the pattern.

export const awardXp = internalMutation({
  args: {
    profileId: v.id('profiles'),
    awards: v.array(
      v.object({
        baseXp: v.number(),
        source: v.union(
          v.literal('word'),
          v.literal('world'),
          v.literal('chapter')
        ),
      })
    ),
  },
  handler: async (ctx, args) => {
    const profile = await ctx.db.get(args.profileId)
    if (!profile || profile.deletedAt) {
      throw appError({
        code: 'NOT_FOUND',
        message: 'Profile not found',
      })
    }

    const streakMultiplier = getStreakMultiplier({
      streakDays: profile.streakCount,
    })

    const outcome = getXpBatchAwardOutcome({
      awards: args.awards,
      currentXp: profile.xp,
      streakMultiplier,
    })

    await ctx.db.patch(profile._id, {
      xp: outcome.newXp,
      level: outcome.newLevel,
    })

    return outcome
  },
})

That keeps the write path consistent. It also makes it very hard to award XP twice by accident in different places.

Why this shape is good

This shape gives you a few strong properties. The math is pure. The mutation is simple. Every reward is explicit. Every reward source is trackable. The frontend gets a clean response with didLevelUp, levelsGained, and totalXpEarned. That is exactly what a dynamic UI needs.

How to think about the algorithm

The algorithm is not just math. It is product design. Here are the practical questions that matter. How fast should level one feel. How long should level growth take later. How much should streaks matter. Should world and chapter bonuses feel rare and meaningful. Should replay give zero XP. The code should make those decisions easy to change. That is another reason pure helpers are so valuable.

A practical reward model

A simple model that works well is this. 10 XP for a normal level. 50 bonus XP for finishing a world. 150 bonus XP for finishing a chapter. Then apply the streak multiplier once to each award item. That gives you good momentum without making the math hard to follow.

Replay should not touch progression

This rule should be strict. Replay is for practice. Not for farming XP. So in replay mode. No progress writes. No XP writes. No unlock changes. That keeps the system fair and keeps the mental model clean.

What to test

The best part of this system is that most of the hard parts are pure. Test these first. getXpForNextLevel getLevelFromXp getCurrentLevelProgress getStreakMultiplier calculateXpEarned getXpBatchAwardOutcome Those tests give you confidence before you ever touch a real mutation.

The main lesson

A good XP system is not one mutation. It is a small progression engine. If you keep the engine pure and keep the write path centralized, the rest of the app gets much easier to build.

We had a simple problem. Query prefetch was working. Images and audio still felt cold. That meant the next screen could have its data ready, but still show an image pop in late, or start audio late. That feels bad. It makes the app feel slower than it really is.

The first thing we checked

We traced the actual asset requests. The built in Convex storage URLs looked like this.

https://<deployment>.convex.cloud/api/storage/<storageId>

Then we checked the response headers. The important detail was the cache policy. The built in storage response was not behaving like a strong public immutable asset. That was the root issue. The browser could cache it, but not in the strongest way we wanted for repeated image and audio usage.

The constraint

We did not want to move assets out of Convex. That is important. The goal was not to replace Convex storage. The goal was to keep assets in Convex, and serve them better.

The fix in one sentence

We kept assets in Convex storage, added our own cached asset route on convex.site, rewrote storage URLs to that route on the client, and made preloading much stricter for both images and audio.

Step 1, create a cached asset route in Convex

The first fix was backend. We added a custom HTTP route that reads from Convex storage and serves the file with stronger caching headers. This is the important pattern.

import { httpRouter } from 'convex/server'
import type { Id } from './_generated/dataModel'
import { httpAction } from './_generated/server'

const http = httpRouter()

const ONE_YEAR_IN_SECONDS = 60 * 60 * 24 * 365
const CACHE_CONTROL = `public, max-age=\({ONE_YEAR_IN_SECONDS}, s-maxage=\){ONE_YEAR_IN_SECONDS}, immutable`

http.route({
  pathPrefix: '/cached-assets/',
  method: 'GET',
  handler: httpAction(async (ctx, request) => {
    const url = new URL(request.url)
    const storageId = decodeURIComponent(
      url.pathname.slice('/cached-assets/'.length)
    ) as Id<'_storage'>

    const metadata = await ctx.storage.getMetadata(storageId)
    if (!metadata) {
      return new Response('Asset not found', { status: 404 })
    }

    const etag = `\"${metadata.sha256}\"`
    const ifNoneMatch = request.headers.get('if-none-match')

    if (ifNoneMatch?.includes(etag)) {
      return new Response(null, {
        status: 304,
        headers: {
          'Cache-Control': CACHE_CONTROL,
          'CDN-Cache-Control': CACHE_CONTROL,
          ETag: etag,
        },
      })
    }

    const blob = await ctx.storage.get(storageId)
    if (!blob) {
      return new Response('Asset not found', { status: 404 })
    }

    return new Response(blob, {
      headers: {
        'Access-Control-Allow-Origin': '*',
        'Cache-Control': CACHE_CONTROL,
        'CDN-Cache-Control': CACHE_CONTROL,
        'Content-Type':
          metadata.contentType ?? blob.type ?? 'application/octet-stream',
        'Cross-Origin-Resource-Policy': 'cross-origin',
        ETag: etag,
      },
    })
  }),
})

export default http

This gives you a stable URL shape and proper immutable caching, while still reading from Convex storage.

Step 2, normalize every Convex storage URL on the client

Once we had a better route, we needed to make the app use it everywhere. The clean way is one helper.

const BUILT_IN_STORAGE_PATH_PREFIX = '/api/storage/'
const CACHED_ASSET_PATH_PREFIX = '/cached-assets/'

function getCachedAssetUrl(url: string | null | undefined) {
  if (!url) {
    return null
  }

  if (
    url.startsWith('/') ||
    url.startsWith('data:') ||
    url.startsWith('blob:')
  ) {
    return url
  }

  const assetUrl = new URL(url)

  if (!assetUrl.pathname.startsWith(BUILT_IN_STORAGE_PATH_PREFIX)) {
    return url
  }

  const storageId = assetUrl.pathname.slice(BUILT_IN_STORAGE_PATH_PREFIX.length)
  const convexSiteUrl = (
    import.meta.env.VITE_CONVEX_SITE_URL as string
  ).replace(/\/$/, '')

  return `\({convexSiteUrl}\){CACHED_ASSET_PATH_PREFIX}${encodeURIComponent(storageId)}`
}

That helper matters a lot. Without it, you end up fixing one component at a time forever.

Step 3, make image preloading strict

Our old image preloader was too optimistic. It marked assets as preloaded too early. That is not enough. You want to dedupe in flight work, wait for real load, and wait for decode if possible. This is the pattern.

const preloadedImagePaths = new Set<string>()
const inFlightImagePreloads = new Map<string, Promise<void>>()

function preloadImage(path: string) {
  const normalizedPath = getCachedAssetUrl(path)
  if (!normalizedPath) {
    return Promise.resolve()
  }

  if (preloadedImagePaths.has(normalizedPath)) {
    return Promise.resolve()
  }

  const existing = inFlightImagePreloads.get(normalizedPath)
  if (existing) {
    return existing
  }

  const preloadPromise = new Promise<void>((resolve) => {
    const image = new Image()
    let hasSettled = false

    function settle(didLoad: boolean) {
      if (hasSettled) return
      hasSettled = true
      inFlightImagePreloads.delete(normalizedPath)
      if (didLoad) {
        preloadedImagePaths.add(normalizedPath)
      }
      resolve()
    }

    image.decoding = 'async'
    image.addEventListener(
      'load',
      () => {
        if (typeof image.decode === 'function') {
          void image
            .decode()
            .catch(() => {})
            .finally(() => settle(true))
          return
        }

        settle(true)
      },
      { once: true }
    )

    image.addEventListener('error', () => settle(false), { once: true })
    image.src = normalizedPath
  })

  inFlightImagePreloads.set(normalizedPath, preloadPromise)
  return preloadPromise
}

Step 4, preload audio as a first class thing

Audio needs the same treatment. If you only solve images, the app still feels cold. This is the audio version of the same idea.

const preloadedAudioUrls = new Set<string>()
const inFlightAudioPreloads = new Map<string, Promise<void>>()

function preloadAudioUrl(url: string) {
  const normalizedUrl = getCachedAssetUrl(url)
  if (!normalizedUrl) {
    return Promise.resolve()
  }

  if (preloadedAudioUrls.has(normalizedUrl)) {
    return Promise.resolve()
  }

  const existing = inFlightAudioPreloads.get(normalizedUrl)
  if (existing) {
    return existing
  }

  const preloadPromise = new Promise<void>((resolve) => {
    const audio = new Audio()
    let hasSettled = false

    function settle(didLoad: boolean) {
      if (hasSettled) return
      hasSettled = true
      inFlightAudioPreloads.delete(normalizedUrl)
      if (didLoad) {
        preloadedAudioUrls.add(normalizedUrl)
      }
      resolve()
    }

    audio.preload = 'auto'
    audio.addEventListener('canplaythrough', () => settle(true), { once: true })
    audio.addEventListener('loadeddata', () => settle(true), { once: true })
    audio.addEventListener('error', () => settle(false), { once: true })
    audio.src = normalizedUrl
    audio.load()
  })

  inFlightAudioPreloads.set(normalizedUrl, preloadPromise)
  return preloadPromise
}

Step 5, make runtime playback use the same normalized URLs

This part is easy to miss. If preload warms one URL and playback uses another URL, you lose the benefit. So your playback layer should normalize URLs too.

function getOrCreateAudio(path: string): HTMLAudioElement {
  const cachedPath = getCachedAssetUrl(path) ?? path
  const cached = state.cache.get(cachedPath)
  if (cached) return cached

  const audio = new Audio(cachedPath)
  state.cache.set(cachedPath, audio)
  return audio
}

We applied the same rule in our sound manager, entry voice manager, route music controller, and celebration audio flow.

Step 6, warm the network early

Even with perfect preload logic, the first request still pays DNS and TLS if the browser has not warmed those origins yet. So we warmed both Convex origins early.

<link rel="dns-prefetch" href="%VITE_CONVEX_URL%" />
<link rel="preconnect" href="%VITE_CONVEX_URL%" crossorigin />
<link rel="dns-prefetch" href="%VITE_CONVEX_SITE_URL%" />
<link rel="preconnect" href="%VITE_CONVEX_SITE_URL%" crossorigin />

That does not solve everything by itself. But it helps the first useful request.

Step 7, prefetch media, not just queries

This was the final important lesson. Query prefetch is not enough for a media heavy app. You also need to preload the exact image and audio for the next screen. This is the pattern we used on hover.

prefetchGameplayScreen(
  {
    chapterId,
    worldId,
    replayMode: false,
  },
  {
    onResult: (result) => {
      if (!result) {
        return
      }

      void preloadImages(
        [result.level.imageUrl, result.world.imageUrl].filter(
          (url): url is string => Boolean(url)
        )
      )

      void preloadAudioUrls(
        [
          result.level.wordAudioUrl,
          result.world.musicUrl,
          result.world.completionVoiceUrl,
        ].filter((url): url is string => Boolean(url))
      )
    },
  }
)

This is what makes the next screen actually feel warm.

What changed after the fix

After this change, the app started doing four things together. It warmed the connection earlier. It rewrote Convex storage URLs to a better cached Convex route. It deduped in flight image and audio preloads. It preloaded the next screen media before navigation. That combination is what mattered.

What this does not solve

The very first uncached request for a brand new asset can still cost real network time. That is normal. You cannot remove physics. What this fix does is remove the repeated cold feeling.

The main lesson

If your next screen is media heavy, query prefetch is only half the job. You need asset delivery, asset caching, and asset preload to be part of the architecture too. If you are using Convex, you can solve that cleanly without moving assets out of Convex.

A daily streak system sounds simple. It is not. The tricky part is not counting. The tricky part is deciding what a day means. If someone played at 10pm, then again at 2am, that is only four hours later. But it is still a new local day. That should count as a streak extension. So the system needs to be local day based, not elapsed hours based.

What to store

Keep the streak state on the profile. That is enough for a solid version one.

profiles: defineTable({
  streakCount: v.number(),
  lastStreakDate: v.optional(v.number()),
  longestStreak: v.number(),
})

These three fields are enough to drive the whole feature. streakCount, the current streak. lastStreakDate, when you last counted a streak day. longestStreak, the best streak this profile has ever had.

The rule set

You need clear rules. These are the rules we use. Same local day, no update. Next local day, extend by one. Miss more than one local day, mark the streak as broken, then start again at one. The return to one is important. The person came back today, so today still counts.

Why local time zone matters

Do not compare raw UTC dates. Do not compare elapsed hours. Do not use the server time zone. Pass the user time zone from the client and calculate the day boundary on the backend. We used date-fns and @date-fns/tz for that.

import { TZDate } from '@date-fns/tz'
import { differenceInDays, startOfDay } from 'date-fns'

function getLocalDayDifference({
  lastStreakDate,
  nowMs,
  timeZone,
}: {
  lastStreakDate: number
  nowMs: number
  timeZone: string
}) {
  const lastUpdateStart = startOfDay(new TZDate(lastStreakDate, timeZone))
  const todayStart = startOfDay(new TZDate(nowMs, timeZone))
  return differenceInDays(todayStart, lastUpdateStart)
}

That one helper is the core of the feature.

Keep the streak math pure

Do not put the streak decision logic straight inside the mutation. Make it a pure helper first. That makes it easy to test and easy to trust. This is the pattern.

type DailyStreakUpdateStatus = 'unchanged' | 'extended' | 'broken'

function getDailyStreakUpdate({
  currentStreakCount,
  lastStreakDate,
  longestStreak,
  nowMs,
  timeZone,
}: {
  currentStreakCount: number
  lastStreakDate: number | null | undefined
  longestStreak: number
  nowMs: number
  timeZone: string
}) {
  if (!lastStreakDate) {
    return {
      status: 'extended' as DailyStreakUpdateStatus,
      shouldUpdate: true,
      wasFirstUpdate: true,
      previousCount: currentStreakCount,
      newCount: 1,
      newLongestStreak: Math.max(longestStreak, 1),
    }
  }

  const dayDifference = getLocalDayDifference({
    lastStreakDate,
    nowMs,
    timeZone,
  })

  if (dayDifference <= 0) {
    return {
      status: 'unchanged' as DailyStreakUpdateStatus,
      shouldUpdate: false,
      wasFirstUpdate: false,
      previousCount: currentStreakCount,
      newCount: currentStreakCount,
      newLongestStreak: longestStreak,
    }
  }

  const status = dayDifference === 1 ? 'extended' : 'broken'
  const newCount = status === 'extended' ? currentStreakCount + 1 : 1

  return {
    status,
    shouldUpdate: true,
    wasFirstUpdate: false,
    previousCount: currentStreakCount,
    newCount,
    newLongestStreak: Math.max(longestStreak, newCount),
  }
}

The mutation

Once the pure helper is right, the Convex mutation gets simple.

export const syncDailyStreak = mutation({
  args: {
    timeZone: v.string(),
  },
  handler: async (ctx, args) => {
    const userId = await getAuthUserId(ctx)
    if (!userId) {
      throw appError({
        code: 'NOT_AUTHENTICATED',
        message: 'You must be signed in to update the daily streak',
      })
    }

    const user = await ctx.db.get(userId)
    const profile = user?.activeProfileId
      ? await ctx.db.get(user.activeProfileId)
      : null

    if (!profile || profile.deletedAt) {
      throw appError({
        code: 'NOT_FOUND',
        message: 'Active profile not found',
      })
    }

    const nowMs = Date.now()
    const update = getDailyStreakUpdate({
      currentStreakCount: profile.streakCount,
      lastStreakDate: profile.lastStreakDate ?? null,
      longestStreak: profile.longestStreak,
      nowMs,
      timeZone: args.timeZone,
    })

    if (!update.shouldUpdate) {
      return {
        didUpdate: false,
        status: update.status,
        previousStreakCount: update.previousCount,
        newStreakCount: update.newCount,
      }
    }

    await ctx.db.patch(profile._id, {
      streakCount: update.newCount,
      lastStreakDate: nowMs,
      longestStreak: update.newLongestStreak,
    })

    return {
      didUpdate: true,
      status: update.status,
      previousStreakCount: update.previousCount,
      newStreakCount: update.newCount,
    }
  },
})

The frontend trigger

You do not want to run this on every render. A good pattern is this. Wait for the first user interaction. Then sync once. Then sync again when the tab becomes visible later. That keeps the system responsive without spamming writes.

useEffect(() => {
  if (hasInteracted) return

  function handleFirstInteraction() {
    setHasInteracted(true)
    void syncDailyStreak({ timeZone })
  }

  window.addEventListener('pointerdown', handleFirstInteraction, {
    once: true,
  })
  window.addEventListener('keydown', handleFirstInteraction, {
    once: true,
  })

  return () => {
    window.removeEventListener('pointerdown', handleFirstInteraction)
    window.removeEventListener('keydown', handleFirstInteraction)
  }
}, [hasInteracted, syncDailyStreak, timeZone])

When to show the streak dialog

Only show the dialog if the mutation says didUpdate. That means. No dialog on the same local day. Dialog on the first ever day. Dialog on a proper next day extension. Dialog on a broken streak that restarts at one. That part keeps the UX honest.

One bug that is easy to create

Do not wipe streak fields when you only meant to reset gameplay progress. This is easy to do in dev tools and admin reset helpers. If you clear streakCount and lastStreakDate, the next interaction looks like day one again. Then the dialog opens again, even on the same day. That is not a streak math bug. That is a reset helper bug.

What to test

The streak helper is pure, so test it first. These cases matter. First ever update returns one. Same local day returns unchanged. Next local day extends by one. Missing more than one local day returns broken and restarts at one. The 10pm to 2am case across local midnight extends correctly. That gives you confidence in the hard part before you wire UI on top.

The main lesson

A good daily streak system is really a local calendar system. Once you treat it that way, the implementation gets much cleaner.

A PNG stores colors as numbers from 0 to 255. That is it. The brightest white and the sun are both 255. But in reality the sun is 10,000x brighter than a white wall. PNG cannot store that. Everything above "white" gets crushed to the same value.

When a 3D engine uses a PNG skybox for lighting, everything looks flat. The sun is not actually bright. The shadows are not actually dark. The light has no real range.

What EXR does differently

EXR stores each pixel as a real floating point number. The sun can be 50000.0. A cloud can be 2.0. A shadow can be 0.003. That is the actual spread of light in the real world, stored in the file.

HDR (.hdr) files do this too, but with a trick. They share one exponent across all three color channels. That means if red is very bright and blue is very dim in the same pixel, blue loses precision. It is a compromise.

EXR gives each channel its own full float. No sharing. No compromise. No precision loss anywhere.

Why this matters

In PBR rendering, the skybox is not just a background picture. It IS the light source. Every material in the scene samples it to figure out ambient lighting and reflections. Metals reflect the sky. Rough surfaces pick up its color. The skybox drives everything.

If the skybox has no real brightness range (PNG), all reflections and lighting look the same. A metal surface reflecting the sun looks identical to one reflecting a cloud. Wrong.

If the skybox has banding in subtle gradients (HDR's shared exponent), those bands show up in every reflection across the scene.

EXR has the full range and full precision. The lighting just works.

How the GPU actually uses it

Three.js takes the EXR skybox and generates blurred versions of it at different levels. Mirror-smooth surfaces sample the sharp version. Rough surfaces sample the blurry version.

This only works when the source has real brightness values. Blurring a PNG averages numbers between 0 and 1. The sun disappears into the blur. Blurring an EXR averages numbers between 0 and 50000. The sun still pumps light into the scene even when heavily blurred. That is what makes rough surfaces glow softly under bright sky. PNG cannot do this.

EXR files are also smaller

HDR files are basically uncompressed. EXR supports lossless compression (ZIP, PIZ). Better quality AND smaller files.

How to use it in Three.js

import { EXRLoader } from 'three/addons/loaders/EXRLoader.js';

const loader = new EXRLoader();
loader.load('sky.exr', (texture) => {
  texture.mapping = THREE.EquirectangularReflectionMapping;
  scene.background = texture;    // The visible sky.
  scene.environment = texture;   // Lights every PBR material in the scene.
});

Two lines. Every material in the scene now gets correct ambient lighting and reflections from the sky. Automatic.

This is a walkthrough of every layer in a procedural 3D world generation system. Each section solves one problem. They build on each other in order. By the end you have a fully textured, threaded, planet-scale terrain with proper LOD, stitching, and depth precision.

1. Heightmap: The Starting Point

What: A flat grid of vertices where each vertex's height is set by sampling some height function.

Why: Every terrain system starts here. Before noise, before LOD, before planets, you need to turn a flat plane into bumpy ground.

How: Create a PlaneGeometry with a resolution (say 128x128 vertices). Loop through every vertex. For each one, sample a height function at its XZ position. Set the Y (or Z depending on orientation) to that value.

for (let v of plane.geometry.vertices) {
  const [height, weight] = heightGenerator.Get(v.x + offset.x, v.y + offset.y);
  v.z = height * weight;
}
plane.geometry.verticesNeedUpdate = true;
plane.geometry.computeVertexNormals();

The height function can be anything. An image (read pixel brightness as height), a math function, or noise. The code supports multiple height generators blended together by weight, so you can layer a heightmap image with procedural noise.

The world is split into chunks. Each chunk is one PlaneGeometry at some offset. This lets you load/unload terrain as the player moves.

2. Perlin/Simplex Noise

What: Replace the heightmap image with a procedural noise function that generates infinite, non-repeating terrain.

Why: An image heightmap has fixed resolution and fixed extent. Noise is infinite. You can sample it at any coordinate and get a consistent, deterministic value. The terrain goes on forever.

How: The noise class wraps either Perlin or Simplex noise with octaves. "Octaves" means you sample the noise multiple times at increasing frequencies and decreasing amplitudes, then add them together. This is called fractal Brownian motion (fBm).

Get(x, y) {
  const xs = x / this._params.scale;
  const ys = y / this._params.scale;
  let amplitude = 1.0;
  let frequency = 1.0;
  let total = 0;
  let normalization = 0;

  for (let o = 0; o < this._params.octaves; o++) {
    total += amplitude * this._noise.Get(xs * frequency, ys * frequency);
    normalization += amplitude;
    amplitude *= this._params.persistence;
    frequency *= this._params.lacunarity;
  }

  total /= normalization;
  return Math.pow(total, this._params.exponentiation) * this._params.height;
}

The key parameters:

• scale: how zoomed in/out the noise is. Larger = smoother hills.

• octaves: how many layers. More = more fine detail.

• persistence: how much each octave's amplitude shrinks. Lower = smoother.

• lacunarity: how much each octave's frequency increases. Higher = more detail per octave.

• exponentiation: raise the final value to a power. Values > 1 flatten valleys and sharpen peaks. Makes terrain look more natural.

3. Quadtree and Level of Detail (LOD)

What: A quadtree that subdivides space near the camera into small chunks and keeps distant areas as large chunks.

Why: You cannot render the entire world at full resolution. A planet might need millions of chunks at max detail. LOD means: high detail near the camera, low detail far away. The quadtree decides where to split.

How: Start with one big node covering the whole terrain. Insert the camera position. If the camera is close enough to a node and the node is bigger than the minimum size, split it into four children. Recurse. Nodes near the camera get split many times (small, detailed). Nodes far away stay large (coarse).

_Insert(child, pos) {
  const dist = child.center.distanceTo(pos);

  if (dist < child.size.x && child.size.x > MIN_NODE_SIZE) {
    child.children = this._CreateChildren(child);
    for (let c of child.children) {
      this._Insert(c, pos);
    }
  }
}

The leaf nodes of the quadtree become terrain chunks. Each leaf gets the same vertex resolution (say 64x64), but covers a different world-space area. A small leaf near the camera covers 500m at 64x64, giving fine detail. A large leaf far away covers 8000m at 64x64, giving coarse detail. Same vertex count, different density. That is LOD.

4. Planetary LOD: From Flat to Spherical

What: Wrap the flat quadtree terrain onto a sphere to make a planet.

Why: A flat terrain has edges. A planet does not. For a space game or planet-scale world, you need the terrain to wrap around a sphere.

How: Instead of one quadtree, use six. Each one maps to one face of a cube. Each face has a transform matrix that positions and rotates it to form the six sides of a cube. This is called a "cube sphere".

// 6 faces: +Y, -Y, +X, -X, +Z, -Z
for (let i = 0; i < 6; i++) {
  sides.push({
    transform: transforms[i],
    quadtree: new QuadTree({
      side: i,
      size: radius,
      localToWorld: transforms[i],
    }),
  });
}

When generating vertices, each vertex position starts as a point on the cube face, gets projected onto a sphere by normalizing it (making it unit length) and multiplying by the planet radius. Then height is added along the radial direction (outward from the planet center).

_P.set(xp - half, yp - half, radius);
_P.add(offset);
_P.normalize(); // Project onto unit sphere.
_D.copy(_P); // Save the radial direction.
_P.multiplyScalar(radius);

const height = generateHeight(worldPos);
_H.copy(_D);
_H.multiplyScalar(height);
_P.add(_H); // Push vertex outward by height.

The terrain is now spherical. The quadtree still works the same, it just operates on each cube face.

5. Texturing: Triplanar Mapping, Splatting, Blending

What: Apply multiple terrain textures (grass, rock, sand, snow) based on height, slope, and biome, without visible tiling.

Why: Vertex colors look flat. Real terrain needs texture detail. But naively mapping a texture onto terrain causes visible repetition (tiling). And you need different textures at different altitudes and slopes.

How: Three techniques combined.

Texture splatting: Each vertex stores weights for up to 4 textures. The CPU decides which textures based on height and surface angle (slope). Steep surfaces get rock. Flat high areas get snow. Low flat areas get grass. These weights are passed to the shader as vertex attributes.

Triplanar mapping: Instead of using UV coordinates (which stretch badly on steep surfaces), sample the texture three times, once for each axis: XY, XZ, YZ. Blend based on the surface normal direction. Steep walls use the XZ projection. Flat ground uses the XY projection. No stretching.

vec4 dx = texture(tex, pos.zy / scale);  // X-facing
vec4 dy = texture(tex, pos.xz / scale);  // Y-facing (top-down)
vec4 dz = texture(tex, pos.xy / scale);  // Z-facing

vec3 weights = abs(normal.xyz);
weights /= (weights.x + weights.y + weights.z);

return dx * weights.x + dy * weights.y + dz * weights.z;

Texture bombing: To hide tiling repetition, the shader randomly offsets and blends the texture samples using a noise lookup. Two slightly offset samples of the same texture are blended with a smooth transition. The pattern never visibly repeats.

All three combine in the fragment shader: splat weights pick which textures, triplanar removes stretch, bombing hides tiling.

6. Atmospheric Scattering

What: A sky shader that simulates light scattering through the atmosphere, giving realistic sunsets, blue skies, and haze at the horizon.

Why: A skybox texture is static. If the sun moves, the sky does not respond. Atmospheric scattering computes sky color physically based on the sun angle.

How: The shader casts a ray from the camera through each pixel into the atmosphere (a shell around the planet). It marches along the ray, accumulating Rayleigh scattering (which makes the sky blue) and Mie scattering (which creates the bright glow around the sun). The result depends on: sun position, altitude, and the angle between the view direction and the sun.

This also adds distance fog naturally. Objects further away pick up more atmospheric haze. It makes the planet feel massive because distant terrain fades into the sky color instead of just clipping at the far plane.

7. Threading with Web Workers

What: Move all terrain mesh generation off the main thread into a pool of Web Workers.

Why: Generating terrain vertices involves thousands of noise samples, normal calculations, texture weight computations. This is heavy math. Doing it on the main thread freezes the game.

How: A WorkerPool manages 7 workers (one per spare CPU core). When a new chunk is needed, the terrain manager serializes the parameters into plain data (no class instances, workers cannot receive those) and enqueues it. The pool assigns it to the next free worker.

The worker reconstructs noise generators from the params, runs all the mesh generation math, packs the results into SharedArrayBuffer instances (zero-copy shared memory), and posts a "done" message. The main thread reads the shared buffers directly into Three.js geometry attributes. No copy, no stall.

// Worker side: pack into shared memory.
const posBuf = new Float32Array(new SharedArrayBuffer(4 * positions.length));
posBuf.set(positions);
self.postMessage({ positions: posBuf });

// Main thread: read directly.
chunk.geometry.setAttribute(
  "position",
  new THREE.Float32BufferAttribute(result.positions, 3),
);

The main thread never waits for workers. It renders what it has. When a chunk finishes in the background, it appears. Completely smooth.

8. Floating Origin

What: Periodically re-center the world around the camera so GPU coordinates stay near zero.

Why: GPUs use 32-bit floats. At large distances from the origin (100,000+ units), precision drops. Vertices jitter, triangles flicker (z-fighting), and the scene breaks visually.

How: Vertex positions are computed relative to the camera position, not in absolute world space. The noise function still samples at the true world coordinate (so terrain is consistent everywhere), but the actual mesh data the GPU receives is always near zero.

// Keep absolute position for noise sampling.
_W.copy(_P);

// Subtract camera position for GPU coordinates.
_P.sub(origin);

// Add height in world space direction.
const height = generateHeight(_W);
_P.add(heightVector);

This is visible in the Rebuild method where origin is the camera position passed in as a parameter. Every vertex subtracts it.

9. Logarithmic Depth Buffer

What: Replace the standard depth buffer encoding with a logarithmic one.

Why: The default depth buffer distributes most of its precision near the camera's near plane. For a planet-scale world where near=1 and far=1,000,000, almost all depth precision is in the first few meters. Everything beyond is z-fighting.

How: In the vertex shader, compute a logarithmic depth value:

vFragDepth = 1.0 + gl_Position.w;

In the fragment shader, write it out:

gl_FragDepth = log2(vFragDepth) * logDepthBufFC * 0.5;

Where logDepthBufFC = 2.0 / log2(farPlane + 1.0). This spreads depth precision evenly across the entire range on a logarithmic scale. Close objects still get fine precision, but distant objects also get usable precision instead of nearly zero.

The cost: writing gl_FragDepth in the fragment shader disables the GPU's early-Z optimization. Every fragment runs the shader even if it would be occluded. This is a performance tradeoff worth making at planetary scale.

10. Mesh Stitching: Gaps, Skirts, and Edge Matching

What: Fix the visible cracks that appear where terrain chunks of different LOD levels meet.

Why: A high-res chunk has 64 vertices along its edge. Its lower-res neighbour has 32. The vertices do not line up. You get cracks you can see through.

How: Three techniques.

Edge skirts: Each chunk generates one extra row of vertices on every side (resolution + 2 instead of resolution). These outer vertices are pushed to match their inner neighbour's position. They form a "flap" that tucks under the adjacent chunk. If there is a crack, the skirt geometry fills it.

Edge snapping: Each chunk knows the size ratio of its neighbours (stored in a neighbours array). If a neighbour is half the resolution, the high-res edge vertices are lerped to match the low-res grid. Vertex 1 between vertex 0 and vertex 2 gets interpolated to lie exactly on the line between them. Both chunks now agree on the same edge geometry.

if (neighbours[side] > 1) {
  const stride = neighbours[side];
  // For each edge vertex, find which two low-res vertices it falls between.
  // Lerp its position to match.
}

Edge normal recomputation: Face-averaged normals at chunk borders are wrong because they only see faces on one side. The code recomputes edge normals using central differences: sample the height function at two nearby points, compute the cross product. This gives correct normals independent of chunk boundaries.

When a chunk's neighbour changes LOD level, only the edges need updating. That is what QuickRebuild does. It recomputes edge positions and normals without regenerating the entire mesh.

11. Biome Generation

What: Use a separate noise function to divide the world into biomes (desert, forest, tundra, etc.) that affect terrain color and texture selection.

Why: Without biomes, the entire planet uses the same height-to-texture mapping everywhere. With biomes, different regions of the world look distinct.

How: A second noise generator produces a biome value at each world position. This biome value is separate from the height noise. It uses different parameters (fewer octaves, larger scale) so biomes change gradually over large distances.

The texture splatter reads both the height and the biome value to decide which textures to apply. Low altitude in a desert biome gets sand. Low altitude in a temperate biome gets grass. The biome noise smoothly transitions between regions, and the texture blending handles the crossover.

const biomeGenerator = new Noise({
  octaves: 2,
  persistence: 0.5,
  lacunarity: 2.0,
  scale: 2048.0, // Very large scale. Biomes are big regions.
  seed: 2, // Different seed from terrain noise.
});

// In the texture splatter:
const biome = biomeGenerator.Get(worldX, worldY);
// Use biome + height + slope to pick texture weights.

The biome noise is cheap (only 2 octaves) because it does not need fine detail. It just needs to vary smoothly across the planet.

How It All Fits Together

The full pipeline for rendering one frame:

1. Quadtree subdivides the six cube faces based on camera distance. Produces a set of leaf nodes (chunks to render).

2. Diff against the previous frame's chunks. New chunks get sent to the worker pool.

3. Each worker receives plain parameters, reconstructs noise generators, generates vertex positions on the sphere surface using noise + height.

4. Positions are offset by the camera origin (floating origin). Heights are sampled from the biome-aware texture splatter.

5. Edge stitching snaps borders to match lower-res neighbours. Skirts fill any remaining gaps.

6. Results are packed into SharedArrayBuffer and sent back zero-copy.

7. Main thread sets the geometry attributes and makes the chunk visible.

8. The terrain shader applies triplanar texturing with bombing, computes lighting, and writes logarithmic depth.

9. Atmospheric scattering renders the sky and distance haze.

Each part solves one specific problem. Together they produce a planet you can walk on, fly over, and zoom out from to see from space, all running smoothly in a browser.

PBR stands for physically based rendering. It is a lighting model that simulates how light actually behaves in the real world.

All examples are from Patina. A moss

How light works in reality

Light hits a surface. Two things happen. Some light bounces off the surface immediately. That is reflection. Some light penetrates the surface, bounces around inside the material, and comes back out. That is diffuse color.

The ratio between these two depends on what the material is made of. That is the entire foundation of PBR.

PBR describes materials using a set of texture maps. Each map controls exactly one physical property. The shader combines them all into realistic lighting.

Basecolor (albedo)

The color of the material itself. Nothing else. No shadows, no highlights, no reflections. Just: what color are the molecules of this thing.

Dirt is brown. Concrete is grey. Rust is orange-brown.

If you took a material into a perfectly evenly lit white room with zero shadows and zero reflections, what you see is the basecolor.

Under the hood: the shader multiplies this color by the diffuse lighting contribution. Light hits the surface, some penetrates, bounces around inside, comes out tinted by this color.

Normal map

A texture where each pixel stores a direction instead of a color. The RGB values encode an XYZ vector. This vector tells the shader "pretend the surface is pointing this direction" even though the actual geometry is flat.

Why it matters: a flat wall with a normal map of bricks will catch light as if every brick edge and groove were actual geometry. Light hits the "grooves" at a different angle than the "faces" so you see shadows and highlights that look 3D. But the mesh is still a flat quad. Zero extra triangles.

Under the hood: the shader reads the normal map and replaces the geometric normal with the one from the texture. All lighting calculations use this new normal. The dot product between the light direction and the normal gives different values per pixel. The surface looks bumpy even though it is flat.

Roughness

Think about two surfaces. A mirror and a chalkboard. Throw a laser beam at a mirror. It bounces in one tight direction. Sharp, focused reflection. Now throw that same laser at a chalkboard. The light scatters everywhere. No clear reflection. Just a soft bright spot.

That is roughness. It controls how scattered or focused the reflected light is.

• Roughness = 0: mirror. Light bounces in one direction. Sharp reflections. Wet surfaces, polished metal, glass.

• Roughness = 0.5: somewhere in between. A soft, blurry highlight. Like plastic or worn leather.

• Roughness = 1: chalk. Light scatters in all directions. No visible reflection. Dry concrete, cloth, raw wood.

Under the hood: the shader uses roughness to control the width of the specular highlight. The way to think about it is: imagine the surface at a microscopic level as millions of tiny mirrors angled randomly. Low roughness means all the tiny mirrors face the same direction (smooth surface). High roughness means the mirrors face random directions (rough surface).

The math (usually GGX distribution) computes how many of those microfacets happen to reflect light toward the camera. More aligned = tight bright highlight. More scattered = wide dim highlight.

// Simplified concept:
float highlight = pow(dot(normal, halfVector), sharpness);
// sharpness comes from roughness.
// Low roughness = high sharpness = tight highlight.
// High roughness = low sharpness = wide dim highlight.

This is also why wet things look shiny. Water fills the microscopic grooves, making the surface smoother at the micro level. Roughness goes down. Reflections appear. Dry the surface out, the grooves are exposed again, roughness goes back up.

Metalness

This answers one question: does this surface conduct electricity?

Metals (steel, gold, copper, aluminum): yes. Non-metals (wood, dirt, plastic, skin): no.

Why does electrical conductivity matter for rendering? Because metals and non-metals reflect light in fundamentally different ways.

Non-metals reflect a small amount of light (about 4%) as white or grey. The rest penetrates the surface and comes back out tinted by the basecolor. So you see the diffuse color strongly and a subtle white highlight on top.

Metals reflect almost all light (60-90%) and that reflection is tinted by the basecolor. No light penetrates. No diffuse contribution at all. The "color" you see on a gold bar IS its reflection color, not diffuse color. Gold reflects yellow light. Copper reflects orange light.

So metalness switches how the shader interprets the basecolor map:

• Metalness = 0: basecolor is used for diffuse. Reflections are white/grey.

• Metalness = 1: basecolor is used for reflection tint. No diffuse at all.

Under the hood:

// Simplified:
vec3 diffuseColor = basecolor * (1.0 - metalness);
vec3 reflectionColor = mix(vec3(0.04), basecolor, metalness);

// metalness = 0: diffuse is full basecolor, reflection is 4% white.
// metalness = 1: diffuse is zero, reflection is basecolor.

The 0.04 is not arbitrary. It is the measured reflectance of most non-metal surfaces (glass, plastic, water all hover around 4% reflectance at direct viewing angles). This is called the Fresnel reflectance at normal incidence, or F0.

In practice, most natural materials are metalness 0. Dirt, rock, grass, wood, skin, cloth. The only things with metalness are actual metals. And metalness is almost always 0 or 1, rarely in between. A value of 0.5 does not mean "kinda metal." It usually means there is a transition zone between metal and non-metal at that pixel, like rust on steel.

Height map

Stores how raised or sunken each point on the surface is. White = high. Black = low.

Two uses:

Parallax mapping. The shader offsets texture coordinates based on the view angle and the height value. This fakes depth without moving any geometry. Cracks look like they go into the surface. Bricks look like they stick out. It is an optical illusion computed per pixel.

Displacement mapping. Actually move the vertices based on the height map. This requires enough geometry to displace. More triangles = more detail. This is the real deal but it is expensive.

For terrain: the noise function handles large-scale height (mountains and valleys). A material's height map adds small-scale detail like individual stones sticking up from rocky ground.

How they all combine in the shader

One lighting pass, all maps working together:

1. Read basecolor, normal, roughness, metalness from textures.

2. Compute material properties from metalness:
   diffuseColor  = basecolor * (1.0 - metalness)
   specularColor = mix(0.04, basecolor, metalness)

3. Perturb the surface normal using the normal map.

4. Compute diffuse lighting:
   diffuse = light * diffuseColor * max(dot(N, L), 0.0)

5. Compute specular lighting using GGX:
   specular = light * specularColor * GGX(roughness, N, H, V)
   (N = normal, H = halfway vector, V = view direction)

6. Final color = diffuse + specular

Each map controls exactly one variable in this pipeline. Basecolor provides color. Normal adjusts the surface direction. Roughness shapes the specular highlight. Metalness routes the basecolor to either diffuse or specular. Height adds geometric detail.

That is PBR. Describe the physics, let the math do the rendering.

Quick reference

Sometimes your program does expensive calculations over and over for no reason. The input changed three times but you only needed the output once. You are throwing away work. The dirty flag pattern fixes this by deferring the expensive part until someone actually needs the result.

The Problem.

You have some primary data. You have some derived data that is computed from it. The computation is expensive. The primary data changes often. But the derived data is not always read immediately after every change.

If you recompute every time the primary data changes, you waste cycles on results that get thrown away before anyone uses them.

A Concrete Example. Scene Graphs.

In a game, objects are often arranged in a hierarchy. A ship has a crow's nest. The crow's nest has a pirate. The pirate has a parrot. Each object stores a local transform, its position relative to its parent.

To render any object, you need its world transform. That means multiplying all the local transforms up the parent chain. Ship times nest times pirate times parrot.

Now imagine in a single frame the ship moves, the nest rocks, the pirate leans, and the parrot hops. If you recalculate world transforms eagerly after each change, the parrot's world transform gets recalculated four times. Only the last result matters. The other three are wasted.

The Solution.

Do not recalculate when the primary data changes. Just set a flag that says "this is out of date." When something actually needs the derived data, check the flag. If dirty, recalculate and clear it. If clean, use the cached value.

Setting a transform becomes two assignments. The expensive math only happens once, right when you need the result.

The Code.

class GraphNode {
  private local: Transform;
  private world: Transform;
  private dirty = true;
  private children: GraphNode[] = [];
  private mesh: Mesh | null;

  setTransform(local: Transform) {
    this.local = local;
    this.dirty = true;
    // no recalculation. just mark it.
  }

  render(parentWorld: Transform, parentDirty: boolean) {
    const dirty = this.dirty || parentDirty;

    if (dirty) {
      this.world = this.local.combine(parentWorld);
      this.dirty = false;
    }

    if (this.mesh) renderMesh(this.mesh, this.world);

    for (const child of this.children) {
      child.render(this.world, dirty);
    }
  }
}

The Clever Part.

When a parent moves, all its children need recalculation too. The naive approach is to recursively mark every child as dirty when the parent moves. That is slow.

Instead, pass parentDirty down the tree during the render traversal. If any ancestor was dirty, the children know they need to recalculate. No recursive marking needed. Setting a transform stays fast no matter how deep the hierarchy is.

When To Use It.

Two conditions must be true.

The primary data changes more often than the derived data is read. The pattern works by batching multiple changes into a single recalculation. If you always need the result immediately after every change, the flag adds overhead for no benefit.

The computation cannot be updated incrementally. If you can adjust the derived data cheaply when the primary data changes, like adding or subtracting from a running total, just do that instead. Dirty flags are for cases where you have to recompute from scratch.

When To Clean The Flag.

Three options depending on your situation.

When the result is needed. This is the most common approach. You defer until something reads the derived data. Simple and avoids all unnecessary work. The risk is that if the computation is heavy, it can cause a visible pause at the moment you need the result.

At a checkpoint. Save the work for a loading screen or a scene transition. The player does not notice. The risk is that you cannot guarantee the player reaches the checkpoint in time.

On a timer in the background. Process changes at a fixed interval. You can tune how often it runs. The risk is you might need threading or concurrency to avoid blocking the main loop.

Where You See This Everywhere.

Scene graphs in game engines. The example above.

Text editors. The "unsaved changes" dot in your title bar is a dirty flag. The primary data is the document in memory. The derived data is the file on disk. It only writes when you save.

Web frameworks. Angular and similar frameworks use dirty flags to track what changed in the browser and needs to be synced to the server.

Physics engines. A resting object gets a flag that says "nothing has touched me." It skips physics processing entirely until a force is applied. Then the flag flips and it re enters the simulation.

The Risk.

You have to set the flag every single time the primary data changes. Miss it in one place and you get stale data. The derived output looks correct but it is not. These bugs are hard to find.

The best defense is to funnel all modifications through a single function. If there is only one way to change the primary data, there is only one place you need to set the flag.

One Sentence Summary.

Do not redo expensive work every time something changes. Mark it dirty, and only recompute when someone actually asks for the result.

Your game has hundreds of units on a battlefield. Each one needs to know which enemies are nearby. The naive approach: compare every unit to every other unit. That is O(n²). Double the units and you quadruple the work. It does not scale.

The fix: organize objects by where they are in space. Then when you ask "what is near this point" you only look at a small slice of the world instead of the entire thing.

The Problem.

function handleMelee(units: Unit[]) {
  for (let a = 0; a < units.length; a++) {
    for (let b = a + 1; b < units.length; b++) {
      if (distance(units[a], units[b]) < ATTACK_RANGE) {
        handleAttack(units[a], units[b]);
      }
    }
  }
}

Every unit checks every other unit. 100 units means ~5,000 checks. 1,000 units means ~500,000 checks. Per frame. Most of those checks are pointless because most units are nowhere near each other.

The Core Idea.

Divide your world into regions. Put each object in the region that matches its position. When you need to find nearby objects, only check the region the object is in and its neighbors. Skip everything else.

The simplest version of this: a flat grid.

The Grid.

Overlay a grid on your world. Each cell holds a list of the objects inside it. When checking for combat, only compare objects within the same cell.

class Grid {
  private cells: Map<string, Unit[]> = new Map();
  private cellSize: number;

  constructor(cellSize: number) {
    this.cellSize = cellSize;
  }

  private key(x: number, y: number): string {
    const cx = Math.floor(x / this.cellSize);
    const cy = Math.floor(y / this.cellSize);
    return `\({cx},\){cy}`;
  }

  add(unit: Unit) {
    const k = this.key(unit.x, unit.y);
    if (!this.cells.has(k)) this.cells.set(k, []);
    this.cells.get(k)!.push(unit);
  }

  remove(unit: Unit) {
    const k = this.key(unit.x, unit.y);
    const cell = this.cells.get(k);
    if (!cell) return;
    const i = cell.indexOf(unit);
    if (i !== -1) cell.splice(i, 1);
  }

  move(unit: Unit, newX: number, newY: number) {
    const oldKey = this.key(unit.x, unit.y);
    const newKey = this.key(newX, newY);
    unit.x = newX;
    unit.y = newY;
    if (oldKey !== newKey) {
      this.remove(unit);
      this.add(unit);
    }
  }

  getNearby(x: number, y: number): Unit[] {
    const cx = Math.floor(x / this.cellSize);
    const cy = Math.floor(y / this.cellSize);
    const result: Unit[] = [];
    // Check this cell and all 8 neighbors.
    for (let dx = -1; dx <= 1; dx++) {
      for (let dy = -1; dy <= 1; dy++) {
        const cell = this.cells.get(`\({cx + dx},\){cy + dy}`);
        if (cell) result.push(...cell);
      }
    }
    return result;
  }
}

Now combat only compares units in the same neighborhood:

function handleMelee(grid: Grid, units: Unit[]) {
  for (const unit of units) {
    const nearby = grid.getNearby(unit.x, unit.y);
    for (const other of nearby) {
      if (other === unit) continue;
      if (distance(unit, other) < ATTACK_RANGE) {
        handleAttack(unit, other);
      }
    }
  }
}

Instead of checking against every unit in the game, you check against the handful that are actually close. The rest do not exist as far as this code is concerned.

Moving Objects.

When an object moves, you need to check if it crossed a cell boundary. If it did, remove it from the old cell and add it to the new one. If it stayed in the same cell, just update its position. This is cheap: a couple of index calculations and a pointer swap.

Cell Size Matters.

Too large: many objects per cell, you are back to checking too many pairs.

Too small: lots of empty cells wasting memory, and you have to check many neighboring cells for range queries.

A good starting point: make cells roughly the size of your largest interaction range. If your attack distance is 20 units, make cells 20x20. That way nearby objects are always in the same cell or direct neighbors.

Flat Grid vs Hierarchical.

A flat grid is the simplest option. Fixed cells, fixed memory, easy to update when objects move. Works great when objects are spread fairly evenly across the world.

When objects clump together, a flat grid breaks down. One cell gets overloaded while most sit empty. Hierarchical structures like quadtrees solve this. They subdivide crowded areas into smaller regions and leave empty areas as one big region. They adapt to where the objects actually are.

The trade off: hierarchical structures are more complex to implement and more expensive to update when objects move. If your objects are spread reasonably well, a flat grid is usually enough.

Common Spatial Partition Structures.

Grid: simplest. Fixed cells. Good for evenly distributed objects. Basically a bucket sort extended to 2D.

Quadtree: subdivides crowded areas recursively into four squares. Good balance between adaptability and simplicity. Its 3D version is called an octree.

BSP (binary space partition): splits space with planes. Often used for static level geometry. Basically a binary search tree in multiple dimensions.

K-d tree: similar to BSP but alternates which axis it splits on. Good for point queries.

Bounding volume hierarchy: groups objects into bounding boxes, then groups those boxes into bigger boxes. Good when objects have varying sizes. Also a binary search tree at its core.

When To Use It.

You have many objects with positions. You frequently ask "what is near X." The naive approach is too slow. That is it. If your object count is small enough that brute force works, do not bother.

Also consider: if your objects move a lot, you pay a cost to keep the partition updated. Make sure the savings from faster queries outweigh the cost of maintenance.

One Sentence Summary.

Do not search the entire world to find what is right next to you.

Allocating and freeing memory is slow. On consoles and mobile devices it is even worse because it fragments the heap. Over time your free memory turns into a scattered mess of tiny gaps that cannot fit anything useful. Your game crashes. Not because you ran out of memory, but because the free memory is in the wrong shape.

Object pools fix this. Allocate everything up front. Reuse it forever. No fragmentation. No allocation cost during gameplay.

How It Works.

At startup, create a fixed array of objects. All of them sit in memory, initialized to "not in use." When you need a new object, grab one from the pool and mark it as active. When you are done with it, mark it inactive. It goes back into the pool, ready to be reused.

No malloc. No free. No garbage collector. Just flipping a flag.

class Particle {
  framesLeft = 0;
  x = 0;
  y = 0;
  xVel = 0;
  yVel = 0;

  inUse() {
    return this.framesLeft > 0;
  }

  init(x: number, y: number, xVel: number, yVel: number, lifetime: number) {
    this.x = x;
    this.y = y;
    this.xVel = xVel;
    this.yVel = yVel;
    this.framesLeft = lifetime;
  }

  update() {
    if (!this.inUse()) return;
    this.framesLeft--;
    this.x += this.xVel;
    this.y += this.yVel;
  }
}

class ParticlePool {
  private particles = Array.from({ length: 1000 }, () => new Particle());

  create(x: number, y: number, xVel: number, yVel: number, lifetime: number) {
    for (const p of this.particles) {
      if (!p.inUse()) {
        p.init(x, y, xVel, yVel, lifetime);
        return;
      }
    }
    // Pool full. No particle created. Player won't notice.
  }

  update() {
    for (const p of this.particles) {
      p.update();
    }
  }
}

All 1000 particles exist from the start. Creating one is just finding an inactive slot and writing values into it. No memory allocation happens at runtime.

The Problem With Linear Search.

The code above scans the entire array to find a free slot. If the pool is large and mostly full, that scan gets slow.

Fix. Use a free list. When a particle is inactive, its memory is not doing anything useful. Reuse that memory to store a pointer to the next free particle. This chains all free particles into a linked list, built directly inside the pool's own memory.

class ParticlePool {
  private particles = Array.from({ length: 1000 }, () => new Particle());
  private firstAvailable = 0;

  constructor() {
    // Chain every particle to the next one.
    for (let i = 0; i < 999; i++) {
      this.particles[i].nextFree = i + 1;
    }
    this.particles[999].nextFree = -1; // end of list
  }

  create(x: number, y: number, xVel: number, yVel: number, lifetime: number) {
    if (this.firstAvailable === -1) return; // pool full

    const p = this.particles[this.firstAvailable];
    this.firstAvailable = p.nextFree;
    p.init(x, y, xVel, yVel, lifetime);
  }

  free(index: number) {
    this.particles[index].framesLeft = 0;
    this.particles[index].nextFree = this.firstAvailable;
    this.firstAvailable = index;
  }
}

Now creating and freeing are both O(1). No scanning. Just follow one pointer and you have your slot.

What Happens When The Pool Is Full.

Four options.

Make sure it never happens. Tune the pool size so it is always big enough. Best for critical objects like enemies or bosses where failing to create one would break the game.

Do nothing. Skip the creation. Works for particles and cosmetic effects. The screen is already full of stuff. One less sparkle is invisible.

Kill the least important active object. Good for sound effects. If all sound channels are in use, cut the quietest one. The new sound will mask the loss.

Grow the pool. Allocate more slots at runtime. Only works if your platform can afford the memory hit. Consider shrinking back later when demand drops.

Watch Out For Stale State.

Pooled objects are not freshly allocated. They still hold data from their previous life. If your init function misses a field, you get ghost state from a dead object leaking into a live one. These bugs are hard to find because the stale data often looks almost correct.

Always fully initialize every field when reusing an object. In debug builds, consider zeroing out the memory when an object is freed so stale reads are obvious.

When To Use It.

You create and destroy objects frequently during gameplay. Particles, bullets, sound effects, enemies.

Objects are the same size or close to it. Pools work best when every slot is the same size. If objects vary wildly, you waste memory padding small objects to fit the largest slot.

You are on a platform where fragmentation or allocation speed matters. Consoles, mobile, embedded. On a PC with a modern allocator and garbage collector, pools are less critical but still useful for hot paths.

One Sentence Summary.

Allocate once at startup, reuse forever, never ask the memory manager for anything during gameplay.