Skip to content

Project Setup

Note

The words "Stage" and "Backdrop" are used interchangeably in Crust.

Note

As of version 0.3.5, Crust allows you to create projects by writing: 

crust-engine --new my_project
This creates a new project with the name my_project in the current directory, and initializes it with a default project.toml with an empty stage and a single sprite named "default-sprite".

Projects are defined by a project.toml file in the root directory. This file contains metadata about the project, such as allowing debug features, the stages, the sprites and their costumes, etc. Here is an example of a project.toml file:

debug_options = [ "show_fps", "show_mouse_pos" ]

[stage]
backdrops = [ "backdrop_0.png" ]

[[sprites]]
name = "title"
code = "title/title.crst"
costumes = [ "title/title.png" ]
sounds = []
x = 0
y = 200
w = 1200
h = 300

[[sprites]]
name = "player"
code = "player/player.crst"
costumes = [ "player/player.png" ]
x = 0
y = 0
w = 150
h = 150

    [[sprites.sounds]]
    name = "jump"
    file = "player/jump.wav"

The project.toml file is written in TOML format, which is a simple and human-readable configuration file format. You can read more about TOML here.

TOML Structure

All paths mentioned are relative to the project.toml file.

  • debug_options: A list of debug options to enable. Only available options are show_fps and show_mouse_pos
    • show_fps: Shows the current frames per second (FPS)
    • show_mouse_pos: Shows the current mouse position on the screen (World coordinates, not screen coordinates)
  • [font]: The font configuration. Defaults to the default Crust font.
    • file: The path to the bitmap font file. The file must be an image file.
    • first_char: The first character in the font.
    • char_width: The width of each character in the font in pixels.
    • char_height: The height of each character in the font in pixels.
    • chars_per_row: The number of characters in each row of the font.
  • [stage]: The stage configuration
    • backdrops: A list of backdrops for the stage. If the list is empty, the stage will have an empty backdrop
  • [sprites]: A list of sprites in the project
    • [[sprites]]: A sprite
      • name: The name of the sprite. Can have spaces and special characters. Case-sensitive.
      • code: The path to the sprite's code file.
      • costumes: A list of costumes for the sprite. The costumes are images that the sprite can use. If the list is empty, the sprite will have no costumes.
      • [sprites.sounds]: A list of sounds for the sprite
        • [[sprites.sounds]]: A sound
          • name: The name of the sound. Can have spaces and special characters. Case-sensitive.
          • file: The path to the sound file. Can only be a .wav file.
      • x: The x-coordinate of the sprite. Center is 0, left is negative, right is positive.
      • y: The y-coordinate of the sprite. Center is 0, up is negative, down is positive.
      • w: The width of the sprite in pixels.
      • h: The height of the sprite in pixels.
      • visible: Whether the sprite is visible. Defaults to true. If set to false, the sprite will not be rendered on the stage.
      • layer: The layer of the sprite. Defaults to 0. A higher value means the sprite will be rendered on top of sprites with a lower layer value. Also effects the order of the sprite in the sprite list after the first frame.
      • direction: The rotation of the sprite in degrees. Defaults to 0. A positive value rotates the sprite clockwise, a negative value rotates it counter-clockwise.
  • [tags]: A list of tags for the project. Tags are used to categorize the sprites. Sprites in tags inherit the tag's code, placing the code after its own code.
    • [[tags]]: A tag
      • name: The name of the tag. Can have spaces and special characters. Case-sensitive. If the name is *, it is a special tag that applies to all sprites in the project, in which case the sprites list is ignored.
      • code: The path to the tag's code file. This file will be executed for all sprites in the tag after their own code.
      • sprites: A list of sprite names that are in the tag.

The recommended project structure is as follows:

project/
|-- project.toml
|-- stages/
|   |-- backdrop_0.png
|-- sprites/
|   |-- sprite/
|   |   |-- sprite.crst
|   |   |-- sprite.png
|   |   |-- sprite.wav