Halcyon

Requirements

• Iris (or a fork such as Oculus) on Minecraft 1.17 or newer. The pack is written in GLSL 330 and targets current Iris releases on 1.20–1.21.x.
• Any GPU with OpenGL 3.3 support.
• Voxy (optional, 0.2.4 or newer) for long-distance LOD terrain. Detected automatically; nothing to configure.
• OptiFine is not a target and is untested.

Installation

1. Copy the whole Shader_Halcyon folder (or a zip of it — shaders/ must be at the top level) into .minecraft/shaderpacks/.
2. In game: Options → Video Settings → Shader Packs, select it and press Apply.
3. Pick a preset under Shader Pack Settings (Potato / Low / Medium / High / Ultra). Medium is the default.

What it looks like

• Sky – A fully procedural gradient replaces the vanilla sky dome: deep blue zenith, pale hazy horizon, orange-to-violet sunsets that glow brightest towards the sun, and dark blue nights. The vanilla sun, moon and stars are kept and layered on top.
• Lighting – Warm sunlight, cool sky-blue ambient light in the shade, dim blue moonlight and orange torch light, all computed in linear HDR and tonemapped with an ACES curve. Vanilla smooth-lighting ambient occlusion is preserved.
• Shadows – Real-time sun and moon shadows with a distorted shadow map (sharp near the player, coarser far away). Edges are softened with up to eight rotated samples for a wide, smooth penumbra. Shadows are coloured: stained glass tints the light that passes through it, and water tints it blue and focuses it into moving caustics on the sea floor. The sun path is tilted 30° so shadows always fall at an angle.
• Fog – Distant terrain fades into the exact colour of the sky behind it, so the edge of the render distance disappears instead of ending in a wall. Fog thickens in rain, and has its own behaviour underwater, in lava and in powder snow.
• Water – The surface actually moves: a rolling swell displaces the water and the same waves drive its shading, with fine ripples on top. Shallow water is clear and turquoise, deep water turns dark and opaque, and foam gathers along the shoreline and breathes with the swell. It reflects the sky by fresnel (stronger at shallow angles), the aurora at night, and a mirror image of the sun or moon — a bright core inside a soft streak that the waves break up. Submerged, the view wobbles slightly.
• Light shafts – Rays fan out around the sun and moon when terrain, trees or clouds partly cover them.
• Aurora – Bright green-to-violet curtains of light sweep and pulse across clear night skies, and are mirrored in water. Strength is adjustable.
• Handheld light – Holding a torch, lantern or any other light source lights up your surroundings.
• Foliage – Grass, flowers, crops and leaves sway in the wind (more in rain, not at all indoors), and leaves glow when the sun is behind them.
• Glowing blocks – Lava, glowstone, sea lanterns, froglights, shroomlights, fire and a few others emit their own light and feed the bloom.
• Clouds – Vanilla clouds, relit by the pack's sun and sky colours and faded into the horizon.
• Post-processing – Soft bloom, filmic tonemapping, a mild saturation boost, an optional vignette, and dithering to prevent banding in the sky.
• The End – A fully procedural sky replaces the vanilla static at every preset: a violet void, purple and teal nebula clouds, twinkling stars, and a black eclipse ringed with light. Low presets draw a simple nebula, Medium and High a noise-based one, Ultra a warped, more detailed one with a second star field. The eclipse is the End's light source — terrain is lit from its direction in cold violet, water mirrors the whole sky, and distance fades into a dark purple haze.
• The Nether – Lit from its biome fog colour, with thick fog.
• Voxy LODs – Distant LOD terrain is shaded with the same sunlight, ambient light, fog and water reflections as regular chunks. Regular chunks no longer fade out at the vanilla render distance; fog is stretched over the whole LOD distance and only the far edge of the LODs melts into the sky.

Why it is fast

• Forward shaded. Every surface is lit once, when it is drawn. There is no G-buffer and no deferred lighting; the only full-screen passes are the sky fill and the final pass.
• One render target. The whole scene lives in a single compact HDR buffer (R11F_G11F_B10F) — less video memory and bandwidth than a typical multi-buffer pack.
• Cheap shadows. A 1536² shadow map by default, sampled with 1, 4 or 8 hardware-filtered taps. Shadow coordinates are computed per vertex, the lookup is skipped for surfaces facing away from the light or beyond shadow distance, and shadow geometry is culled to the shadow distance. Coloured shadows add one extra depth sample, plus one colour sample only where light actually passed through something translucent; with them off, translucent blocks are not drawn into the shadow map at all.
• No shadow pass in the Nether or the End, where nothing casts sun shadows anyway.
• Bloom without blur passes. It reuses the scene buffer's mip chain instead of running separate downsample and blur programs.
• Analytic effects. The sky, aurora, End nebula, caustics, water waves, foam and water reflections are pure maths — no noise textures, no ray marching, no screen-space reflections. Water depth costs a single depth lookup, and the caustics are computed in the shadow pass, so lit surfaces pay nothing extra for them.
• Bounded light shafts. 10 depth samples by default, and only for pixels near a sun or moon that is actually on screen.
• LODs stay cheap. Voxy terrain skips the shadow map entirely and uses skylight instead.
• Work moved to the vertex shader. Light colours, shadow positions, wind and the water swell are all per vertex.
• Same pipeline at every preset. Ultra raises shadow resolution, shadow distance and sample counts, but adds no passes and no buffers.

