brs.js

Read and write Brickadia save files (.brs)

Currently supports save versions <= 10

Warning: Unreal Engine uses numbers potentially larger than Javascript can handle.

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 .js examples are for node, .html are for web.

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],
  materials: [string],
    // --- Known available materials
    // BMC_Ghost
    // BMC_Ghost_Fail
    // BMC_Plastic
    // BMC_Glow
    // BMC_Metallic
    // BMC_Hologram
  brick_owners: [{
    id: uuid,
    name: string,
    bricks: int // (v8+ only)
  }, ... ],
  components: {
    [componentName]: {
      version: int,
      brick_indices: [int, ...],
      properties: {[name]: [value], ...},
    },
    ...
  },
  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: 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 | | 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[].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 | |

Development

NPM Scripts (npm run <cmd>)

| name | description | |-------|----------------------------------------------------------| | build | Build library in development mode | | watch | Auto-build library in development mode when files change | | dist | Build library in production mode | | test | Run tests |