File formats

Optional

You don’t need this to make games in Brasa: the editor takes care of the files. This page is for those who want to understand what is on disk, use Git or edit something by hand.

A Brasa project is an ordinary folder, with readable text files. The folders are free-form: Brasa figures out the type of each file by its extension.

File	What it is
project.brasa	The project settings. It marks the folder as a project.
Name.room.json	A room.
Name.obj.json + Name.hpp + Name.cpp	An object: the data and the code. An object without code has only the .obj.json.
name.sprite.json + the image	A sprite. The "image" points to the PNG.
name.wav	A sound.
loose *.cpp, *.hpp	Shared code, such as game.hpp.
.brasa/	Files generated by Play (build). You can delete it; it doesn’t go to Git.
.vscode/	Autocomplete configuration, generated by Brasa.

project.brasa

{
  "formatVersion": 2,
  "name": "Primeiro Jogo",
  "width": 320,
  "height": 180,
  "windowScale": 3,
  "startRoom": "Main"
}

width and height are the resolution of the game, startRoom is the start room and windowScale is the initial scale of the window (absent = automatic).

fullscreen (true opens in full screen) and scale ("integer", "fit" to keep the aspect ratio, or "stretch") only show up when they differ from the default.

Two optional fields keep the rest of the project settings:

{
  "input": {
    "esquerda": ["Left", "A", "Pad:Left", "Pad:LeftX-"],
    "atirar": ["Space", "Pad:A"]
  },
  "globalObjects": ["Controle"]
}

input holds the input actions: each name with its keys and buttons. globalObjects is the list of global objects.

Object (.obj.json)

{
  "sprite": "nave",
  "visible": true,
  "solid": false,
  "vars": [
    { "name": "velocidade", "type": "number", "default": 2.0 }
  ]
}

The code is in the .hpp and the .cpp of the same name, next to it.

These fields only show up when they differ from the default: mask, flipX, persistent, gravity, gravityDirection, friction and maxFallSpeed.

vars holds the object’s variables. The type is number, int, bool, string, color, room, object, sprite or sound. A color is [red, green, blue, alpha], from 0 to 255.

Room (.room.json)

{
  "width": 320,
  "height": 180,
  "layers": [
    { "type": "instances", "name": "Instancias", "depth": 0, "instances": [
      { "object": "Player", "x": 160, "y": 150 }
    ] },
    { "type": "tiles", "name": "Chao", "depth": 100, "tileset": "Terreno", "data": [ "0,0,0", "1,2,3" ] },
    { "type": "background", "name": "Fundo", "depth": 200, "color": [16, 14, 32] }
  ]
}

layers are the layers, from front to back. The type is instances, tiles, sprites or background. In a tile layer, data has one row per line: 0 is empty and n is tile n - 1 of the tileset.

Each instance can also have scaleX, scaleY, angle and vars (the variables’ own values, by name: "vars": { "velocidade": 3 }). They only show up in the file when they differ from the default. The room’s camera is also saved here.

Tileset (.tileset.json)

{
  "sprite": "tiles",
  "collision": "ssss..s",
  "terrains": [ { "name": "grama", "at": 0 } ]
}

sprite is the sprite with the tiles (each frame is a tile). collision has one character per tile: s is solid and . is free. terrains are the 3 × 3 blocks of the terrain brush: at is the tile at the top-left corner.

Sprite (.sprite.json)

{
  "image": "nave.png",
  "frameW": 16,
  "frameH": 16,
  "frames": 2,
  "origin": [8.0, 8.0],
  "bbox": [3.0, 2.0, 10.0, 12.0]
}

origin is [x, y] inside the frame, and bbox is the collision box: [x, y, width, height].

The optional field "fps" (greater than 0 and at most 120) keeps the speed of the animation in frames per second, set in the sprite editor. With it, the object’s animSpeed becomes a multiplier; without it, animSpeed counts in frames per step.

Old projects

Projects in the old format (with a central assets/sprites.json) are converted to format 2 when you open them in the editor. From the command line, use brasa_cli migrate <folder>: see brasa_cli.