Custom Skybox and Distance LOD API

Custom Skybox and Distance LOD API

This page is for shader-pack authors who want their packs to work with AUSM's skybox repair and distance-LOD controls. These interfaces are client-side and optional: a pack must retain its normal appearance when AUSM is absent or the related option is disabled.

Skybox integration

AUSM provides these runtime uniforms to the final presentation pass:

uniform int ausmSkyboxRepair;
uniform int ausmUiSkyRepair;

They are boolean-style values. ausmSkyboxRepair is non-zero when AUSM has selected its lower-sky correction for the current world; ausmUiSkyRepair covers GUI/menu worlds. Do not assign either uniform, replace it with a constant, or declare it a second time.

For a custom final pass, preserve the normal final colour and depth paths and treat both values as opt-in repair signals. In particular, do not discard or overwrite depth-1.0 sky pixels before your final sky treatment has run. A safe custom branch looks like this:

// `color` is the final scene colour and `depth` is the scene depth.
if (ausmSkyboxRepair > 0 && depth > 0.999) {
    // Keep a valid sky colour here, or blend your own sky colour into color.
    color.rgb = mix(color.rgb, mySkyColor(uv), mySkyRepairWeight(uv));
}

Use a conservative blend rather than treating every far-depth pixel as missing sky: clouds, portals, and modded sky effects can also render at far depth. AUSM's own repair remains active, so packs normally only need this branch when they replace the final sky/presentation route themselves.

Distance LOD integration

The LOD interface lets a pack reduce expensive distant terrain and water work while keeping the feature fully switchable. Declare support in shaders/shaders.properties:

ausm.lod.api=1

Vendor the current distantLod.glsl helper into your pack at shaders/lib/ausm/distantLod.glsl, then include it in every terrain or water program that uses the API:

#include "/lib/ausm/distantLod.glsl"

The helper declares the option and runtime inputs:

#define AUSM_LOD_FALLBACK 1 // [0 1]

uniform int ausmLodFallbackEnabled;
uniform float ausmLod1RadiusBlocks;
uniform float ausmLod2RadiusBlocks;
uniform float ausmLod3RadiusBlocks;
uniform float ausmLod4RadiusBlocks;

Never write these uniforms. Guard any LOD-specific work with AUSM_LOD_FALLBACK == 1 && ausmLodFallbackEnabled > 0, either directly or through the helper functions below.

Functions

float ausmLodTransition(float playerDistance);
float ausmEntreeDetailWeight(vec3 playerPosition);
float ausmEntreeWaterDetailWeight(vec3 playerPosition);
float ausmEntreeFoliageWaveWeight(vec3 playerPosition);
float ausmEntreeLodResolutionScale(float playerDistance);
float ausmEntreeLodFeatureWeight(float playerDistance);
int ausmEntreeLodSampleCount(int fullResolutionSamples, float resolutionScale);
float ausmEntreeReflectionMipBias(float reflectionDistance);

ausmEntreeDetailWeight and ausmEntreeWaterDetailWeight return a smooth 0-to-1 blend weight for terrain and water detail. Apply the weight by blending the result of an expensive effect, not by branching a texture lookup with implicit derivatives.

vec3 displaced = position.xyz;
applyExpensiveTerrainWave(displaced);
position.xyz = mix(position.xyz, displaced, ausmEntreeDetailWeight(position.xyz));

Use ausmEntreeFoliageWaveWeight specifically for foliage animation. It is 1 through LOD 1 and becomes 0 at the LOD 2 boundary, avoiding unstable distant foliage motion.

vec3 waved = position.xyz;
applyFoliageWave(waved);
position.xyz = mix(position.xyz, waved, ausmEntreeFoliageWaveWeight(position.xyz));

For screen-space or ray-marched effects, use ausmEntreeLodResolutionScale to reduce the sampling budget and ausmEntreeLodSampleCount to keep at least one sample. ausmEntreeReflectionMipBias is suitable for selecting a coarser reflection mip at distance. ausmEntreeLodFeatureWeight is the final fade-out weight after LOD 4.

float distance = length(playerPosition);
float scale = ausmEntreeLodResolutionScale(distance);
int samples = ausmEntreeLodSampleCount(16, scale);
float featureWeight = ausmEntreeLodFeatureWeight(distance);

Compatibility rules

• Keep the helper's uniform names and function signatures unchanged.
• Preserve the AUSM_LOD_FALLBACK option so players can disable the integration.
• Use the supplied smooth weights to blend visual detail; avoid hard distance cut-offs.
• Do not assume the four radii have their default values. Read the uniforms every frame.
• Test both fallback states and a range of distances, including the LOD 1, LOD 2, and LOD 4 boundaries.