Docs / Scenes

A scene is a single screen of your game, it can contain multiple actors and triggers. A game is typically made-up of many scenes connected together with triggers using the Change Scene event.

Adding a Scene

Click the + button in the Editor Tools and select Scene from the menu. Click on any empty space in the Project Viewport to place the new scene.

You can use the Editor Sidebar to give your scene a name and a background from your project's assets. See the documentation for Backgrounds for more information on adding background images.

Scene Properties

  • Name - Names your scene. Useful for locating your scene with the search bar.
  • Type - Lets you choose from the list of gamemodes. A scene's type cannot be changed in-game.
  • Background - Lets you choose a background from the assets/backgrounds folder.
  • Add Notes - Adds an editor-only text field to your scene.

Navigation is a list that shows every Actor and Trigger inside the scene. Clicking any name in the list will select that object and show its properties in the Editor Sidebar.


To start building a script, select a scene and click the Add Event button in the Editor Sidebar to open the event menu. Select an event to add it to the script.

For more information see the documentation for Scripting.

Adding Collision to a Scene

Select the Collision Tool from the Editor Tools. There are 6 collision types that can be added.

Solid Collision stops colliding actors from entering the tile on any side.
Top/Bottom/Left/Right collision stops colliding actors from entering the tile from that specific side. This is useful for one-way collision and semi-solid platforms.

Each tile can hold a maximum of 1 ladder and 3 collision sides. Adding 4 collision sides will replace the sides with a single solid block. Ladders will not replace existing collision when placed on top of other collision.

Colorizing a Scene

Select the Colorizer Tool from the Editor Tools. There are 6 palettes types that can be added to a scene with Color Mode enabled. Palettes can be adjusted in Settings.

The palettes used in the Colorizer Tool can be swapped out for existing palettes (such as the UI palette) by long-clicking on a palette.

For more information about the drawing mode used for the Colorize Tool and the Collision Tool, see Keyboard Shortcuts.

Scene Limits

There are several limits that GB Studio has put in place to keep game performance consistent, and to minimize visual bugs.

Each scene can have a maxmimum of 30 actors, 25 unique actor sprite frames, and 30 triggers. You can check this information by selecting a scene and looking for the gray bar under your scene that reads: A: 0/30 F: 0/25 T: 0/30. The letters on this bar represent the following:

  • A: represents the number of actors that the scene is using.
  • F: represents the number of unique frames that each actor is using in their sprite sheet.
  • T: represents the number of triggers that the scene isusing.

Actor Limits

Each scene can have a maximum of 30 actors. Ideally, there should never be more than 10 actors within a 20 x 18 tile boundary, equivalent to 160px x 144px. Clustering more than 10 actors together in a scene will cause some actors to become invisible in-game. GB Studio will warn you if it thinks this will be the case for a scene:

You can address this message by moving or deleting actors so no more than 10 will be seen in a 20 x 18 tile boundary. You can use the Eraser Tool to delete actors. Actors will still become invisible if more than 10 actors move into the screenspace after the scene starts.

Frame Limits

Each scene can have a maximum of 25 unique sprite frames. Read more about frame limits on the Actors page.

Trigger Limits

Each scene can have a maximum of 30 triggers. Each trigger has its collision checked actively during gameplay, even when it's not being touched. Performance issues start to arise above 30 triggers. You can use the Eraser Tool to delete triggers.

Next: The Player