Glue supports the creation and management of CollisionRelationship objects. This document covers the features provided by Glue, and explains common scenarios where you may need to interact with the CollisionsRelationships in code.
For information about creating and working with CollisionRelationships in code, see the CollisionManager page.
What is a CollisionRelationship?
CollisionRelationships are objects which indicate that two objects in Glue require some type of game logic whenever colliding (overlapping). 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:
- Entities which implement ICollidable
- Lists of entities which implement ICollidable
- ShapeCollections (regular, as opposed to TileShapeCollections)
All CollisionRelationships will at include at least one Entity or Entity list, so it is important to mark Entities which you intend to use in relationships as ICollidable.
For information on ICollidable entities, see the ICollidable Entity page.
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)
Note that the TileShapeCollection may have its SetByDerived value set to true. This allows the creation of CollisionRelationships in a base Screen even though the TileShapeCollection is created in a derived Screen.
In this screen all objects can be a part of a collision relationship. When selected, any of these objects will display a Collision tab.
The image above displays the Collision tab for the BulletList. Notice that the BulletList can collide with any of the four 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.
Alternate Way to Create a CollisionRelationship
CollisionRelationships are regular Glue objects which can be created through the right-click menu. To create a CollisionRelationship through the right-click menu:
- Right-click on a Screen’s Objects
- Select Add Object
- Verify FlatRedBall or Custom Type is selected
- Select the CollisionRelationship type
- 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 Glue
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 the Add button as shown earlier, the objects in the drop-downs can be left as-is.
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.
Physics can be set up through the Collision tab using one of three options:
- No Physics – Colliding objects will not automatically be moved 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)
- 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.
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.
Collision events can be created by dropping a CollisionRelationship on a Screen’s Events folder.
For more information on Glue events, see the Glue Events page.
Like all other events, collision events can be edited in code. In the example above, the GameScreen.Event.cs file now includes an function OnEnemyListVsPlayerListCollisionOccurred which is called whenever a collision occurs between an Enemy and Player instance.
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 called multiple times per frame.
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:
EnemyListVsPlayerList.IsActive = false;
void CustomActivity(bool firstTimeCalled)
// before calling collision, reset the Enemy's DidCollide:
foreach(var enemy in EnemyList)
enemy.DidCollide = false;
// now do the collision. This assumes that the
// DidCollide property gets set or used in the event
// handling method for this relationship: