Compatibility
Target API: 5 · Target build:
bbb6l5(verified in production and preprod 2026-11-20) · Status: Verified
How the current game and old-version packs interoperate.
Accepted versions
Only apiVersion: 5. The loader compares manifest.apiVersion !== 5 strictly and v1/v2/v3/v4 packs fail at the instant of load. No multi-version acceptance exists.
Load-time messages (verbatim from the live i18n dictionary)
pack.json needs "apiVersion": {{version}}.— theapiVersionkey is missingThis pack is shader pack API version {{packVersion}}. Bloxd supports version {{version}}.— the key exists but isn’t 5
Saved old packs (no exceptions — silent inactivation)
Previously-saved v1–v4 packs don’t throw. The saved-pack result resolves to:
{kind: "none", reason: "otherApiVersion"}and the pack becomes silently inactive. Only the shader-pack settings tab explains why:
This shader pack is for API version {{packVersion}}, so it won't run. Load a version {{version}} pack to replace it.
The nature of the v4 → v5 conversion
The conversion is mostly mechanical (full checklist in the v5 migration guide):
blockFlags & bloxdBlockFlagX != 0u→flags.x(a 1:1 rename)#ifdef BLOXD_LIGHTING→if (bloxdLit()) { ... } else { return bloxdDefaultLight(...); }bloxdFragmentBlockPositioncall sites still compile (the engine injects it), but it is undocumented now — migrating off it is the safe move (Functions)- bump
pack.jsonto"apiVersion": 5
The quiet trap this time: packs that keep reading blockFlags or wrapping light hooks in #ifdef BLOXD_LIGHTING fail validation with dedicated messages (the analyzer now explains both cases), so nothing misbehaves silently — they just stay refused until migrated.
Saved-pack re-validation (“needs re-check”)
HEADER_VERSION is 9.<hash> from the engine’s validator, with the texture-registry fingerprint folded into the page-level validation version (the leading integer went from v4’s 8 to 9). When the engine’s header or texture registry changes (common with game updates), saved packs are marked “needs re-check” and re-validate automatically on page load.
The v98qt8 folding regression is fixed on bbb6l5: the animated-texture table is slot-keyed again, so the registry fingerprint is computed over the intended folded table, the 43 animation-family base names validate again, and saved packs that reference them no longer fail re-validation. The bbb6l5 header change (the shadow additions) does force one re-validation pass of every stored pack — a one-time automatic event, not a rejection.
A measured example of registry movement (two builds, 10 days apart): entries 1200 → 1219 (98 added, 79 removed), and of the names that kept their spelling, 779 of 1121 changed id. In other words:
- packs written with names (
bloxdTextureIdLava) survive drift (the loader re-resolves against the live registry) - packs written with raw ids (
19) break on re-validation
Details: Engine Internals: Texture Registry.
Runtime environments
- WebGPU-renderer only: installing a pack force-enables the WebGPU renderer
- Mobile: WebGPU-limited environments can’t run packs at all (Requirements)
- Non-atlas renderer configurations:
bloxdTexel/bloxdTextureSizedegrade to stubs (white texels, 1×1); code still compiles and runs (Texture API)
Version support summary
| API version | Live since | Treatment by the current game |
|---|---|---|
| v1 | — | rejected at load (migrate via v2) |
| v2 | — | rejected at load |
| v3 | 2026-10-19 | rejected at load |
| v4 | 2026-10-26 | rejected at load |
| v5 | 2026-11-03 | current |