Scene programs & shadows

Replace a scene pipeline

A scene rule selects an exact namespaced ID or prefix with a terminal *:

{
  "scenePrograms": [{
    "pipeline": "sodium:pipeline/solid_terrain",
    "vertex": "shaders/terrain.vsh",
    "fragment": "shaders/terrain.fsh"
  }]
}

This is a manifest fragment. Both shaders must match the selected pipeline’s actual attributes, bindings, and varyings. Matching rules cannot overlap. Geometry, topology, culling, depth, existing bindings, and primary color blending remain inherited.

Additional scene targets

Declare images in resources, list up to seven in sceneTargets, and enable writes by naming them in the scene rule’s writes.

{
  "resources": { "scene.normal": { "format": "RGBA16_FLOAT" } },
  "sceneTargets": ["scene.normal"]
}

Location 0 stays Minecraft’s main color. Locations 1 onward follow root sceneTargets order, not a rule’s writes order. Targets must be full-resolution, non-history 2D images. Extra targets use unblended replacement writes.

This applies to world passes on the main color target. Separate offscreen transparency/effect targets are not consolidated into the G-buffer; rules requesting extra outputs are not applied there.

Scene textures

A rule’s textures maps sampler names to declared asset names or terrain snapshots:

{
  "textures": { "Noise": "noise", "Opaque": "$terrainOpaque", "OpaqueDepth": "$terrainOpaqueDepth" }
}

Bindings are available to both stages and cannot collide with existing samplers. Earlier scene shaders see cleared snapshots; later shaders see the frozen terrain-boundary copy.

Terrain material IDs

{
  "materials": {
    "minecraft:oak_leaves": 7,
    "minecraft:grass_block[snowy=true]": 8
  }
}

ID 0 is unassigned; declared IDs are 1–65535. State-specific mappings override less-specific ones. Equally specific conflicts and unknown blocks/state values fail activation.

Declared materials extend Sodium’s standard 20-byte compressed terrain vertex to 24 bytes with uint a_SulkanMaterial. Pass it to fragments with flat interpolation. Changing materials rebuilds terrain after activation.

This covers terrain and fluids, not a general entity/item material interface or normal/tangent/mid-UV extension.

Native shadows

Set root "shadows": true. The pack still supplies lighting and applies visibility:

#include "sulkan/shadows.glsl"
// Inside a compatible scene fragment shader:
float visibility = sulkanTerrainShadow(cameraRelativeWorldPosition, worldNormal);

Positions use world axes relative to the camera, not view axes. Evaluate normal derivatives before discard.

Distance is capped by loaded view distance. Declare these options to expose choices in Pack Settings. Shadow samplers and data are reserved loader bindings; use the includes. Directional shadows are scene-only, not general post/compute inputs.

The bundled pack includes terrain, foliage, and nearby supported entity casters. It is not a universal geometry interface; consult its port notes for limits.

Start from a real interface

Download the exact 0.5.1 pack. Read terrain.vsh, terrain.fsh, material helpers, and shadow includes together before writing replacements. Preserve its attribution and licensing when deriving work.