Skip to Content
Getting StartedVariants and guards

Variants and guards

Target API: 5 · Target build: bbb6l5 (verified in production and preprod 2026-11-20) · Status: Analyzed

6 variants

You write one body of code, but it must compile in all 6 variants: {strict, allow} × {terrain, liquid, model}. The loader validates all six at load time.

The v4-and-earlier “lighting on/off” axis is gone (v4 had 8 variants). Lighting state is now a runtime question for bloxdLit(), not a compile-time branch.

VariantExampleMacros defined
allow.terrainterrain in an allow gameBLOXD_ALPHA
allow.liquidwater in an allow gameBLOXD_ALPHA · BLOXD_SCENE_DEPTH
allow.modelmodels in an allow gameBLOXD_ALPHA
strict.terrainterrain in a strict game—
strict.liquidwater in a strict gameBLOXD_SCENE_DEPTH
strict.modelmodels in a strict game—

Conditionals

Only #define NAME (no value) / #ifdef / #ifndef / #else / #endif are available. The # goes at the start of a line (inside functions is fine).

GuardMeaningTypical use
#ifndef BLOXD_STRICTnon-strict (allow) variants onlywrap whole vertex hooks, wrap discard
#ifdef BLOXD_ALPHAvariants where alpha exists (all liquid + non-strict terrain/model)wrap alpha-touching code
#ifdef BLOXD_SCENE_DEPTHall liquid variantswrap bloxdOpaqueBehind() calls

BLOXD_LIGHTING was removed in v5. Using it fails validation with: “BLOXD_LIGHTING was removed in apiVersion 5; test bloxdLit() in code instead.”

The strict-games contract

Most games are strict (no vertex animation, no discard). An unguarded vertex hook reports <hook> moves terrain, which strict games prevent. and a reachable discard reports discard makes terrain see-through, which strict games prevent. — both disable all hooks in that strict game. Always wrap vertex hooks in #ifndef BLOXD_STRICT.

For per-game policy internals, see Engine Internals: policy.