Custom Skybox and Distance LOD API

Custom Skybox and Distance LOD API

AUSM exposes two shader-pack integration points in generated 1.12.2 Euphoria and Complementary-derived patches. They are owned by AUSM: pack authors should use the documented uniforms and helper functions, but should not redeclare or set them.

Skybox repair

AUSM transforms the final program and makes the following uniforms available:

uniform int ausmSkyboxRepair;
uniform int ausmUiSkyRepair;

ausmSkyboxRepair is 1 only when AUSM has identified the current world as needing its lower-sky repair. ausmUiSkyRepair is the corresponding GUI-world safeguard. A pack that supplies its own final.fsh should preserve these uniforms and the final colour path; AUSM injects its repair after the original final main function and applies it only to sky pixels (depth near 1.0 and no nearby scene geometry).

The repair is deliberately runtime-controlled. Do not force either uniform to a constant or add a duplicate declaration: AUSM supplies both declarations when they are absent.

Distance LOD fallback

Generated shader patches declare their support in shaders/shaders.properties:

ausm.lod.api=1

Terrain and water programs receive this include before their regular program body:

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

The helper exposes the following public option and runtime uniforms:

#define AUSM_LOD_FALLBACK 1 // [0 1]

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

AUSM_LOD_FALLBACK is shown under AUSM Patches → Distance LOD. With it enabled, AUSM gradually reduces distant terrain and water detail, turns foliage waving off at the LOD 2 boundary, and fades optional detail after LOD 4.

Helper 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);

Use ausmEntreeDetailWeight or ausmEntreeWaterDetailWeight to blend expensive vertex/detail effects down with distance. Use ausmEntreeFoliageWaveWeight for foliage-specific waving: it remains fully enabled through LOD 1 and switches off at LOD 2. ausmEntreeLodResolutionScale returns 1x, 2x, 4x, or 8x according to the active tier; it can drive sampling budgets through ausmEntreeLodSampleCount and reflection mip selection through ausmEntreeReflectionMipBias.

Client ranges

The default boundaries are 96, 144, 192, and 240 blocks for LOD 1 through LOD 4. They can be changed in AUSM's client configuration, in 16-block steps, from 16 to 2048 blocks. Keep the values ascending so the distance transitions remain meaningful.

Compatibility contract

Only generated AUSM patches should add ausm.lod.api=1 and the bundled include. Third-party packs can use the same symbols only after they include the helper and preserve AUSM's uniform names. The feature is inert when the fallback option is disabled, so supported packs can keep a single shader source for both modes.