Project Structure

GBS Toolkit splits a GB Studio project is split into many files and folders. This page documents the file structure of each folder, along which what content goes in each file.

Overview

Project
- project.kdl
- backgrounds.kdl
- sprite-sheets.kdl
- music.kdl
- variables.kdl
- palettes.kdl
- custom-events
  - <custom event file>
- scenes
  - <scene folder>
    - meta.kdl
    - collisions.kdl
    - tile-colors.kdl
    - init.kdl
    - player-hit-1.kdl
    - player-hit-2.kdl
    - player-hit-3.kdl
    - actors
      - <actor folder>
        - meta.kdl
        - init.kdl
        - interact.kdl
        - update.kdl
        - hit-1.kdl
        - hit-2.kdl
        - hit-3.kdl
    - triggers
      - <trigger folder>
        - meta.kdl
        - interact.kdl

Script Files

Some files contain lists of events that will run when a certain condition is met. These are known as script files, and are crucial to making a GB Studio project function. Each event in a script file will include a command and arguments passed to that command. For a list of what commands are available, see Command Reference.

project.kdl

The main project metadata file for the project.

Properties

• name: The name of the project.
• author: The name of the project author/authors.
• version: The version of GB Studio used for the project.
• release: The build of the GB Studio version used for the project.
• engineFieldValues: The engine field values for the project.
  • global: The section for engine-wide field values.
  • topDown: The section for field values in top-down scenes.
    • gridSize: The size of the tile grid: 8 or 16.
  • platformer: The section for field values in platformer scenes.
    • minVelocity: The minimum velocity the player will have while moving.
    • walkVelocity: The maximum velocity the player will have while walking.
    • runVelocity: The maximum velocity the player will have while running.
    • walkAcceleration: How quickly the player will accelerate while walking.
    • runAcceleration: How quickly the player will accelerate while running.
    • deceleration: How quickly the player will slow down.
    • jumpVelocity: How quickly the player will ascend while jumping.
    • gravity: How quickly the descension speed of a player will increase.
    • jumpGravity: How quickly the ascension speed of a jumping player will decrease.
    • terminalVelocity: The maximum vertical velocity the player will have while falling.
• settings: The settings for this project.
  • startScene: The scene the game will launch into.
  • playerSpriteSheet: The sprite sheet to use for the player when the game launches.
  • startX: The X-coordinate the player will start at when the game launches.
  • startY: The Y-coordinate the player will start at when the game launches
  • startMoveSpeed: The movement speed the player will have when the game launches.
  • startAnimSpeed: The animation speed the player will have when the game launches.
  • customColorsEnabled: Whether Color Mode is activated.
  • customHead: The HTTP custom header for the game's web player.
  • defaultBackgroundPalettes: The default background palettes for each palette slot.
    • palette0: The ID of the palette for default palette 0.
    • palette1: The ID of the palette for default palette 1.
    • palette2: The ID of the palette for default palette 2.
    • palette3: The ID of the palette for default palette 3.
    • palette4: The ID of the palette for default palette 4.
    • palette5: The ID of the palette for default palette 5.
  • defaultSpritePalette: The default palette to use for sprites.
  • defaultUIPalette: The default palette to use for UI.
  • defaultPlayerPalette: The default palette to use for the player, or "" to use the default sprite palette.
  • customColors: The colors to use in the web build if Color Mode is not activated.
    • white: The color to use for the lightest color on the Game Boy screen.
    • light: The color to use for the second-lightest color on the Game Boy screen.
    • dark: The color to use for the second-darkest color on the Game Boy screen.
    • black: The color to use for the darkest color on the Game Boy screen.
  • cartType: The type of cartridge the game is meant to run on.
  • customControls: Custom keyboard controls for the web build.
    • up: Keys that will trigger an up input.
    • down: Keys that will trigger a down input.
    • left: Keys that will trigger a left input.
    • right: Keys that will trigger a right input.
    • a: Keys that will trigger an a input.
    • b: Keys that will trigger an b input.
    • start: Keys that will trigger a start input.
    • select: Keys that will trigger a select input.
  • __showCollisions: Whether the GB Studio editor will display collision boxes. Should not be hand-edited.
  • __showConnections: Whether the GB Studio editor will display flow links between scenes. Should not be hand-edited.
  • __worldScrollX: The X-coordinate scroll value of the GB Studio editor viewport. Should not be hand-edited.
  • __worldScrollY: The Y-coordinate scroll value of the GB Studio editor viewport. Should not be hand-edited.
  • __zoom: The zoom level of the GB Studio editor viewport. Should not be hand-edited.
  • __navigatorSplitSizes: The three sizes of the navigator panels of the GB Studio editor. Should not be hand-edited.
  • __showNavigator: Whether the navigator should be visible in the GB Studio editor. Should not be hand-edited.
