> 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/code/gum-tool-code-contributing-and-plugins/gumprojectsave.md).

# GumProjectSave

## Introduction

The GumProjectSave object is a serializable object representing a Gum project. Specifically, the GumProjectSave object represents the data in the .gumj file. The GumProjectSave provides access to all Screens (ScreenSave), Components (ComponentSave), Standard Elements (StandardElementSave), and Behaviors (BehaviorSave).

The **Save** suffix is added to any model which can e serialized (saved) to disk.

Game projects can load a GumProjectSave through GumServices.Initialize.

The Gum tool loads GumProjectSave instances when the user opens a .gumj file.

Both games and the Gum tool can access the current GumProjectSave through the `ObjectFinder.Self.GumProjectSave` property.

## Project Structure

A fully-loaded Gum project is a hierarchical structure. GumProjectSave is the root of this hierarchy, providing access to all contained objects.

Since everything in a GumProjectSave can be saved to disk, all types have the Save suffix. Some important types include:

* ScreenSave - a Screen in the Gum project, saved as a .gusx file
* ComponentSave - a Component in the Gum project, saved as a .gucx file
* StandardElementSave - a StandardElement in the Gum project, saved as .gutx
* BehaviorSave - a Behavior in the Gum project, saved as a .behx
* ElementSave - the base type for ScreenSave, ComponentSave, and StandardElementSave
* InstanceSave - an instance in an Element or Behavior. These instances include the name of the instance and its type. InstanceSaves do not include variables, and are not embedded within other InstanceSaves. The parent/child relationships are stored as variables.
* StateSave - a State in an Element or Behavior. These can be the default State, or can be contained within a CategorySave.
* CategorySave - a Category in an Element or Behavior. These can include any number of States.
* VariableSave - a variable including its name and value. If the variable applies to the element itself, then the variable name is *unqualified*, such as "X". If the variable applies to an instance, then the variable includes the name of the instance, such as "TitleScreen.XUnits".

The following shows how a typical Gum project might be structured. Keep in mind that Gum projects can be very large so the following is a simplified example.

* GumProjectSave
  * Screens (List\<ScreenSave>)
    * CreditsScreen
    * TitleScreen
    * ...
  * Components (List\<ComponentSave>)
    * Button
      * DefaultState
    * Label
    * ...
  * StandardElements (List\<StandardElementSave)
    * ColoredRectangle
    * Sprite
    * Text
    * ...
  * Behaviors (List\<BehaviorSave>)
    * ButtonBehavior
    * LabelBehavior
    * ...

Each ScreenSave, ComponentSave, StandardElementSave and BehaviorSave contains its own variables including the instances that each includes, states, categories, and variables.

Each ScreenSave, ComponentSave, and StandardElementSave includes a list of InstanceSaves, CategorySaves, and a Default state. A typical ScreenSave might have the following structure:

* Instances
  * CreditsTitle
  * LeftSideContainer
  * RightSideContainer
  * LeftCredits1
  * RightCredits1
  * LeftCredits2
  * RightCredits2
  * ...
* DefaultState
  * Variables
    * CreditsTitle.Text
    * CreditsTitle.X
    * CreditsTitle.XUnits
    * LeftSideContainer.X
    * RightSidContainer.X
    * ...
* Categories
  * FadeInOutCategory
    * FadeIn
      * Variables
        * Overlay.Alpha
    * FadeOut
      * Variables
        * Overlay.Alpha
  * ...

## Code Example

The following code loops through all screens, components, and standard elements in the current project and adds their names to a list of strings:

```csharp
List<string> allObjectsInGumProject = new List<string>();

foreach (var screen in ObjectFinder.Self.GumProjectSave.Screens)
{
    allObjectsInGumProject.Add(screen.Name);
}

foreach (var component in ObjectFinder.Self.GumProjectSave.Components)
{
    allObjectsInGumProject.Add(component.Name);
}

foreach (var standardElement in ObjectFinder.Self.GumProjectSave.StandardElements)
{
    allObjectsInGumProject.Add(standardElement.Name);
}
```


---

# 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/code/gum-tool-code-contributing-and-plugins/gumprojectsave.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.
