Generating Voxel Minecraft Worlds - Ray-Marching and HeightMaps.
Voxels to Create Minecraft-Like Terrains (Boxy World)
With the new Minecraft movie hitting the cinemas - and my love of the game - I thought I'd write a simple tutorial on how you'd create simple minecraft-like worlds that look nice and are interactive.
There are two ways of creating minecraft scenes - either brick by brick (builds the scene up from blocks) - like you do with lego - or converting an existing scene into a 'minecraft-like' one.
This tutorial will focus on 'converting' existing worlds and geometry into a minecraft-like looking ones (voxels and blocks).
We'll 'voxelate' a scene - which means we'll take a smooth surface and pass it through an extra calculation to round the values to the nearest voxel edge (flattening them) and generate blocks.
We'll then mix in some color - so the result looks nice (e.g., lighting and colors).
The tutorial will start of simple - using 2d visualizations and minimal working code - then incrementally keep adding new things (pointing out any pitfalls/artifacts or issues along the way).
Voxelate is like 'pixelate' - but instead of working with an image of pixels in 2d - we do it in 3d and work with the world positions (xyz coordinates). In 2d pixel space it's called pixelation and in 3d world coordinates it's called voxelation.
For the code examples - we'll use a fragment shader for all of the graphical outputs - the examples will use WebGPU and WGSL so you can run/interact with the examples in the web browser without needing to install anything - you can access the source code for the section at the end (and other links for related projects/code).
Fragment Shader (Full Screen Quad)
First thing first, let's setup a vanilla fragment shader - that has the texture coordinates for a full screen quad. If we draw the texture coordinates as the 'red' and 'green' color components - it should look like this:
Full screen quad - draw the texture coordinates as the red and green color in the fragment shader.
The fragment shader for the full screen quad is given below:
@fragment fn main(@location(0) uv: vec2<f32>) -> @location(0) vec4<f32> { // uv range [0,0] to [1,1] top-left to bottom-right return vec4( uv, 0.0, 1.0 ); }
Simple Height Map Function
Let's define a height map function - so any position in the world, if we pass the
x
and
z
value to the function it will give us the height of the terrain at that location.
We want a hilly terrain with some variation - which we can do by combining a few trigonmetric functions together.
function takes a vec3 but only uses the 'x' and 'z' values in the calculation of the height (does not use the 'y' value). Also the return value is a single 'float' - which is the 'height' of the terrain at the 'x' and 'z' location.
2D Visualization (Smooth) - Top Down
Top down visualization of the 'height map' function to see what sort of pattern it generates - we'll mix between blue and red for the height (blue bottom and red height).
Top down 2d visualization of the height map function (color represents the height value).
@fragment fn main(@location(0) uv: vec2<f32>) -> @location(0) vec4<f32> { // uv range [0,0] to [1,1] top-left to bottom-right // Normalize UV coordinates to range [-1,1] let nuv: vec2<f32> = -1.0 + 2.0 * uv.xy;
let z = sin( mytimer * 0.1 ); // slice location for the z
// set 'y' - height to 0 as we're going to 'find' the height using the height function let pos = vec3( nuv.x, 0.0, z ) * 20.0;
let y = abs( getGroundHeight( pos ) );
var red = vec3(1.0, 0.0, 0.0); var blue = vec3(0.0, 0.0, 1.0); var color = blue;
if ( abs(nuv.y-y)<0.01 ) { color = red; }
return vec4<f32>( color, 1.0 ); }
Side View as 'Gradient'
We can modify the previous example to draw a gradient color (distance) from the surface instead of using a threshold.
Draw the 2d side view (slice) as a 'gradient' instead of a hard threshold tolerance.
@fragment fn main(@location(0) uv: vec2<f32>) -> @location(0) vec4<f32> { // uv range [0,0] to [1,1] top-left to bottom-right // Normalize UV coordinates to range [-1,1] let nuv: vec2<f32> = -1.0 + 2.0 * uv.xy;
let z = sin( mytimer * 0.1 ); // slice location for the z
// set 'y' - height to 0 as we're going to 'find' the height using the height function let pos = vec3( nuv.x, 0.0, z ) * 20.0;
let y = abs( getGroundHeight( pos ) );
var red = vec3(1.0, 0.0, 0.0); var blue = vec3(0.0, 0.0, 1.0);
// d is the distance from the surface let d = abs(nuv.y-y); var color = mix( red, blue, pow(d,0.5) );
return vec4<f32>( color, 1.0 ); }
Voxelize 2D (Pixelate)
This is a key step on our journey to developing a `minecraft` scene - as we use the two key functions floor and fract - which will round the numbers and also get us the fractional part of the number.
The 'floor' function will clamp our x, y and z position - while the 'fract' function will be used to detect the 'edges' of each square (so we can mix in color information).
For this example, we'll voxelate the terrain and draw it as a 2d visualization (slice - fixed z). We'll also 'animate' the z-value - so you can see how the result changes for different z-values. We draw the 'fract' value on top - to confirm the edges of each block - and to make sure they're all the same size.
2d visualization of the terrain after voxelization.
@group(0) @binding(2) var <uniform> mytimer : f32;
// Smooth ground height function fn getGroundHeight(pos: vec3<f32>) -> f32 { var v = 0.2 * sin(pos.x * 0.4) + 0.3 * cos(pos.z * 0.45) + 0.15 * sin(pos.z * 1.7) * cos(pos.x * 0.4); return v * 15.0; // amplify the height of the terrain }
@fragment fn main(@location(0) uv: vec2<f32>) -> @location(0) vec4<f32> { // uv range [0,0] to [1,1] top-left to bottom-right // Normalize UV coordinates to range [-1,1] let nuv: vec2<f32> = -1.0 + 2.0 * uv.xy;
let z = sin( mytimer * 0.1 )*3.0; // slice location for the z
// Going to find the surface 'height' at this location let pos = vec3( nuv.x, nuv.y, z ) * 10.0;
// voxelate the input - which will correct our 'x' and 'z' input values // so they're on the correct boundaries let sizeVoxels = 0.8; var floorPos = floor( pos * sizeVoxels ) / sizeVoxels; var fractPos = fract( pos * sizeVoxels );
// We have the height using the voxel x-z input locations let y = getGroundHeight( floorPos );
// This little nugget - we want the 'y' values to also lay on the // correct boundary - so we need to 'floor' the y value (if not they'll be offset wrong) floorPos.y = y; floorPos = floor( floorPos * sizeVoxels ) / sizeVoxels;
// visualize the result var red = vec3(1.0, 0.0, 0.0); var blue = vec3(0.0, 0.0, 1.0); var color = blue;
if ( pos.y > floorPos.y ) { color = red;
// color the edges - check the values are 'square' and they're on // the correct boundaries - using the 'fract' part of the value color *= fractPos.y; color *= fractPos.x; }
return vec4<f32>( color, 1.0 ); }
We can visualize the steps from the 'smooth' height function to the 'voxelated' grid:
Show the steps going from the smooth height function to the voxelated grid.
2D Boxes (Lines)
Use the 'fract' which gives us the fractional part of the number which goes from 0.0 to 1.0 - we use this to draw the edges (boxes). We'll also show the scene in different voxel resolutions (how big or small we want our boxes).
Visualize the voxelized terrain with diffrent size blocks.
If the pixel is on the lower edge (i.e., less than 0.05) we draw it darker (so the edges of the voxels) stand out as lines in the 2d visualization.
// fractPos goes from 0.0 to 1.0 (repeats for the x, y and z axis) if ( fractPos.y < 0.05 ) { color *= 0.1; } if ( fractPos.x < 0.05 ) { color *= 0.1; }
We control the voxel size using:
let sizeVoxels = 2.0; var floorPos = floor( pos * sizeVoxels ) / sizeVoxels; var fractPos = fract( pos * sizeVoxels );
Minecraft Colors
As we have boxes (or voxels in 3d) - and we have a way to detect the lower and upper value of each axis (x, y and z) using the 'fract' function - we can use this to mix and blend color across the surface (e.g., brown for the bottom of the box and green for the top).
Linearly interpolate between brown and green along the y-axis.
Linearly interpolate between brown and green inside the squares along the y-axis.
let brown: vec3<f32> = vec3<f32>(0.6, 0.4, 0.2); // RGB for brown let green: vec3<f32> = vec3<f32>(0.0, 0.5, 0.0); // RGB for green color = mix( green, brown, fractPos.y );
Non-Linear Color Interpolation
Instead of linearly interpolating between brown and green - we can modify the code to make it only interpolate in the 'middle' within a range - making the bottom and top a solid color and in the middle interpolate - to give a nicer result.
Non-linear interpolation of the color from brown to green (middle step).
let brown: vec3<f32> = vec3<f32>(0.6, 0.4, 0.2); // RGB for brown let green: vec3<f32> = vec3<f32>(0.0, 0.5, 0.0); // RGB for green
// Transform the value to create a sharper transition let sharp_value = smoothstep(0.2, 0.8, fractPos.y); // Adjust 0.4 and 0.6 for tighter blending color = mix(green, brown, sharp_value); // Use the transformed value for blending
Random Texel Noise
To make the colors look more pixelated (give them that 'minecraft' feel) - we add a bit of noise - but we also need to do the same thing we've been doing to the level (pixelate the noise) - so it's 'blocky'.
Add texel noise to the voxel texture gradients.
let brown: vec3<f32> = vec3<f32>(0.6, 0.4, 0.2); // RGB for brown let green: vec3<f32> = vec3<f32>(0.0, 0.5, 0.0); // RGB for green
// Transform the value to create a sharper transition let sharp_value = smoothstep(0.2, 0.8, fractPos.y); // Adjust 0.4 and 0.6 for tighter blending color = mix(green, brown, sharp_value); // Use the transformed value for blending
// How blocky the texel noise is (e.g., 1 - no noise and 1000 is just speckles) let texelNoiseSize = 80.0; let texelnoise = random( floor(uv*texelNoiseSize)/texelNoiseSize ); color += texelnoise*0.1;
Random Grass-Soil
The transiton from grass to soil (green to brown) is a bit linear - it is a straight line - and if you look at a Minecraft block - the grass on the top has a 'jittery' edge. So we add in some more randomness - instead of the transition from green to brown being constant - we'll use a randomn number so it gives the grass edge a jagged feel that we'd expect.
Add a jitter variable for the transiton from brown to green - instead of a straight line.
This is the updated part of code with the 'jagged' edge for the grass-soil transition:
let brown: vec3<f32> = vec3<f32>(0.6, 0.4, 0.2); // RGB for brown let green: vec3<f32> = vec3<f32>(0.0, 0.5, 0.0); // RGB for green
let jitterNoiseSize = 100.0; let jitterNoise = random( floor(uv*jitterNoiseSize)/jitterNoiseSize );
// Transform the value to create a sharper transition let sharp_value = smoothstep(0.2, 0.3, fractPos.y + sin( (jitterNoise)*3.14*2.0)*0.05 ); color = mix(green, brown, sharp_value); // Use the transformed value for blending
let texelNoiseSize = 80.0; let texelnoise = random( floor(uv*texelNoiseSize)/texelNoiseSize ); color -= texelnoise*0.15;
At this point - there is so many cool things we could do with the 2d version alone - we could keep extending the 2d concept:
• develop a full level layout (scroll left and right)
• generate infinite number of levels (since the data is from a procedural function)
• create a game (mario-type retro game) - move along and avoid hitting certain blocks
• add more texture patterns (not just grass bricks - but water, stone)
• also create minecraft creatures (voxel people/animals)
• start developing an 'editor' - so you can 'click' and add/remove blocks
• animated movies/films - move around and it tells a story/adventure
• extend the idea to creating 'data visualization' charts
• animation effects (mix in particles - fire, water, .. voxelated)
• 'distance' - layers - 2d but you can see hills in the background which are 'smaller' blocks - while closer layers use 'bigger' blocks
3D Ray-Tracing (Linear Ray-Marching) - Smooth
We're going to move from the 2d view to a 3d view. We'll render the scene using ray-tracing in the fragment shader. We just need to modify the fragment shader - so each pixel becomes a 'ray' that we fire into the scene. Whatever it hits becomes the color for that pixel. As we're dealing implicit surfaces - we can't do a direct 'ray-geometry' intersection test - instead we'll have to march along the ray until it hits something. This is known as 'ray-marching' - still ray-tracing but the collision detection is done using a ray-marching algorithm.
Sketch to explain the process of ray-tracing using ray-marching - shoot a ray into the scene through the pixel for the color.
We'll start by ray-tracing the smooth surface function - to show the basic setup for the ray-marching algorithm - in the main we construct the ray-origin (ro) and ray-direction (rd). We then call 'ray' - which marches along the ray at a fixed distance until the point goes below the surface (which is a 'hit').
Fixed step ray-marching algorithm - notice the artifacts - the banding and the large number of steps required to get even a reasonably good quality result.
For the example we hard code the 'ray-origin' - the 'ray-direction' is calculated using the 'pixel' (or fragment) information which we can access using the texture coordinates. We do this in the 'main(..)' function. Once we've got the ray-origin and ray-direction - we have everything we need to shoot a ray into the scene - which we do using the 'ray(..)' function - this function returns the 'color' from the intersection (plus any lighting calculations).
// Smooth ground height function fn getGroundHeight(pos: vec3<f32>) -> f32 { var v = 0.2 * sin(pos.x * 0.4) + 0.3 * cos(pos.z * 0.45) + 0.15 * sin(pos.z * 1.7) * cos(pos.x * 0.4); return v * 15.0; // amplify the height of the terrain }
fn ray(ro:vec3<f32>, rd:vec3<f32>) -> vec3<f32> { // background color var color = vec3<f32>( 0.1, 0.1, 0.3 );
let numSteps: i32 = 256; for (var i: i32 = 0; i < numSteps; i++) { // step along the ray ('fixed' distance) let pos = ro + rd * f32(i) * 0.25;
let y = getGroundHeight( pos );
// if the pos step goes below the surface if ( pos.y < y ) { let hitPos = vec3<f32>(pos.x, y, pos.z );
color = vec3<f32>(1.0, 0.0, 0.0);
// Compute terrain normal using small offsets let eps: f32 = 0.1; let normal: vec3<f32> = normalize(vec3<f32>( getGroundHeight(hitPos + vec3<f32>(eps, 0.0, 0.0)) - getGroundHeight(hitPos - vec3<f32>(eps, 0.0, 0.0)), 2.0*eps, getGroundHeight(hitPos + vec3<f32>(0.0, 0.0, eps)) - getGroundHeight(hitPos - vec3<f32>(0.0, 0.0, eps)) ));
let lightDir: vec3<f32> = normalize(vec3<f32>(0.6, 1.0, 0.5));
// Compute Lambertian lighting (dot product of normal and light direction) let diffuse: f32 = 0.2 + abs(dot(normal, lightDir));
color *= diffuse;
break; } } return color; }
@fragment fn main(@location(0) uv: vec2<f32>) -> @location(0) vec4<f32> { // Normalize UV coordinates to range [-1,1] var nuv: vec2<f32> = -1.0 + 2.0 * uv.xy;
// Define ray origin (camera position) let ro: vec3<f32> = vec3<f32>(0.3, 9.0, -5.0);
// Define target position (where the ray should aim) let ctarget: vec3<f32> = vec3<f32>(0.0, 5.0, 0.0);
// Compute forward direction (camera looking at target) let forward: vec3<f32> = normalize(ctarget - ro);
// Define an up vector (for orientation) let up: vec3<f32> = vec3<f32>(0.0, 1.0, 0.0);
// Compute right and adjusted up vectors for a proper camera basis let right: vec3<f32> = normalize(cross(up, forward)); let adjustedUp: vec3<f32> = -cross(forward, right);
// Construct ray direction based on the camera basis let rd: vec3<f32> = normalize(forward + nuv.x * right + nuv.y * adjustedUp);
// Get color from the raymarching function var color = ray(ro, rd);
return vec4<f32>(color, 1.0); }
Linear ray-marking works - but you get 'rings' and the final image isn't very nice - also has visual artifacts - have to use a very high number of small steps to get anything that looks good.
Ray-Marching - for Voxelized Scene
Take our voxelized 2d code from earlier - and we plug it into the 3d ray-marching implementation. We'll still use the linear ray-marching code - so each step along the ray is the same.
This produces a nice 'voxel' scene - instead of the smooth surface - and it's a good start - but as you'll nocie the quality is a bit lacking.
As you can see from the results - it isn't very nice - as a 'fixed' step ray-marching algorithm gives us lots of artifacts unless we go crazy with the number of steps.
Notice the 'rings' and the poor quality of the voxelized ray-marched result - we'll resolve this next by using a non-linear step.
// Smooth ground height function fn getGroundHeight(pos: vec3<f32>) -> f32 { var v = 0.2 * sin(pos.x * 0.4) + 0.3 * cos(pos.z * 0.45) + 0.15 * sin(pos.z * 1.7) * cos(pos.x * 0.4); return v * 15.0; // amplify the height of the terrain }
fn ray(ro:vec3<f32>, rd:vec3<f32>) -> vec3<f32> { // background color var color = vec3<f32>( 0.1, 0.1, 0.3 );
let numSteps: i32 = 256; for (var i: i32 = 0; i < numSteps; i++) { // step along the ray ('fixed' distance) let pos = ro + rd * f32(i) * 0.15;
// voxelate the input - which will correct our 'x' and 'z' input values // so they're on the correct boundaries let sizeVoxels = 1.0; var floorPos = floor( pos * sizeVoxels ) / sizeVoxels; var fractPos = fract( pos * sizeVoxels );
// We have the height using the voxel x-z input locations let y = getGroundHeight( floorPos );
// This little nugget - we want the 'y' values to also lay on the // correct boundary - so we need to 'floor' the y value (if not they'll be offset wrong) floorPos.y = y; floorPos = floor( floorPos * sizeVoxels ) / sizeVoxels;
// if the pos step goes below the surface if ( pos.y < floorPos.y ) { let hitPos = vec3<f32>(pos.x, floorPos.y, pos.z );
color = vec3<f32>(1.0, 0.0, 0.0);
// Compute terrain normal using small offsets let eps: f32 = 0.1; let normal: vec3<f32> = normalize(vec3<f32>( getGroundHeight(hitPos + vec3<f32>(eps, 0.0, 0.0)) - getGroundHeight(hitPos - vec3<f32>(eps, 0.0, 0.0)), 2.0*eps, getGroundHeight(hitPos + vec3<f32>(0.0, 0.0, eps)) - getGroundHeight(hitPos - vec3<f32>(0.0, 0.0, eps)) ));
let lightDir: vec3<f32> = normalize(vec3<f32>(0.6, 1.0, 0.5));
// Compute Lambertian lighting (dot product of normal and light direction) let diffuse: f32 = 0.2 + abs(dot(normal, lightDir));
color *= diffuse;
// edges of the voxel darker so we can see the cubes if ( (fractPos.x < 0.05) || (fractPos.y < 0.05) || (fractPos.z < 0.05) ) { color *= 0.3; } break; }// end hit } return color; }
@fragment fn main(@location(0) uv: vec2<f32>) -> @location(0) vec4<f32> { // Normalize UV coordinates to range [-1,1] var nuv: vec2<f32> = -1.0 + 2.0 * uv.xy;
// Define ray origin (camera position) let ro: vec3<f32> = vec3<f32>(0.3, 9.0, -5.0);
// Define target position (where the ray should aim) let ctarget: vec3<f32> = vec3<f32>(0.0, 5.0, 0.0);
// Compute forward direction (camera looking at target) let forward: vec3<f32> = normalize(ctarget - ro);
// Define an up vector (for orientation) let up: vec3<f32> = vec3<f32>(0.0, 1.0, 0.0);
// Compute right and adjusted up vectors for a proper camera basis let right: vec3<f32> = normalize(cross(up, forward)); let adjustedUp: vec3<f32> = -cross(forward, right);
// Construct ray direction based on the camera basis let rd: vec3<f32> = normalize(forward + nuv.x * right + nuv.y * adjustedUp);
// Get color from the raymarching function var color = ray(ro, rd);
return vec4<f32>(color, 1.0); }
Non-Linear Ray-Marching (Voxelization)
With a tiny modification - one or two lines - we can drastically improve the quality and performance of our ray-marching implementation! We'll scale the step size so it has small steps nearer the origin of the ray - and as it gets further away - the step size will increase.
We swap these couple of lines for the ray-marching loop:
// Ray marching loop for (var i: f32 = 0.0; i < numSteps; i += 0.01) {
// step along the ray ('varying' distance) pos += rd * i * 0.001; // very important - the steps are 'smaller' closer together nearer // the ray origin - to give more detail closer to the screen (viewer).
This produces the following results:
Non-linear step size to improve the quality of the voxels.
This is the full modified code (with the non-linear marching):
// Smooth ground height function fn getGroundHeight(pos: vec3<f32>) -> f32 { var v = 0.2 * sin(pos.x * 0.4) + 0.3 * cos(pos.z * 0.45) + 0.15 * sin(pos.z * 1.7) * cos(pos.x * 0.4); return v * 15.0; // amplify the height of the terrain }
fn ray(ro:vec3<f32>, rd:vec3<f32>) -> vec3<f32> { // background color var color = vec3<f32>( 0.1, 0.1, 0.3 );
let numSteps:f32 = 40; var totalDist:f32 = 0.0; var pos = ro;
// Ray marching loop for (var i: f32 = 0.0; i < numSteps; i += 0.01) {
// step along the ray ('variable' distance) pos += rd * i * 0.001; // very important - as the steps are 'smaller' closer to the // ray origin - to give more detail closer to the viewer.
// voxelate the input - which will correct our 'x' and 'z' input values // so they're on the correct boundaries let sizeVoxels = 1.0; var floorPos = floor( pos * sizeVoxels ) / sizeVoxels; var fractPos = fract( pos * sizeVoxels );
// We have the height using the voxel x-z input locations let y = getGroundHeight( floorPos );
// This little nugget - we want the 'y' values to also lay on the // correct boundary - so we need to 'floor' the y value (if not they'll be offset wrong) floorPos.y = y; floorPos = floor( floorPos * sizeVoxels ) / sizeVoxels;
// if the pos step goes below the surface if ( pos.y < floorPos.y ) { let hitPos = vec3<f32>(pos.x, floorPos.y, pos.z );
color = vec3<f32>(1.0, 0.0, 0.0);
// Compute terrain normal using small offsets let eps: f32 = 15.0; let normal: vec3<f32> = normalize(vec3<f32>( getGroundHeight(floorPos + vec3<f32>(eps, 0.0, -0.1)) - getGroundHeight(floorPos - vec3<f32>(eps, 0.0, 0.0)), 2.0*eps, getGroundHeight(floorPos + vec3<f32>(-0.01, 0.1, eps)) - getGroundHeight(floorPos - vec3<f32>(0.0, 0.1, eps)) ));
let lightDir: vec3<f32> = normalize(vec3<f32>(0.3, 0.8, 0.5));
// Compute Lambertian lighting (dot product of normal and light direction) let diffuse: f32 = 0.2 + abs(dot(normal, lightDir))*0.8;
color *= diffuse;
// edges of the voxel darker so we can see the cubes if ( (fractPos.x < 0.06) || (fractPos.y < 0.06) || (fractPos.z < 0.06) ) { color *= 0.3; } break; }// end hit } return color; }
@fragment fn main(@location(0) uv: vec2<f32>) -> @location(0) vec4<f32> { // Normalize UV coordinates to range [-1,1] var nuv: vec2<f32> = -1.0 + 2.0 * uv.xy;
// Define ray origin (camera position) let ro: vec3<f32> = vec3<f32>(1.3, 16.0, 3.0);
// Define target position (where the ray should aim) let ctarget: vec3<f32> = vec3<f32>(0.0, 14.0, 0.0);
// Compute forward direction (camera looking at target) let forward: vec3<f32> = normalize(ctarget - ro);
// Define an up vector (for orientation) let up: vec3<f32> = vec3<f32>(0.0, 1.0, 0.0);
// Compute right and adjusted up vectors for a proper camera basis let right: vec3<f32> = normalize(cross(up, forward)); let adjustedUp: vec3<f32> = -cross(forward, right);
// Construct ray direction based on the camera basis let rd: vec3<f32> = normalize(forward + nuv.x * right + nuv.y * adjustedUp);
// Get color from the raymarching function var color = ray(ro, rd);
return vec4<f32>(color, 1.0); }
Ray-Tracing - Animate Camera - Mix in Colors
We take things a bit further by mixing in some colors - brown is the bottom of each voxel and the top is green. We use the 'fract' function (y-direction) - 0.0 is the bottom and 1.0 is the top.
We can also mix in a bit of randomness instead of a 'flat' color - it gives it that minecraft pixelated feel.
Blend between brown and green - with a bit of randomness for the color - so it looks a bit more pixelated retro feel.
@group(0) @binding(2) var <uniform> mytimer : f32;
// If the ray hits the terrain if ( hitPos.y < groundHeight ) {
var blendFactor: f32 = fracPos.y; // Value from 0 to 1 var green: vec3<f32> = vec3<f32>(0.3, 0.6, 0.2); var brown: vec3<f32> = vec3<f32>(0.5, 0.3, 0.1);
var baseColor: vec3<f32> = mix(brown, green, pow(blendFactor, 2 ) );
//baseColor *= texelColor; // give each a slight variation baseColor *= texelNoise; // add pixelated look (instead of smooth color)
// edges of the voxel darker so we can see the cubes if ( (fracPos.x < 0.1) || (fracPos.y < 0.1) || (fracPos.z < 0.1) ) { baseColor *= 0.5; }
color = baseColor;
// Compute terrain normal using small offsets let eps: f32 = 0.1; let normal: vec3<f32> = normalize(vec3<f32>( getGroundHeight(hitPos + vec3<f32>(eps, 0.0, 0.0)) - getGroundHeight(hitPos - vec3<f32>(eps, 0.0, 0.0)), 2.0*eps, getGroundHeight(hitPos + vec3<f32>(0.0, 0.0, eps)) - getGroundHeight(hitPos - vec3<f32>(0.0, 0.0, eps)) ));
// Compute Lambertian lighting (dot product of normal and light direction) let diffuse: f32 = 0.2 + abs(dot(normal, lightDir));
color *= diffuse; break; } } return color; }
@fragment fn main(@location(0) uv: vec2<f32>) -> @location(0) vec4<f32> { // Normalize UV coordinates to range [-1,1] let nuv: vec2<f32> = -1.0 + 2.0 * uv.xy;
// Define ray origin (camera position) let ro: vec3<f32> = vec3<f32>(0.3, 1.5, 2.0);
let tx = cos(mytimer); let tz = sin(mytimer);
// Define target position (where the ray should aim) let ctarget: vec3<f32> = vec3<f32>(tx, 0.1, tz);
// Compute forward direction (camera looking at target) let forward: vec3<f32> = normalize(ctarget - ro);
// Define an up vector (for orientation) let up: vec3<f32> = vec3<f32>(0.0, 1.0, 0.0);
// Compute right and adjusted up vectors for a proper camera basis let right: vec3<f32> = normalize(cross(up, forward)); let adjustedUp: vec3<f32> = cross(forward, right);
// Construct ray direction based on the camera basis let rd: vec3<f32> = normalize(forward + nuv.x * right + nuv.y * adjustedUp);
// Get color from the raymarching function var color = ray(ro, rd);
return vec4<f32>(color, 1.0); }
Animating the Terrain
A nice little thing you can do - is modulate the height of the terrain data (terrain height function) by sine wave function - so you can watch the voxel-terrain change in real-time (grow and shrink).
fn getGroundHeight(pos: vec3<f32>) -> f32 { var v = 0.2 * sin(pos.x * 1.8) + 0.5 * cos(pos.z * 2.25) + 0.15 * sin(pos.z * 1.7) * cos(pos.x * 0.4); return v * abs( sin(mytimer) ); // Animates the height of the terrain from 0 to 100% }
Smooth Random Noise
Instead of using trignometric functions for the height data - we can use smooth random noise - which produces more organic and natural looking height information.
fn randomsmooth( st:vec2<f32> ) -> f32 { var i = floor( st * 3.0 ); // uv - 0, 1, 2, 3, var f = fract( st * 3.0 ); // uv - 0-1, 0-1, 0-1, 0-1
// Four corners in 2D of a tile var a = random(i); var b = random(i + vec2<f32>(1.0, 0.0)); var c = random(i + vec2<f32>(0.0, 1.0)); var d = random(i + vec2<f32>(1.0, 1.0));
// Ease-in followed by an ease-out (tweening) for f // f = 0.5 * (1.0 - cos( 3.14 * f ) ); // version without cos/sin // f = 3*f*f - 2*f*f*f;
f = 3*f*f - 2*f*f*f;
// bilinear interpolation to combine the values sampled from the // four corners (a,b,c,d), resulting in a smoothly interpolated value.
// Interpolate Along One Axis - interpolate between `a` and `b` using the fractional coordinate `f.x`, // then interpolate between `c` and `d` using the same `f.x`. // This gives two intermediate values, say `e` and `f`.
// Interpolate Along the Other Axis - linearly interpolate between `e` and `f` // using the fractional coordinate `f.y`. // Final interpolation gives a moothly interpolated value across the square
var x1 = mix( a, b, f.x ); var x2 = mix( c, d, f.x );
var y1 = mix( x1, x2, f.y );
return y1; }
Clouds and Ambient Occlusion (Complete Demo)
We add a few voxel clouds in the sky - some ambient occlusion for the lighting - so things look a little nice - we also animate the camera - fly around like a bird - see the minecraft-like world.
We two ray-marching functions - one for the 'cloud' and another for the 'terrain' - so you can debug and test them seperately (easy to remove/add the cloud/terrain).
Add clouds and ambient occluson - we use a gradient background, smooth noise for the height and more.
fn background(d: vec3<f32>, sunDir: vec3<f32>) -> vec3<f32> { // Sun intensity calculation let sunIntensity = 1.0; let sunDot = max(0.0, dot(d, sunDir));
// Direct sun intensity based on the dot product, with a smooth curve applied let sun = (pow(sunDot, 48.0) + pow(sunDot, 4.0) * 0.25) * sunIntensity * vec3<f32>(1.0, 0.85, 0.5);
// Sky color blending based on vertical position (d.y) let sky = mix(vec3<f32>(0.6, 0.65, 0.8), vec3<f32>(0.15, 0.25, 0.65), d.y) * 1.15;
// Return the combined sun and sky colors return sun + sky; }
fn randomsmooth( st:vec2<f32> ) -> f32 { var i = floor( st * 3.0 ); // uv - 0, 1, 2, 3, var f = fract( st * 3.0 ); // uv - 0-1, 0-1, 0-1, 0-1
// Four corners in 2D of a tile var a = random(i); var b = random(i + vec2<f32>(1.0, 0.0)); var c = random(i + vec2<f32>(0.0, 1.0)); var d = random(i + vec2<f32>(1.0, 1.0));
// Ease-in followed by an ease-out (tweening) for f // f = 0.5 * (1.0 - cos( 3.14 * f ) ); // version without cos/sin // f = 3*f*f - 2*f*f*f;
f = 3*f*f - 2*f*f*f;
// bilinear interpolation to combine the values sampled from the // four corners (a,b,c,d), resulting in a smoothly interpolated value.
// Interpolate Along One Axis - interpolate between `a` and `b` using the fractional coordinate `f.x`, // then interpolate between `c` and `d` using the same `f.x`. // This gives two intermediate values, say `e` and `f`.
// Interpolate Along the Other Axis - linearly interpolate between `e` and `f` // using the fractional coordinate `f.y`. // Final interpolation gives a moothly interpolated value across the square
var x1 = mix( a, b, f.x ); var x2 = mix( c, d, f.x );
var y1 = mix( x1, x2, f.y );
return y1; }
fn noise(p: vec3<f32>) -> f32 { // simple trignometric scene - repeating lumps //return abs(sin(p.x*2.0)*cos(p.z*3.0)); // more random scene - smooth random return randomsmooth( p.xz ); }
fn traceVoxel(pin: vec3<f32>, d: vec3<f32>, distin: f32) -> TraceResult { var p = pin; var dist = distin; var r: TraceResult;
// Initializing the TraceResult with default values r.hit = false; r.n = -d; r.r = dist;
// Calculate the inverse of the direction vector and its sign let id = vec3<f32>(1.0) / d; let sd = sign(d); let nd = max(-sd, vec3<f32>(0.0));
// Adjust the starting point to the nearest voxel boundary var vp = floor(p) - nd * vec3<f32>( f32(floor(p.x) == p.x), f32(floor(p.y) == p.y), f32(floor(p.z) == p.z) );
// Trace through the voxel grid (maximum of 256 steps) for (var i: i32 = 0; i < 256; i = i + 1) {
// If we hit a voxel, store the result and return if (voxel(vp)) { r.vp = vp; r.p = p; r.r = dist; r.hit = true; return r; // Return the result if a voxel is hit }
// Calculate the next voxel boundary in each axis let n = vec3<f32>( mix(floor(p.x + 1.0), ceil(p.x - 1.0), nd.x), mix(floor(p.y + 1.0), ceil(p.y - 1.0), nd.y), mix(floor(p.z + 1.0), ceil(p.z - 1.0), nd.z) );
// Calculate the distance to the next voxel boundary in each axis let ls = (n - p) * id; let l = min(min(ls.x, ls.y), ls.z);
// Determine which axis will hit the next boundary first let a = vec3<f32>( f32(l == ls.x), f32(l == ls.y), f32(l == ls.z) );
// Update the position by moving to the next voxel boundary p = vec3<f32>( mix(p.x + d.x * l, n.x, a.x), mix(p.y + d.y * l, n.y, a.y), mix(p.z + d.z * l, n.z, a.z) );
// Update the voxel position and normal vector vp += sd * a; r.n = -sd * a;
// Decrease the remaining distance to the hit voxel boundary dist -= l; }
// Return the result after 256 steps if no hit occurred return r; }
fn traceClouds(pin: vec3<f32>, d: vec3<f32>, distin: f32, cloudsOffset: vec3<f32>) -> TraceResult { var p = pin; var dist = distin; var result: TraceResult;
// Initialize the TraceResult with default values result.hit = false; result.n = -d; result.r = dist;
// Offset the starting point by the clouds offset p += cloudsOffset;
// Check for initial cloud intersections in the Y direction if (p.y < cloudHeight && d.y > 0.0) { let cloudIntersection = (cloudHeight - p.y) / d.y; p += d * cloudIntersection; result.n = vec3<f32>(0.0, -1.0, 0.0); dist -= cloudIntersection; } else if (p.y > cloudHeight + 1.0 && d.y < 0.0) { let cloudIntersection = (cloudHeight + 1.0 - p.y) / d.y; p += d * cloudIntersection; result.n = vec3<f32>(0.0, 1.0, 0.0); dist -= cloudIntersection; }
// Prepare for voxel traversal let invDirection = vec3<f32>(1.0) / d; let directionSign = sign(d); let negDirection = max(-directionSign, vec3<f32>(0.0));
// Start from the adjusted position and compute the first voxel boundary var voxelPosition = floor(p) - negDirection * vec3<f32>( f32(floor(p.x) == p.x), f32(floor(p.y) == p.y), f32(floor(p.z) == p.z) );
// Traverse through the voxel grid (up to 16 steps) for (var i: i32 = 0; i < 16; i = i + 1) { // Break the loop if we have gone too far or moved past the clouds if (dist <= 0.0 || (p.y < cloudHeight && d.y < 0.0) || (p.y > cloudHeight + 1.0 && d.y > 0.0)) { break; }
// If a cloud voxel is hit, store the result and return immediately if (cloudVoxel(voxelPosition)) { result.vp = voxelPosition; result.p = p - cloudsOffset; result.r = dist; result.hit = true; return result; }
// Calculate the next boundary in each axis (X, Y, Z) let nextBoundary = vec3<f32>( mix(floor(p.x + 1.0), ceil(p.x - 1.0), negDirection.x), mix(floor(p.y + 1.0), ceil(p.y - 1.0), negDirection.y), mix(floor(p.z + 1.0), ceil(p.z - 1.0), negDirection.z) );
// Calculate the distance to each voxel boundary let stepLengths = (nextBoundary - p) * invDirection; let minStep = min(min(stepLengths.x, stepLengths.y), stepLengths.z);
// Determine which axis hits the voxel boundary first let axisHit = vec3<f32>( f32(minStep == stepLengths.x), f32(minStep == stepLengths.y), f32(minStep == stepLengths.z) );
// Move to the next voxel boundary p = vec3<f32>( mix(p.x + d.x * minStep, nextBoundary.x, axisHit.x), mix(p.y + d.y * minStep, nextBoundary.y, axisHit.y), mix(p.z + d.z * minStep, nextBoundary.z, axisHit.z) );
// Update the voxel position and normal vector voxelPosition += directionSign * axisHit; result.n = -directionSign * axisHit;
// Decrease the remaining distance to the next voxel boundary dist -= minStep; }
// Return the result after the loop finishes if no cloud voxel is hit return result; }
Explanation for the Ambient Occlusion Function
The approximate ambient occlusion function calculates an ambient occlusion (AO) factor for a fragment based on its position within a voxel grid. AO is used in shading to approximate how much ambient light reaches a surface, where nearby geometry can block light and create soft shadowing effects. This function works by sampling neighboring voxels and adjusting the AO factor accordingly.
1. Initial Setup and Neighbor Sampling
The function begins by defining constants:
s = 0.5
(a scaling factor for occlusion strength) and
i = 1.0 - s
(ensuring a balanced occlusion effect). The base sampling point
b
is computed by shifting the voxel position `vp` along the normal
n
, helping to determine which voxels contribute to occlusion. Two perpendicular vectors,
e0
and
e1
, are derived from
n
by swapping components, allowing for AO sampling in different directions.
2. Checking Nearby Voxels
The function evaluates the occupancy of adjacent voxels along `e0` and `e1` in both positive and negative directions. If a neighboring voxel is solid (determined by the
voxel()
function), the AO factor `a` is adjusted using a weighted combination of
i
,
s
, and a fractional dot product of the voxel's offset with the fragment position
p
. This ensures that AO smoothly varies depending on the fragment’s sub-voxel position.
3. Sampling Corner Voxels
To refine the AO effect, the function also checks diagonal neighbors (
b + e0 + e1
,
b + e0 - e1
, etc.), considering two neighboring voxels at once. If these voxels are occupied,
a
is further reduced based on the minimum occlusion contribution of the diagonal offsets. The
length(fract(...))
function ensures a smooth transition in AO intensity, preventing hard edges.
4. Returning the Final AO Value
After considering all voxel samples, the function returns
a
, which represents the final ambient occlusion factor. Values close to
1.0
mean little to no occlusion, while lower values indicate strong occlusion due to nearby geometry.
It does a good job in simulating a basic ambient occlusion for the voxel-scen - while helping to take into account the depth perception factors to keep the shadking looking good.
fn sampleAO(vp: vec3<f32>, p: vec3<f32>, n: vec3<f32>) -> f32 { let s = 0.5; let i = 1.0 - s; let b = vp + n; let e0 = vec3<f32>(n.z, n.x, n.y); let e1 = vec3<f32>(n.y, n.z, n.x); var a = 1.0;
if (voxel(b + e0)) { a *= i + s * pow(fract(dot(-e0, p)), 2.0); } if (voxel(b - e0)) { a *= i + s * pow(fract(dot(e0, p)), 2.0); } if (voxel(b + e1)) { a *= i + s * pow(fract(dot(-e1, p)), 2.0); } if (voxel(b - e1)) { a *= i + s * pow(fract(dot(e1, p)), 2.0); }
if (voxel(b + e0 + e1)) { a = min(a, i + s * pow(min(1.0, length(fract((-e0 - e1) * p))), 2.0)); } if (voxel(b + e0 - e1)) { a = min(a, i + s * pow(min(1.0, length(fract((-e0 + e1) * p))), 2.0)); } if (voxel(b - e0 + e1)) { a = min(a, i + s * pow(min(1.0, length(fract((e0 - e1) * p))), 2.0)); } if (voxel(b - e0 - e1)) { a = min(a, i + s * pow(min(1.0, length(fract((e0 + e1) * p))), 2.0)); }
return a; }
fn ray(p: vec3<f32>, d: vec3<f32>, cloudsOffset: vec3<f32>, sunDir: vec3<f32> ) -> vec3<f32> { let grassColor = vec3<f32>(0.63, 1.0, 0.31); let dirtColor = vec3<f32>(0.78, 0.56, 0.4); let ambientColor = vec3<f32>(0.5, 0.5, 0.5); let sunColor = vec3<f32>(0.5, 0.5, 0.5); let viewDistance = 85.0;
// did it hit the terrain? var r = traceVoxel(p, d, viewDistance); // did it hit a cloud? var rc = traceClouds(p, d, viewDistance, cloudsOffset); if (rc.hit && (!r.hit || rc.r > r.r)) { r = rc; }
if (r.hit) { var sunFactor = max(-0.1, dot(r.n, sunDir)); let dd = length(r.p - p); let fogFactor = min( 1.0, pow(dd / viewDistance, 2.0) ); let fogColor = background(d, sunDir);
if (r.vp.y == cloudHeight) { let c = 1.9 * ambientColor + sunFactor * sunColor; return mix(c, fogColor, fogFactor * 0.6 + 0.4); }
if (sunFactor > 0.0) { let sd = (cloudHeight - r.p.y) / sunDir.y; if (traceVoxel(r.p, sunDir, sd).hit) { sunFactor = 0.0; } else if (traceClouds(r.p, sunDir, sd + 2.0, cloudsOffset).hit) { sunFactor *= 0.3; }
}
let ambientFactor = sampleAO(r.vp, r.p, r.n); let texelNoise = random( vec2( floor( (r.p.xz + r.p.xy + r.p.zy)*10.0 )*0.1 ) );
let cloudsOffset = cloudMovement * mytimer * 20.0;
let sxz = cos(vec2<f32>(0.0, -PI * 0.5) - mytimer * sunMovement); let sunDir = normalize(vec3<f32>(sxz.x, 1.1, sxz.y));
var eye = cameraPosition + eyeMovement * mytimer * 12.0;
let ry = -2.0; let rx = 2.8 + 0.5*sin(mytimer*2.0);
let cs = cos(vec4<f32>(ry, rx, ry - PI * 0.5, rx - PI * 0.5)); let forward = -vec3<f32>(cs.x * cs.y, cs.w, cs.z * cs.y); let up = vec3<f32>(cs.x * cs.w, -cs.y, cs.z * cs.w); let left = cross(up, forward);
let uv = fov * nuv; var dir = normalize(forward + uv.y * up + uv.x * left);
var color = ray(eye, dir, cloudsOffset, sunDir);
// Final color let finalColor:vec3<f32> = color;
return vec4<f32>(finalColor, 1.0); }
The code and interactive versions for all the examples are available at the end on the resource and links. You can open and run the examples - and try modifying and experimenting with them.
Things to Try
Only just the beginning of what's possible using code - what you can create and imagine, for example:
• Contiue to add more 'brick' types (different textures/designs)
• Add in voxel people/animals/planes
• Add in a 'road' that goes through the terrain (not just hills) - but also has a road going through it - maybe with a car driving along?
Related article on working with 3d-point data - using voxels to visualize the information
• LiDAR Tutorial (point data file format) - explain how to load the data from the .ldr file format and render the scene (also take it a bit further by explain how to 'tesselate' the points - convert the cubes into a 3d mesh - using the marching cube algorithm).
