Skip to Content
Version HistoryAPI v4 migration guide

API v4 migration guide

Version: 4 · Status: Historical (migration guide of the era; the target build is noted in the text) Superseded 2026-11-03: the live API is now version 5 — v4 packs are rejected at load exactly as described here for v3. Apply this part and then the v5 guide (v4 → v5: the BloxdFlags struct replaces blockFlags, bloxdLit() and the public lighting recipe, the enchant/overlay inputs, the 9-hook default pack). This part’s internals (§56–§66) remain accurate for the v4 builds they were measured on.

Target build: cnty9.main.669f8081.js — live on production and preprod simultaneously since 2026-10-26. Unlike the v3 rollout (a preprod build promoted to production), v4 flipped both environments to the same new bundle in one move, and the two bundles are byte-identical (main and every shader-pack chunk md5-checked), so everything here applies to production as-is. The bundle was also reorganised around this release — the main bundle shrank from 4.73 MB to 3.03 MB (-36%), the chunk count grew from 169 to 193, and the whole shader-pack pipeline (loader, validator, code generator, WebGPU compiler) now lives in a contiguous c49–c54 cluster. The pack model itself keeps its shape: same pack.json fields, same loader limits, same 64 B uniform, same six hooks.

Re-verified on tcwczu.main.357faec1.js (2026-10-30, production and preprod again byte-identical): the whole v4 API surface is unchanged. The engine header (6,021 B decoded), the default pack template (1,122 B as shipped), the 27 bloxdSp* symbols, the blockFlags bits, the loader limits, and the 12 allow titles are all byte-identical to the cnty9 baseline this part documents — the v4 freeze held through the first post-v4 bundle refresh. The bundle layout moved on: the main bundle grew to 3.28 MB, the chunk map now has 202 ids (195 emitted), the shader pipeline cluster sits at c51–c56 with the default pack in c124, and the §66 “chunk c8” references for the lift/cone constants are now c9. None of that is visible to a pack. The one thing this re-verification did not re-measure is the texture-name registry (§68): its cnty9 ids remain a snapshot, and names remain the stable API.

One thing changed around this release that is not in the bundle: the engine now cites reference files by name. Its own error messages point at bloxd-api.wgsl (the annotated engine header) and BLOCK_TEXTURES.md (the complete texture-name list) — ...BLOCK_TEXTURES.md lists them. This guide carries the content of both instead of pointing you elsewhere: the complete header, restored verbatim from the live build, is embedded in Engine Internals: Engine header, and the complete catalogue of usable texture names (905 in the v4 build) is the Texture catalog. Every pack-facing fact in this part was restored from the production bundle.

The v4 change set in one screen:

Areav3v4
pack.json apiVersion3 (strict)4 (strict) — v3 packs are rejected at load
Texture accessnone (“cannot sample textures”)new texture API: bloxdTexel(), bloxdTextureSize(), bloxdTextureId* constants
Hook inputs13/5 fields+4 fields each: textureId, textureRotation, uv, mipLevel (surface and light)
fogVisibility1 = no fogrenamed fogAlpha, meaning inverted: 0 = no fog, 1 = only fogColour
bloxdFaceBlock()—renamed bloxdFragmentBlockPosition() (same math)
BloxdOpaqueBehind.foundfoundrenamed hit
Strict gamespolicy + guards documentednow enforced by the bundled validator with exact diagnostics (§60)
Everything else—frozen: 6 hooks, blockFlags bits, uniform layout, loader limits, variant matrix, pack @group(3) bindings

Conversion from v3 is mechanical (§61) except for one silent trap: if you port everything but ignore the fogAlpha inversion, your fog-dependent code runs with inverted fog and compiles fine. As always, verify with an in-game compile before distributing.

55. Fate of v3 packs (conclusion first)

Every v3 pack — including every pack distributed as v3 — now fails on production exactly at load. The loader compares manifest.apiVersion !== 4 with strict JavaScript !==, so the comparison is type- and value-exact: the JSON must carry the number 4. A string "4" fails and is reported with its JSON spelling ({{packVersion}} is JSON.stringify-ed, so the settings screen shows This pack is for shader pack API version "4"... with quotes — a useful tell that you wrote a string).

The two load-time messages, verbatim from the live i18n dictionary:

This pack is for shader pack API version {{packVersion}}. Bloxd supports version {{version}}. — the key is present but doesn’t equal 4.

A stored (previously working) v3 pack doesn’t throw anything at the player. The stored-pack outcome resolves to {kind: "none", reason: "otherApiVersion"}, the pack is silently inactive, and the shader-pack settings tab explains itself with the status line:

This shader pack is for API version {{packVersion}}, so it won't run. Load a version {{version}} pack to replace it.

