Introduction

The Circle object is commonly used for collision and as a placeholder graphic in game development. Circles can be added to entities which implement the ICollidable interface to act as the entity's collision shape.

Adding a Circle

To add a circle to an existing entity:

1. Expand the entity

2. Right-click on the entity's Objects folder

3. Select Add Object

4. Verify the FlatRedBall or Custom Type option is selected

5. Select Circle

6. Click OK

Adding a Circle to a New Entity

Circles can also be added to a new entity. To do this:

1. Right-click on Entities

2. Select Add Entity

3. Check the Circle option. Notice that this automatically checks the ICollidable check box.

Introduction

Layers are a type of object which can be used to control the order in which visible objects in FlatRedBall are drawn. Most objects sort by their Z value. In other words, objects which are further from the Camera will draw behind objects which are closer to the Camera. Layers allow control over draw order without changing the Z of objects.

Layers are often used to draw certain categories of objects. For example, you may have regular game objects (such as trees, the ground, the sky), a Layer specifically for HUD elements (score, health, ammo), and another Layer for popup screens (pause screen, disconnected controller screen). Layers can also be used to draw visuals in 2D coordinates on top of a 3D Camera.

For a general tutorial on Layers in Glue, see the Using Layers Glue Tutorial page. For information on using Layers in code, see the Layer page.

Creating a Layer in the FRB Editor

To create a Layer in the FRB Editor:

1. Select a Screen or Entity which will contain the Layer. Usually Layers are added to Screens.

2. Click the Quick Actions tab

3. Click the Add Object button

4. Select Layer

5. Click OK

Layer Order

Layers are drawn in the same order that they are added in code. In other words, if Layer1 was added first, then Layer2, Layer1 would draw first, then Layer2 would be drawn on top of Layer1. Similarly, the order of Layers in Glue impacts the order that they are drawn. Layers draw top-to-bottom. Therefore, the first layer when looking at the list of elements in Glue will be drawn first, and any subsequent Layers will be drawn on top.

You can adjust the order of layers by right-clicking on a Layer and selecting one of the options to move it:

Adding an Object to a Layer

To add an object to a layer:

1. Make sure you have a Layer in the same Screen as your object

2. Drag+drop the object onto the layer

You can verify that the layer was changed by looking at the LayerOn property. Entity instances can be moved to a layer in code using the MoveToLayer function.

Introduction

AxisAlignedRectangles are rectangular shapes which cannot be rotated. AxisAlignedRectangles can be used as collision objects. For information on using AxisAlignedRectangles in code, see the AxisAlignedRectangle code page.

Adding an AxisAlignedRectangle to an entity

To add an AxisAlignedRectangle to an entity:

1. Expand your entity

2. Right-click on the Objects item

3. Select "Add Object"

4. Enter the name "Collision"

5. Set the SourceType to "FlatRedBallType

6. Set the SourceClassType to "AxisAlignedRectangle"

Introduction

The CameraControllingEntity provides a standardized way to control camera position in games which contain a moving character or which use Tiled for maps.

This page discusses working with the CameraControllingEntity in the FRB Editor. For information about how to work with it in code, see the CameraControllingEntity API Documentation.

Default Implementation

If your game was created with the wizard, then your GameScreen has an instance called CameraControllingEntityInstance.

This instance targets the PlayerList (averages the position of all Players in the PlayerList) and will restrict the visible area to the Map object.

The Extra Map Padding property adds a number of pixels of offset between the edge of the actual map and the desired visible edge. A positive value adds padding, effective shrinking the available area that the camera can view. A negative value allows the camera to move outside of the map. Note that the property on the CameraControllingEntity is called Map since this is the most common type of object used to control bounds, but it doesn't have to be a map.

Example: Adding a New CameraControllingEntity Instance

You can manually add a new instance to your game if you do not already have an instance in the GameScreen. Keep in mind this may have already been done for you if your game was created using the new project Wizard. To add a CameraControllingEntity to a game that has not used the Wizard:

1. Select your GameScreen

2. Select the Quick Actions tab

3. Click the Add Object to GameScreen button
4. Select the Camera Controlling Entity option

5. Click OK

