brs.js

Read and write Brickadia save files (.brz, .brdb, .brs)

Warning: Unreal Engine uses numbers potentially larger than Javascript can handle. 64-bit integer fields outside the safe-integer range (±2⁵³−1) decode as JSON-safe { $bigint: '<decimal>' } wrappers instead of plain numbers; the write path accepts the wrapper, a raw bigint, or a number interchangeably, so decoded data round-trips losslessly (including through JSON.stringify/parse).

Install

npm install brs-js

Documentation and Usage

Node:

const brs = require('brs-js');

ES6:

import brs from 'brs-js';

Web:

Head: <script src="https://cdn.jsdelivr.net/npm/brs-js/dist/dist.js"></script>

Script: window.BRS

Examples

Examples are available in the examples/ directory. All .mjs examples are for node, .html are for web.

Brickadia Worlds (.brz, .brdb)

brs-js reads and writes both Brickadia World formats — the .brz archive and the live .brdb SQLite database (see below) — covering bricks, components, wires, entities, multiple grids (microchips), and prefab metadata. There are two writers, and each can target either format:

• the World builder — author worlds from scratch, including sub-grids, entities, microchips, and prefabs (w.toBrz() or db.save(desc, w));
• writeBrzLegacy — convert the same legacy WriteSaveObject that write() takes, except that components on bricks is a modern typed array (the legacy .brs component map is not converted) and wires on the save uses modern component and port names.

import { writeBrzLegacy, WorldReader } from 'brs-js';

const brz = writeBrzLegacy({
  description: 'my world',
  bricks: [{ size: [5, 5, 6], position: [0, 0, 6], color: [255, 0, 0] }],
});

// WorldReader is lazy: schemas are parsed once and cached, and chunk
// payloads are only decoded when you ask for them.
const world = WorldReader.from(brz);
world.bundle(); // Meta/Bundle.json
world.brickAssets(); // basic asset names followed by procedural
world.brickOwners(); // owner rows (PUBLIC excluded)
world.gridIds(); // [1] plus any entity sub-grids
for (const brick of world.bricks()) {
  // decoded chunk by chunk
}
for (const entity of world.entities()) {
  // dynamic grids, microchip grids, ...
}

World builder

World mirrors the reference Rust crate's wrapper::World: add bricks, components, wires, entities, and microchip grids, then serialize with toBrz(). Brick assets and materials are referenced by name, and the generated COMPONENTS/BRICK_ASSETS catalogs provide typo-safe names with editor completion.

import { Brdb, World, brdb } from 'brs-js';
const { COMPONENTS, BRICK_ASSETS } = brdb;

const w = new World();

// Main-grid bricks. addBrick returns a handle used by wires and links.
const light = w.addBrick({
  position: [0, 0, 6], // default asset is a 1x1 PB_DefaultBrick
  color: [255, 255, 255],
  components: [
    // omitted data fields take the game's default values
    { type: COMPONENTS.PointLight.NAME, data: { Brightness: 200 } },
  ],
});
w.addBrick({
  asset: BRICK_ASSETS.B_2x2F_Round,
  position: [20, 0, 2],
});

// serialize to a .brz archive...
const bytes = w.toBrz({ bundle: { description: 'My World' } });

// ...or write the same World into a .brdb as a revision
const db = await Brdb.openOrCreate('My World.brdb');
db.save('built with brs-js', w);

Wires connect component ports by name; endpoints may be in different grids or chunks (the writer emits remote wire rows automatically):

const TARGET = COMPONENTS.Target;
const PRINT = COMPONENTS.Exec_PrintToConsole;

const sensor = w.addBrick({
  asset: TARGET.BRICK,
  position: [0, 0, 6],
  components: [{ type: TARGET.NAME }],
});
const printer = w.addBrick({
  asset: PRINT.BRICK,
  position: [20, 0, 2],
  components: [{ type: PRINT.NAME, data: { Text: 'hit!' } }],
});
w.addWire(
  { brick: sensor, component_type: TARGET.NAME, port: TARGET.PORTS.bJustHit },
  { brick: printer, component_type: PRINT.NAME, port: PRINT.PORTS.Exec }
);

Microchips place an outer shell brick linked to an inner brick grid. makePrefab turns the bundle into a prefab (Meta/Prefab.json with pivots/bounds from the main-grid bricks) so the .brz pastes like a native copied selection — see examples/writeMicrochip.mjs:

const CHIP_IN = COMPONENTS.MicrochipInput;
const CHIP_OUT = COMPONENTS.MicrochipOutput;

const w = new World();
const { grid } = w.addMicrochip({ position: [0, 0, 2] });

