What shader packs can and cannot do
Target API: 5 · Target build:
bbb6l5(2026-11-20, production and preprod) · Status: Verified (ported to the current API — on-device re-check recommended)
The realism ceiling of shader packs in one page: what the current API reaches, what it fundamentally cannot, what is conditional, why the limits exist, and the closest substitutes. Scope a look here before building it.
What the current API can do
- Colors, transparency and emission, per face — the three
Surfacehooks return colour (plus conditional alpha and emission) for terrain, liquids and models - A full lighting rebuild — the three
Lighthooks and the lighting API (bloxdShading()/bloxdWorldLight()/bloxdLitColour()) expose the engine’s own recipe as composable functions (Lighting) - Projected-style shadows that track block edits in real time —
skyLightis voxel sky-occlusion data; lift inversion + threshold cut turns it into clear shadows under trees and roofs (Shadows) - Reading the game’s own textures —
bloxdTexel()samples the block-texture atlas and model-owned textures exactly as the engine’s sampler does (Texture API) - Per-model effects —
flagstells you “this is a held item”, “this is a dropped item”, “this is a player”, “this is a slab” (Flags);localPositiongives model-local coordinates (Structures) - Enchant glints and hurt-flash overlays —
enchantTier/enchantColour/enchantSpeedandoverlayColourare readable and overridable (Enchant effects) - Time and animation —
bloxdSeconds(), world position, and the sun direction drive motion (Time & animation)
What the current API cannot do
| Look | Reason |
|---|---|
| Pixel-accurate shadow maps (sun-tracking shadows, penumbra) | Depth textures cannot be referenced (liquid-only bloxdOpaqueBehind() is geometry-only and unusable as a shadow map). Light-ray occlusion is not fed into hooks |
| SSAO | No scene-depth access (only mesher-baked vertex AO; liquid-only depth is unusable for SSAO) |
| SSR (reflections) | No scene color. Only pseudo looks blending sky color via fresnel |
| Bloom / glare | No hook into post-processing |
| Depth of field, chromatic aberration, grain | Full-screen post-processing required |
| Volumetric light (god rays) | Same |
| Custom PBR maps (normal / roughness / metalness textures) | Packs cannot add textures of their own — the API only reads the game’s existing textures via bloxdTexel(), and those are plain color textures with no PBR channels. A pseudo-PBR response can only be estimated from color luminance plus flags (Texture API) |
| Underwater refraction | No scene color. Liquid-only depth (bloxdOpaqueBehind()) enables thickness absorption and bottom projection (Making water look natural) |
| Underwater veil (blue tint) removal / change | The veil is an emissive fullscreen quad generated from the liquid block definition color/alpha the camera is in, drawn outside hook pipelines (frontmost), so packs can change neither its color nor density |
| Direct underwater detection | No input indicates camera submersion, and fogStart / fogEnd / fogColour don’t change underwater, so there is no reliable way to estimate underwater from fogAlpha etc. |
| Changing the sky, clouds or the sun disc itself | Hooks run per-face on terrain / liquid / model geometry; the skybox is not part of any hook pipeline |
Conditional capabilities
- Vertex animation and
discard— only in games whose definition carriesshaderPackPolicy: "allow"; everywhere elseBLOXD_STRICTcompiles those hooks out (Per-game shader-pack policy) - Scene depth (
bloxdOpaqueBehind()) — liquid hooks only, and it needsBLOXD_SCENE_DEPTH; terrain and model hooks have no depth access (Functions) bloxdTexel()/bloxdTextureSize()— surface and light hooks only, and only where the pipeline has a texture; texture-less configurations compile them as white-returning stubs (Texture API)- Terrain alpha (
BLOXD_ALPHA) — only where the variant defines it (Variants and guards)
Why these limits exist
Four inputs a “real” post-processing shader would need are structurally absent:
- No scene color — hooks run while each face is drawn; there is no framebuffer texture to read, so SSR, refraction and anything derived from “what is behind me” cannot be computed
- No scene depth — except the liquid-only
bloxdOpaqueBehind()geometry probe; SSAO and shadow maps need a full depth buffer - No post-processing stage — no hook runs after the frame is composed, so bloom, DOF, aberration, grain and god rays have no entry point
- No sky access — the skybox, clouds and sun disc are drawn outside the hook pipelines, and no input describes them beyond
bloxdSunDirection()
The underwater veil is a special case of the same structure: it is an emissive fullscreen quad drawn frontmost, generated from the liquid block definition the camera is inside — outside every hook pipeline.
Closest substitutes
| Wanted | Closest pack-side approach |
|---|---|
| Reflections | Fresnel-weighted blend toward a sky-like color + sun glint (Making water look natural) |
| PBR materials | Luminance-based specular/roughness estimation + flags-based material classes (Colors, Realism) |
| Bloom / glow | Emission output — genuinely additive glow, but per-face, not a post-process blur (Emission) |
| Ambient occlusion | The mesher-baked vertex AO already in surface.colour; skyLight darkening doubles as large-scale AO (Shadows) |
| Water depth absorption | bloxdOpaqueBehind() thickness + bottom projection in liquid hooks (Liquids) |
| Underwater mood | Accept the veil; style what is visible through it (terrain/liquid still render normally underwater) |
The truth about shadows — “tree shadows” are buildable
Only sun-tracking pixel-accurate shadow maps are impossible in the table above. The engine already computes “shadows” from the start, and that is skyLight. The mesh-side LightEngine runs a Minecraft-style algorithm:
- Column scan: scan each (x,z) column top to bottom. Light from the sky starts at 15, becomes 0 at opaque blocks, dimming down with
lightFilter(air 1 / water 3 / opaque 15) - BFS flood fill: spreads sideways to 6 neighbors (-1 per block) — this is what softens shadow edges. Raw value under radius-r occlusion is (15-r)/15
- blockLight (torches etc.) is a separate BFS of RGB 3 channels (4bit packed)
So l.skyLight is not a mere brightness parameter but voxel-resolution occlusion data of “whether sky is visible from here” = a shadow map. Under trees, under roofs, and indoors it is already numerically low, arriving smoothed by vertex interpolation. Placing/breaking blocks recalculates immediately = real-time-tracking shadows. Vanilla only uses it “gently” via mix(ambient, sky, skyLight).
The right tools are the two steps in Shadows (restore raw values via lift inversion → binarize with threshold smoothstep; th = 1 - r/15 directly dials “occlusion radius treated as shadow”) plus gating direct sun by sky (sun only reaches where sky is visible = the essence of projection), composed with warm sunlit / cool shadow tinting.
Honest limits: these shadows are “upward sky” based, so they don’t rotate as the sun moves over time. Resolution is per block (soft edges come from BFS spread). The engine lighting template still contains a closed var shadow: f32 = 1.; stub for shadow maps (always 1.0 = disabled) — interpreted as a trace of “planned” pixel-accurate rotating shadows. If pixel-accurate rotating shadows are a must, only out-of-API approaches remain (e.g. userscript GLSL injection, with policy risk).
Underwater reality
Underwater looks consist of 3 layers:
| Layer | Content | Operable from packs? |
|---|---|---|
| ① Terrain/liquid rendering | Hook-processable. Light hooks are called normally underwater | Yes (works “under the veil”) |
| ② Liquid-definition veil | Emissive fullscreen quad from the liquid block definition color/alpha at the camera position, drawn frontmost. The game setting cameraTint wins if set | No (neither color nor density changeable) |
| ③ cameraTint | Game setting | No |
Practical points: packs keep working underwater / the veil cannot be removed / underwater cannot be branched on (fogStart / fogEnd / fogColour don’t change underwater, so fogAlpha can’t detect it either).
Related
- Shadows — the skyLight shadow technique in full
- Models and textures — what the model pipeline reaches
- Compatibility — how old-version packs behave
- Version-by-version changes to these limits: Version History