• notes: A set of notes about the project as a whole.

backgrounds.kdl

A file comprising the info for all the background images in the game.

Properties

• <background name>: The name of this background, for use in scene meta.kdl files.
  • id: The UUID of this background.
  • width: How many tiles wide this background is.
  • height: How many tiles tall this background is.
  • imageWidth: How many pixels wide this background is.
  • imageHeight: How many pixels tall this background is.
  • filename: The filename of this background.
  • timestamp: The timestamp at which this file was last edited.

sprite-sheets.kdl

A file comprising the info for all the sprite sheets in the game.

Please keep in mind that this will be restructured in GB Studio V3.

Properties

• <sprite sheet name>: The name of this sprite sheet, for use in scripts and actor meta.kdl files.
  • id: The UUID of this sprite sheet.
  • numFrames: How many frames of animation this sprite sheet has.
  • type: The type of sprite sheet this is: "static", "animated", "actor", or "actor_animated".
  • filename: The filename of this sprite sheet.
  • timestamp: The timestamp at which this file was last edited.

music.kdl

A file comprising the info for all the songs in the game.

Properties

• <song name>: The name of this song, for use in scripts.
  • id: The UUID of this song.
  • filename: The filename of this song.
  • timestamp: The timestamp at which this file was last edited.

variables.kdl

