Introduction

The "Type" property on a variable defines what kind of data the variable can hold. For example, the "string" type would be used for variables which should hold words and sentences, "float" and "int" may be used for variables which should hold numbers, and the "bool" value is useful for variables which old true or false values.

How to set Type

The type of the variable depends on whether the variable is an exposed, tunneled, or "new" variable:

• If the variable is an exposed variable, then the type of the variable is set by the given element. For example, the X variable on Entities will always be a "float" type.

• If the variable is a tunneled variable, then the type is defined by the variable being tunneled to. It is possible for a tunneled variable to convert the type to a new type.

• If the variable is a new variable, then the type of the variable is defined by the new variable window.

Available types

Variable types fall into one of three categories:

1. Primitive types (int, float, string, bool)

2. Non-primitive types used in tunneled variables (such as Color in a Circle)

3. Project-specific types (types defined in spreadsheet files)

The default value for any variable of a primitive type can be set in Glue. Some non-primitive types can be set in Glue. Project specific types can (at the time of this writing) only be set in code.

Introduction

Variable naming is something which may seem like a very simple topic; however, the variable names you choose for your object can be very important. There are three types of variables in Glue:

1. Exposed

2. Tunneled

3. Custom (under the "Create New" tab)

Exposed Variables

The Exposed category of variables is simply the exposing of an existing variable. Because of this, the name of the variable is already set. In other words, there's not much point in discussing variable naming regarding Exposed variables because Exposed variable names can't be changed.

Custom Variables

Custom variables are brand new variables which have no impact on an Entity or Screen, at least as far as Glue is concerned. The purpose of these variables is to "escalate access" of variables that are used in custom code. Usually the naming of these variables is fairly straight-forward. It's best to name these variables according to what they do. For example, if a variable is used to control how fast a character walks in game, then "Speed" or "WalkSpeed" are perfectly appropriate names.

Tunneled Variables

Tunnled variables are the variables which deserve the most discussion about naming. The reason is because it may not be immediately obvious what the name of a variable should be. Let's consider a situation where you are creating an Entity called Button, and this Button uses a graphical object (such as a SpriteFrame) to display itself. You may want to allow each instance of Button to change its size independently, so you decide to tunnel in to the SpriteFrame's ScaleX and ScaleY properties. If you tunnel in to ScaleX and leave the default name, then the variable name will be the name of the SpriteFrame with "ScaleX" at the end. For example, if your SpriteFrame Object is named "SpriteFrameInstance" then the variable will be "SpriteFrameInstanceScaleX". What a long name! Length isn't the only problem with the variable "SpriteFrameInstanceScaleX". In this particular case, the variable is unnecessarily specific. That is, if your Button Entity only contains a SpriteFrame object and nothing else which can be scaled, then there's no need to name the variable "SpriteFrameInstanceScaleX"; the name "ScaleX" is sufficient. Of course, in a situation where you have multiple objects which you want to tunnel in to, it may be a good idea to keep the default name the same. For example, if you are creating a character that has a Sword and a Shield Object and you want to control the ScaleX of each individually, then SwordScaleX and ShieldScaleX are perfectly acceptable variable names. Since Glue doesn't understand the purpose of Entities or what objects you intend to add and tunnel in to, it can't predict whether it should prepend the name of the Object that is being tunneled into. Therefore it makes the safest assumption and suggests the more-specific name. It's up to you to click the "Advanced >>" button and change the name to be less specific if appropriate.

Introduction

Variables in entities and screens can have events which are raised whenever the variable is changed. These events can be used to broadcast changes (such as in the case of INotifyPropertyChanged) or to perform other custom logic such as updating a health bar when health changes.

Example : Adding an Event to a Variable by Drag+Dropping

To add an event to a variable:

1. Expand your Screen or Entity's Objects folder

2. Drag+drop the variable onto the Events folder

1. Open your project in Visual Studio

2. Look for the Events file for your Screen or Entity, which will be named ScreenOrEntityName.Events.cs. In this example, the file is named FanRight.Events.cs.
3. Add code to the event to respond to the variable change.

Example : Assigning Event Handlers

• Before<VariableName>Set - for example BeforeForceVelocityXSet

• After<VariableName>Set - for example AfterForceVelocityXSet

These can be seen in generated code:

Notice that the Before event is an Action which takes a float. This argument contains the new value, enabling the handler to decide how to respond to the new value before it has been assigned. These can be handled in custom code. For example, the following code could be used to print out that the variable is being assigned:

private void CustomInitialize()
{
    BeforeForceVelocityXSet += HandleBeforeForceVelocityXSet;
    AfterForceVelocityXSet += HandleAfterForceVelocityXSet;
}

private void HandleBeforeForceVelocityXSet(float newValue)
{
    FlatRedBall.Debugging.Debugger.Write($"About to set value to {newValue}");
}

private void HandleAfterForceVelocityXSet(object sender, EventArgs e)
{
    FlatRedBall.Debugging.Debugger.Write($"Just assigned value to {ForceVelocityX}");
}

Static Events (IsSharedStatic)

If a variable's IsShared is set to true, then the variable is generated as a static variable in code. This means that its events must also be static. If a variable with IsShared set to true generates an event, the following occurs:

• All events are static

• If the variable is drag+dropped onto the Events node, the event handler method is generated as static

• A static constructor is added to generated code for the owning Screen/Entity. This may conflict with static constructors if you have added one in custom code

