States

Introduction

States allow you to modify your object in an organized, type-safe, way. States can also be previewed when the game is running in edit mode, speeding up iteration. States are a lightweight alternative to using inheritance, and can even be used to apply changes to a Screen or Entity multiple times. States can exist on any Screen or Entity, and appear under the States folder in the FRB Editor tree view.

Previous versions of FlatRedBall supported uncategorized states. These states can cause confusion about when properties are assigned so they have been removed from FlatRedBall. Now, all states must be categorized.

The following image shows a PowerUp entity with a PowerUpCategory containing three states.

PowerUp entity with 3 categorized states

Adding States

The FRB Editor provides two different ways to add states. The preferred method is using the State Data tab. The second way is using the right-click menu. The two can both be used, so you don't have to pick which to use; that said, using the State Data method can be easier, so it is recommended.

Before you can add states, you must first add a state category. For information on how to add a state category, see the State Categories page.

State Data

Once a category has been created, states can be added in the State Data tab.

PowerUpCategory showing the State Data tab

New states can be added by entering names in the left-most column. Adding a new name creates a new state.

New states added to the PowerUpCategory in the State Data tab

By default, variables do not appear in the State Data tab (and are not accessible by states in the category). You must explicitly add variables which you would like to edit in your state. Conceptually, this makes sense considering categories are usually built to only modify a subset of variables.

For example, consider a variable which tunnels into a Sprite's CurrentChainName - which we'll call "Animation" to keep the name short:

Animation variable in a PowerUp entity

To make this variable accessible to the PowerUpCategory, drag+drop the variable onto the category. Doing so results in the variable appearing in the State Data grid.

Drag+drop a variable onto a State category to have it show up in the State Data grid

Alternatively, a category's variables can be added and removed in the State Data tab.

Variables can be included and excluded from categories

Right-Click Menu

States can also be added through the right-click menu on a category.

This method is the old way of adding states. It is still supported, but it is a little more cumbersome compared to using state data. States added this way still appear in the State Data tab.

Setting States in Code

Every state category generates a class which is embedded in the screen or entity containing the state. By default states can only be assigned inside the entity or screen defining the state. For example, if the PowerUp entity defines a state category named PowerUpCategory, then states can be assigned in code.

Assigning the CurrentPowerUpCategoryState in code

Assigning the state in code applies all state's variables which were assigned in the FRB Editor.

Conditional Logic Based on State

The state can be compared against the values which are assigned to perform logic. For example, the following code could be written to perform logic based on the state of the power up.

if(this.CurrentPowerUpCategoryState == PowerUpCategory.FirstState)
{
  // Do logic for first state
}
else if(this.CurrentPowerUpCategoryState == PowerUpCategory.SecondState)
{
  // Do logic for second state
}
// and so on...