> For the complete documentation index, see [llms.txt](https://docs.flatredball.com/gum/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flatredball.com/gum/gum-tool/tutorials-and-examples/working-with-gum/1-the-basics.md).

# 1 - The Basics

## Introduction

This page walks you through the basics of using the *Gum tool*, which we'll refer to simply as Gum for this tutorial series.

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2Fv4ncXZpFk6Zt2yCWRTLQ%2F13_05_33_49.png?alt=media&amp;token=e11c7451-e702-4f86-83d4-322e4b364a1a" alt=""><figcaption><p>Gum tool with New Project window open</p></figcaption></figure>

### Creating a Project

Before we begin looking at the Gum tool, we'll create a new project. The New Project window opens automatically when Gum starts with no project to reopen, and from **File** > **New Project**. To create a new project:

1. Enter a name for your project
2. Select a location for your project
3. Keep **Include Forms controls** and **Include demo screen** checked
4. Select a theme - this tutorial series uses the Standard theme, but you are free to use a different theme. If you choose a different theme, there will be some differences between your selected theme and the tutorial screenshots.
5. Leave **Create C# project** unchecked
6. Click OK

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2FeCuZhp43pO0mgMoCP82z%2F13_05_37_14.png?alt=media&amp;token=5cef3dcd-c472-4fe5-8b6f-5733a17ebba4" alt=""><figcaption><p>Enter or confirm options when creating a new project</p></figcaption></figure>

{% hint style="info" %}
Create C# project also creates a runnable game project that contains your Gum project. This series does not cover working with that project.
{% endhint %}

For more on creating projects, see [Creating a Project](https://docs.flatredball.com/gum/gum-tool/setup/creating-a-project.md).

After you click OK, your project should contain screens, components, and behaviors.

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2FtgkyTSVcsYGhbETfyqnh%2F13_05_40_13.png?alt=media&amp;token=5eeb5c43-2c31-4ca2-8802-fbf1017550bb" alt=""><figcaption><p>Screens, Components, and Behaviors after creating a new project</p></figcaption></figure>

The Project tab lists your Screens, Components, and Behaviors as folders. We'll use it throughout this tutorial series. For everything the Project tab does, see [Project Tab](https://docs.flatredball.com/gum/gum-tool/project-tab.md).

The examples in this series use a blank screen named MainScreen, which a new project does not contain.

1. In the Project tab, right-click the **Screens** folder and select **Add Screen**.
2. In the **Add Screen** dialog, type `MainScreen` and click **OK**.

A MainScreen item now appears under **Screens** in the Project tab.

### Gum Elements

Gum separates its elements into a few categories: Screens, Components, Behaviors, and Standards.

Let's take a look at each of the different types.

#### Screens

Screens are objects which can contain standard elements and instances of other components. Screens cannot be added to other Screens and are considered *top level* objects. Screens exist mainly for organization. Screens can be simple, such as a loading screen, or complex such as a HUD in an RTS game.

Your project includes DemoScreenGum which shows how controls can be created and laid out.

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2Fn3c6qhbdvvx1bme2GkAz%2F13_05_49_52.png?alt=media&amp;token=7e6521f5-235e-4ecf-b8dd-8dd4de3f1490" alt=""><figcaption><p>DemoScreenGum with default controls</p></figcaption></figure>

#### Components

Components are objects which can contain standard elements and instances of other components. Components can be very simple, such as a Label, or very complex, such as an options menu with dozens of *instances*. Items added to components or screens are called *instances*.

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2FhYYhzlr7XhLlczPZ6j9R%2F13_05_53_41.png?alt=media&amp;token=6bb4e8b7-0d7e-405f-a9cc-010ea24705a8" alt=""><figcaption><p>ButtonStandard component in the Controls folder</p></figcaption></figure>

For example you can think of screens in a video game which might include a main menu, credits screen, options screen, and level selection screen. You can think of components as elements which are composed of multiple standard elements. Examples include a Button component which is made up of a Sprite instance and a Text instance, or a Logo component which may be made up of multiple Sprites and Text objects.

#### Behaviors

Behaviors are sets of requirements, such as required states and instances, that let Gum treat a component as a Forms control like a Button. Adding Forms controls to your project also adds their behaviors, so this series does not cover creating or editing them. For more, see [Behaviors](https://docs.flatredball.com/gum/gum-tool/gum-elements/behaviors.md).

#### Standard Elements

* ![](https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2Fgit-blob-3a790167212935c3379ffdd22ab848004507eae3%2Fimage.png?alt=media\&token=a7a3d6d9-8beb-41c7-b7c4-4ccdd223161d)\
  Circle - a circle which can be filled in, outlined, or both. Often used for visualizations or for defining collision in your Gum objects for a game.
* ![](https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2Fgit-blob-bbc4ac720b2de22435c7e5d2629f06840ac07256%2Fimage.png?alt=media\&token=da440165-f226-4c7e-8c63-ece8c5ef9e77)\
  Container - invisible object used to contain other objects. These are used to provide margins, change layouts (such as vertical vs horizontal stacking), and to organize your UI.
* ![](https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2Fgit-blob-d28d657919dc1406965380c5e315584be4ea4c4d%2Fimage.png?alt=media\&token=e0dd855a-952f-43c0-a7c1-a989d6b2b791)\
  NineSlice - visual object which uses nine sprites to create a resizable object from a source PNG (or portion of a PNG). The corner sprites (4) are not resized. The top, bottom, left, and right sprites are stretched on one axis. The middle sprite stretches both horizontally and vertically. These are used to create resizable frames.
* ![](https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2Fgit-blob-bd7b9f46a6ce006be69d783145279e6d5a6b1335%2Fimage.png?alt=media\&token=b0e7b53a-1fd3-4c61-a339-e4777b7699ab)\
  Polygon - polygon outline which can have any number of points. These are usually not used for UI, but can be used if you are defining collision in your Gum objects for a game.
* ![](https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2Fgit-blob-ae1c54b0f6295ab3ca1d4d887c7647c673ac0dbe%2Fimage.png?alt=media\&token=d2e0c4b9-2e1e-410e-bb1e-f7136db57acf)\
  Rectangle - a rectangle which can be filled in, outlined, or both. Used for solid-colored backgrounds, frames, blocking out a UI, or for defining collision in your Gum objects for a game.
* ![](https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2Fgit-blob-cd27aec9072263a0532846537447c29001a511de%2Fimage.png?alt=media\&token=f3f9826c-6a5e-4374-ab91-146f4e9405ac)\
  Sprite - a visual object which displays a source PNG (or a portion of a PNG). These are used for icons, backgrounds, and other visual objects which are usually not resized dynamically.
* ![](https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2Fgit-blob-6b4a03a9ee1084ed9990790ca6fb05ef4c1fd936%2Fimage.png?alt=media\&token=5e6d7055-9cd8-4b38-b6c4-84010e772ed3)\
  Text - a visual object which can display characters. These are used for any situation where text needs to be displayed such as labels and paragraphs.

{% hint style="info" %}
Plugins can add additional standard elements. The list above is the default list of standard elements before plugins have made any changes.
{% endhint %}

For more on each element, see [Gum Elements](https://docs.flatredball.com/gum/gum-tool/gum-elements.md).

### Previewing your Project

Gum can run your project as a live game in a Preview window. The **Preview** button is the play triangle at the top right of the Editor tab.

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2FFGPjJQyMwTLL6I7AKPMu%2F13_05_57_16.png?alt=media&amp;token=0fab18f3-1e47-4365-8c5b-e3f0da2d2198" alt=""><figcaption><p>The Preview button in the Editor tab</p></figcaption></figure>

By default, Gum saves your project automatically, and the Preview window refreshes whenever it saves. For more on Preview, see [Editor Tab](https://docs.flatredball.com/gum/gum-tool/editor-tab.md#preview).

The selected screen or component is displayed in the preview window. This preview is a live game running, so all controls react to cursor events. This preview lets you easily test whether your controls are behaving as expected, including any styling changes that you might make.

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2FvzaAFDiQrvuPVbLnxmQ0%2F13_05_58_48.gif?alt=media&amp;token=0776e051-5ee5-4ed9-a5c1-38e3de1acb7f" alt=""><figcaption><p>DemoScreenGum in the Gum preview window</p></figcaption></figure>

Note that while these controls react to events, their reactions are just the built-in behaviors. For example the Detect Resolutions button does not actually have the ability to detect your screen's display adaptor's display resolutions.

The Preview window shows the screen or component selected in Gum. The **pin** button, to the left of the **Preview** button, stops the Preview window from following the selection.

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2FfcvXcXYm0G8ZqWyBPfVc%2F13_06_00_34.png?alt=media&amp;token=64824b4d-677c-405b-8b13-ddf75d3f254c" alt=""><figcaption><p>The pin button in the Editor tab toolbar</p></figcaption></figure>

### Adding Instances

Instances can be added to screens and components. To add an instance:

1. Select the destination screen or component. For example, select the MainScreen.
2. Drag a Standard or Component onto the Editor tab. For example, drag **ButtonStandard** from **Components** > **Controls**.
3. Release the mouse button and the instance appears in the desired location

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2FWxIAdoD9CZZKxNMZ4qv0%2F13_06_05_38.gif?alt=media&amp;token=7a8e9b75-f7b5-428e-8104-c47b70c2db3d" alt=""><figcaption><p>Adding instances by drag+dropping</p></figcaption></figure>

Alternatively, you can also drag+drop onto the tree item to add instances.

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2FfBeNwsiOA5rwAqLYeii2%2F13_06_07_06.gif?alt=media&amp;token=1185986a-6b28-4518-90eb-5d203e8f9de1" alt=""><figcaption><p>Drag+drop onto the screen item in the Projects tab to add a new instance</p></figcaption></figure>

{% hint style="info" %}
If an element is dropped in the Editor window, it appears at the location where it has been dropped - setting its X and Y values. If an element is dropped in the Project tab, then it preserves its default X and Y values.
{% endhint %}

### Editing in the Editor Tab

Once an instance is part of a screen or component, it can be edited visually in the Editor tab. The selected instance can be moved or resized with its resize handles.

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2FpbvF0K3BC2I6buUV6jiZ%2F13_06_09_03.gif?alt=media&amp;token=6411ec02-f6d3-4787-b968-4ee6de1a1427" alt=""><figcaption><p>Editing in the Editor tab</p></figcaption></figure>

### Conclusion

This tutorial introduces the Gum tool and the basics of working with Screens, Components, and Standard Elements. The next tutorial covers working with the Variables tab.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.flatredball.com/gum/gum-tool/tutorials-and-examples/working-with-gum/1-the-basics.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