• The event is subscribed in the static constructor, so it will always be active

• The event is never unsubscribed. By contrast instance events are unsubscribed when the owning Screen/Entity are destroyed

As mentioned above, if your Screen/Entity already has a static constructor, adding a static event in the FRB editor will result in a conflicting static constructor.

Also note that even if an event is raised for a Screen/Entity, that does not mean that the content has been loaded for that entity. The content will only have been loaded if an instance of the Screen/Entity has been created, or if the content has been loaded explicitly through a LoadStaticContent method call.

Introduction

The IsShared variable determines whether a given variable is shared among all instances of a given Entity. In code, a variable which is marked as IsShared is generated as static. A variable which is marked as IsShared has the following characteristics:

• All instances will always have the same value

• The value can be set or read in code even if no instances have been created, or if no instances are available in the current scope

• The value persists even when a Screen is switched or an instance of the entity is destroyed

Setting IsShared

To set the IsShared property:

1. Expand the Variables tab on the Entity or Screen which contains the variable

2. Select the variable

3. Click the Properties tab

4. Change IsShared to True or False as desired

Accessing a IsShared (static) Variable in Code

Once a variable has been marked as IsShared, it can be accessed from anywhere in code through the type. For example, to access the DebuggingVariables ShowTerrainCollision variable in code, the following snippet could be used:

if(Entities.DebuggingVariables.ShowTerrainCollision == true)
{
   // do something to show the terrain collision
}

IsShared and CreatesEvent

Variables which have IsShared set to true generate static events. For more information, see the CreatesEvent page.

The HasAccompanyingVelocityProperty property is a property that tells Glue to generate a Velocity value for the given variable. The velocity variable is useful in the following situations:

• If you intend to change a variable at a constant rate over time then you can set this value to true. Glue will generate a velocity property which will be applied at a time-based rate. The application of this value considers pausing.

• If you intend to interpolate a custom variable, then it will be necessary to create a velocity property. If a velocity property is created Glue will use it in interpolating states.

Introduction

SetByDerived is a variable that allows derived Entities to access variables defined in a base Entity. Once a variable is SetByDerived, any Entities that derive from the given Entity (that is, use it as its ) can set the variable to a different value.

When using inheritance, the derived Entity in code inherits from the base Entity, therefore all variables are available in custom code. The SetByDerived is only useful for exposing the variable in Glue.

Usage Example

Consider a situation where your game has three Entities: Enemy, Ghost, and Zombie: In this situation the Enemy entity is the base for Ghost and Zombie: Notice that by default the Enemy's MovementSpeed variable is not part of Zombie or Ghost: If the MovementSpeed in Enemy has its SetByerived value set to True, the variables will automatically appear in the Ghost and Zombie Entities:

Introduction

Variables in Glue are not automatically ordered alphabetically. The reason for this is because the order that variables appear in Glue impacts the order that they are set in Glue's generated code. Instead, variables can be reordered through the "Move" commands when right-clicking on a variable in Glue:

When does order matter

The order of variables does not matter in most cases; however, it can matter in some. For example consider an object that contains an object that is an Entire Scene. In this situation one Sprite in the entire Scene has a special purpose and will at times be visible when the entire Scene is invisible, or will be invisible when the entire scene is visible. To accomplish this, you would need two tunneled variables - one that tunnels into the Scene's Visibility, one that tunnels into the the Sprite's visibility. However, setting the Scene's Visible property is just a shortcut way of setting the visibility of all objects. Therefore, the special Sprite (which is part of the Scene) must have its Visible property set after the Scene's Visible property is set.

Introduction

Variables allow modifying built-in properties on objects (such as the position of an entity) or the creation and modification of new properties (such as a character's max movement speed). The FRB Editor includes three types of variables:

1. Tunneled variables - variables which can be added to a screen or entity that provide access to a variable of an object contained within the screen or entity

2. New variables - variables which do not have any built-in functionality, but which are added through the editor and used in custom code

3. Exposed variables - variables which are available in code but not available (by default) on an entity. Exposed variables expand the available variables on an entity or screen.

Adding a Variable

Variables can be added to creens and entities by following these steps:

1. Expand an existing screen or entity

2. Right-click on the Variables folder

3. Select Add Variable

This will bring up the New Variable window which is used to select the variable type and set options according to the selected variable type.

Expose an existing variable

Exposing an existing variable enables editing a variable which would otherwise only be available in code. The variable dropdown provides a list of available variables for the selected object. Note that this type of variable creation is rarely used.

Tunnel a variable in a contained object

Tunneled variables enable exposing a variable from a contained object to that it is editable at the entity level. For example, consider an Enemy entity with an AxisAlignedRectangle instance.

You may want to change the color of the AxisAlignedRectangle per instance (or through a State). To do this, you can tunnel in to the variable. To do this:

1. Drag+drop the AxisAlignedRectangleInstance onto the Variables folder

2. Use the dropdown to select the desired variable - Color

3. Optionally - change the Alternative Name

4. Click OK

Note that variables can be tunneled by right-clicking on the Variables folder, but this drag+drop approach auto-selects the Tunnel a variable in a contained object option, and selects the object in the Object dropdown.

Create a new variable

To add a new variable:

1. Right-click on the Variables folder

2. Click the Create a new variable option

3. Select the type such as float

4. Enter a name such as MaxSpeed

5. Click OK