// chip contents live in the inner grid (positions are grid-local)
const input = w.addBrick(
  {
    asset: CHIP_IN.BRICK,
    position: [0, 0, 2],
    components: [{ type: CHIP_IN.NAME, data: { PortLabel: 'In' } }],
  },
  grid
);
const output = w.addBrick(
  {
    asset: CHIP_OUT.BRICK,
    position: [20, 0, 2],
    components: [{ type: CHIP_OUT.NAME, data: { PortLabel: 'Out' } }],
  },
  grid
);
w.addWire(
  {
    brick: input,
    component_type: CHIP_IN.NAME,
    port: CHIP_IN.PORTS.RER_Output,
  },
  {
    brick: output,
    component_type: CHIP_OUT.NAME,
    port: CHIP_OUT.PORTS.RER_Input,
  }
);

w.makePrefab({ isMicrochipPrefab: true });
writeFileSync('chip.brz', w.toBrz());

Standalone entities and dynamic sub-grids:

const owner = w.addOwner({ id: '...uuid...', name: 'cake' });

// a frozen dynamic brick grid floating at Z 40, holding one brick
const grid = w.addBrickGrid({ frozen: true, location: { X: 0, Y: 0, Z: 40 } });
w.addBrick({ position: [0, 0, 3], owner_index: owner }, grid);

// or a bare entity
w.addEntity({ type: 'Entity_DynamicBrickGrid', frozen: true });

Compression

Blobs are stored uncompressed by default, which is valid and matches the reference implementation byte for byte. To compress with zstd (Node 22.15 or newer):

import { zstdCompressSync, constants } from 'node:zlib';
const brz = writeBrzLegacy(save, {
  compress: data =>
    zstdCompressSync(data, {
      params: { [constants.ZSTD_c_compressionLevel]: 14 },
    }),
});

Reading notes

Reading applies a few normalizations:

• Brick order round-trips per chunk rather than in global save order.
• collision.tool always reads true because the format does not store it.
• Palette color indices are resolved to [r, g, b] at write time.
• save.map is not mapped; pass { environment } in the options instead.

The cross-language fixture tests skip unless fixtures have been generated. To enable them, run just fixtures with a crate checkout at ../brdb (or set BRDB_CRATE).

.brdb (SQLite worlds)

.brdb is the game's live world format: the same virtual filesystem as .brz, stored in SQLite with full revision history. Reading and writing requires better-sqlite3 (an optional peer dependency, node only):

npm install better-sqlite3

import { Brdb } from 'brs-js';

const db = await Brdb.open('MyWorld.brdb');
const reader = db.worldReader(); // same surface as WorldReader.from(brz)
for (const brick of reader.bricks()) console.log(brick.position);

const out = await Brdb.create('New.brdb');
// save() takes a World builder instance or a legacy save object
out.save('initial save', {
  bricks: [{ size: [5, 5, 6], position: [0, 0, 6] }],
});

Every save/writePending call is one revision: unchanged files are shared, changed files are soft-deleted and reinserted, and blobs are deduplicated by BLAKE3 hash. Blobs compress with zstd level 14 when node's zlib supports it (pass compress: null to store raw). Advanced: new Brdb(db) wraps any SQLite handle with a compatible synchronous API, with no dependency at all.

Legacy saves (.brs)

Supports all BRS save versions. BRS files are no longer supported by the game as of Brickadia EA3 — use .brz/.brdb above for current builds.

Save Object

The Save Object is the input and output of this program. It represents the decoded/decompressed contents of the save. Strings can be UCS-2 or UTF-8. UUIDs follow the spec. The save_time field is 8 bytes (Little Endian) instead of a long. Unsigned ints, while unlikely, may overflow.