A file storing all the names of the variables in GB Studio, in the format of `$$ ""

palettes.kdl

A file comprising the info for all the color palettes in the game.

Properties

• <palette name>: The name of this palette, for use in scripts and actor meta.kdl files.
  • id: The UUID or keyword name of this palette.
  • name: The non-sanitized version of the palette name, for display in GB Studio.
  • colors: The hex values for each color in the palette.
    • white: The hex value for the lightest color in the palette.
    • light: The hex value for the second-lightest color in the palette.
    • dark: The hex value for the second-darkest color in the palette.
    • black: The hex value for the darkest color in the palette.
  • defaultName: The default name of this palette, if it is based off a default palette. Should not be hand-edited.
  • defaultColors: The default colors of this palette, if it is based off a default palette. Should not be hand-edited.

Custom Event <name>.kdl

A custom event that can be called from other event scripts.

Properties

• id: The UUID of this custom event.
• name: The non-sanitized version of the custom event name, for display in GB Studio.
• description: The description of what this custom event does.
• __index: The positional index of this custom event in the .gbsproj file. Should not be edited by hand.
• variables: The names of the custom variables used in this script, for display in GB Studio.
• actors: The names of the custom actors used in this script, for display in GB Studio.
• script: The script for this custom event, formatted like a script file.

Scene meta.kdl

A file comprising all the metadata information for a scene.

Properties

• id: The UUID of this scene.
• name: The non-sanitized version of the scene name, for display in GB Studio.
• type: The type of scene this is: 0 for top-down, 1 for platformer, 2 for adventure, 3 for shoot-em-up, and 4 for point-and-click. This value will be different in GB Studio version 3. Please keep this in mind.
• background: The name of the background image for this scene.
• x: The X coordinate for this scene's position in GB Studio. Should not be hand-edited.
• y: The Y coordinate for this scene's position in GB Studio. Should not be hand-edited.
• width: How many tiles wide this scene is.
• height: How many tile tall this scene is.
• __index: The positional index of this scene in the .gbsproj file. Should not be hand-edited.
• palettes: The IDs of the palettes to use in this scene.
  • palette0: The ID of the palette for default palette 0.
  • palette1: The ID of the palette for palette 1.
  • palette2: The ID of the palette for palette 2.
  • palette3: The ID of the palette for palette 3.
  • palette4: The ID of the palette for palette 4.
  • palette5: The ID of the palette for palette 5.
• notes: A set of notes about this scene.
• labelColor: The color of the label this project will have in GB Studio. Should not be hand-edited.

Scene collisions.kdl

A file containing collision information for the scene. Each node is one of six types:

• all <X> <Y>: The tile at (X, Y) has collision on all sides.
• up <X> <Y>: The tile at (X, Y) has collision from the top only.
• down <X> <Y>: The tile at (X, Y) has collision on the bottom only.
• left <X> <Y>: The tile at (X, Y) has collision on the left only.
• right <X> <Y>: The tile at (X, Y) has collision on the right only.
• ladder <X> <Y>: The tile at (X, Y) can be climbed like a ladder. Can be combined with any other collision type.

All tiles which do not have a specific node pointing to them will be assumed to have no collision.

Scene tile-colors.kdl

A file containing palette information for the scene. Each node is one of six types:

• palette1 <X> <Y>: The tile at (X, Y) uses palette 1.
• palette2 <X> <Y>: The tile at (X, Y) uses palette 2.
• palette3 <X> <Y>: The tile at (X, Y) uses palette 3.
• palette4 <X> <Y>: The tile at (X, Y) uses palette 4.
• palette5 <X> <Y>: The tile at (X, Y) uses palette 5.

All tiles which do not have a specific node pointing to them will be assumed to use palette 0.

Scene init.kdl

A script file run whenever the scene is entered.

Scene player-hit-1.kdl

A script file run whenever the player is hit by something in collision group 1.

Scene player-hit-2.kdl

A script file run whenever the player is hit by something in collision group 2.

Scene player-hit-3.kdl

A script file run whenever the player is hit by something in collision group 3.

Actor meta.kdl

A file comprising all the metadata information for an actor.

Properties

• id: The UUID of this actor.
• name: The non-sanitized version of the actor name, for use in GB Studio.
• spriteSheet: The name of the sprite sheet this actor will start on whenever the scene is entered.
• spriteType: The type of this actor, either "static", or "actor".
• startFrame: The animation frame this actor will start on whenever the scene is entered.
• x: The X-coordinate this actor will start on whenever the scene is entered.
• y: The Y-coordinate this actor will start on whenever the scene is entered.
• movementType: The type of movement this actor will naturally have, either "static", "randomWalk", or "faceInteraction".
• direction: The direction this actor will face whenever the scene is entered.
• moveSpeed: How quickly this actor will move whenever the scene is entered.
• animSpeed: How quickly this actor will animate whenever the scene is entered.
• collisionGroup: The collision group this actor belongs to, either 1, 2, or 3.
• __index: The positional index of this actor in the .gbsproj file. Should not be hand-edited.
• notes: A set of notes about this actor.

Actor init.kdl

A script file run whenever the scene this actor is in is entered.

Actor interact.kdl

A script file run whenever the player interacts with this actor.

Actor update.kdl

A script file run once per frame while the actor is loaded.

Actor hit-1.kdl

A script file run whenever this actor his hit by something in collision group 1.

Actor hit-2.kdl

A script file run whenever this actor his hit by something in collision group 2.

Actor hit-3.kdl

A script file run whenever this actor his hit by something in collision group 3.

Trigger meta.kdl

A file comprising all the metadata information for a trigger.

Properties

• id: The UUID of this trigger.
• name: The non-sanitized version of the trigger name, for use in GB Studio.
• x: The X-coordinate this trigger will be placed at.
• y: The Y-coordinate this trigger will be placed at.
• width: How many tiles wide this trigger is.
• height: How many tiles tall this trigger is.
• __index: The positional index of this trigger in the .gbsproj file. Should not be hand-edited.
• notes: A set of notes about this trigger.

Trigger interact.kdl

A script file run whenever this trigger is stepped on.