> 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/gum-elements/behaviors/creating-new-behaviors-advanced.md). # Creating New Behaviors (Advanced) ## Introduction {% hint style="warning" %} Standard Forms behaviors (`ButtonBehavior`, `TextBoxBehavior`, and so on) already ship with every project that uses Forms controls - see [Behaviors](/gum/gum-tool/gum-elements/behaviors.md). Creating or editing a behavior yourself is a rare, advanced scenario, needed only when you're standardizing categories/states/instances for your own components that are **not** part of Gum Forms. {% endhint %} This document walks through creating a behavior from scratch, using a `ButtonBehavior`-style definition as a familiar illustration. You would not actually recreate `ButtonBehavior` in a real project — it already exists - but the same steps apply to any custom behavior you define for your own components. ### Creating a Behavior To add a behavior: 1. Right-click on the Behaviors folder 2. Select **Add Behavior:**

3. Enter the new behavior name. Often time the word **Behavior** is added at the end of the name, such as **ButtonBehavior** New behaviors appear in the Project tab.

Once a behavior is created, it can be given categories, states, and instances. Components which use this behavior are required to have matching categories and states. The process of adding and removing states to behaviors is the same as adding and removing states in other elements. For more information, see the [States](/gum/gum-tool/gum-elements/states.md) page. For example, the ButtonBehavior may have the following: * ButtonCategory (Category) * Enabled (State) * Disabled (State) * Focused (State) * Pushed (State)

ButtonCategory defined on ButtonBehavior

A behavior can have as many categories and states as needed. Once a behavior is added, it can be used in a component. To add a behavior to a component, drag+drop the behavior onto the component in the tree view.

Add a behavior to a component by drag+dropping the behavior on the component in the Project tab

Behaviors can also be added and removed on the component's Behaviors tab: 1. Select a component which should use the behavior 2. Click the Behaviors tab 3. Click the Edit button 4. Check the desired behaviors - a component may use multiple behaviors 5. Click OK

Button component adding the ButtonBehavior

Notice that once a behavior is added to a component, the component automatically creates the matching categories and states. If the behavior is selected in the Behaviors tab, the required states and categories are highlighted in the States tab.

States and Categories required by the selected behavior are highlighted

These categories cannot be removed as long as the component uses the behavior. ### Category and State Requirements As mentioned above, if a component uses a behavior, then the component is required to include all of the states and categories defined by the behavior. If a behavior is added to a component, then all states and categories in the behavior are automatically added to the component. Keep in mind that newly-added states do not automatically assign any values. The behavior only requires that the states exist but it does not decide which variables are assigned by the states. These required states can even be left to their default so they have no affect on the component. Required states and categories cannot be removed or renamed. Required states cannot be moved to different categories.

Renaming and deleting states and categories required by behaviors is not allowed

If a new category or state is added to a behavior, all components which use the behavior also have the new category or state added.

Adding states and categories in a component adds the states and categories to all components using the behavior

If a state or category is removed from a behavior, Gum does not remove the state or category from components which implement the behavior. Behaviors only define what is required, but they do not prevent components from defining additional states and categories. Also, the states on components may still be needed even if the behavior is removed. Therefore, if you remove any states or categories from a behavior, you may need to manually remove the same states and categories from components which use the behavior if these are no longer needed. ### Instance Requirements Behaviors can include instances, resulting in required instances existing in components which use the behavior. Instances in behaviors only include two properties: * Name * Base Type Instances in behaviors only require that instances in components have these two matching properties. All other properties can be set to any value. To add an instance to a behavior, drag+drop a standard element or component onto the behavior in the Project tab.

Drag+drop standard elements or components onto behaviors to create instances in the behavior

An instance can have its Name changed, Base Type changed, or removed.

The Variables tab lets you change Name and Base Type. Right-click to delete an instance.

If a component is missing a behavior then the Error window provides information about the missing requirement.

Button component is missing a SpriteInstance which is required by the ButtonBehavior

{% hint style="info" %} At this time Gum does not automatically add required instances to components which need them. This may change in future versions of Gum. For now, instances must be manually added to resolve errors.

{% endhint %} ### Behavior Properties on Custom Behaviors The standard Forms behaviors ship with **Behavior Properties** (see [Behavior Properties](/gum/gum-tool/gum-elements/behaviors.md#behavior-properties)) that surface a Behavior category in the Variables tab and drive design-time preview. A custom behavior can declare these too, but there is currently no tool UI for it - they are added by hand-editing the behavior's `.behx` file. This is an advanced, rarely-needed scenario; the standard Forms behaviors already cover the common cases. --- # 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.flatredball.com/gum/gum-tool/gum-elements/behaviors/creating-new-behaviors-advanced.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.