Once you have created the instance, you can assign it the object to follow and the map to use as the visible bounds. To set which object the camera will follow:

1. Select the newly-created CameraControllingEntityInstance

2. Click the Variables tab

3. Select which object to follow in the Targets list. Notice that you can select entire lists of objects too, which will result in the CameraControllingEntity using the center position for all objects.

Similarly, the Map object can be set to control the visible bounds of the camera using the Map dropdown.

At runtime the Camera will automatically follow the target with no additional code required.

Introduction

Cameras can be added to Screens and Entities. Camera objects (by default) represent the main Camera (FlatRedBall.Camera.Main). If an object in an Entity is a Camera, then this (by default) attaches the main Camera to the Entity. If an object in a Screen is a Camera, then this object serves as an alias for FlatRedBall.Camera.Main, but no attachment occurs.

Example - Adding a Camera to GameScreen

Cameras added to a Screen can be modified in the FlatRedBall Editor. By default, adding a Camera object to a Screen does not create a new Camera, but rather it provides access to the main Camera. For more information, see the IsNewCamera property below. To access the camera in a Screen:

1. Select the Screen to contain the object. To make changes for all levels, select the GameScreen.

2. Click the Add Object button to add a new object to the screen
3. Select Camera as the type and click OK

The new camera appears in the GameScreen. It can be modified to make changes to the game, including in edit mode. For example, the Background Color can be changed from Black to any desired color.

IsNewCamera

The IsNewCamera property only appears on Camera objects.

• If this property is false (the default value) then the Camera object represents the main camera (FlatRedBall.Camera.Main).

• If this property is true, this is a new Camera instance. This is not often used but can be used for split-screen games, or games which use multiple overlayed cameras for control over rendering

Multiple Overlayed Cameras

Multiple cameras can be used for games which have camera-specific post processing. This section assumes that the cameras are added to GameScreen. You can also manage cameras in code if your game needs multiple cameras with lifecycles separate from Screens.

To add a camera:

1. Add a new object

2. Select Camera as the type

3. Enter a name for the new Camera. Usually the name for the camera should indicate its purpose, such as UiCamera

4. Click OK to add the new camera

5. Select the newly-added camera

6. Click on its Properties tab

7. Set the IsNewCamera property to true

Now that we have a new Camera we need to initialize the camera. Specifically, we need to update its values according to the game's display settings and we need to update the Camera's position. This section assumes that the overlayed Camera should move along with the main camera.

To initialize the Camera according to display settings, add the following code to your GameScreen's CustomInitialize:

CameraSetup.ResetCamera(UiCamera);

To attach the camera to the main camera, add the following code to CustomInitialize:

UiCamera.AttachTo(FlatRedBall.Camera.Main);

If you have specific entities which should appear only on this camera, you can call MoveToLayer.

EntityWhichShouldBeOnCamera.MoveToLayer(UiCamera);

Alternatively if you've created a Layer in your GameScreen, you can move this Layer to the Camera using the following code:

SpriteManager.RemoveLayer(HudLayer);
UiCamera.AddLayer(HudLayer);

Overlaying Cameras typically do not draw the world. You can set DrawsWorld to false either in the FRB Editor or in code.

UiCamera.DrawsWorld = false;

If you are using this Camera to draw post processing, you can add post processing to either the main camera or cameras created in the FRB Editor. For more information see the .fx file page.

Introduction

The Is2D option can be used to make a Layer use 2D coordinates. Layers which are 2D can be used even if the current Camera is in 3D. Layers which are 2D are often used to create HUDs and UI Screens.

Common Usage

The most common usage of the Is2D property is to create a 2D layer in a game which uses a 3D camera. Typically 3D games will have some type of 2D hud, so a 2D layer is needed to hold hud.

2D Layer on a 3D camera

This example shows a simple setup where a 2D layer can be used on a 3D graphic. First, the game is set up to use a 3D camera.

Next, a Sprite is added to a GameScreen. It has the following variable values:

• Texture = GroundTexture
• Right Texture Pixel = 512

• BottomTexturePixel = 512

• Texture Address Mode = Wrap

• Y = -10

• Rotation X = 1.5708