The manifest rules around apiVersion are otherwise unchanged and worth re-stating because the loader enforces them before anything else:

  • pack.json must be a JSON object at the root of the pack (not an array, not a number).
  • apiVersion must be present and === 4.
  • name is required, a string, and non-empty after trimming.
  • author is optional, but if present it must be a string — explicit null is rejected (pack.json's "author" must be a string.).
  • Everything else in the manifest is ignored by the loader.

56. pack.json and the uniform buffer (what stays unchanged)

The whole non-texture pack model carries over from v3 byte-for-byte, so §41 of the v3 guide remains the reference. The v4 re-measurements, from the live loader chunk (c51):

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 zips, Zip64, encrypted entries, and unsupported compression methods are each rejected with a dedicated message; every file must be valid UTF-8; exactly one pack.json; no duplicate paths

The per-frame uniform is untouched: @group(3) @binding(0) var<uniform> bloxdPackInputs: BloxdPackInputs, 64 bytes, std140-style layout:

OffsetFieldTypeNote
0secondsf32backs bloxdSeconds()
16renderOffsetvec3ibacks bloxdRenderOffset()
32sunDirectionvec3fbacks bloxdSunDirection()
48eyePositionvec3fbacks bloxdEyePosition()

The six-hook template ships with only comment polish (1059 → 1122 bytes; the v3 behaviour described in §45 is unchanged). The v4 template, verbatim — still the best starting skeleton, and still the strict-games pattern to copy:

// Every hook here returns its engine default. // Copy a hook and change its output to start a shader pack. // Strict games keep terrain where it is. We use #ifndef to define the hook for // non-strict games, but to disable it in strict games, so our pack can stay on. #ifndef BLOXD_STRICT fn bloxdTerrainVertex(vertex: BloxdVertexIn) -> BloxdVertex { return bloxdDefaultVertex(vertex); } #endif fn bloxdTerrainSurface(surface: BloxdSurfaceIn) -> BloxdSurface { return bloxdDefaultSurface(surface); } fn bloxdTerrainLight(surface: BloxdSurface, light: BloxdLightIn) -> BloxdLight { return bloxdDefaultLight(surface, light); } // Water uses liquid hooks. If deleted, water uses your terrain hooks instead. #ifndef BLOXD_STRICT fn bloxdLiquidVertex(vertex: BloxdVertexIn) -> BloxdVertex { return bloxdDefaultVertex(vertex); } #endif fn bloxdLiquidSurface(surface: BloxdSurfaceIn) -> BloxdSurface { return bloxdDefaultSurface(surface); } fn bloxdLiquidLight(surface: BloxdSurface, light: BloxdLightIn) -> BloxdLight { return bloxdDefaultLight(surface, light); }

57. The texture API: bloxdTexel, bloxdTextureSize, bloxdTextureId* (the headline)

v3 packs could read a face’s colour but not its texture. v4 opens the block-texture atlas itself: three new engine functions, one named-constant family, and four new input fields (§58). The engine header’s own one-line summary of the headline: “This face’s texture. Compare with bloxdTextureId*.”

57.1 bloxdTexel(textureId: u32, uv: vec2f, mipLevel: f32) -> vec4f

Samples the block-texture atlas exactly as the engine’s own sampler does — the same texture_2d_array<f32> atlases, the same atlasSampler, textureSampleLevel at round(mipLevel) — so a texel you read and the texel the engine rendered agree by construction. Semantics, all restored from the generated WGSL (§63 has the verbatim source):

  • textureId == 0 returns vec4f(1.0) — white. That is the “no texture” id, and it is also what the four input fields carry when a face has no texture, so bloxdTexel(surface.textureId, ...) is always safe to call.
  • Animated textures return the current frame, automatically. The frame advances with the game’s animation clock — you cannot freeze or step it, and you don’t need to: sampling an animated texture’s id is sampling its live frame (§63.3 for the frame math).
  • mipLevel is clamped the way the engine clamps its own: clamp(round(mipLevel), 0, textureNumLevels(textureAtlas0) - 1). Out-of-range mips saturate instead of erroring.
  • The current fragment’s textureRotation is applied to the uv you pass — see 57.4; this is the one subtlety with real visual consequences.

textureId is 1-based: bloxdTextureIdGrassTop is the id, and the atlas layer the engine samples for it is id - 1. Ids are stable per texture name, not per atlas layout — the engine re-lays-out the atlas freely across builds while your bloxdTextureId* comparisons keep meaning “this texture”.

57.2 bloxdTextureSize(mipLevel: f32) -> vec2u

textureDimensions(textureAtlas0, <clamped mip>) — the size in texels of the atlas at that mip level. Since every texture occupies one array layer of that atlas, this is also the texel size of any one texture at that mip (all block textures in an atlas tier are the same square size). Pair it with bloxdTexel when you want texel-grid effects:

// A texel-aligned "pixel art" re-sample of this face's own texture. let size = bloxdTextureSize(surface.mipLevel); let uv = fract(surface.uv); let texel = bloxdTexel(surface.textureId, uv, surface.mipLevel);

57.3 bloxdTextureId*: named texture constants

Every usable texture name becomes a const you can compare against — spelled CamelCase over the texture’s file name:

Texture fileConstantNote
grass_top.pngbloxdTextureIdGrassTopthe engine’s own example
lava0.png (frames lava0–lava7)bloxdTextureIdLavaanimated family: the frame suffix is dropped from the canonical name
black_portal0.png (frames 0–3)bloxdTextureIdBlackPortalsame rule
radar_screen0 (turned copies [rot[1–[rot[4)bloxdTextureIdRadarScreen0turned family: folds to the root name

The spelling rule, restored from the validator: split the name on every non-alphanumeric run, capitalise each part, concatenate after the bloxdTextureId prefix. Lookup is case- and underscore-insensitive in the other direction (the engine folds your spelling the same way before matching), with three dedicated error families when a spelling doesn’t resolve — all verbatim from the live validator:

Misspelt prefix / wrong case: bloxdTextureIdGrassTop isn't part of the shader pack API. Texture names start with exactly bloxdTextureId: did you mean bloxdTextureIdGrassTop?

A frame of an animated texture: ...names a frame of the animated texture lava: use bloxdTextureIdLava, which bloxdTexel animates.

A turned copy: ...names a turned copy of radar_screen0: use bloxdTextureIdRadarScreen0, which bloxdTexel turns as each face shows it.

Ambiguous after folding: ...could name X and Y, which differ only by case or underscores, so it can't be used.

Not found, with a suggestion: There's no texture called X. Did you mean bloxdTextureIdY? — the suggestion threshold is Levenshtein distance max(2, floor(len/4)) + 1.

Not found, no suggestion: There's no texture called X. Texture names are the file names texture packs use, as in bloxdTextureIdGrassTop for grass_top.png; BLOCK_TEXTURES.md lists them.

That last message points at a file this guide embeds instead: the complete measured catalogue — every one of the 905 usable names with its then-current id, plus the turned and animated family tables — is §68 below; §64 has the registry measurement and the folding rules behind it. The live successor of that catalogue is the Texture catalog.

57.4 The rotation subtlety — and the neutral-sampling helper

bloxdTexel un-rotates the uv you pass by the current fragment’s textureRotation, whatever id you hand it. For the two common cases this is exactly right:

  • Re-sampling this face’s own texture with surface.uv — the uv is in the face’s rotated frame, the un-rotation converts it to the atlas frame, and you get the true texel. This is the intended primary use.
  • Sampling with a uv you computed in atlas terms for a different texture on a face whose rotation isn’t 0 — the un-rotation still fires, and your sample lands rotated. This is the trap.

The engine has no per-texture rotation to consult (rotation is face geometry data, §63.2), so it always uses the fragment’s. To sample another texture rotation-neutrally, pre-rotate your uv by the same quarter-turn — the inverse of the un-rotation — which cancels it:

// Rotation-neutral texel sampling: pre-turn the uv so bloxdTexel's // un-turn (by this face's textureRotation) cancels out. // Pass surface.textureRotation as r from your hook. fn texelNeutral(id: u32, uv: vec2f, mip: f32, r: u32) -> vec4f { var turned = uv; if (r == 1u) { // turn: (x,y) -> (1-y, x) turned = vec2f(1.0 - uv.y, uv.x); } else if (r == 2u) { // (x,y) -> (1-x, 1-y) turned = vec2f(1.0 - uv.x, 1.0 - uv.y); } else if (r == 3u) { // (x,y) -> (y, 1-x) turned = vec2f(uv.y, 1.0 - uv.x); } return bloxdTexel(id, turned, mip); } // usage, inside a surface hook: // let t = texelNeutral(bloxdTextureIdLava, fract(surface.uv), // surface.mipLevel, surface.textureRotation);

(When textureRotation == 0 no compensation is needed. In practice most faces carry 0; turned faces are the minority — but a distribution pack should not assume it.)

57.5 Worked examples

Emission from texel luminance. The engine already multiplies texture × tint × AO into surface.colour; here we instead drive emission from the texture’s own brightness, sampling one mip above the face’s for a soft, blocky average that survives distance:

fn bloxdTerrainSurface(surface: BloxdSurfaceIn) -> BloxdSurface { var out = bloxdDefaultSurface(surface); // +1 mip = quarter resolution: a 4x4-texel average, cheap and stable let avg = bloxdTexel(surface.textureId, surface.uv, surface.mipLevel + 1.0); let lum = dot(avg.rgb, vec3f(0.2126, 0.7152, 0.0722)); if ((surface.blockFlags & bloxdBlockFlagEmissive) != 0u) { // keep the engine look, add a gentle bloom source proportional to the texture itself out.emission += avg.rgb * lum * 0.5; } return out; }

Texture-specific effects. Compare textureId and act only on chosen textures — the v4 replacement for “guess from colour”, and the sanctioned way to make e.g. ores glint:

fn bloxdTerrainLight(surface: BloxdSurface, light: BloxdLightIn) -> BloxdLight { var out = bloxdDefaultLight(surface, light); if (light.textureId == bloxdTextureIdDiamondOre) { // sparkle: phase from world position + time let p = bloxdWorldPosition(light.position); let s = sin(bloxdSeconds() * 3.0 + p.x * 2.7 + p.y * 1.3 + p.z * 4.1); out.colour += vec3f(0.35, 0.45, 0.55) * max(0.0, s); } return out; }

Depth-of-field-style distance blur on terrain detail — read a high mip far away, the native mip up close:

fn bloxdTerrainSurface(surface: BloxdSurfaceIn) -> BloxdSurface { var out = bloxdDefaultSurface(surface); let d = distance(surface.position, bloxdEyePosition()); if (d > 40.0 && surface.textureId != 0u) { // the engine's own texel for this face — carries tint and AO with it let own = bloxdTexel(surface.textureId, surface.uv, surface.mipLevel); if (any(abs(own.rgb - vec3f(0.0)) > vec3f(1e-6))) { // guard the division // blur level rises with distance, up to +3 mips let blur = clamp((d - 40.0) / 60.0, 0.0, 3.0); let t = bloxdTexel(surface.textureId, surface.uv, surface.mipLevel + blur); // restore tint & AO by ratio: (t / own) * colour out.colour = t.rgb / own.rgb * out.colour; } } return out; }

(The ratio trick keeps the engine’s colour = texture × tint × AO intact: dividing the blurred texel by the native texel cancels the texture content, leaving a blur factor you multiply back into surface.colour. On white vec4f(1.0) reads — untextured faces and anti-X-ray-culled faces — the guard skips the effect entirely.)

57.6 Where the texture API does not reach

  • Vertex hooks cannot call it. bloxdTexel / bloxdTextureSize are surface/light-hook functions; a vertex hook reaching them is rejected with the “reaches” diagnostic (§65.3).
  • You cannot add textures. The atlas is the engine’s; the API reads it, nothing more. Custom textures remain the texture-pack system’s job, not the shader pack’s.
  • Non-atlas renderer configurations degrade to stubs. On a configuration where the terrain material isn’t atlas-based, the engine compiles bloxdTextureSize() -> vec2u(1u) and bloxdTexel(...) -> vec4f(1.0) and feeds the four input fields as 0u, 0u, vec2f(0.0), 0.0. Code written against the real atlas still compiles and runs there — it just sees white texels and a 1×1 size. Write such code to tolerate textureId == 0 and it tolerates this too.

58. The four new input fields

Both BloxdSurfaceIn and BloxdLightIn gain the same four trailing fields, quoted from the v4 header (the light struct carries the same quartet the surface struct does — your light hook can act on the texture without plumbing anything through the surface hook):

// These are 0 if the face has no texture. textureId: u32, // This face's texture. Compare with bloxdTextureId*. textureRotation: u32, // Quarter turns clockwise, which bloxdTexel applies. uv: vec2f, // Texture coordinates in blocks; fract(uv) is drawn. mipLevel: f32, // Texture mipmap level. 0 = full size, 1 = half, etc.
  • textureId — the stable, name-derived id (§57.3). 0 on untextured faces; otherwise never 0.
  • textureRotation — 0–3, quarter turns clockwise as the face displays the texture. Comes from geometry/texture-pack overrides (§63.2); same value in both hooks.
  • uv — the interpolated texture coordinate in block units: one block of face area maps to one 1.0 of uv span, so fract(uv) is the within-block texture tile — the header’s own phrasing. On a wall of repeated stone, uv grows along the wall while fract(uv) tiles.
  • mipLevel — the engine’s own choice of mip for this fragment, derived from screen-space derivatives of the texel position and clamped to the atlas’ level range (§63.1 has the exact formula). 0 on screen-filling faces, rising with distance/obliquity. It is a read — you can’t steer the engine’s sampling with it, but you can pass it (or ± n) to bloxdTexel.

Recipe idea unique to v4 — uv-anchored detail patterns that respect the block grid without world coordinates:

// Fine grid keyed to the texture's own tiling: visible on every textured // face, stable under camera motion, and free of floating-point world drift. fn bloxdTerrainSurface(surface: BloxdSurfaceIn) -> BloxdSurface { var out = bloxdDefaultSurface(surface); let cell = fract(surface.uv * 8.0); // 8x8 sub-tiles per block let edge = min(min(cell.x, 1.0 - cell.x), min(cell.y, 1.0 - cell.y)); out.colour *= mix(vec3f(0.86), vec3f(1.0), step(0.06, edge)); return out; }

59. Renames and semantic changes

Four renames, one of which inverts its meaning. Everything else in the header — bloxdPi, bloxdTau, the six bloxdBlockFlag* constants and their bits (1/2/4/8/16/32), bloxdEyePosition / bloxdRenderOffset / bloxdSunDirection / bloxdSeconds, bloxdWorldPosition, the default hooks, the BLOXD_* macro matrix, the 8-variant matrix — is unchanged from v3, and the blockFlags name-classifier rules of §42 carry over verbatim.

v3v4Note
l.fogVisibilityl.fogAlphameaning inverted — port expressions, don’t just rename
bloxdFaceBlock(pos, nrm)bloxdFragmentBlockPosition(pos, nrm)identical body: vec3i(floor(pos - nrm * 0.5)) + bloxdRenderOffset()
behind.foundbehind.hitBloxdOpaqueBehind field rename
header first line—// Engine-provided and read-only, prepended to all packs. apiVersion 3. → // The Bloxd shader pack API, apiVersion 4. Read-only, prepended to all packs.

59.1 fogVisibility → fogAlpha: the inverted one

v3: fogVisibility: f32, // 1 = no fog, 0 = fully fogged. v4: fogAlpha: f32, // 0 = no fog, 1 = only fogColour. The default fog application flipped with it:

// v3 fn bloxdApplyFog(colour: vec3f, light: BloxdLightIn) -> vec3f { return mix(light.fogColour, colour, light.fogVisibility); } // v4 fn bloxdApplyFog(colour: vec3f, light: BloxdLightIn) -> vec3f { return mix(colour, light.fogColour, light.fogAlpha); }

Port table — every v3 fog idiom has a mechanical v4 replacement:

v3 expressionv4 port
l.fogVisibility1.0 - l.fogAlpha
mix(l.fogColour, col, l.fogVisibility)mix(col, l.fogColour, l.fogAlpha) (or bloxdApplyFog(col, l))
mix(l.fogColour, col, max(l.fogVisibility, 0.15)) (fog floor)mix(col, l.fogColour, min(l.fogAlpha, 0.85))
“fog visibility is 1 up close”“fogAlpha is 0 up close”

The fog-distance behaviour is unchanged — same curve, same colours; only the field’s polarity and name moved. Note also the comment change on fogColour: v3 said games “always have fog”; v4 documents 0 when the game has no fog (and the engine indeed feeds vec3f(0.0) when the scene’s fog is off) — relevant if you divide by or compare against fogColour.

59.2 bloxdFaceBlock → bloxdFragmentBlockPosition

A pure rename — the engine’s own doc comment changed from “the world block the face … belongs to” to “identify the block’s world position”, the body is byte-identical, and parameter names remain free. Recipe R4 and every bloxdFaceBlock(l.position, l.normal) call site ports by search-and-replace.

59.3 found → hit

bloxdOpaqueBehind() still returns BloxdOpaqueBehind, still compiled only where BLOXD_SCENE_DEPTH is defined (liquid programs — §60.4), and its implementation is unchanged apart from the field name. Port behind.found → behind.hit and re-read the semantics from the v4 header comments: position and distance are 0 (not “meaningless”) when !hit. R-E (water absorption) and friends port mechanically.

60. The strict-games contract: vertex hooks, discard, and X-ray

Strict games are the rule, not the exception: everything defaults to strict, and only the 12 allow titles enumerated in the game policy list opt out (re-verified verbatim on the v4 bundle, 2026-10-27 — the same 12 titles: Test Gym, Doodle Cube, Rocket Obby, Creative, Bloxd Hop, Fishing, Dress Up, Evil Tower, Plots, Test Mode, Tsunami Steal Brainrots, Work at a Restaurant; every other title — survival, bedwars, skywars, custom games, … — is strict). v4 turns what used to be a documentation-level contract into an enforced one: the bundled validator analyses every strict variant and emits dedicated diagnostics.

60.1 The two enforced rules and their exact diagnostics

bloxdTerrainVertex moves terrain, which strict games prevent.

discard makes terrain see-through, which strict games prevent.

The mechanics, restored from the validator:

  • A vertex hook defined in a strict variant (i.e. not wrapped in #ifndef BLOXD_STRICT) triggers the first message. “Moves terrain” is taken literally: any vertex hook that isn’t the exact default passthrough counts (the check is movesVertices = vertexHook && !isExactDefault — even a hook that returns the input unchanged but through different spelling counts as movement).
  • A discard reachable from the surface or light hooks triggers the second. discard itself is newly legal in v4 for non-strict games — the v1–v3 hard prohibition is gone — but strict games treat it as X-ray (see below).
  • One trip disables everything in strict games. If a strict variant’s analysis produces any such diagnostic, the validator nulls all three hooks for the strict variants: the pack still loads, still runs in allow games, and in strict games does exactly nothing. An unguarded vertex hook therefore doesn’t just lose the sway — it loses your lighting too.
  • Guarded code keeps the rest alive. With the template’s #ifndef BLOXD_STRICT wraps, the strict variants define no vertex hook, produce no diagnostic, and your surface/light hooks keep running in strict games. That is the entire point of the template’s comment: “so our pack can stay on.”

The settings UI walks the author through exactly this. The status line, verbatim:

Off in strict games. To run any other parts of the pack in them, wrap each one listed below in #ifndef BLOXD_STRICT ... #endif

…followed by the offending hook list, each entry optionally suffixed (only in {{variants}}) with the variant axes spelled strict / non-strict, lighting on / off, terrain / liquid. And in-game, when a pack has nothing left to run under the current mode, the chat shows: Your shader pack is off in this game.

60.2 Why: X-ray

Both rules exist for the same reason — in competitive games, a shader that moves terrain or punches holes in it can reveal buried structures and ores: a vertex hook that pulls occluding blocks aside is a wall-hack, and discard on selected fragments is a pinhole X-ray. This is also why the engine’s own template guards only the vertex hooks: surface/light effects (colour, lighting, emission) can’t move geometry, so they’re safe everywhere. The community tutorial channel confirms the policy from the player side — grass-sway packs are the canonical “doesn’t work in strict games” example, and the anti-X-ray culling that strict games perform also hides some textures from the render path entirely, so even texel reads can come back white there. Design for strict-first: treat allow-games-only effects (sway, holes) as progressive enhancement, never as the headline feature.

60.3 What’s not in v4: the shadow API

The same community channel records the engine author as having a shadow-API draft (a bloxd-api companion file) that did not ship in this release, with block/grass shadows expected to arrive together with a future shader-pack API update. Nothing shadow-related exists in the v4 bundle (no shadow symbols, no reserved names beyond §63.4’s list) — treat shadows as announced-but-unshipped, and don’t build distribution packs against them yet. The skyLight-based projected-shadow recipes of R9.12 remain the only shadow look available in v4.

60.4 Strict recap for liquid authors

The macro matrix is unchanged from §46: BLOXD_ALPHA in every liquid variant plus non-strict terrain; BLOXD_SCENE_DEPTH in every liquid variant; BLOXD_STRICT / BLOXD_LIGHTING on their axes. Strict liquid programs still give you alpha and depth — only terrain alpha is strict-gated.

61. v3 → v4 migration checklist

  1. pack.json: "apiVersion": 4 — the number, not a string.
  2. Rename bloxdFaceBlock → bloxdFragmentBlockPosition everywhere (arguments unchanged; parameter names free as always).
  3. Port fog (the silent one — a pack that skips this compiles and looks wrong):
    • every read l.fogVisibility → 1.0 - l.fogAlpha
    • every hand-rolled mix(l.fogColour, col, VIS) → mix(col, l.fogColour, ALPHA) — or better, replace with bloxdApplyFog(col, l) and let the engine own the formula
    • floor/cap idioms invert with the field: max(VIS, 0.15) → min(ALPHA, 0.85)
  4. Port depth recipes: behind.found → behind.hit; position/distance are 0 when !hit.
  5. (Optional) Adopt the texture API: bloxdTexel / bloxdTextureSize / bloxdTextureId* and the four new fields (§57–§58). Remember the rotation subtlety (57.4) and that texel code must tolerate textureId == 0.
  6. Strict audit (required for distribution): wrap every vertex hook in #ifndef BLOXD_STRICT ... #endif; if you use discard, wrap it (or the hook containing it) the same way, or accept that strict games disable the whole pack’s hooks.
  7. In-game compile check across the 8 variants: the loader screen’s “Checking the pack…” validates every variant at once — strict/non-strict × lighting on/off × terrain/liquid — so one pass covers it. Then eyeball one allow game (Test Mode is the fastest) and one strict game.
  8. Bump your own version metadata and re-distribute: stored v3 copies on players’ machines are silently inactive (§55) and only the settings tab says why.

61.1 A complete v3 → v4 port, before and after

// ---- v3 pack: hot sand shimmer + fog-aware emission ---- fn bloxdTerrainSurface(s: BloxdSurfaceIn) -> BloxdSurface { var out = bloxdDefaultSurface(s); if ((s.blockFlags & bloxdBlockFlagSand) != 0u) { let p = bloxdWorldPosition(s.position); out.colour *= 1.0 + 0.04 * sin(p.x * 7.0 + bloxdSeconds() * 2.0); } return out; } fn bloxdTerrainLight(s: BloxdSurface, l: BloxdLightIn) -> BloxdLight { var out = bloxdDefaultLight(s, l); // v3: keep glowing at distance by adding emission AFTER fog let col = mix(l.fogColour, out.colour, l.fogVisibility); out.colour = col + s.emission * l.fogVisibility; return out; }
// ---- v4 port: same look, plus texel-aware sand and a texture guard ---- fn bloxdTerrainSurface(surface: BloxdSurfaceIn) -> BloxdSurface { var out = bloxdDefaultSurface(surface); if ((surface.blockFlags & bloxdBlockFlagSand) != 0u) { let p = bloxdWorldPosition(surface.position); out.colour *= 1.0 + 0.04 * sin(p.x * 7.0 + bloxdSeconds() * 2.0); } // v4 extra: real texture knowledge — darken fine grain on close faces if (surface.textureId != 0u && surface.mipLevel < 1.0) { let t = bloxdTexel(surface.textureId, surface.uv, surface.mipLevel); let grain = abs(dot(t.rgb, vec3f(0.33)) - 0.5); out.colour *= 1.0 - 0.08 * grain; } return out; } fn bloxdTerrainLight(surface: BloxdSurface, light: BloxdLightIn) -> BloxdLight { var out = bloxdDefaultLight(surface, light); // v4: fogAlpha port — emission added after fog, gated by (1 - fogAlpha) let col = mix(out.colour, light.fogColour, light.fogAlpha); out.colour = col + surface.emission * (1.0 - light.fogAlpha); return out; }

Both hooks are surface/light-only, so this pack needs no #ifndef BLOXD_STRICT wraps and runs (with its new texel effects) in strict games too. The textureId != 0u guard covers untextured faces; for strict games’ anti-X-ray culling, style effects should also degrade gracefully if a texel read comes back white despite a non-zero id — branch on ranges and ratios, never on one expected texel value.

62. Other v4 changes and notes

  • The bundle reorg (numbers in the intro) moved the shader pipeline into chunks c49 (loader/persistence), c50–c51 (loader UI + zip), c53 (validator + header + registry builder), c54 (WGSL code generator + Lite renderer). For anyone re-researching the bundle after a v3-era guide: the anchors all moved, the code didn’t.
  • The header text was rewritten for clarity — every doc comment re-worded (terser, second person), no semantic change beyond §59. Size 5,637 → 6,021 bytes, 128 → 150 lines; the first line is now // The Bloxd shader pack API, apiVersion 4. Read-only, prepended to all packs.
  • Emission ordering is now documented in-header: emission: vec3f, // Emissive RGB output, added after lighting, before fog. — v3’s §43 finding, now official wording.
  • i18n surface for the shader-pack feature is 58 keys (v4 build); the loader family (load*) is quoted across §55–§56, the status family (status*) in §55, the variant labels in §60.1.
  • Reference material, embedded (intro): the engine’s error messages cite bloxd-api.wgsl and BLOCK_TEXTURES.md; this guide ships their content instead of citing them — the complete restored header (§67) and the complete measured catalogue (§68) — so nothing external is needed to author or debug a pack.
  • Auto-recheck now also fires on texture-registry changes (§65.1) — a consequence of the registry hash joining HEADER_VERSION. A saved pack can flip to “needs re-check” after an engine update that merely adds textures, even when the header text didn’t change. This is by design: your bloxdTextureId* constants are baked at validation time.
  • bloxdSp* reservation expanded to 27 symbols (§63.4) — the engine-private namespace inside generated shaders. The pack-level reservation rule is unchanged and broader: anything matching /^bloxd/i (case-insensitive) is reserved.

63. Engine internals: how bloxdTexel actually samples

As with §49–§51 for v3, the following is restored verbatim from the production bundle (chunk c54’s code generator, build cnty9, 2026-10-26) and is the deepest public account of the mechanism. Nothing in §57 goes beyond what these snippets prove.

63.1 The generated functions, verbatim

On renderer configurations with the atlas texture mode and no animation, the engine emits exactly:

var<private> bloxdSpTextureRotation: u32; @group(3) @binding(2) var<storage, read> bloxdSpTextureLayers: array<u32>; fn bloxdTextureSize(bloxdSpMipLevel: f32) -> vec2u { return textureDimensions(textureAtlas0, u32(clamp(round(bloxdSpMipLevel), 0.0, f32(textureNumLevels(textureAtlas0) - 1u)))); } fn bloxdTexel(bloxdSpTextureId: u32, bloxdSpUv: vec2f, bloxdSpMipLevel: f32) -> vec4f { if (bloxdSpTextureId == 0u) { return vec4f(1.0); } // Each quarter turn clockwise the face shows its texture at reads the // unturned texture at (v, 1 - u) var bloxdSpTurned = bloxdSpUv; if (bloxdSpTextureRotation == 1u) { bloxdSpTurned = vec2f(bloxdSpUv.y, 1.0 - bloxdSpUv.x); } else if (bloxdSpTextureRotation == 2u) { bloxdSpTurned = 1.0 - bloxdSpUv; } else if (bloxdSpTextureRotation == 3u) { bloxdSpTurned = vec2f(1.0 - bloxdSpUv.y, bloxdSpUv.x); } let bloxdSpLayer = bloxdSpTextureId - 1u; return textureSampleLevel(textureAtlas0, atlasSampler, bloxdSpTurned, bloxdSpLayer, round(bloxdSpMipLevel)); }

With more than one atlas, the tail becomes a layer-window ladder — atlas k owns layers [k * layersPerAtlas, (k+1) * layersPerAtlas):

if (bloxdSpLayer < 2u * layersPerAtlas) { return textureSampleLevel(textureAtlas1, atlasSampler, bloxdSpTurned, bloxdSpLayer - layersPerAtlas, round(bloxdSpMipLevel)); } // ... one rung per atlas, the last one unguarded ... return textureSampleLevel(textureAtlasLast, atlasSampler, bloxdSpTurned, bloxdSpLayer - N * layersPerAtlas, round(bloxdSpMipLevel));

Note what this proves: textureId is the global 1-based layer index across all atlases (bloxdSpLayer = textureId - 1u), and bloxdTextureSize reads atlas 0 only — valid because all atlas tiers share dimensions.

63.2 Where the fragment’s texture quartet comes from

The per-vertex attribute texAtlasIndices (the geometry’s texture-slot index) is resolved through the storage buffer, not used directly:

// vertex stage (injected): vertexOutputs.vPackTexture = bloxdSpTextureLayers[ min(u32(vertexInputs.texAtlasIndices), arrayLength(&bloxdSpTextureLayers) - 1u)];

bloxdSpTextureLayers is filled on the JS side, one u32 per slot, packed exactly as:

layers[slot] = (id & 0xffff) | ((rotation & 3) << 16);

The fragment stage unpacks both halves before your surface hook runs:

// fragment stage (injected, ahead of the surface hook): let bloxdSpTexture = fragmentInputs.vPackTexture; bloxdSpTextureRotation = bloxdSpTexture >> 16u; // -> textureRotation field // BloxdSurfaceIn constructor tail: // bloxdSpTexture & 0xffffu, // textureId // bloxdSpTextureRotation, // textureRotation // fragmentInputs.vMainUV1, // uv // bloxdSpMipLevel // mipLevel (derived below)

and the mip is derived exactly as the engine derives its own:

let bloxdSpTexelUV = fragmentInputs.vMainUV1 * atlasWidth; let bloxdSpDdx = dpdx(bloxdSpTexelUV); let bloxdSpDdy = dpdy(bloxdSpTexelUV); let bloxdSpLod = 0.5 * log2(max(max(dot(bloxdSpDdx, bloxdSpDdx), dot(bloxdSpDdy, bloxdSpDdy)), 1e-10)); let bloxdSpMipLevel = clamp(bloxdSpLod, 0.0, f32(textureNumLevels(textureAtlas0) - 1u));

Two consequences worth internalising: the rotation really is per-slot geometry data (there is no rotation-per-texture lookup anywhere — which is why §57.4’s subtlety exists), and the default (pack-less) terrain shader samples the atlas differently — it uses the pre-rotated layer copies directly at the raw uv, while the pack path normalises to the unturned layer and re-applies rotation in bloxdTexel. Same pixels, two representations.

63.3 Animation: the frame ladder

For animated textures the layer assignment grows a frame computation (this is the entire difference — sampling, rotation, and mip logic are unchanged):

let atlasIdxIn = f32(bloxdSpTextureId - 1u); let animTick = material.anim.x; // animation clock let animTickStride = material.anim.y; let numAnimTextures = material.anim.z; let animParamIndex = 3.0 * min(numAnimTextures, floor(atlasIdxIn)); let animStateMask = animDataPerTex[i32(animParamIndex)]; // frames - 1 let animTexIndexStart = animDataPerTex[i32(animParamIndex + 1.0)]; let animInterval = max(animTickStride, animDataPerTex[i32(animParamIndex + 2.0)]); let animTickForTex = floor((animTickStride / animInterval) * animTick); let animState = animTickForTex - (animStateMask + 1.0) * floor(animTickForTex / (animStateMask + 1.0)); let isAnimTex = min(1.0, animState); let bloxdSpFrame = (1.0 - isAnimTex) * atlasIdxIn + isAnimTex * (animTexIndexStart + animState - 1.0); let bloxdSpLayer = u32(round(bloxdSpFrame));

animDataPerTex (group 2, array<f32>) carries one {mask, startLayer, interval} triplet per animated texture, frames are power-of-two counted (a JS-side build check rejects non-power-of-2 frame counts with <block> has N animation states, which is not a power of 2), and the static-sentinel design means non-animated indices resolve through the same arithmetic without a branch. Pack-facing summary, once more: the id is stable, the frame is automatic. The intervals are engine content, and measured on cnty9 they take exactly three values — 200 ms (lava, toxic_waste, radar_screen), 250 ms (smoke, homestead_core_mid, the machine *_running families), 300 ms (the seventeen portals, toxic_waste_barrel_top) — the per-family column is §68.4.

63.4 The bloxdSp* namespace — all 27 symbols

Everything the generator can inject into your shader, i.e. everything you cannot redeclare (the pack-level /^bloxd/i reservation makes most of this moot, but for engine-source readers this is the complete v4 set, extracted from the generator’s templates):

bloxdSpBehind · bloxdSpDdx · bloxdSpDdy · bloxdSpEye · bloxdSpFrame · bloxdSpLayer · bloxdSpLight · bloxdSpLightIn · bloxdSpLitColour · bloxdSpLod · bloxdSpMipLevel · bloxdSpPixel · bloxdSpPositionW · bloxdSpScale · bloxdSpSceneDepth · bloxdSpSurface · bloxdSpSurfaceIn · bloxdSpTexelUV · bloxdSpTexture · bloxdSpTextureId · bloxdSpTextureLayers · bloxdSpTextureRotation · bloxdSpTurned · bloxdSpUv · bloxdSpVertex · bloxdSpVertexIn · bloxdSpZ

63.5 The full bind-group layout (Lite renderer, pack variant)

GroupBindingResourceNotes
00uniform sceneLiteSceneUniforms — viewProjection / view / vEyePosition
12–3storage quads, quadLightchunk geometry
20uniform materialTerrainMaterialUniforms; anim drives §63.3
21+storage animDataPerTexanimated-texture triplets (animated configs only)
2nexttextureAtlas0..N-1texture_2d_array<f32>, one layer per texture
2nextsampler atlasSamplerthe one sampler bloxdTexel uses
30uniform bloxdPackInputsthe pack’s 64 B per-frame uniform (§56)
31texture_2d<f32> scene depthliquid programs; backs bloxdOpaqueBehind() (§51)
32storage bloxdSpTextureLayersthe id+rotation table (§63.2)

Group 3 is the pack’s group: three engine-provided slots, none of them nameable by pack code.

64. The texture name registry

The engine builds the name catalogue once per session from the block registry — the same pipeline that produced the texture-pack system’s textureNameToIndex. The builder (module 28833 in the bundle), restored as pseudocode:

for each (name, index) in textureNameToIndex: # e.g. ("lava0", 0), ("radar_screen0[rot[2", 19) if name matches /(.*)\[rot\[([1-4])$/ : # a turned copy slot turnedSlot → { id: rootUnturnedId, rotation: N-1 } # §63.2's table entry register alias: name → root, kind "rotation" else if index is an animation frame (not the base): # via animDataPerTex register alias: name → base, kind "frame" else: canonical name = strip trailing "_?0" if this texture is animated named[canonical] = index + 1 # the bloxdTextureId* value

The rules that matter to an author, deduplicated:

  1. Usable names are canonical names: animation bases drop their frame suffix (lava0 → lava), turned families fold to their root (chest_top[rot[1..4] → chest_top), and the two folds compose (radar_screen0[rot[1..4] → radar_screen, because that family is animated as well). Every other file name is itself. The constant spelling then CamelCases the canonical name (§57.3).
  2. Frame and turned aliases are known and error-explained — using one isn’t a “did you mean” guess, it gets the specific frame/turned message (§57.3). This is deliberate API shaping: bloxdTexel handles both animation and turning for you, so addressing a frame or a turned copy directly is always the wrong move.
  3. Ambiguity kills the name: two names that fold to the same case/underscore-insensitive key are both unusable (could name X and Y ... it can't be used). Rare, but real — if a name you expect isn’t in the §68 catalogue, this is one reason.
  4. The id is 1-based and equals “atlas layer + 1”; the no-texture id 0 is reserved as white.

Measured on the live registry (build cnty9, 2026-10-27, by running the engine’s own builder module on the shipped data): 1,219 atlas entries, folding 57 turned families (228 turned spellings) and 42 animated families (188 frame spellings), leaving 905 usable named constants — the complete list, with per-name ids and both family tables, is embedded as §68 below (and, in its current form, as the Texture catalog). The registry-hash mechanism in §65.1 is what keeps baked bloxdTextureId* values from silently going stale as those numbers drift.

65. Validation internals v4: HEADER_VERSION, the registry hash, special functions

65.1 HEADER_VERSION grows a second hash

The v3 format was 6.<fnv1a32> over five inputs (§53). v4 keeps the same five inputs — per-variant header tokens, the parser’s lexical universe, the four macro names, the special-function map, and the BloxdPackInputs declaration — but the prefix moves to 8. and a second FNV-1a-32 is appended, hashed over the sorted "<name> <id>" list of the entire texture registry:

v2 (sjr0p7): 6.bc5e8338 v3 (3ymzdd): 6.5bc26a63 v4 (cnty9): 8.<header-hash>.<registry-hash> ← format restored from the bundle

(The concrete v4 hashes weren’t measured for this guide — they’re runtime-computed — but the format is exact, and the v2/v3 values above are the previously published measurements. Any pack settings screen after an engine update shows the current one.)

The consequence is the important part: a stored pack’s saved validation now also invalidates when the texture registry changes — engine adds textures, renames, re-orders — because your bloxdTextureId* comparisons were resolved against the old registry. The “needs re-check” flow that v3 triggered on header edits now has a second, content-driven trigger. Authors don’t act on this (the engine re-validates automatically); distributors should just expect it.

65.2 Reserved names, again, precisely

The rule is the regex /^bloxd/i — case-insensitive, so BloxdFoo is as reserved as bloxdFoo, and bloxdTextureIdAnything falls under it even when it names nothing (that’s why the misspelt-prefix diagnostic in §57.3 exists as its own message family). The 27-symbol bloxdSp* set of §63.4 is the engine-side complement inside generated code.

65.3 Special functions: now three

The validator’s special-function registry grew from v3’s one entry to three — the texture API’s two functions registered alongside depth:

[ ["bloxdOpaqueBehind", { params: "", returns: "BloxdOpaqueBehind", symbol: "BLOXD_SCENE_DEPTH" }], ["bloxdTexel", { params: "textureId: u32, uv: vec2f, mipLevel: f32", returns: "vec4f", symbol: null }], ["bloxdTextureSize", { params: "mipLevel: f32", returns: "vec2u", symbol: null }] ]

symbol: null means “no variant gate” — callable wherever the function exists (surface/light hooks). The two “reaches” diagnostics carry over verbatim, now also covering texture misuse:

${hook} reaches ${name}, which only surface and light hooks can use. — e.g. bloxdTexel from a vertex hook.

${hook} reaches ${name}, which needs ${symbol}, but this hook also runs on ${program}, which doesn't define it; guard the call with #ifdef ${symbol}. — e.g. bloxdOpaqueBehind() from terrain hooks without the wrap (unchanged from v3 §53).

65.4 What else carries over from v3 §53 unchanged

Hook signature checking (token-exact on types, free on names — the three signature entries are byte-identical to v3’s), the pack_-prefix renaming with diagnostic mapping, the undeclared-identifier message family, the parser’s extra lexical universe (bufferView, bufferArrayView, bufferLength, atomicStoreMax, atomicStoreMin — still not guaranteed in browsers), and the two-stage validation (built-in parser, then the browser’s WGSL compiler — still stricter; §38’s lessons hold).

66. Confirmed constants, limits, and layouts (v4)

The v4 row of the guide’s measurement ledger — everything here measured on cnty9 (2026-10-26, prod = preprod, byte-identical) unless a date is given:

ItemValue
apiVersion4 (strict ===, number)
Engine header6,021 B / 150 lines; first line // The Bloxd shader pack API, apiVersion 4. Read-only, prepended to all packs. — full text embedded in §67
Hooks6 (terrain/liquid × vertex/surface/light); template comment-polished only
Variants8 (strict × lighting × program); names strict|allow.lit|unlit.terrain|liquid
MacrosBLOXD_STRICT (strict) · BLOXD_LIGHTING (lit) · BLOXD_ALPHA (all liquid + non-strict terrain) · BLOXD_SCENE_DEPTH (all liquid)
Pack uniform@group(3) @binding(0), 64 B: seconds@0, renderOffset@16, sunDirection@32, eyePosition@48
Pack bindingsgroup 3: 0 uniform · 1 scene depth (liquid) · 2 bloxdSpTextureLayers storage
blockFlags bitsopaque 1 · emissive 2 · vegetation 4 · dirt 8 · sand 16 · rock 32 (unchanged; §42 name rules carry over)
Loader limits256 .wgsl / 256 KB source / 64 KB pack.json / 32 MB zip / 1,024 zip entries; UTF-8; one manifest; unique paths
Texture registry1,219 entries (measured 2026-10-27, build cnty9) → 905 usable names; complete catalogue: §68 below (current form: Texture catalog)
Light curve0–15 levels → 0–1 on the ease-out curve (6 → 0.45, 12 → 0.92) — in-header, unchanged
Lift curve1 - (1 - x / (3 - 2x))^3 — unchanged, now in chunk c8
Directional cone0.12 / 0.65 / 0.62 / 0.95 — unchanged, now in chunk c8
Fog colourvec3f(183/255, 191/255, 195/255) — unchanged; fogAlpha is the v4 name (§59.1)
Reserved names/^bloxd/i (case-insensitive) + 27 bloxdSp* engine symbols
HEADER_VERSION8.<fnv1a32(header)>.<fnv1a32(texture registry)>
Strict titleseverything except the 12 allow titles listed in Game policy (re-verified 2026-10-27, unchanged)

67. The complete v4 engine header, verbatim

This is the 6,021-byte, 150-line header the engine prepends to every pack, exactly as shipped in cnty9 — the same text whose first line opens // The Bloxd shader pack API, apiVersion 4. Read-only, prepended to all packs. (§66). It is reproduced here in full because a pack author should never have to wonder what the engine declares on their behalf: every free function you may call, every const you may compare against, and both input structs with all their fields and comments are below, in engine order.

Two things are not in this text and never were, because they are generated per renderer configuration at compile time rather than prepended per pack: the bloxdTexel/bloxdTextureSize pair (§63.1 has the verbatim generated WGSL) and the 27 bloxdSp* engine symbols (§63.4). The #ifdef BLOXD_ALPHA gate you see in BloxdSurface and bloxdDefaultSurface is resolved by the engine’s own preprocessor per variant — the canonical text keeps the gate, and §59.1/§56 explain which variants define it.

// The Bloxd shader pack API, apiVersion 4. Read-only, prepended to all packs. const bloxdPi: f32 = 3.1415926535898; const bloxdTau: f32 = 6.2831853071796; // These functions return 1 value per frame, the same for every call site. // The camera's render position. fn bloxdEyePosition() -> vec3f { return bloxdPackInputs.eyePosition; } // Changes as the player travels, so render positions stay close to 0,0,0. // Integer distance, in blocks. Render position + this offset = world position. // See bloxdWorldPosition for how this can be used. fn bloxdRenderOffset() -> vec3i { return bloxdPackInputs.renderOffset; } // This unit vector points towards the sun, in world orientation; 0 when no sun. fn bloxdSunDirection() -> vec3f { return bloxdPackInputs.sunDirection; } // Seconds since the page loaded. As an f32, it has sub-millisecond precision // for the first 4.5 hours. Get a recurring timer using bloxdSeconds() % period. fn bloxdSeconds() -> f32 { return bloxdPackInputs.seconds; } // Each bit of the binary representation of blockFlags is a flag corresponding // to a collection of blocks. The collections overlap, so blocks can be in 0-2+. // (blockFlags & bloxdBlockFlagRock) != 0 // The block has this flag. // (blockFlags & bloxdBlockFlagRock) == 0 // The block doesn't have this flag. // Opaque blocks, leaves and ice included. Not glass, water, spawners, etc. const bloxdBlockFlagOpaque: u32 = 1; // These blocks emit light, e.g. neon, portals, lamps, lava, and glowing ores. const bloxdBlockFlagEmissive: u32 = 2; // 'Leafy', e.g. leaves, and grass blocks. Not cacti, mushroom blocks or hay. const bloxdBlockFlagVegetation: u32 = 4; // Dirt and soil, grass blocks included. Rocky Dirt is both dirt and rock. const bloxdBlockFlagDirt: u32 = 8; // Sand, Red Sand, and every sandstone, which is rock too. const bloxdBlockFlagSand: u32 = 16; // Stone variants, and more, e.g. gravel, ores, sandstone, magma and obsidian. const bloxdBlockFlagRock: u32 = 32; // Convert a render position to a world position, with possible f32 inaccuracy. fn bloxdWorldPosition(position: vec3f) -> vec3f { return position + vec3f(bloxdRenderOffset()); } // Using a fragment's position and normal, identify the block's world position. fn bloxdFragmentBlockPosition(position: vec3f, normal: vec3f) -> vec3i { return vec3i(floor(position - normal * 0.5)) + bloxdRenderOffset(); } struct BloxdVertexIn { position: vec3f, // Render position. normal: vec3f, // Unit vector direction pointing away from the face. blockFlags: u32, // What kind of block. See bloxdBlockFlag*. } struct BloxdVertex { position: vec3f, // The render position output. } struct BloxdSurfaceIn { colour: vec3f, // RGB colour = texture * tint * ambient occlusion. alpha: f32, // Opacity. normal: vec3f, // Unit vector direction pointing away from the face. position: vec3f, // Render position. blockFlags: u32, // What kind of block. See bloxdBlockFlag*. // These are 0 if the face has no texture. textureId: u32, // This face's texture. Compare with bloxdTextureId*. textureRotation: u32, // Quarter turns clockwise, which bloxdTexel applies. uv: vec2f, // Texture coordinates in blocks; fract(uv) is drawn. mipLevel: f32, // Texture mipmap level. 0 = full size, 1 = half, etc. } struct BloxdSurface { colour: vec3f, // RGB colour output. #ifdef BLOXD_ALPHA alpha: f32, // Opacity output. #endif emission: vec3f, // Emissive RGB output, added after lighting, before fog. } // blockLight, skyLight and heldLight are 0-1, from the 0-15 light levels on an // ease-out curve, e.g. 6->0.45, 12->0.92. They all exclude ambientLightColour. struct BloxdLightIn { litColour: vec3f, // RGB surface colour, lit, before emission and fog. directional: f32, // Summed Lambert from directional lights; 0 when off. ambient: vec3f, // RGB ambient colour, added to directional light. blockLight: vec3f, // RGB block light; 0 without BLOXD_LIGHTING. skyLight: f32, // Sky light; 1 without BLOXD_LIGHTING. ambientLightColour: vec3f, // Minimum RGB light; 1 without BLOXD_LIGHTING. skyLightColour: vec3f, // RGB colour of skyLight; 1 without BLOXD_LIGHTING. heldLight: vec3f, // 0 without BLOXD_LIGHTING. 0 with no light source held. fogColour: vec3f, // The game's RGB fog colour. 0 when the game has no fog. fogAlpha: f32, // 0 = no fog, 1 = only fogColour. position: vec3f, // Render position. normal: vec3f, // Unit vector direction pointing away from the face. blockFlags: u32, // What kind of block. See bloxdBlockFlag*. // These are 0 if the face has no texture. textureId: u32, // This face's texture. Compare with bloxdTextureId*. textureRotation: u32, // Quarter turns clockwise, which bloxdTexel applies. uv: vec2f, // Texture coordinates in blocks; fract(uv) is drawn. mipLevel: f32, // Texture mipmap level. 0 = full size, 1 = half, etc. } struct BloxdLight { colour: vec3f, // RGB colour output. } struct BloxdOpaqueBehind { hit: bool, // False where nothing opaque is behind (sky). position: vec3f, // The render position; 0 when !hit. distance: f32, // From the camera; 0 when !hit. } fn bloxdDefaultVertex(vertex: BloxdVertexIn) -> BloxdVertex { return BloxdVertex(vertex.position); } fn bloxdDefaultSurface(surface: BloxdSurfaceIn) -> BloxdSurface { #ifdef BLOXD_ALPHA return BloxdSurface(surface.colour, surface.alpha, vec3f(0.0)); #else return BloxdSurface(surface.colour, vec3f(0.0)); #endif } // Applies this fragment's fog to colour, as the engine does. fn bloxdApplyFog(colour: vec3f, light: BloxdLightIn) -> vec3f { return mix(colour, light.fogColour, light.fogAlpha); } fn bloxdDefaultLight(surface: BloxdSurface, light: BloxdLightIn) -> BloxdLight { return BloxdLight(bloxdApplyFog(light.litColour + surface.emission, light)); }

68. The complete texture catalogue (905 names, measured)

68.1 How to read it

The Name column is the registry name — the handle you actually write. The constant spelling then CamelCases it on _ and - boundaries exactly as §57.3 documents: grass_top → bloxdTextureIdGrassTop, lava → bloxdTextureIdLava, chest_double_top_1_lo → bloxdTextureIdChestDoubleTop1Lo. Names are the API; they survive registry drift because the validator re-resolves them against the live registry at load.

The id column is what that constant compares equal to — the atlas layer + 1, measured on cnty9. Use it to interpret surface.textureId dumps and debug output, and to cross-check a misbehaving pack against today’s build. Do not hardcode it in WGSL: it is a snapshot of one build’s atlas order (§68.5 shows how fast it moves).

The Notes column marks the two folded families. animated (N frames) means sampling this name returns the current animation frame automatically — never address a frame suffix (lava0, radar_screen2), those are known aliases with dedicated diagnostics. turned (4 rotated copies) means the texture exists only as pre-rotated atlas slots; the name addresses the root and bloxdTexel re-applies the rotation (§57.4). One name carries both notes (radar_screen).

What is deliberately absent: the other 416 registry spellings — 188 frame aliases and 228 turned aliases — are not usable constants, and the engine explains each with its specific error message family when you try them (§57.3). The 1,219-row layer table behind everything (including the 171 pre-rotated slots) is engine-internal and covered in §63.2/§63.4.

68.2 The catalogue

Every usable name, alphabetically. The id column is the bloxdTextureId* value — the atlas layer + 1, measured on build cnty9 (2026-10-27). Treat ids as a snapshot, names as the API: between the two October builds measured for this guide, 779 of 1121 unchanged names got a different id (§68.5). The engine resolves names at validation time, so a pack written with names survives registry drift; a pack written with raw ids does not.

Nameid (cnty9)Notes
alloy_kiln_back1091
alloy_kiln_front1085
alloy_kiln_side1086
alloy_kiln_side_running33animated (4 frames)
alloy_kiln_top1087turned (4 rotated copies)
andesite_brick465
apple_block_bottom441
apple_block_side439
apple_block_top440
armour_lucky_block995
armour_lucky_block_rare997
armour_lucky_block_super999
artisan_table_side367
artisan_table_top368
ash1031
auto_bench_back1106
auto_bench_front1100
auto_bench_side1101
auto_bench_side_running35animated (4 frames)
auto_bench_top1102turned (4 rotated copies)
autocrafter_bottom962
autocrafter_lunite_bottom973
autocrafter_lunite_side972
autocrafter_side961
banana_block_side899
banana_block_top900
beacon330
bedrock334
beetroot_block_bottom925
beetroot_block_side923
beetroot_block_top924
belt_drop_side1185
belt_drop_top1184
belt_lift_side1183
belt_lift_top1182
belt_loader_slab_front1110
belt_loader_top1109
belt_tunnel_back1199
belt_tunnel_exit_top1200turned (4 rotated copies)
belt_tunnel_mouth1193
belt_tunnel_side1194
belt_tunnel_top1195turned (4 rotated copies)
black_concrete273
black_glazed_terracotta429turned (4 rotated copies)
black_planks366
black_portal2animated (4 frames)
black_spawn_block_side760
black_spawn_block_top756turned (4 rotated copies)
block_destroyer_tnt_side1017
block_destroyer_tnt_top1018
blue_concrete274
blue_gen_spawn_coal774
blue_gen_spawn_iron775
blue_gen_spawn_top773
blue_glazed_terracotta413turned (4 rotated copies)
blue_lucky_block994
blue_lucky_block_rare996
blue_lucky_block_super998
blue_planks362
blue_portal3animated (4 frames)
blue_spawn_block_side755
blue_spawn_block_top751turned (4 rotated copies)
bone_block_side818
bone_block_top819
bookshelf564
bookshelf_1566
bookshelf_2567
bookshelf_3568
bookshelf_4569
bookshelf_5570
bookshelf_empty565
bouncy_bomb_block591
bowling_alley_floor978
bread_block_back435
bread_block_front434
bread_block_side436
bread_block_top437
brick315
brown_concrete275
brown_glazed_terracotta417turned (4 rotated copies)
brown_mushroom_block536
brown_planks363
brown_portal4animated (4 frames)
brown_spawn_block_side750
brown_spawn_block_top746turned (4 rotated copies)
building_lucky_block989
building_lucky_block_rare991
building_lucky_block_super993
burner_drill_back1048
burner_drill_bottom1047
burner_drill_front1041
burner_drill_side1042
burner_drill_side_running27animated (4 frames)
burner_drill_top1043turned (4 rotated copies)
cactus_dry350
cactus_top349
carrot_block_bottom921
carrot_block_side919
carrot_block_top920
carved_messy_stone827
carved_pumpkin543
chalk839
chalk_black855
chalk_blue854
chalk_bricks_black871
chalk_bricks_blue870
chalk_bricks_brown869
chalk_bricks_cyan868
chalk_bricks_gray867
chalk_bricks_green866
chalk_bricks_light_blue865
chalk_bricks_light_gray864
chalk_bricks_lime863
chalk_bricks_magenta862
chalk_bricks_orange861
chalk_bricks_pink860
chalk_bricks_purple859
chalk_bricks_red858
chalk_bricks_slab_side_black887
chalk_bricks_slab_side_blue886
chalk_bricks_slab_side_brown885
chalk_bricks_slab_side_cyan884
chalk_bricks_slab_side_gray883
chalk_bricks_slab_side_green882
chalk_bricks_slab_side_light_blue881
chalk_bricks_slab_side_light_gray880
chalk_bricks_slab_side_lime879
chalk_bricks_slab_side_magenta878
chalk_bricks_slab_side_orange877
chalk_bricks_slab_side_pink876
chalk_bricks_slab_side_purple875
chalk_bricks_slab_side_red874
chalk_bricks_slab_side_white873
chalk_bricks_slab_side_yellow872
chalk_bricks_white857
chalk_bricks_yellow856
chalk_brown853
chalk_cyan852
chalk_gray851
chalk_green850
chalk_light_blue849
chalk_light_gray848
chalk_lime847
chalk_magenta846
chalk_orange845
chalk_pink844
chalk_purple843
chalk_red842
chalk_white841
chalk_yellow840
charge_vault_side1114
charge_vault_top1113
charging_pad_side1159
charging_pad_top1158
checkpoint_block761turned (4 rotated copies)
cherry_block_bottom590
cherry_block_side588
cherry_block_top589
chest_back347
chest_double_back_hi1219
chest_double_back_lo1218
chest_double_front_hi1213
chest_double_front_lo1212
chest_double_top_1_hi1215
chest_double_top_1_lo1214
chest_double_top_2_hi1217
chest_double_top_2_lo1216
chest_front341
chest_side342
chest_top343turned (4 rotated copies)
chili_pepper_block_bottom678
chili_pepper_block_side676
chili_pepper_block_top677
chiseled_red_sandstone456
chiseled_sandstone325
clay195
coal_block233
coal_deposit1032
coal_ore227
coarse_dirt191
coconut_block_bottom522
coconut_block_side520
coconut_block_top521
code_block679
comet_heart1170
comet_ore1169
compressed_messy_stone530
conveyor_belt_bottom1081
conveyor_belt_slab_side1080
conveyor_belt_top1079
conveyor_belt_turn_left1171
conveyor_belt_turn_right1172
copper_deposit1035
copper_ore1040
corn_block_bottom594
corn_block_side592
corn_block_top593
crafting_table_side338
crafting_table_top339
crate918
crop_harvester_back1192
crop_harvester_back_running45animated (4 frames)
crop_harvester_front1186
crop_harvester_side1187
crop_harvester_side_running44animated (4 frames)
crop_harvester_top1188turned (4 rotated copies)
crusher_back1055
crusher_front1049
crusher_side1050
crusher_side_running28animated (4 frames)
crusher_top1051turned (4 rotated copies)
crystal_block1029
crystal_vat_back1166
crystal_vat_front1160
crystal_vat_side1161
crystal_vat_side_running42animated (4 frames)
crystal_vat_top1162turned (4 rotated copies)
custom_lobby_block_side769
custom_lobby_block_top765turned (4 rotated copies)
cut_red_sandstone457
cut_sandstone453
cyan_concrete276
cyan_gen_spawn_coal783
cyan_gen_spawn_iron784
cyan_gen_spawn_top782
cyan_glazed_terracotta405turned (4 rotated copies)
cyan_planks360
cyan_portal5animated (4 frames)
cyan_spawn_block_side745
cyan_spawn_block_top741turned (4 rotated copies)
dark_green_bricks460
darkstone1206
darkstone_bricks1207
darkstone_bricks_cracked1208
darkstone_bricks_lava1209
darkstone_engraved1210
darkstone_smooth1211
deep_drill_back1140
deep_drill_bottom1139
deep_drill_front1133
deep_drill_side1134
deep_drill_side_running39animated (4 frames)
deep_drill_top1135turned (4 rotated copies)
diamond_block340
diamond_gen_spawn_side807
diamond_gen_spawn_top806
diamond_ore232
diorite_brick463
dirt190
drop_location_block_side814
drop_location_block_top813
drop_pad1038
dry_grass_block980
dry_grass_block_side979
electric_drill_back1099
electric_drill_bottom1098
electric_drill_front1092
electric_drill_side1093
electric_drill_side_running34animated (4 frames)
electric_drill_top1094turned (4 rotated copies)
emerald_block237
emerald_ore231
end_stone226
engraved_andesite464
engraved_diorite462
engraved_granite466
evil_lucky_block1022
evil_lucky_block_face1023
explosive_paint_black_side626
explosive_paint_black_top627
explosive_paint_blue_side624
explosive_paint_blue_top625
explosive_paint_brown_side622
explosive_paint_brown_top623
explosive_paint_cyan_side620
explosive_paint_cyan_top621
explosive_paint_gray_side618
explosive_paint_gray_top619
explosive_paint_green_side616
explosive_paint_green_top617
explosive_paint_light_blue_side614
explosive_paint_light_blue_top615
explosive_paint_light_gray_side612
explosive_paint_light_gray_top613
explosive_paint_lime_side610
explosive_paint_lime_top611
explosive_paint_magenta_side608
explosive_paint_magenta_top609
explosive_paint_orange_side606
explosive_paint_orange_top607
explosive_paint_pink_side604
explosive_paint_pink_top605
explosive_paint_purple_side602
explosive_paint_purple_top603
explosive_paint_quick_black643
explosive_paint_quick_blue642
explosive_paint_quick_brown641
explosive_paint_quick_cyan640
explosive_paint_quick_gray639
explosive_paint_quick_green638
explosive_paint_quick_light_blue637
explosive_paint_quick_light_gray636
explosive_paint_quick_lime635
explosive_paint_quick_magenta634
explosive_paint_quick_orange633
explosive_paint_quick_pink632
explosive_paint_quick_purple631
explosive_paint_quick_red630
explosive_paint_quick_white629
explosive_paint_quick_yellow628
explosive_paint_red_side600
explosive_paint_red_top601
explosive_paint_seeking_black659
explosive_paint_seeking_blue658
explosive_paint_seeking_brown657
explosive_paint_seeking_cyan656
explosive_paint_seeking_gray655
explosive_paint_seeking_green654
explosive_paint_seeking_light_blue653
explosive_paint_seeking_light_gray652
explosive_paint_seeking_lime651
explosive_paint_seeking_magenta650
explosive_paint_seeking_orange649
explosive_paint_seeking_pink648
explosive_paint_seeking_purple647
explosive_paint_seeking_red646
explosive_paint_seeking_white645
explosive_paint_seeking_yellow644
explosive_paint_sticky_black675
explosive_paint_sticky_blue674
explosive_paint_sticky_brown673
explosive_paint_sticky_cyan672
explosive_paint_sticky_gray671
explosive_paint_sticky_green670
explosive_paint_sticky_light_blue669
explosive_paint_sticky_light_gray668
explosive_paint_sticky_lime667
explosive_paint_sticky_magenta666
explosive_paint_sticky_orange665
explosive_paint_sticky_pink664
explosive_paint_sticky_purple663
explosive_paint_sticky_red662
explosive_paint_sticky_white661
explosive_paint_sticky_yellow660
explosive_paint_white_side598
explosive_paint_white_top599
explosive_paint_yellow_side596
explosive_paint_yellow_top597
extra_compressed_messy_stone531
fallen_cherry_leaves_side586
fallen_maple_leaves_side478
farmland433
fast_belt_slab_side1157
fast_belt_top1156
fast_belt_turn_left1173
fast_belt_turn_right1174
fertilised_soil926
finish_block812
fireball_block539
food_lucky_block1007
food_lucky_block_rare1009
food_lucky_block_super1011
forge_hopper_top1168
furnace_front335
furnace_side336
furnace_top337
generator_side1063
generator_side_running30animated (4 frames)
generator_top1064
ghost_chest_back956
ghost_chest_front953
ghost_chest_side954
ghost_chest_top955
ghost_lucky_block957
ghost_mystery_block958
glass294
glass_black295
glass_blue296
glass_brown297
glass_cyan298
glass_gray299
glass_green301
glass_light_blue302
glass_light_gray300
glass_lime303
glass_magenta304
glass_orange305
glass_pink306
glass_purple307
glass_red308
glass_silver311
glass_white309
glass_yellow310
glowstone331
gold_block235
gold_deposit1036
gold_ore229
granite_brick467
grass_block_side192
grass_top193
gravel196
gray_concrete271
gray_gen_spawn_coal792
gray_gen_spawn_iron793
gray_gen_spawn_top791
gray_glazed_terracotta397turned (4 rotated copies)
gray_planks358
gray_portal6animated (4 frames)
gray_spawn_block_side740
gray_spawn_block_top736turned (4 rotated copies)
green_bricks459
green_concrete285
green_glazed_terracotta421turned (4 rotated copies)
green_lucky_block1006
green_lucky_block_rare1008
green_lucky_block_super1010
green_planks364
green_portal7animated (4 frames)
green_spawn_block_side735
green_spawn_block_top731turned (4 rotated copies)
green_stone458
grenade_block581
grey_portal8animated (4 frames)
gun_lucky_block952
hardened_clay254
hardened_clay_stained_black270
hardened_clay_stained_blue266
hardened_clay_stained_brown267
hardened_clay_stained_cyan264
hardened_clay_stained_gray262
hardened_clay_stained_green268
hardened_clay_stained_light_blue258
hardened_clay_stained_lime260
hardened_clay_stained_magenta257
hardened_clay_stained_orange256
hardened_clay_stained_pink261
hardened_clay_stained_purple265
hardened_clay_stained_red269
hardened_clay_stained_silver263
hardened_clay_stained_white255
hardened_clay_stained_yellow259
harvester_bottom969
harvester_lunite_bottom977
harvester_lunite_side_0974
harvester_lunite_side_1975
harvester_lunite_top976
harvester_side0966
harvester_side1967
harvester_top968
hay_block_side328
homestead_core1037
homestead_core_cap1122
homestead_core_crown1121
homestead_core_mid26animated (4 frames)
hyper_compressed_messy_stone533
ice326
ice_brick468
iceball_block540
invisible_solid314
iron_block234
iron_chest_back917
iron_chest_front911
iron_chest_side912
iron_chest_top913turned (4 rotated copies)
iron_deposit1033
iron_ore228
iron_watermelon_side546
iron_watermelon_top547
jungle_grass_block889
jungle_grass_block_side888
lapis_block236
lapis_ore230
lava1animated (8 frames)
leather_block_side908
leather_block_top909
leaves_aspen288
leaves_aspen_autumn910
leaves_cedar470
leaves_cherry585
leaves_cherry_fruity906
leaves_jungle290
leaves_mango894
leaves_mango_fruity907
leaves_maple289
leaves_maple_autumn477
leaves_maple_fruity901
leaves_palm471
leaves_palm_fruity904
leaves_pear525
leaves_pear_fruity905
leaves_pine287
leaves_pine_cone902
leaves_plum469
leaves_plum_fruity903
leaves_spectral831
light_blue_concrete277
light_blue_glazed_terracotta381turned (4 rotated copies)
light_blue_lucky_block933
light_blue_planks354
light_blue_spawn_block_side730
light_blue_spawn_block_top726turned (4 rotated copies)
light_gray_concrete272
light_gray_glazed_terracotta401turned (4 rotated copies)
light_gray_planks359
light_gray_spawn_block_side725
light_gray_spawn_block_top721turned (4 rotated copies)
lightblue_portal9animated (4 frames)
lightgray_portal10animated (4 frames)
lime_concrete278
lime_gen_spawn_coal777
lime_gen_spawn_iron778
lime_gen_spawn_top776
lime_glazed_terracotta389turned (4 rotated copies)
lime_planks356
lime_portal11animated (4 frames)
lime_spawn_block_side720
lime_spawn_block_top716turned (4 rotated copies)
log_ancient_maple1021
log_aspen202
log_cedar201
log_cherry582
log_jungle203
log_mango891
log_maple198
log_palm472
log_pear523
log_pine199
log_plum200
log_spectral828
lucky_block_pink_question959
lucky_block_pink_question_rare1013
lucky_block_pink_question_super1015
lunite_block971
lunite_ore970
machine_bench_side1115
machine_bench_top1116
machine_side1039
magenta_concrete279
magenta_glazed_terracotta377turned (4 rotated copies)
magenta_planks353
magenta_portal12animated (4 frames)
magenta_spawn_block_side715
magenta_spawn_block_top711turned (4 rotated copies)
magma451
mailbox_front571
mailbox_front_full573
mailbox_side572
mango_block_bottom898
mango_block_side896
mango_block_top897
mega_compressed_messy_stone535
melon_side544
melon_top545
melting_ice595
messy_stone216
mob_spawner_block_empty_side823
mob_spawner_block_top821
mob_spawner_hostile_block_side822
mob_spawner_neutral_block_side838
mob_spawner_passive_block_side820
moonstone_block450
moonstone_chest_back449
moonstone_chest_front443
moonstone_chest_side444
moonstone_chest_top445turned (4 rotated copies)
moonstone_explosive_side332
moonstone_explosive_top333
moonstone_gen_spawn_side809
moonstone_gen_spawn_top808
moonstone_ore442
mossy_cobblestone438
mushroom_stem538
mystery_block578
neon_black951
neon_blue950
neon_brown949
neon_cyan948
neon_gray947
neon_green946
neon_light_blue945
neon_light_gray944
neon_lime943
neon_magenta942
neon_orange941
neon_pink940
neon_purple939
neon_red938
neon_white937
neon_yellow936
nether_brick317
netherrack318
obby_absorb_block816
obby_absorb_death_block817
obby_death_block815
obsidian327
orange_concrete280
orange_glazed_terracotta373turned (4 rotated copies)
orange_lucky_block1000
orange_lucky_block_rare1002
orange_lucky_block_super1004
orange_planks352
orange_portal13animated (4 frames)
orange_spawn_block_side710
orange_spawn_block_top706turned (4 rotated copies)
ore_gen_spawn_side811
ore_gen_spawn_top810
packed_snow826
parts_bench_side1117
parts_bench_top1118
patterned_glass_black548
patterned_glass_blue549
patterned_glass_brown550
patterned_glass_cyan551
patterned_glass_gray552
patterned_glass_green554
patterned_glass_light_blue555
patterned_glass_light_gray553
patterned_glass_lime556
patterned_glass_magenta557
patterned_glass_orange558
patterned_glass_pink559
patterned_glass_purple560
patterned_glass_red561
patterned_glass_white562
patterned_glass_yellow563
pear_block_bottom529
pear_block_side527
pear_block_top528
pet_lucky_block960
pine_cone_block_side836
pine_cone_block_top837
pine_grass_block834
pine_grass_block_side833
pink_concrete281
pink_gen_spawn_coal789
pink_gen_spawn_iron790
pink_gen_spawn_top788
pink_glazed_terracotta393turned (4 rotated copies)
pink_planks357
pink_portal14animated (4 frames)
pink_spawn_block_side705
pink_spawn_block_top701turned (4 rotated copies)
planks_aspen205
planks_cedar209
planks_cherry584
planks_jungle207
planks_mango893
planks_maple204
planks_palm473
planks_pear524
planks_pine208
planks_plum206
planks_spectral830
plum_block_bottom519
plum_block_side517
plum_block_top518
podzol_top452
potato_block922
potion_lucky_block1012
potion_lucky_block_rare1014
potion_lucky_block_super1016
press_back1071
press_front1065
press_side1066
press_side_running31animated (4 frames)
press_top1067turned (4 rotated copies)
protector348
protector_faction575
protector_tribe574
pumpkin_face_on291
pumpkin_side541
pumpkin_top542
pure_coal_ore1024
pure_copper_ore1204
pure_diamond_ore1027
pure_gold_ore1026
pure_iron_ore1025
pure_moonstone_ore1028
pure_voltite_ore1205
purple_concrete282
purple_glazed_terracotta409turned (4 rotated copies)
purple_lucky_block988
purple_lucky_block_rare990
purple_lucky_block_super992
purple_planks361
purple_portal15animated (4 frames)
purple_spawn_block_side700
purple_spawn_block_top696turned (4 rotated copies)
quartz_block_chiseled320
quartz_block_side319
radar_bottom929
radar_screen19animated (4 frames) · turned (4 rotated copies)
radar_side_active927
radar_side_inactive930
radar_top_active928
radar_top_inactive931
recycler_back1181
recycler_front1175
recycler_side1176
recycler_side_running43animated (4 frames)
recycler_top1177turned (4 rotated copies)
red_concrete283
red_gen_spawn_coal771
red_gen_spawn_iron772
red_gen_spawn_top770
red_glazed_terracotta425turned (4 rotated copies)
red_lucky_block934
red_lucky_block_rare984
red_lucky_block_super986
red_mushroom_block537
red_planks365
red_portal16animated (4 frames)
red_sand474
red_sandstone454
red_sandstone_brick475
red_sandstone_top455
red_spawn_block_side695
red_spawn_block_top691turned (4 rotated copies)
redstone_lamp_off313
redstone_lamp_on312
rocket_block579
rocky_dirt476
rope_block1030
sand194
sandstone_brick461
sandstone_normal225
sandstone_top324
shatter_mill_back1147
shatter_mill_front1141
shatter_mill_side1142
shatter_mill_side_running40animated (4 frames)
shatter_mill_top1143turned (4 rotated copies)
shop_trader_spawn_face799
shop_trader_spawn_side798
shop_trader_spawn_top794turned (4 rotated copies)
shop_wizard_spawn_face805
shop_wizard_spawn_side804
shop_wizard_spawn_top800turned (4 rotated copies)
sky_tap_back1155
sky_tap_bottom1154
sky_tap_front1148
sky_tap_side1149
sky_tap_side_running41animated (4 frames)
sky_tap_top1150turned (4 rotated copies)
slab_andesite_brick_side498
slab_aspen_side483
slab_brick_side515
slab_cedar_side482
slab_cherry_side587
slab_chiseled_red_sandstone_side512
slab_chiseled_sandstone_side508
slab_cobblestone_side488
slab_cut_red_sandstone_side513
slab_cut_sandstone_side509
slab_diorite_brick_side502
slab_dirt_side486
slab_dry_grass_top_side981
slab_engraved_andesite_side497
slab_engraved_diorite_side501
slab_engraved_granite_side505
slab_granite_brick_side506
slab_grass_top_side487
slab_ice_brick_side516
slab_jungle_grass_top_side890
slab_jungle_side484
slab_mango_side895
slab_maple_side479
slab_mossy_cobblestone_side493
slab_palm_side485
slab_pear_side526
slab_pine_grass_top_side835
slab_pine_side480
slab_plum_side481
slab_red_sandstone_brick_side514
slab_red_sandstone_side511
slab_sandstone_brick_side510
slab_sandstone_normal_side507
slab_smooth_stone_side490
slab_spectral_side832
slab_stone_andesite_side495
slab_stone_andesite_smooth_side496
slab_stone_diorite_side499
slab_stone_diorite_smooth_side500
slab_stone_granite_side503
slab_stone_granite_smooth_side504
slab_stone_side489
slab_stonebrick_carved_side491
slab_stonebrick_mossy_side494
slab_stonebrick_side492
smelter_back1062
smelter_front1056
smelter_side1057
smelter_side_running29animated (4 frames)
smelter_top1058turned (4 rotated copies)
smoke23animated (4 frames)
smooth_stone218
snow197
snowy_messy_stone824
snowy_messy_stone_side825
solar_panel_bottom965
solar_panel_side963
solar_panel_top964
sorting_gate_slab_side1108
sorting_gate_top1107
splitter_slab_side1083
splitter_top1082
sponge329
starframe1167
stone217
stone_andesite221
stone_andesite_smooth222
stone_deposit1034
stone_diorite219
stone_diorite_smooth220
stone_granite223
stone_granite_smooth224
stonebrick316
stonebrick_carved321
stonebrick_cracked323
stonebrick_mossy322
storage_silo_side1112
storage_silo_top1111
stripped_aspen_log211
stripped_cedar_log215
stripped_cherry_log583
stripped_jungle_log213
stripped_mango_log892
stripped_maple_log210
stripped_palm_log576
stripped_pear_log577
stripped_pine_log214
stripped_plum_log212
stripped_spectral_log829
super_compressed_messy_stone532
super_rocket_block580
tool_bench_side1119
tool_bench_top1120
tools_lucky_block1001
tools_lucky_block_rare1003
tools_lucky_block_super1005
toxic_waste25animated (8 frames)
toxic_waste_barrel_bottom1020
toxic_waste_barrel_side1019
toxic_waste_barrel_top24animated (4 frames)
toxin_ball_block680
tree_cutter_back1129
tree_cutter_back_running37animated (4 frames)
tree_cutter_front1123
tree_cutter_side1124
tree_cutter_side_running36animated (4 frames)
tree_cutter_top1125turned (4 rotated copies)
ultra_compressed_messy_stone534
unloaded189
volt_engine_side1131
volt_engine_side_running38animated (4 frames)
volt_engine_top1132
voltite_deposit1130
voltite_ore1084
watermelon_side292
watermelon_top293
weapon_lucky_block935
weapon_lucky_block_rare985
weapon_lucky_block_super987
white_concrete284
white_gen_spawn_coal786
white_gen_spawn_iron787
white_gen_spawn_top785
white_glazed_terracotta369turned (4 rotated copies)
white_planks351
white_portal17animated (4 frames)
white_spawn_block_side690
white_spawn_block_top686turned (4 rotated copies)
wire_mill_back1078
wire_mill_front1072
wire_mill_side1073
wire_mill_side_running32animated (4 frames)
wire_mill_top1074turned (4 rotated copies)
wool_colored_black253
wool_colored_blue249
wool_colored_brown250
wool_colored_cyan247
wool_colored_gray245
wool_colored_green251
wool_colored_light_blue241
wool_colored_light_grey246
wool_colored_lime243
wool_colored_magenta240
wool_colored_orange239
wool_colored_pink244
wool_colored_purple248
wool_colored_red252
wool_colored_white238
wool_colored_yellow242
yellow_concrete286
yellow_gen_spawn_coal780
yellow_gen_spawn_iron781
yellow_gen_spawn_top779
yellow_glazed_terracotta385turned (4 rotated copies)
yellow_lucky_block932
yellow_lucky_block_rare982
yellow_lucky_block_super983
yellow_planks355
yellow_portal18animated (4 frames)
yellow_spawn_block_side685
yellow_spawn_block_top681turned (4 rotated copies)

68.3 Turned families (57 roots)

These textures exist only as pre-rotated copies (name[rot[1..4). The registry folds them to the root below; bloxdTexel re-applies the rotation when sampling (§57.4), so you address the root and never the copies. Aliasing one of the [rot[N spellings gets the dedicated turned-name diagnostic (§57.3).

  • alloy_kiln_top (id 1087)
  • auto_bench_top (id 1102)
  • belt_tunnel_exit_top (id 1200)
  • belt_tunnel_top (id 1195)
  • black_glazed_terracotta (id 429)
  • black_spawn_block_top (id 756)
  • blue_glazed_terracotta (id 413)
  • blue_spawn_block_top (id 751)
  • brown_glazed_terracotta (id 417)
  • brown_spawn_block_top (id 746)
  • burner_drill_top (id 1043)
  • checkpoint_block (id 761)
  • chest_top (id 343)
  • crop_harvester_top (id 1188)
  • crusher_top (id 1051)
  • crystal_vat_top (id 1162)
  • custom_lobby_block_top (id 765)
  • cyan_glazed_terracotta (id 405)
  • cyan_spawn_block_top (id 741)
  • deep_drill_top (id 1135)
  • electric_drill_top (id 1094)
  • gray_glazed_terracotta (id 397)
  • gray_spawn_block_top (id 736)
  • green_glazed_terracotta (id 421)
  • green_spawn_block_top (id 731)
  • iron_chest_top (id 913)
  • light_blue_glazed_terracotta (id 381)
  • light_blue_spawn_block_top (id 726)
  • light_gray_glazed_terracotta (id 401)
  • light_gray_spawn_block_top (id 721)
  • lime_glazed_terracotta (id 389)
  • lime_spawn_block_top (id 716)
  • magenta_glazed_terracotta (id 377)
  • magenta_spawn_block_top (id 711)
  • moonstone_chest_top (id 445)
  • orange_glazed_terracotta (id 373)
  • orange_spawn_block_top (id 706)
  • pink_glazed_terracotta (id 393)
  • pink_spawn_block_top (id 701)
  • press_top (id 1067)
  • purple_glazed_terracotta (id 409)
  • purple_spawn_block_top (id 696)
  • radar_screen0 (id 19) · also animated
  • recycler_top (id 1177)
  • red_glazed_terracotta (id 425)
  • red_spawn_block_top (id 691)
  • shatter_mill_top (id 1143)
  • shop_trader_spawn_top (id 794)
  • shop_wizard_spawn_top (id 800)
  • sky_tap_top (id 1150)
  • smelter_top (id 1058)
  • tree_cutter_top (id 1125)
  • white_glazed_terracotta (id 369)
  • white_spawn_block_top (id 686)
  • wire_mill_top (id 1074)
  • yellow_glazed_terracotta (id 385)
  • yellow_spawn_block_top (id 681)

68.4 Animated families (42 names)

Sampling one of these names returns the current animation frame automatically (§63.3’s frame ladder). The engine advances frames per texture at a fixed, per-family interval — measured on cnty9 it takes exactly three values: 200 ms (lava, toxic_waste, radar_screen), 250 ms (smoke, homestead_core_mid, every machine *_running family), 300 ms (the seventeen portals and toxic_waste_barrel_top) — see the Interval column — so packs never address a frame suffix (lava0 is an error; lava is the name).

NameFramesIntervalRegistry base
lava8200 mslava0
toxic_waste8200 mstoxic_waste0
alloy_kiln_side_running4250 msalloy_kiln_side_running0
auto_bench_side_running4250 msauto_bench_side_running0
black_portal4300 msblack_portal0
blue_portal4300 msblue_portal0
brown_portal4300 msbrown_portal0
burner_drill_side_running4250 msburner_drill_side_running0
crop_harvester_back_running4250 mscrop_harvester_back_running0
crop_harvester_side_running4250 mscrop_harvester_side_running0
crusher_side_running4250 mscrusher_side_running0
crystal_vat_side_running4250 mscrystal_vat_side_running0
cyan_portal4300 mscyan_portal0
deep_drill_side_running4250 msdeep_drill_side_running0
electric_drill_side_running4250 mselectric_drill_side_running0
generator_side_running4250 msgenerator_side_running0
gray_portal4300 msgray_portal0
green_portal4300 msgreen_portal0
grey_portal4300 msgrey_portal0
homestead_core_mid4250 mshomestead_core_mid0
lightblue_portal4300 mslightblue_portal0
lightgray_portal4300 mslightgray_portal0
lime_portal4300 mslime_portal0
magenta_portal4300 msmagenta_portal0
orange_portal4300 msorange_portal0
pink_portal4300 mspink_portal0
press_side_running4250 mspress_side_running0
purple_portal4300 mspurple_portal0
radar_screen4200 msradar_screen0[rot[1
recycler_side_running4250 msrecycler_side_running0
red_portal4300 msred_portal0
shatter_mill_side_running4250 msshatter_mill_side_running0
sky_tap_side_running4250 mssky_tap_side_running0
smelter_side_running4250 mssmelter_side_running0
smoke4250 mssmoke0
toxic_waste_barrel_top4300 mstoxic_waste_barrel_top0
tree_cutter_back_running4250 mstree_cutter_back_running0
tree_cutter_side_running4250 mstree_cutter_side_running0
volt_engine_side_running4250 msvolt_engine_side_running0
white_portal4300 mswhite_portal0
wire_mill_side_running4250 mswire_mill_side_running0
yellow_portal4300 msyellow_portal0

One structural note the raw data makes visible: the atlas holds 45 animated roots, not 42 — radar_screen’s four pre-rotated copies each carry their own 4-frame ladder, which is also why radar_screen is the one name bearing both family notes.

68.5 Registry drift, measured (sjr0p7 → cnty9)

The registry is content shipped with the build, so it drifts with block updates. The two builds this guide measured (2026-10-17 and 2026-10-27, ten days apart) show exactly how fast:

  • Entries: 1200 → 1219 (98 added, 79 removed)
  • Names that kept their spelling: 1121 — of which 779 changed id (69%)
  • A naming convention migrated mid-month: 68 _rot1..4 suffix names (e.g. chest_top_rot1) became [rot[1..4 slots (e.g. chest_top[rot[1), and the double-chest textures (chest_double_*, 8 entries) appeared with them
  • The usable-name count moved 900 → 905, and the registry hash in HEADER_VERSION (§65.1) re-invalidated every saved pack that had baked ids

That last point is the operational lesson: write bloxdTextureIdLava, not 19 — a name-constant survives every one of those bullets unchanged, because the validator re-resolves it against the live registry at load.

68.6 The drift lists, in full (98 added, 79 removed)

§68.5’s headline numbers, spelled out name by name — because a texture-pack author updating an October pack needs to know exactly which file names stopped matching. The lists compare the spelling layer (the file names texture packs use); §64’s folding rules are what turn spellings into the usable constants of §68.2.

Turned-fold migration — 17 machine tops (68 spellings out, 68 slots in). alloy_kiln_top, auto_bench_top, belt_tunnel_exit_top, belt_tunnel_top, burner_drill_top, crop_harvester_top, crusher_top, crystal_vat_top, deep_drill_top, electric_drill_top, press_top, recycler_top, shatter_mill_top, sky_tap_top, smelter_top, tree_cutter_top, wire_mill_top moved from _rot1..4 variant spellings to [rot[1..4 pre-rotated slots; the folded root is the usable name, so a texture pack now ships one X_top.png instead of four X_top_rotN.png files.

Chest tops folded — 3 families (6 spellings out, 12 slots in). chest_top_1/chest_top_2 → chest_top, iron_chest_top_1/_2 → iron_chest_top, moonstone_chest_top_1/_2 → moonstone_chest_top: the two-variant spellings became pre-rotated slots under the root — rename the PNG files accordingly.

New textures — 17 names. The double chest (chest_double_back_hi/_lo, chest_double_front_hi/_lo, chest_double_top_1_hi/_lo, chest_double_top_2_hi/_lo), the darkstone family (darkstone, darkstone_bricks, darkstone_bricks_cracked, darkstone_bricks_lava, darkstone_engraved, darkstone_smooth), pure_copper_ore, pure_voltite_ore, and forge_hopper_top.

One plain fold. ghost_chest_top_1/ghost_chest_top_2 collapsed to a single ghost_chest_top.

Removed outright — 3 names. shaft_hopper_top, sun_panel_side, sun_panel_top have no successor spelling in the new registry — the content left the game with this build. forge_hopper_top is a genuinely new texture, not a verified rename.

The raw spelling diff, for verification:

+ 98 added (cnty9): alloy_kiln_top[rot[1, alloy_kiln_top[rot[2, alloy_kiln_top[rot[3, alloy_kiln_top[rot[4, auto_bench_top[rot[1, auto_bench_top[rot[2 auto_bench_top[rot[3, auto_bench_top[rot[4, belt_tunnel_exit_top[rot[1, belt_tunnel_exit_top[rot[2, belt_tunnel_exit_top[rot[3, belt_tunnel_exit_top[rot[4 belt_tunnel_top[rot[1, belt_tunnel_top[rot[2, belt_tunnel_top[rot[3, belt_tunnel_top[rot[4, burner_drill_top[rot[1, burner_drill_top[rot[2 burner_drill_top[rot[3, burner_drill_top[rot[4, chest_double_back_hi, chest_double_back_lo, chest_double_front_hi, chest_double_front_lo chest_double_top_1_hi, chest_double_top_1_lo, chest_double_top_2_hi, chest_double_top_2_lo, chest_top[rot[1, chest_top[rot[2 chest_top[rot[3, chest_top[rot[4, crop_harvester_top[rot[1, crop_harvester_top[rot[2, crop_harvester_top[rot[3, crop_harvester_top[rot[4 crusher_top[rot[1, crusher_top[rot[2, crusher_top[rot[3, crusher_top[rot[4, crystal_vat_top[rot[1, crystal_vat_top[rot[2 crystal_vat_top[rot[3, crystal_vat_top[rot[4, darkstone, darkstone_bricks, darkstone_bricks_cracked, darkstone_bricks_lava darkstone_engraved, darkstone_smooth, deep_drill_top[rot[1, deep_drill_top[rot[2, deep_drill_top[rot[3, deep_drill_top[rot[4 electric_drill_top[rot[1, electric_drill_top[rot[2, electric_drill_top[rot[3, electric_drill_top[rot[4, forge_hopper_top, ghost_chest_top iron_chest_top[rot[1, iron_chest_top[rot[2, iron_chest_top[rot[3, iron_chest_top[rot[4, moonstone_chest_top[rot[1, moonstone_chest_top[rot[2 moonstone_chest_top[rot[3, moonstone_chest_top[rot[4, press_top[rot[1, press_top[rot[2, press_top[rot[3, press_top[rot[4 pure_copper_ore, pure_voltite_ore, recycler_top[rot[1, recycler_top[rot[2, recycler_top[rot[3, recycler_top[rot[4 shatter_mill_top[rot[1, shatter_mill_top[rot[2, shatter_mill_top[rot[3, shatter_mill_top[rot[4, sky_tap_top[rot[1, sky_tap_top[rot[2 sky_tap_top[rot[3, sky_tap_top[rot[4, smelter_top[rot[1, smelter_top[rot[2, smelter_top[rot[3, smelter_top[rot[4 tree_cutter_top[rot[1, tree_cutter_top[rot[2, tree_cutter_top[rot[3, tree_cutter_top[rot[4, wire_mill_top[rot[1, wire_mill_top[rot[2 wire_mill_top[rot[3, wire_mill_top[rot[4 - 79 removed (sjr0p7): alloy_kiln_top_rot1, alloy_kiln_top_rot2, alloy_kiln_top_rot3, alloy_kiln_top_rot4, auto_bench_top_rot1, auto_bench_top_rot2 auto_bench_top_rot3, auto_bench_top_rot4, belt_tunnel_exit_top_rot1, belt_tunnel_exit_top_rot2, belt_tunnel_exit_top_rot3, belt_tunnel_exit_top_rot4 belt_tunnel_top_rot1, belt_tunnel_top_rot2, belt_tunnel_top_rot3, belt_tunnel_top_rot4, burner_drill_top_rot1, burner_drill_top_rot2 burner_drill_top_rot3, burner_drill_top_rot4, chest_top_1, chest_top_2, crop_harvester_top_rot1, crop_harvester_top_rot2 crop_harvester_top_rot3, crop_harvester_top_rot4, crusher_top_rot1, crusher_top_rot2, crusher_top_rot3, crusher_top_rot4 crystal_vat_top_rot1, crystal_vat_top_rot2, crystal_vat_top_rot3, crystal_vat_top_rot4, deep_drill_top_rot1, deep_drill_top_rot2 deep_drill_top_rot3, deep_drill_top_rot4, electric_drill_top_rot1, electric_drill_top_rot2, electric_drill_top_rot3, electric_drill_top_rot4 ghost_chest_top_1, ghost_chest_top_2, iron_chest_top_1, iron_chest_top_2, moonstone_chest_top_1, moonstone_chest_top_2 press_top_rot1, press_top_rot2, press_top_rot3, press_top_rot4, recycler_top_rot1, recycler_top_rot2 recycler_top_rot3, recycler_top_rot4, shaft_hopper_top, shatter_mill_top_rot1, shatter_mill_top_rot2, shatter_mill_top_rot3 shatter_mill_top_rot4, sky_tap_top_rot1, sky_tap_top_rot2, sky_tap_top_rot3, sky_tap_top_rot4, smelter_top_rot1 smelter_top_rot2, smelter_top_rot3, smelter_top_rot4, sun_panel_side, sun_panel_top, tree_cutter_top_rot1 tree_cutter_top_rot2, tree_cutter_top_rot3, tree_cutter_top_rot4, wire_mill_top_rot1, wire_mill_top_rot2, wire_mill_top_rot3 wire_mill_top_rot4