Adding Gum Components to Entities

Introduction

Gum components can be added to entities within Glue without any code or additional setup. A common example of needing a Gum component on a Glue entity is a health bar in a RTS game.

Adding a Gum Component

For this example we will add a component called HealthBar to an entity named Soldier

  1. Expand the Soldier entity in Glue
  2. Right-click on the Objects folder
  3. Select Add Object
  4. Verify the FlatRedBall or Custom Type category is selected
  5. Select the type HealthBarRuntime (note that a search can help narrow down the options)
  6. Click OK

An instance of the HealthBar component will now be a part of the entity and will be attached (moves with) the entity automatically.

Changing Component Variables

Component variables can be changed in multiple locations depending on the needs of the project.

If a component should be the same across the entire project, then its variables should be changed in Gum.

If the component requires changes specific to each entity, then the variables can be changed in Glue.

If a component requires instance-by-instance modifications, it can be modified in code just like any other component Gum object.

Disabling Entity Attachment

As mentioned above, Gum objects which are added to Glue entities will automatically be attached. This can be disabled by detaching the Gum object from its parent.

For example, to detach the HealthBarRuntimeInstance  from its parent, the following code could be added to CustomInitialize :

Changing Gum Components Attachment at Runtime

Gum components which are part of an entity are attached to the entity itself (which is a PositionedObject ). Gum component attachment can be changed at runtime. The following code changes the HealthBarRuntimeInstance  so it is attached to the SpriteInstance  instead of the entire entity.

Coordinates and Sizes

Gum provides a powerful layout system for positioning objects. Attached Gum objects can take full advantage of this coordinate system. To use Gum layout effectively we must first understand how Gum objects attach to FlatRedBall objects.

For starters, consider a simple Glue entity with a single Sprite:

By default the origin of the object is its center. This can be visualized as shown in the following image:

We can therefore visualize the behavior of a Gum object that is added to the entity.

By default the component will be positioned at 0,0, and the default position values will make its top-left corner align with the center of the entity.

We can change this by adjusting the origin values:

  • XOrigin = Center
  • YOrigin = Center

Keep in mind that FlatRedBall entities do not have size values (width and height), so adjusting the width of the Gum object to be based on its parent width will result in the Gum object behaving as if its parent has Width and Height values of 0:

  • Width = 0
  • WidthUnits = RelativeToContainer
  • YOrigin = Center

Even though the Gum object is attached to a FlatRedBall object, the Gum object is still drawn using the Gum coordinate system (relative to the FlatRedBall object position). For example, by default Gum objects move down when their Y value is increased (assuming YUnits is not set to inverted).

  • XUnits = PixelsFromLeft
  • YUnits = PixelsFromTop
  • X = 20
  • Y = 40

As shown above, Gum objects can be attached to Sprites within an entity. This provides the added benefit of being able to use the Sprite’s size for layout.

If the Gum object is attached to the sprite (using the code above), then the Gum object will (by default) position itself according to the top-left of the Sprite:

  • XUnits = PixelsFromLeft
  • YUnits = PixelsFromTop
  • X = 0
  • Y = 0

We can also reference the Sprite’s dimensions by changing the WidthUnits and HeightUnits:

  • XUnits = PixelsFromLeft
  • YUnits = PixelsFromTop
  • X = 0
  • Y = 0
  • WidthUnits = RelativeToContainer
  • Width = 0
  • HeightUnits = RelativeToContainer
  • Height = 0

Keep in mind that the relationships are updated constantly, so if the Sprite changes size due to an animation, the Gum object will adjust automatically too.

Attaching to Scalable Entities

Although entities do not have a size by default, entities can implement the IReadOnlyScalable  interface to define their size. Implementing IReadOnlyScalable  serves as an alternative to attaching to a FlatRedBall Sprite.

Note that FlatRedBall Sprites implement the IReadOnlyScalable  interface, so that is why Gum attachment to Sprites allows referencing the Sprite’s size.

The following code shows how to implement the IReadOnlyScalable  interface on an entity called Soldier which has a SpriteInstance:

The example above shows a simple implementation. An actual implementation can have more features, such as having setters on the scale values, or creating width and height values which are not tied to the SpriteInstance.