The GameScreen has a layer named Layer2D for 2D objects.

Finally the GameScreen has a Text instance called GameOverText which has been placed on Layer2D.

The result is SpriteInstance is drawn in 3D, but the GameOverText is drawn and positioned in 2D.

Introduction

The FRB Editor supports the creation and management of CollisionRelationship objects. This document covers the features provided by the FRB Editor, and explains common scenarios where you may need to interact with the CollisionsRelationships in code. Most cases can be handled by CollisionRelationships in the FRB Editor; however, more advanced situations can be handled in code. For information about creating and working with CollisionRelationships in code, see the .

What is a CollisionRelationship?

CollisionRelationships define how to respond when two types of objects collide (overlap). Examples of reactions to overlapping objects include:

• A player must take damage when colliding with a bullet

• A bullet must be destroyed when colliding with a wall

• An enemy must be moved so that it doesn't overlap the same space as another enemy

• A car must reduce its maximum speed when driving over grass

Even simple games will require multiple relationships, and larger games may include dozens of relationships. Glue makes the creation and management of these much simpler than management purely in code.

What Types of Objects Can be Used in CollisionRelationships?

Collision relationships can be created between:

• Lists of entities which implement ICollidable

• Individual Entity instances which implement ICollidable

• TileShapeCollections

• ShapeCollections (regular, as opposed to TileShapeCollections)

Creating a CollisionRelationship

CollisionRelationships can be created a few ways. Typically collision relationships are added to a screen, such as a base GameScreen. In this example we will use a screen called GameScreen which already has a few objects:

• PlayerList (a list of Player entities)

• BulletList (a list of Bullet entities)

• EnemyList (a list of Enemy entities)

• SolidCollision (a TileShapeCollection)

Option 1 - Drag+drop

You can drag+drop one collidable object (such as a list) onto another collidable object (such as another list or a TileShapeCollection) so long as the two objects are in the same screen. This will create a CollisionRelationship between the two objects.

Option 2 - Collision Tab

The Collision tab displays when a collidable object or list is selected

The image above displays the Collision tab for the BulletList. Notice that the BulletList can collide with any of the other collidable objects in the GameScreen including itself. Adding collision is easy - just click the Add button next to the object in the Collision tab to create a new relationship. For example, clicking on the Add button next to EnemyList creates a relationship between BulletList and EnemyList.

Option 3 - Create CollisionRelationship Object Manually

CollisionRelationships are regular Objects which can be created through the right-click menu. To create a CollisionRelationship through the right-click menu:

1. Right-click on a Screen's Objects

2. Select Add Object

3. Verify FlatRedBall or Custom Type is selected

4. Select the CollisionRelationship type

5. Click OK

In this case the newly-created CollisionRelationship will not yet reference any collidable objects in the screen, and the game will not compile until the objects in the relationship are set (as shown in the next section).

Editing a CollisionRelationship in FlatRedBall

Once a CollisionRelationship is created, it can be edited by selecting it under the Screen's Objects folder and clicking the Collision tab.

A CollisionRelationship objects can be changed using the two drop-downs. Note that if the Auto-name Relationship checkbox is checked, the name of the relationship will automatically change when either of the two objects in the relationship changes. Of course, if you create CollisionRelationships using either the Add button or the drag-drop method, you do not need to set the object types.

Subcollision

Subcollision allows specifying a specific shape within a collidable entity to use when performing collision. This is useful if an entity includes multiple shapes, each for different purposes. For example, an enemy may have a circle for solid collision (preventing the enemy from walking through walls) but it may also have a line for line-of-sight collision. In this case, we do not want the line to collide against the walls, so we would specify that only the enemy's circle should collide with the walls. All available shapes for subcollisions appear in the Subcollision dropdowns for each object. Note that changing the subcollision will also rename the CollisionRelationship if the Auto-name Relationship option is checked.

Collision Physics

Physics can be set up through the Collision tab which offers multiple options.

:

• No Physics - Colliding objects will not automatically have their positions or velocities changed by the CollisionRelationship.

