API version errors
Target API: 5 · Target build:
bbb6l5(verified in production and preprod 2026-11-20) · Status: Verified (verbatim from the live i18n dictionary)
Errors around apiVersion. The current game accepts only 5.
“pack.json needs “apiVersion”: {{version}}.”
- Symptom: this message right after load (
loadNoApiVersion) - Cause: the
apiVersionkey is missing entirely - Fix: add
"apiVersion": 5— a number (the string"5"fails) - Prevention: start from the pack.json template
“This pack is shader pack API version {{packVersion}}. Bloxd supports version {{version}}.”
- Symptom:
loadWrongApiVersion - Cause:
apiVersionexists but isn’t 5 (a v1–v4 pack) - Fix: apply the matching migration (Version History):
- v4 → v5: the v5 guide — mostly mechanical (flags ·
bloxdLit()· thebloxdFragmentBlockPositioncaveat) - v3 → v5: apply v4 first
- v2 or earlier → v5: step through v3 → v4 → v5
- v4 → v5: the v5 guide — mostly mechanical (flags ·
- Prevention: after any API update, check Compatibility and the matching migration guide
The string “5” is rejected
- Cause: the loader compares
manifest.apiVersion !== 5strictly (===); a JSON string"5"is not the number 5 - Fix:
"apiVersion": 5(unquoted)
A saved old pack silently stopped working
- Symptom: a previously-working v1–v4 pack is unresponsive, with no exception
- Cause: saved packs resolve to
{kind: "none", reason: "otherApiVersion"}and become silently inactive - Check: the settings-tab status line:
This shader pack is for API version {{packVersion}}, so it won't run. Load a version {{version}} pack to replace it. - Fix: load a migrated replacement from the same screen
- Prevention: after API updates, re-release a bumped version and announce it (Distribution)
A migrated v4 pack fails validation
The three typical patterns (full steps in the v5 migration guide):
| Validation message | Cause | Fix |
|---|---|---|
BLOXD_LIGHTING was removed in apiVersion 5; test bloxdLit() in code instead. | #ifdef BLOXD_LIGHTING usage | rewrite as if (bloxdLit()) { ... } else { return bloxdDefaultLight(s, l); } |
bloxdBlockFlagRock isn't part of the shader pack API... (reserved-name diagnostic) | leftover bit-constant references | use surface.flags.rock etc. (1:1 table in Flags) |
bloxdFragmentBlockPosition missing | out of the documented header since v5 (still injected and accepted — see Functions) | not an error to fix: it compiles; prefer flags / bloxdWorldPosition() in new code |