Sulkan icon Sulkan | Minecraft Visual Engine
Shader pack author reference

Sulkan Shader Pack API

This is the technical contract for shader pack creators targeting Sulkan. Use it as the primary compatibility reference for layout, bindings, and rendering passes.

Accepted structure

Pack layout rules

Sulkan accepts both direct namespaced packs and shorthand shader folders.

Supported container formats

Directory packs and `.zip` packs in the game `shaders` folder are scanned.

Accepted shader roots

`assets/sulkan/shaders/...` is native. `shaders/...` is accepted and remapped into the Sulkan namespace during staging.

Optional image asset

`pack.png` is preserved if present.

Unsupported entries

Entries without a Sulkan shader layout are ignored and treated as unsupported rather than partially loaded.

shader-pack.zip |- pack.png |- shaders/ | |- core/ | | |- water.vsh | | |- water.fsh | | |- terrain_shadow.vsh | | |- terrain_shadow.fsh | | |- shadow_depth.vsh | | |- shadow_depth.fsh | | |- entity_shadow.vsh | | |- entity_shadow.fsh | | |- entity_shadow_depth.vsh | | |- entity_shadow_depth.fsh
Core entry points

Core shader program set

These are the expected program names used by the Sulkan rendering pipeline.

Program Role Notes
core/water Water vertex and fragment pipeline Handles wave displacement, water normals, tinting, refraction, and screen-space reflection behavior.
core/shadow_depth Terrain shadow caster Used by solid and alpha-cutout terrain caster pipelines.
core/terrain_shadow Terrain shadow receiver Consumes terrain cascade depth plus dynamic entity shadow depth for shaded terrain output.
core/entity_shadow_depth Entity shadow caster Used for solid, cutout, and translucent casting variants.
core/entity_shadow Entity shadow receiver Supports overlay, lightmap, shadow cascades, and optional per-face/translucent variants.
Named binds

Uniform blocks and sampler slots

These names are significant because Sulkan uses explicit binding contracts across its render pipelines.

ShadowMatrices

Terrain caster uniform block containing the active shadow projection-view matrix plus shadow direction and parameter vectors.

TerrainShadowSplits

Receiver block containing up to four cascade projection matrices, split ranges, sun direction, strength, floor, and transition parameters.

EntityShadowMatrices

Entity block carrying the entity shadow transform and inverse view rotation matrix needed to recover receiver-space orientation.

WaveUniforms

Water animation block. In the current runtime, `WaveData.x` acts as animation time in seconds.

Binding Name Purpose
1 Sampler1 Overlay sampler for entity receivers.
3 Sampler3 Water scene color sampler used for refraction and reflection sourcing.
4, 6, 7, 8 Terrain shadow depth samplers Cascades 0 through 3 for terrain receiver shading.
5 Sampler5 Water scene depth sampler for SSR, thickness, and refraction depth testing.
9 Sampler9 Dynamic entity shadow depth sampler.
Pipeline behavior

Authoring expectations

Treat these as runtime-level behavior guarantees when creating or adapting shader packs.

Terrain receivers

Expect up to four active terrain cascades, with runtime blend between cascade ranges and dynamic adjustment based on quality preset and render distance.

Entity receivers

Expect three terrain receiver cascades plus one short-range dynamic entity shadow depth source.

Water logic

Water shaders can rely on animated displacement, derived wave normals, screen-space reflection tracing, depth-aware thickness, and fog integration.

Alpha cutout variants

Both terrain and entity caster and receiver paths include alpha-cutout variants controlled by compile-time defines.

Compatibility boundary

What pack authors should not assume

These boundaries help avoid fragile integrations and maintain forward compatibility.

  • Do not assume undocumented internal Java classes are part of the public authoring API.
  • Do assume bind names, file entry points, and quality semantics are the meaningful compatibility layer right now.
  • Do not assume arbitrary foreign shader-pack layouts will be partially adapted. Sulkan expects a Sulkan-targeted pack structure.
  • Do assume future revisions may extend the API, but current packs should target the observed core program set and named uniform contracts.