Architecture
How Rockstar Shaders works
Rockstar Shaders is two engines sharing one Apple GPU. Minecraft's own Vulkan renderer, running through MoltenVK on top of Metal, draws the frame, and a native Metal library beside it traces the rays. Four figures describe the whole renderer: one frame, how far you can see, where the distant terrain comes from, and the water.
Each figure comes with what you are looking at, what every part of it does, and why it matters, both for the picture and for how your Mac runs it. Click or tap a figure to open it full size. The settings themselves are explained in help.
1. One frame
Every frame, the chunk sections around you become a Metal acceleration structure, three ray tracing kernels run against it, and their results feed the lighting, atmosphere and water passes of Minecraft's own renderer.
What you are looking at
The frame reads left to right. The top band is Minecraft's Vulkan renderer, running through MoltenVK. The bottom band is the Metal library that ships inside the jar, libvrt.dylib and vrt.metallib. The tall box on the left is what Minecraft hands over each frame, and both bands start from it. The vertical arrows are where the two engines meet: traced light going up into the lighting and the fog, and the water pass trading ray requests and hits with the reflection kernel. The two dashed boxes are not passes of their own: the cutout test runs inside the ray traversal, and MetalFX is an experimental upscaler.
What each part does
- Minecraft 26.3
- The source of everything: the chunk sections around you, the entities and the camera.
- Shadow maps
- Four cascades of sun shadow with PCSS soft edges, plus a height map of the far field, so distant mountains still cast shadow past the last cascade.
- G-buffer
- Terrain, entities and the far field are drawn once, with their material stored beside the color: LabPBR normals, AO, parallax, smoothness, F0 and metals, porosity, subsurface and emission. Every later pass reads it instead of drawing the world again.
- Screen space
- SSAO, contact shadows and screen-space reflections, worked out from what is already on screen. They catch the fine detail close to the camera.
- Lighting
- Deferred physically based shading. Sun, sky and block light are combined with the traced shadow, sky visibility and bounce light once those are denoised.
- Atmosphere
- The physically based sky, the clouds, volumetric fog and light shafts. The fog kernel tells it where the sun and the sky can really be seen from inside the fog.
- Water
- A forward pass: the wave spectrum, the ripple simulation in figure 4, caustics, and the resolve of the traced reflections.
- Post
- Temporal anti-aliasing, auto exposure, bloom and AgX tone mapping, and then the display.
- BLAS
- A bottom-level acceleration structure for each chunk section, compacted so it takes less memory.
- TLAS
- The top level, built every frame from the sections, the player and the entities, so the rays see the world as it is on this frame.
- Cutout test
- An intersection function for alpha-tested blocks: leaves, plants and glass. A ray that touches a leaf checks its texture, so light passes through the gaps and stops at the leaf.
vrt_shadow_kernel- Sun shadow, sky visibility and one bounce of light.
vrt_fog_kernel- Sun and sky visibility inside the fog volume.
vrt_reflect_kernel- Water reflections, with the player and entities in them. The water pass sends the ray requests and reads back the hits.
- MetalFX
- Temporal upscaling. It is experimental; Render scale is the supported way to trade pixels for speed.
Why it matters
For the picture. Shadows, sky light and bounce light come from rays that hit the real blocks around you, not from a guess based on what the screen shows. A tree shades the ground because a ray hit a leaf, and light carries the color of the surfaces it bounces off. Reflections in the water show what is behind you or off the edge of the screen, where a screen-space trace has nothing to show. And because the fog knows where the sky is, light shafts are cut by whatever really blocks the sun, and an enclosed room does not fill with a sky-lit haze.
For your Mac. On a Mac, Vulkan runs through MoltenVK, which offers no Vulkan ray query extension, so the rays are traced in Metal, where Apple's ray tracing is, and the two engines are joined through VK_EXT_metal_objects. They share the frame's textures and buffers directly in the Mac's unified memory and synchronize on one shared timeline semaphore. On M3 and later the intersections run on the GPU's ray tracing hardware; M1 and M2 run the same kernels with software traversal. On the M4 Max the engine is measured on, switching the traces off made the frame slower, not faster: every fallback costs more than the trace it replaces.
2. Seeing to the horizon
Past Minecraft's render distance, the far field takes over: simplified terrain in rings, each sampled at twice the step of the one inside it, so distant mountains cost a fraction of what full chunks would.
What you are looking at
The left half is a plan view of the world around you, seen from above and drawn to scale, with Minecraft's render distance at 12 chunks and the horizon at 128. The white disc in the middle is R, the render distance. The squares around it are the far field, lighter as they get coarser, and the numbers 1, 2, 4 and 8 are each ring's sampling step in blocks. The round edge is the horizon. The chart on the right plots the same steps against distance from the camera, out to 2,048 blocks.
What each part does
- R, render distance
- Minecraft's own chunks at full geometry. Everything in figure 1 happens here: ray traced, shaded and reflected.
- Far field
- Simplified terrain beyond R, meshed in regions of 8 by 8 chunks. It is sampled every block just outside R, every 2 blocks from 300 blocks out, every 4 from 600 and every 8 from 1,200. Steep regions are drawn one step finer, so mountains keep their shape.
- Horizon
- Horizon distance sets how far the far field reaches: 32 to 128 chunks, 64 by default, which is 1,024 blocks.
- Seam
- Where near terrain hands over to far terrain, the edge follows vanilla's round chunk boundary, so the two meet without a square border.
Why it matters
For the picture. The far field is drawn into the same G-buffer as the terrain you walk on, so it takes the same lighting, fog, clouds and anti-aliasing. Distant mountains are lit by the same sun and fade into the same air as the hill in front of you, instead of standing behind it like a painted backdrop.
For your Mac. Pushing Minecraft's own render distance that far would mean building and meshing every block out to the horizon and keeping all of it in memory. Here each ring covers four times the ground of the ring inside it at a quarter of the density, so every ring costs about the same, and the full-detail, ray traced world stays the size of the part you can reach. One mesh for each region of 64 chunks keeps the number of draws small too.
3. Where far terrain comes from
The far field is built in the background. Terrain is summarized column by column and meshed on worker threads, then drawn into the same G-buffer with its own shadow height map, so it fills in around you without stalling the game.
What you are looking at
Three lanes, read left to right: what Minecraft provides, the work done on background threads, and the render thread and GPU. The arrows are the terrain moving from one step to the next. The one dashed box, Generate horizon, is the part you can switch off.
What each part does
- World chunks
- The chunks you have seen, kept after Minecraft unloads them, and in singleplayer the saved world read from disk. On a server, everywhere you have been stays on the horizon.
- Generate horizon
- Singleplayer only, on by default. It generates chunks the world has never had, in the background, and saves them into your world, about 24 KB a chunk. Turn it off on the Performance page before opening a world you want to keep untouched.
- LOD store
- Each chunk is summarized column by column instead of kept block by block, which is what makes a horizon up to 2,048 blocks away affordable to keep.
- Generator estimate
- In singleplayer, a column that has never been generated gets its height and biome sampled from the world generator, so the horizon has the right shape before the real chunk exists.
- Mesher
- One mesh per region of 8 by 8 chunks, at the sampling step its distance calls for in figure 2.
- GPU upload
- Finished meshes go to the GPU as they arrive.
- Far-field draw
- The meshes are drawn into the G-buffer from figure 1, where the lighting, fog and clouds treat them like any other terrain.
- Far-field shadow
- The column heights also build a height map 128 by 128 chunks around the camera. The lighting and the fog read it, so far mountains cast shadows past the reach of the shadow cascades.
Why it matters
For the picture. The horizon is the world you are actually in: the terrain you flew over, the saved world on disk, and in singleplayer, ground estimated from the same generator that will build it. Because the far field has its own shadow map, a ridge a long way off can still throw the valley in front of it into shadow at sunset.
For your Mac. Reading the world from disk, summarizing columns, sampling the generator and meshing all happen on worker threads, and the render thread only uploads what is finished. The far field fills in around you as you move, without stalling the game.
4. Water that reacts
Water is a real-time simulation. A 64 by 64 block height field follows the camera at 16 cells per block, stepped at a fixed 60 Hz. Anything that enters the water makes a splash, boats leave a wake, rain rings the surface and falling water stirs the pool below.
What you are looking at
On the left, the ripple field seen from above: a square of water 64 blocks on a side, centered on the camera and moving with it, divided into 1,024 cells a side, 16 to each block. The numbered marks are the five things that shape it. On the right is the same field as a pipeline: the sources and the mask go in, the height field is simulated, and three things read the result.
What each part does
- 1. Splash
- Anything that enters the water, you included, starts a ring that spreads out from where it landed.
- 2. Boat wake
- Boats and other moving bodies stir the field along their path, so a wake opens behind them.
- 3. Rain rings
- Each raindrop that lands rings the surface.
- 4. Falling water
- Where a waterfall lands, it keeps stirring the pool below.
- 5. Mask
- Where the water is and how deep, in 1-block cells, rebuilt every 20 ticks. Waves stop at the shore and come back off walls instead of running onto land.
- Height field
- 1,024 by 1,024 cells, or 512 by 512 (a 32-block field) on Low and Medium, simulated on the GPU in fixed 1/60 s sub-steps. Waves spread across it and fade.
- Water surface
- Reads the field for its normals, which decide how the surface catches the light and what it reflects.
- Caustics
- The moving light on the floor below, from the same field.
- Foam
- Built up and kept over time.
- Sleep
- Idle water stops simulating after 18 seconds with nothing moving.
Why it matters
For the picture. The ripples are physics, not an animated texture. A ring spreads, meets the edge of a pool and comes back; a wake opens behind a boat; rain on a still bay rings where every drop lands. The surface, the caustics and the foam all read the same field, so the light moving on the floor of a pool moves with the ripple above it.
For your Mac. The field is a fixed size around the camera, so it costs the same on a pond as on an ocean. The fixed 60 Hz step keeps the waves moving at the same speed whatever your frame rate. And once the water has been still for 18 seconds the simulation sleeps, and costs nothing until something disturbs it again.
Also in the engine
LabPBR materials
Resource packs with LabPBR 1.3 normal and specular maps give blocks, items, block entities and mobs real surface detail. The G-buffer keeps what the maps describe: normals, material AO, height for relief, smoothness, F0 and the metals, porosity, subsurface and emission, and the lighting, the reflections and the traced resolve all read it. Packs without the maps render as they did before.
Sharp far from the center
A GPU works in 32-bit floats, which lose precision far from zero, so a long way from the world's center the textures used to break into streaks. Every position is now measured from a local origin on a 4,096-block lattice instead of from the center of the world. The origin moves as you travel, and the waves, clouds and noise carry its exact offset, so nothing jumps when it does.
Render scale on Retina
The world renders at 75% of the window by default and is upscaled under sharp menus, because that one setting is worth more than every quality knob together. Target FPS, 60 by default, steers it: while frames miss the target the scale steps down, and it steps back up when there is room, never above your Render scale. On a 2x Retina display it may go down to one world pixel per screen point, a scale of 0.5; on a 1x display it leaves the scale where you set it.
See where the time goes
Turn on Show pass timings in the settings and every Rockstar Shaders pass is listed in GPU milliseconds, live, so you can see what each change buys on your own Mac. A screenshot of it is the most useful thing in a performance report.
See it on your Mac
Version 1.0.0 is free for Minecraft 26.3 on Apple Silicon. The full stage table is on GitHub, and every setting is explained in help.
Download free (1.0.0)
Technical details on GitHub