{
  version: short,
  map: string,
  author: {id: uuid, name: string},
  host: {id: uuid, name: string} // (v8+ only)
  description: string,
  save_time: UTC as 8 bytes,
  brick_count: int,
  mods: string array,
  brick_assets: [string],
    // --- See bottom of page for known bricks ---
  colors: [[byte, byte, byte, byte], ... ],
  physical_materials: [string], // BPMC_Default
  materials: [string],
    // --- Known available materials
    // BMC_Ghost
    // BMC_Ghost_Fail
    // BMC_Plastic
    // BMC_Glass
    // BMC_TranslucentPlastic
    // BMC_Glow
    // BMC_Metallic
    // BMC_Hologram
  brick_owners: [{
    id: uuid,
    name: string,
    displayName: string, // (v14+ only)
    bricks: int // (v8+ only)
  }, ... ],
  components: {
    [componentName]: {
      version: int,
      brick_indices: [int, ...],
      properties: {[name]: [value], ...},
    },
    ...
  },
  wires: [{
    source: {
      component: string, // component name
      brick_index: int, // index of the brick in `bricks`
      port: string, // port name
    },
    target: {
      component: string, // component name
      brick_index: int, // index of the brick in `bricks`
      port: string, // port name
    },
  }]
  bricks: [{
    asset_name_index: int,
    size: [uint, uint, uint],
      // must be [0, 0, 0] for all B_ prefixed brick_assets
      // must NOT be [0, 0, 0] for all PB_ prefixed brick_assets
      // 1x1 brick has size [5, 5, 6]
      // 1x1F plate has size [5, 5, 2]
    position: [int, int, int],
    direction: 0-5,
      // --- Directions (facing axis) ---
      // 0: X Positive
      // 1: X Negative
      // 2: Y Positive
      // 3: Y Negative
      // 4: Z Positive
      // 5: Z Negative
    rotation: 0-3,
      // --- Rotations (along the facing axis) ---
      // 0: 0 Deg
      // 1: 90 Deg
      // 2: 180 Deg
      // 3: 270 Deg
    collision: {
      player: bool,
      weapon: bool,
      interaction: bool,
      tool: bool,
      physics: bool, // disable physics collision
    }, // or bool
    visibility: bool,
    material_index: uint,
    physical_index: uint,
    material_intensity: 0-10,
    color: uint or [byte, byte, byte, byte] or (v9) -> [byte, byte, byte],
    owner_index: uint,
    components: {
      [componentName]: {
        [propName]: [propVal],
        ...
      },
      ...
    },
  }, ... ],
}

Fields: (optional fields during brs.write(save) will be set to default)

field	type	default	optional	description
version	short	Latest Save Version	auto	Save file version
game_version	int	Game Version	☑	Saving version of the game
map	string	'Unknown'	☑	Map where the save was generated
author.id	uuid	00000000-0000-0000-0000-000000000000	☑	Save author UUID
author.name	string	'Unknown'	☑	Save author name
description	string	'' (Empty String)	☑	Save author name
save_time	array	[0, 0, 0, 0, 0, 0, 0, 0]	☑	UTC in bytes of creation time
brick_count	int	Number of bricks in bricks	auto	Number of bricks in save
mods	array	[]	☑	In game mods required for load
brick_assets	array	['PB_DefaultBrick']	☑	List of brick assets
colors	array	[]	☑	List of colorset colors
materials	array	['BMC_Plastic']	☑	List of used materials
physical_materials	array	[]	☑	List of physical materials
brick_owners	array	[{}]	☑	Brick owner list
brick_owners[].id	uuid	00000000-0000-0000-0000-000000000000	☑	Brick owner list user uuid
brick_owners[].name	string	'Unknown'	☑	Brick owner list user name
brick_owners[].display_name	string	'Unknown'	☑	Brick owner list display name
preview	array	undefined	☑	1280x720 png screenshot data
bricks	array			List of bricks in the save
bricks[].asset_name_index	int	0 (0 indexed)	☑	Index of asset in brick_assets
bricks[].size	array			Brick size
bricks[].position	array			Brick position
bricks[].direction	int	4 (Positive Z, Upward)	☑	Brick axis / facing direction
bricks[].rotation	int	0 (0 degrees)	☑	Brick rotation on axis
bricks[].collision	bool	true	☑	Brick has collision with players
bricks[].collision	object		☑	Brick collision in general
bricks[].visibility	bool	true	☑	Brick renders to players
bricks[].material_index	int	0 (0 indexed)	☑	Index of material in materials
bricks[].material_intensity	int	0 (0 indexed)	☑	Material intensity (0-10)
bricks[].physical_index	int	0 (0 indexed)	☑	Index of physical material
bricks[].color (colorset)	int	0	☑	Index of color in colors
bricks[].color (rgba)	array	[255, 255, 255, 255]	☑	Color in RGBA Bytes
bricks[].color (rgb)	array	[255, 255, 255] (v9+)	☑	Color in RGBA Bytes
bricks[].owner_index	int	1 (1 indexed)	☑	Index of owner in brick_owners
bricks[].components	object	{}	☑	Components on this brick
components	object	{}	☑	List of components in the save
components[].version	int			Game version for this component
components[].brick_indices	array			Indices of assigned bricks
components[].properties	object			Map of properties names and types

Function brs.read(buffer, options)

Returns: Save Object

In node, the buffer can be obtained from fs.readFile without an encoding specified. In web, the buffer can be obtained via File.arrayBuffer(). Be sure to resolve promises where necessary.

parameter	type	description
buffer	Uint8Array / Buffer	Input bytes to be parsed
options	Object	Options for the parser, see table below

Options

name	type	description	default
bricks	boolean	Whether to read bricks	true
preview	boolean	Whether to copy previews	false

Function brs.write(saveObj)

Returns: Uint8Array

In node, the buffer can be saved with from fs.writeFile(fileName, buffer). In web, the buffer can be made into a new Blob([buffer]), and can be downloaded with an <a download> with href as URL.createObjectURL(blob).

