Skip to Content
API ReferencePack format

Pack format

Target API: 5 · Target build: bbb6l5 (verified in production and preprod 2026-11-20) · Status: Verified (re-measured on the live loader)

The whole pack model on one page — manifest, loader limits, per-frame uniform. For the step-by-step version see Getting Started.

pack.json

{ "apiVersion": 5, "name": "My Pack", "author": "your name" }
FieldTypeRequiredDescription
apiVersionnumberrequiredmust strictly equal 5 (===). A string "5" fails and is reported with its JSON spelling
namestringrequirednon-empty after trimming; shown in settings
authorstringoptionalmust be a string if present
keepCircleShadowsbooleanoptionalnew in the bbb6l5 build — keep the old circular blob shadows under players and mobs when your pack’s shaders also use the real sun-shadow API (Shadows). Default false; any other type is rejected with a dedicated load message

Everything else in the manifest is ignored. pack.json must be exactly one JSON object at the zip root.

Loader limits (re-measured on the live loader)

LimitValueMessage when exceeded
.wgsl files per pack256The pack has more than 256 .wgsl files.
total .wgsl source256 KBThe pack's .wgsl files are over 256 KB in total.
pack.json size64 KBpack.json is over 64 KB.
zip size32 MBThe zip is over 32 MB.
zip entries1,024The zip has more than 1024 entries.
zip shape—split zip / zip64 / encrypted / unsupported compression each rejected with its own message; all files valid UTF-8; exactly one pack.json; no duplicate paths

API-version check

The loader compares manifest.apiVersion !== 5 with JavaScript strict !==. The version constant 5 and the header it validates against ship together in the game’s validator, so the check and the header move together. Mismatch messages: see Compatibility.

Per-frame uniform: bloxdPackInputs

@group(3) @binding(0) var<uniform> bloxdPackInputs: BloxdPackInputs — 80 bytes as of the bbb6l5 build (64 before it), from the live uniform-layout module:

OffsetFieldTypeNote
0secondsf32backs bloxdSeconds()
4litu321 when block/sky lighting is on; backs bloxdLit()
16renderOffsetvec3ibacks bloxdRenderOffset()
32sunDirectionvec3fbacks bloxdSunDirection()
48eyePositionvec3fbacks bloxdEyePosition()
64shadowDirectionvec3fnew in bbb6l5 — the direction the shadow-casting light travels; backs bloxdShadowDirection()

shadowDirection slots into the padding after eyePosition (a vec3f spans 12 bytes, so offsets 60–63 were alignment slack; shadowDirection lands at 64, a 16-byte boundary, keeping the struct at exactly 80 bytes). The engine writes it as three setFloat32 writes — it is a unit vector (from the sun by day, the moon by night, and the default sky’s sun when there is no sun), never above the horizon. Its arrival grew the uniform from 64 to 80 bytes and bumped the pack bind-group’s minBindingSize to 80.

lit still fits into the padding v4 had between seconds and renderOffset (offsets 4–15 were alignment gaps; vec3i needs 16-byte alignment so renderOffset stays at 16).

Never reference the uniform directly from a pack. Use it through the header functions (bloxdSeconds() etc.). Stage visibility is VERTEX|FRAGMENT, so header functions work from module-scope functions and vertex hooks too.

Bind-group layout

bindingContents
0bloxdPackInputs uniform (80 B)
1scene-depth texture (liquid variants)
2bloxdSpTextureLayers storage buffer

minBindingSize is 80 (it grew with the uniform). The depth texture (binding 1) is FRAGMENT-only, which is why bloxdOpaqueBehind() is surface/light-hook only.

wgsl concatenation

Multiple .wgsl files are concatenated into one module in dictionary order by path name. Module-scope declarations are order-independent; only var initialization order can matter. Non-.wgsl files are ignored.