Settings

Menu	Option	Default	Notes
Lighting	Shadows	On	Biggest performance cost. Off also disables the shadow pass entirely.
Lighting	Shadow Softening	Soft (4)	1, 4 or 8 shadow samples.
Lighting	Coloured Shadows	On	Tinted light through stained glass, caustics under water.
Lighting	Shadow Resolution	1536	1024–4096.
Lighting	Shadow Distance	112	64–192 blocks.
Lighting	Sun Angle	-30°	Tilt of the sun's path.
Lighting	Torch Light Strength	1.0
Lighting	Cave Brightness	0.012	Minimum light in unlit areas.
Lighting	Glowing Blocks	On
Lighting	Handheld Light	On
Lighting	Underwater Caustics	On	Cast by the water surface when Coloured Shadows is on; otherwise a simpler effect while the camera is underwater.
Atmosphere	Fog Density	0.6	0 leaves only the render-distance fade.
Atmosphere	Waving Plants	On
Atmosphere	Aurora / Strength	On / 1.5	0.5–4.0.
Atmosphere	End Sky	Nebula	Simple, Nebula or Detailed. The custom End sky is always on.
Atmosphere	Light Shafts / Quality	On / 10	6–24 samples.
Water	Water Waves	On	Surface movement and ripples.
Water	Shallow Water Opacity	0.55	Deep water is always nearly opaque.
Post-processing	Bloom / Bloom Strength	On / 0.10
Post-processing	Exposure	1.0	Overall brightness.
Post-processing	Saturation	1.1
Post-processing	Vignette	On

Presets: Potato (no shadows, bloom, animation or sky effects; simple End sky), Low (1024 shadows, no bloom, light shafts or coloured shadows; simple End sky), Medium (default), High (2048 shadows, 128 blocks, 8-sample soft shadows), Ultra (4096 shadows, 192 blocks, detailed End sky).

Known limitations

These were left out on purpose to keep the pack light:

• No screen-space reflections — water reflects the sky only, not terrain.
• No volumetric light or volumetric clouds.
• No PBR / LabPBR resource pack support (normal and specular maps are ignored).
• No anti-aliasing pass; use a higher resolution or a mod if you want it.
• No Distant Horizons support (Voxy is the supported LOD mod).
• Shadows only come from objects within the shadow distance; Voxy LODs are never shadowed and do not cast shadows.
• Distant LOD water has no waves, depth colouring or foam.
• Coloured shadows and water caustics only reach as far as the shadow distance.
• Water is only drawn into the shadow map with Coloured Shadows on; with it off, caustics only appear while the camera itself is underwater.
• The End and the Nether run no shadow pass; the eclipse light in the End is directional shading only.

Status

Version 1.2. The 1.0 base was confirmed loading and rendering on Minecraft 1.21.10 with Iris. The 1.1 additions (Voxy support, the End sky and lighting, light shafts, aurora, handheld light) and everything added in 1.2 — water waves, depth colouring and foam, coloured shadows and shadow-cast caustics, the 8-sample shadow filter, the stronger reflected aurora and the End sky quality levels — was written without access to a running game or a GLSL compiler and has not yet been tested in game. If a program fails to compile, Iris will show the error (enable debug mode with Ctrl+D on the shader pack screen for the full log); Voxy reports problems with its own patches in the game log.

Layout

Shader_Halcyon/
├── shaderpack.md
└── shaders/
    ├── shaders.properties      pipeline config, option menu, presets
    ├── block.properties        which blocks wave, glow, or are water
    ├── lang/en_us.lang         option names
    ├── lib/                    all the actual shader code
    │   ├── settings.glsl       every tweakable value
    │   ├── sky.glsl  skyfx.glsl  lighting.glsl  fog.glsl  water.glsl  distort.glsl
    │   ├── waving.glsl  uniforms.glsl  voxy.glsl
    │   └── program/            solid, water, sky, clouds, shadow, deferred, final, voxy_*
    ├── *.vsh / *.fsh           overworld programs (thin wrappers around lib/program)
    ├── voxy.json  voxy_*.glsl  Voxy LOD shading (also in each dimension folder)
    ├── world-1/                Nether programs
    └── world1/                 End programs