parameter	type	description
saveObj	Save Object	Save Object to be turned into a buffer

Brick Assets

Notes:

• Size must be [0, 0, 0] for bricks using non-procedural brick assets
• Size must NOT be [0, 0, 0] for bricks using procedural brick assets
• 1x1 brick has size [5, 5, 6] and 'PB_DefaultBrick' brick asset
• 1x1F plate has size [5, 5, 2] and 'PB_DefaultBrick' brick asset

name	procedural
PB_DefaultBrick	☑
PB_DefaultRamp	☑
PB_DefaultRampCrest	☑
PB_DefaultRampCrestCorner	☑
PB_DefaultRampCrestEnd	☑
PB_DefaultRampInnerCornerInverted	☑
PB_DefaultRampInverted	☑
PB_DefaultSideWedge	☑
PB_DefaultSideWedgeTile	☑
PB_DefaultTile	☑
PB_DefaultWedge	☑
PB_DefaultMicroBrick	☑
PB_DefaultMicroWedge	☑
B_1x1_Brick_Side
B_1x1_Brick_Side_Lip
B_1x1_Cone
B_1x1_Round
B_1x1F_Octo
B_1x1F_Round
B_1x2_Overhang
B_1x2f_Plate_Center
B_1x2f_Plate_Center_Inv
B_1x4_Brick_Side
B_1x_Octo
B_1x_Octo_90Deg
B_1x_Octo_90Deg_Inv
B_1x_Octo_T
B_1x_Octo_T_Inv
B_2x1_Slipper
B_2x2_Cone
B_2x2_Corner
B_2x2_Overhang
B_2x2_Round
B_2x2_Slipper
B_2x2F_Octo
B_2x2F_Octo_Converter
B_2x2F_Octo_Converter_Inv
B_2x2f_Plate_Center
B_2x2f_Plate_Center_Inv
B_2x2F_Round
B_2x4_Door_Frame
B_2x_Cube_Side
B_2x_Octo
B_2x_Octo_90Deg
B_2x_Octo_90Deg_Inv
B_2x_Octo_Cone
B_2x_Octo_T
B_2x_Octo_T_Inv
B_4x4_Round
B_8x8_Lattice_Plate
B_Bishop
B_Bone
B_BoneStraight
B_Branch
B_Bush
B_Cauldron
B_Chalice
B_CheckPoint
B_Coffin
B_Coffin_Lid
B_Fern
B_Flame
B_Flower
B_Gravestone
B_GoalPoint
B_Handle
B_Hedge_1x1
B_Hedge_1x1_Corner
B_Hedge_1x2
B_Hedge_1x4
B_Inverted_Cone
B_Jar
B_King
B_Knight
B_Ladder
B_Pawn
B_Picket_Fence
B_Pine_Tree
B_Pumpkin
B_Pumpkin_Carved
B_Queen
B_Rook
B_Sausage
B_Small_Flower
B_SpawnPoint
B_Swirl_Plate
B_Turkey_Body
B_Turkey_Leg
B_1x1_Gate_Constant
B_1x1_Gate_Subtract
B_1x1_Gate_Multiply
B_1x1_Gate_ModFloored
B_1x1_Gate_Mod
B_1x1_Gate_Divide
B_1x1_Gate_Blend
B_1x1_Gate_Add
B_1x1_Gate_XOR
B_1x1_Gate_OR
B_1x1_Gate_NOR
B_1x1_Gate_NAND
B_1x1_Gate_EdgeDetector
B_1x1_Gate_Floor
B_1x1_Gate_Ceiling
B_1x1_EntityGate_ReadBrickGrid
B_1x1_Gate_NotEqual
B_1x1_Gate_LessThanEqual
B_1x1_Gate_LessThan
B_1x1_Gate_GreaterThanEqual
B_1x1_Gate_GreaterThan
B_1x1_Gate_XOR_Bitwise
B_1x1_Gate_ShiftRight_Bitwise
B_1x1_Gate_ShiftLeft_Bitwise
B_1x1_Gate_OR_Bitwise
B_1x1_Gate_NOR_Bitwise
B_1x1_Gate_NAND_Bitwise
B_1x1_Gate_AND_Bitwise
B_1x1_Reroute_Node
B_1x1_Gate_Timer_Tick
B_1x1_Gate_Timer
B_1x1_NOT_Gate
B_1x1_Gate_AND
B_1x1_Gate_Equal
B_1x1_Gate_NOT_Bitwise

Development

NPM Scripts (npm run <cmd>)

name	description
build	Build all targets (web + node) and type declarations
watch	Rebuild the library when files change
dist	Alias for build
test	Run the test suite once
test:watch	Run the test suite in watch mode