Skip to Content
Bloxd.io Shader Pack Documentation

Bloxd.io Shader Pack Documentation

An unofficial guide to shader packs for the Bloxd.io WebGPU renderer — from creating, implementing, validating and distributing packs to the API specification and engine-internals research.

Current spec

  • Current API: 5 (pack.json must declare apiVersion: 5)
  • Target: WebGPU renderer
  • Last verified: 2026-11-20
  • Target build: bbb6l5.main.0244a119.js (production and preprod, verified 2026-11-20 — registry, header, hooks, limits and the new shadow API re-measured)
  • Shader hooks: 9 (Terrain / Liquid / Model × Vertex / Surface / Light)

New to shader packs? Start with Getting Started. Looking up the API? Start with API Reference.

This documentation is not an official resource from the game’s developers. Engine internals may change with updates — check the target build and verification status noted on each page.

This guide was created with AI assistance; accuracy is not guaranteed. Verify against actual in-game behavior. Keep verifying recipes against the loader screen and in-game compilation.

The shader pack feature itself is an official feature accessible from the in-game UI, and packs are pure WGSL (no JS execution, no networking), so nothing dangerous happens with normal code.

Entry points by goal

GoalCategoryAudience
Make your first shader packGetting StartedFirst-time pack authors
Look up API functions & fieldsAPI ReferenceAuthors mid-implementation
Implement an effect (light, water, models…)Guides · RecipesAnyone building a look
Fix an errorTroubleshootingAnyone with a broken pack
Research engine internalsEngine Internals & ResearchEngine analysts
Look up older versions (v1–v5)Version HistoryMigrating legacy packs

Documentation map

  • Getting Started — overview, quick start, pack structure, pack.json, the 9 hooks, variants, validation, distribution. A single-track tutorial to your first pack.
  • API Reference — the systematic v5 specification: hooks, flags, input/output structures, all functions, lighting, texture API, constants, preprocessor, restrictions, compatibility, and the 911-name texture catalog.
  • Guides — how lighting works, shadows, water, night, model rendering, performance, realism concepts.
  • Recipes — goal-oriented code examples: colors, lighting, emission, coordinates, animation, liquids, vertices, math, realism, model shaders, enchant effects.
  • Troubleshooting — symptom-driven error resolution: loading, API version, compilation, validation, variants, visual, texture, lighting, model, performance.
  • Engine Internals & Research — rendering pipeline, hook invocation, engine header, validation & compilation internals, reserved identifiers, lighting/fog internals, texture sampling & registry, model rendering, measured data.
  • Version History — v1 through v5: changes per version, migration steps, removed APIs.

Verification status labels

Each page notes its target API version, build, last-verified date and status.

LabelMeaning
VerifiedVerified on-device / on the target build
AnalyzedConfirmed by analyzing the internal implementation
Partially VerifiedOnly partially confirmed
ExperimentalExperimental / unsettled
HistoricalMaterial for a past version

Raw engine-extracted data (header, registry, measurements) lives in Engine Internals; the methodology and logs behind it are tracked in the research log.