• Move Collision - Colliding objects will be separated if a collision occurs using their relative mass values. The most common values for First Mass and Second Mass are 1, 1 if both objects have equal mass and 0, 1 if the first object should not be able to push the second (in the case of colliding against a solid TileShapeCollection)

  • First Mass - the mass of the first object in the relationship (the mass of enemies) relative to the mass of the second object. If this object should not be able to push the second object, it should have a mass of 0.

  • Second Mass - the mass of the second object relative to the first object. If this object should not be able to push the first object, it should have a mass of 0.

• Move Soft Collision - Colliding objects will be separated, but gradually over time. This creates a "soft" feel, allowing objects to overlap and push each other around.

• Bounce Collision - Colliding objects will be separated if a collision occurs. They will also have their velocity adjusted in response to the elasticity value. An elasticity value of 1 will preserve momentum. An elasticity of 0 will be an inelastic collision - where momentum is lost.

  • First Mass/Second Mass - see Move collision

  • Elasticity - A multiplier for an object's velocity when it collides. A value of 0 will absorb momentum. A value of 1 will preserve momentum. A value greater than 1 will add momentum.

Physics can also be applied using collision events if your game needs to customize the behavior when a collision occurs. For example, you may want the relaitive masses between entities to vary rather than always being fixed.

Collision Events

In some cases games will need to perform custom logic when a collision occurs. For example:

• A Player entity takes damage when colliding with a bullet

• The Bullet entity being destroyed when colliding with a wall

• An Enemy entity's movement speed being slowed when colliding with mud TileShapeCollection

• Certain objects should have different masses when performing collision.

Collision events can be created by dropping a CollisionRelationship on a Screen's Events folder.

Notice that the CollisionRelationship used in this example is between a list of Enemies and a list of Players, but the event is raised for a single Enemy and a single Player. Since each enemy may collide with each player, the event method may get raised multiple times per frame. Every time the event is raised, the arguments tell you which two objects collided.

Code Example - Destroying Entities in Collision

For example, in the code above, you could destroy either the enemy (which is called first) or the player (which is called second) in the event. To destroy the enemy, you can do the following code:

Code Example - Detecting TileShapeCollection Collided Shapes

Code Example - Custom Entity Masses

If all entity instances have the same mass, then you can set your collision relationship physics through the FlatRedBall Editor. If your game requires custom masses, then you can implement your own physics in the collision event.

For example, the following code would adjust the player's mass so that it is higher if the player is shooting. This makes the player harder to move when shooting.

Manual Collision Relationships

CollisionRelationships created in Glue will be automatically managed and will automatically perform their every-frame logic. In some cases games need to manually perform collision logic. For example, a game may need to first reset variables on an entity before collision logic is performed for that frame. In that case, the CollisionRelationships created in Glue can be modified in the CustomInitialize method of the GameScreen. For example, to disable the EnemyListVsPlayerList CollisionRelationship, the following code can be used:

Introduction

The FlatRedBall Editor supports creating objects of type ShapeCollection.

Note that entities which are created as ICollidable automatically have a ShapeCollection named Collision, and all shapes shapes are added to the default Collision shape collection. In this case you do not need to manually create a ShapeCollection. For more information, see the page.

Adding a ShapeCollection

To add a ShapeCollection:

1. Right-click on Objects under a Screen or Entity

2. Select Add Object

3. Verify that FlatRedBall or Custom Type is selected.

4. Select ShapeCollection

5. Click OK

Note that FlatRedBall also supports the .shcx file format, but this is no longer recommended. The PolygonEditor tool is no longer maintained, and the recommended approach is to add a ShapeCollection as shown above and to modify the shapes using FlatRedBall's LiveEdit.

Adding Shapes to a ShapeCollection in FlatRedBall

ShapeCollections can have shapes added manually. The ShapeCollection serves as a "list" of shapes, but unlike normal lists, the ShapeCollection can contain multiple types of objects.

To add a new shape to the ShapeCollection:

1. Right-click on the ShapeCollection instance

2. Select Add Object

3. Select one of the shapes - notice that FlatRedBall filters the available types to the types allowed in a ShapeCollection.
4. Click OK

Your newly-created shape is added to ShapeCollection in the tree view.

ShapeCollection in code

RenderTarget2D instances can be created in the FRB Editor. When created in the FRB editor, they have the following behavior:

• They will automatically match the resolution of the screen

• They will be cleaned up when the Screen is destroyed

For an example on using RenderTarget2Ds with FlatRedBall Layers, see the Layer RenderTarget page.

Introduction

PositionedObjectLists (also referred to as lists) in the FlatRedBall Editor hold lists of objects which inherit from the PositionedObject type. Positioned objects include:

• Any Entity (the most common types of lists)

• Circles

• AxisAlignedRectangles

• Texts

• Sprites

In code all of the objects mentioned above inherit from the FlatRedBall.PositionedObject class.

The most common place for lists is in GameScreen, although lists can exist in any screen and even in other entities.

Entity List Behavior

As shown below, when an entity is created, the FlatRedBall suggests creating a list in GameScreen as well as adding a factory for the list. This configuration enables the following common and useful behaviors and relationships:

• Entity lists automatically associated themselves with factories, so that creating a new instance through a factory in code results in the instance being added to the list.

• Entity lists call Activity on all contained instances, keeping activity behavior consistent whether the instance is created in the FRB editor or at runtime (such as through a factory)

• Entity lists automatically destroy all instances when the screen ends, making screen cleanup easy

Default Functionality - Automatically Created Lists in GameScreen

By default the FRB Editor creates lists for newly-created entities if the default options are left unchanged. For example, the following animation shows the creation of an entity called Enemy which also results in an EnemyList added to GameScreen.

Creating a PositionedObjectList Manually

The FlatRedBall Editor provides a number of ways to create new lists.

Option 1 - Add List to GameScreen Quick Action

If your game has a GameScreen, and if your GameScreen does not already contain a list for an entity, then the Quick Actions tab shows a button to add a list to the GameScreen. Clicking this button creates a new list in the GameScreen.

Option 2 - Right-Click Drag+Drop

Entity lists can be created by right-click drag+dropping an entity into a screen. This is useful if you are adding lists of entities to screens other than the GameScreen.

Option 3 - Right-click Add Object Menu

PositionedObjectLists can also be created through the regular right-click menu in an screen or entity's Objects node:

1. Right-click on Objects

2. Select Add Object

3. Make sure FlatRedBall or Custom Type is selected

4. Select PositionedObjectList<T>

5. Select the type of list to create using the dropdown

6. Enter the name of the list

Adding to a List

Once a list has been created, instances of the list's type can be added through the FRB Editor using a number of methods.

Option 1 - Drag+drop onto Screen, Objects folder or List

If a list contains a screen, it becomes the default container for newly-created instances that are added by drag+drop. For example, the following shows enemies being added to the EnemyList by drag+dropping an enemy on Level1, Level1's Objects folder, and directly on the EnemyList.

Option 2 - Right-click, Add Object

Objects can be directly added to the list by right-clicking on the list. Notice that the Add Object window restricts the types of entities which can be added to the types that are supported by the list. For example, the following animation shows how to add an Enemy to an Enemy list with the right-click menu.

If the list is of a base type, then the right-click option provides all available options for the list. For example, the following is a screenshot from a game which has multiple entity types inheriting from Enemy:

CallActivity

The CallActivity property controls whether the FRB Editor should generate Activity calls for a PositionedObjectList. By default this value is set to true. For example, the following shows a BulletList inside a screen which has its CallActivity set to true:

If this value is changed to false, then the Bullet instances inside of BulletList would not have their Activity (and CustomActivity) methods called automatically in generated code.

The most common reason to set this value to false is when dealing with derived entity lists. For example, consider a game which has a base Enemy entity as well as Skeleton entity which inherits from Enemy (Skeleton is an Enemy variant). If the game needs to perform custom logic on Skeleton instances then it may need both an EnemyList and SkeletonList in GameScreen.

In this case, Skeletons which are created through the Skeleton factory would be added to both the EnemyList and the SkeletonList. If both EnemyList and SkeletonList called Activity, then Skeleton instances would have activity called twice per frame. This can result in unexpected behavior such as movement logic being applied twice per frame.

If a derived entity type list is added to a screen through the quick action button, FlatRedBall automatically sets CallActivity to false.

If an entity list