Engineering notes for building tools that read, write, and generate Brickadia content. Each document covers one problem domain and is derived from working implementations rather than from first principles.
| Document | Covers |
|---|---|
| SAVE_FORMATS.md | The .brs / .brdb / .brz formats, .brs version history, msgpack-schema encoding, and the brdb crate's read/write/patch API |
| CONSOLE_COMMANDS.md | Driving a dedicated server from outside the game: command namespaces, log-line response parsing, GetAll reflection |
| BRICK_MERGE_OPTIMIZATION.md | Reducing brick count: greedy binary-plane meshing, quadtree collapse, and 3D box growth over a voxel octree |
| MICRO_TERRAIN_GEOMETRY.md | Measured geometry contract for smooth procedural terrain built from micro bricks |
| MICROWEDGE_TRIANGLE_PLANES.md | Using thin micro-wedges on independent frozen grids as arbitrarily oriented triangle planes |
| TEXT_DECAL_TEXTURES.md | Rendering arbitrary images as Component_TextDisplay decals: encoding, character budget, font calibration |
| PREFAB_IMPORT.md | Parsing a .brz into a reusable template and stamping rotated instances with wires, joints, and dynamic sub-grids |
| WIRING_AND_WIRESCRIPT.md | Wire graph storage and emission via brdb, plus the Wirescript language and its gate-count patterns |
Writing a save from scratch — SAVE_FORMATS.md for the
World API and the format's traps, then
BRICK_MERGE_OPTIMIZATION.md if you are
generating from voxels or a heightmap.
Converting from another format — SAVE_FORMATS.md for the target format and PREFAB_IMPORT.md for coordinate conventions and multi-brick assemblies.
Building a server-side tool or plugin — CONSOLE_COMMANDS.md.
Building logic circuits — WIRING_AND_WIRESCRIPT.md.
Generating terrain — MICRO_TERRAIN_GEOMETRY.md for the geometry contract, BRICK_MERGE_OPTIMIZATION.md for keeping the brick count down, or MICROWEDGE_TRIANGLE_PLANES.md when each surface triangle needs its own arbitrary plane.
The documents cite these projects. Read them when a document does not go deep enough.
| Project | What it is |
|---|---|
| brdb | Rust library for .brdb / .brz, plus the authoritative format documentation in docs/format/ |
| brickadia-rs | Rust reader/writer for the legacy .brs format |
| brs-js | JS/TS save library |
| omegga | Node.js server wrapper and plugin host |
| obj2brz | 3D model to bricks, via voxelization and box merging |
| heightmap2brz | Heightmap and image to bricks, plus the TextDisplay decal renderer |
| bls2brz | Blockland .bls to Brickadia, including prefab-backed brick mappings |
| wirescript | Language that compiles to Brickadia wire graphs |
| wirescript-projects | Complete game circuits written in Wirescript |
Documents are derived from code that works. If you add one, cite the source
files it came from in a ## Sources section at the bottom, and prefer
measured facts over inferred ones — several of the sharper edges here
(embedded prefab filenames, material intensity range, font pitch constants)
were only discovered by loading a save and watching what the game did.