Introduction

IAttachableRemovable is the base class for FlatRedBall.Math.AttachableList. This interface requires that the implementer has a method called RemoveGuaranteedContain.

Information about RemoveGuaranteedContain

RemoveGuaranteedContain is a method with the following signature:

void RemoveGuaranteedContain(IAttachable attachable);

RemoveGuaranteedContain is a method which removes the argument attachable from the list and in the case of FlatRedBall.Math.AttachableList it cleans up the two-way relationship. For AttachableLists calls Remove, which means that the argument method must be contained in the list (a Contains check is not performed internally). This is why the method includes the phrase "GuaranteedContain".

Introduction

The Relationships list contains all of the relationships being managed by the CollisionManager. In most cases, FlatRedBall games (using Glue) will not modify this list, but it is exposed publicly for:

• Plugins to add new types of relationships

• Debugging

• Manual removal of collision relationships

Code Example - Clearing Relationships

The Relationships property is a standard List so it can be modified just like any other list. Collisions can be cleared by calling the Clear function:

CollisionManager.Self.Relationships.Clear();

Note that Glue will automatically clear relationships when a screen is destroyed, so this does not need to be called in most games.

Introduction

The MakeOneWay method makes the calling AttachbleList a one-way list. In other words, it means that the AttachableList will still contain all of the objects that it contained before calling MakeOneWay; however, the contained elements will no longer know that they belong to this List. This essentially makes the AttachableList behave like a regular List - at least until new objects are added to the List, or until MakeTwoWay is called.

Usage Example

The MakeOneWay method is useful if you have a list of IAttachables (such as Sprites) which you want to remove from their respective managers without having them removed from their List. In the following example, the element at index 0 will get removed:

// assuming MySpriteList is a valid SpriteList, which in inherits from AttachableList
SpriteManager.Remove(MySpriteList[0]);

To prevent the removal from the list, it can be made one way:

MySpriteList.MakeOneWay();
SpriteManager.Remove(MySpriteList[0]); // <- This call will not modify MySpriteList now

Introduction

The AxisAlignedCube is a geometric shape from the FlatRedBall.Math.Geometry class. As a 3D shape, it can be used for detecting collisions with 3D or 2D shapes. The AxisAlignedCube class shares many similarities with other shape classes (Circle, Line, AxisAlignedRectangle, Polygon, etc). For general information about shapes, see the ShapeManager wiki entry.

Creating an AxisAlignedCube

AxisAlignedCubes are created through the ShapeManager. The following code creates an AxisAlignedCube through the ShapeManager and resizes it: Add the following using statement using FlatRedBall.Math.Geometry; Create the instance globally AxisAlignedCube mCube; In the Initialize method

mCube = new AxisAlignedCube();
mCube.Visible = true;
mCube.ScaleX = 3;
mCube.ScaleY = 4;

Alternatively, you can create an AxisAlignedCube with the Visible property set first by doing this Create the instance globally AxisAlignedCube mCube = ShapeManager.AddAxisAlignedCube();

Relationship with ShapeManager

See ShapeManager wiki entry.

Collisions With AxisAlignedCube

For detecting collisions with AxisAlignedCubes, use the following code: Add the following using statement

using FlatRedBall.Math.Geometry;
using FlatRedBall.Input;

Create the instance globally

AxisAlignedCube mCube;
AxisAlignedCube mCube2;

In the Initialize method before the base call

mCube = new AxisAlignedCube();
mCube.Visible = true;
mCube.Color = Color.Red;
            
mCube2 = new AxisAlignedCube();
mCube2.Visible = true;
mCube2.Color = Color.Red;
mCube2.X = 1;

In the Update method before the base calls

if (mCube.CollideAgainst(mCube2))
{
  mCube2.Color = Color.Blue;
}

if (mCube2.CollideAgainst(mCube))
{
  mCube.Color = Color.Orange;
}

Determining Collision Side

When two AxisAlignedCubes collide the collision side can be determined rather easily. The following code determines the side that two rectangles collided on: Add the following using statements

using FlatRedBall.Math.Geometry;
using Side = FlatRedBall.Math.Collision.CollisionEnumerations.Side3D;

Assuming cube1 and cube2 are valid AxisAlignedCubes:

Side side = Side.None;

if (mCube1.CollideAgainstMove(mCube2, 0, 1))
{
  if (mCube1.LastMoveCollisionReposition.X > 0)
      side = Side.Right;
  else if (mCube1.LastMoveCollisionReposition.X < 0)
      side = Side.Left;
  else if (mCube1.LastMoveCollisionReposition.Y > 0)
      side = Side.Top;
  else if (mCube1.LastMoveCollisionReposition.Y < 0)
      side = Side.Bottom;
  else if (mCube1.LastMoveCollisionReposition.Z > 0)
      side = Side.Front;
  else if (mCube1.LastMoveCollisionReposition.Z < 0)
      side = Side.Back;
}

AxisAlignedCube Members

• FlatRedBall.Math.Geometry.AxisAlignedCube.CollideAgainstBounce

Did this article leave any questions unanswered? Post any question in our forums for a rapid response.

Introduction

The FindByName method returns the first object in the list with the name matching the argument. The signature for the method is:

Common Usage

The FindByName method is most commonly used on AttachableLists which are populated by data which is loaded from file (or through the content pipeline), such as lists contained in or . For example, a .scnx may be created as the level for a platform game. The goal of the level is to reach a door, which is a in the .scnx. This requires special logic (collision tests, then advancing to the next level on a successful collision). To perform this logic, the code that's loading the .scnx needs to have reference to the door Sprite. To accomplish this, the person assembling the .scnx should appropriately name the door and communicate this to the programmer. We'll assume that the door is named "door". Add the following code to get a handle to this object:

Introduction

Although AxisAlignedRectangles inherit from the PositionedObject class, which inherits from the IRotatable interface, AxisAlignedRectangles cannot be visibly rotated. This article discusses how rotation values are applied to AxisAlignedRectangles.

AxisAlignment and the collision/visible representation of an AxisAlignedRectangle

As far as the visible representation and collision behavior of an AxisAlignedRectangle, rotation will have no impact on an AxisAlignedRectangle. For more information, see this section.

How do children of AxisAlignedRectangles behave?

All positions in FlatRedBall are defined by a combination of X, Y, and Z values. These values, when measuring absolute space, represent the distance from the origin along each axis by the same name as the component (X axis, Y axis, and Z axis). In FlatRedBall, when using an unrotated Camera, positive X points to the right and positive Y points up. The "axis aligned" part of AxisAlignedRectangles simply means that the edges of the rectangle are parallel (line up with) the X and Y axes. This is always true for AxisAlignedRectangles - even if they are rotated. However, that doesn't mean that the underling rotation values are always 0. In other words, if another PositionedObject is attached to an AxisAlignedRectangle, and the (parent) AxisAlignedRectangle is rotated, then the child PositionedObject will react to the rotation.

Introduction

CollideAgainstMoveSoft performs the following logic:

1. It checks to see if two AxisAlignedRectangles are overlapping

2. If so, it adjusts the velocity of the caller and the argument AxisAlignedRectangles according to how much the two shapes overlap each other and according to the separation velocity.

Since this function adjusts the velocity of the caller and the argument, then your code must not explicitly set Velocity on either of the two objects or else your code will overwrite the Velocity values set by this function.

Understanding CollideAgainstMoveSoft

CollideAgainstMoveSoft adjusts the velocities of the two involved objects according to the strength of the separation (the last parameter in the function) as well as how far the two overlap.

A physical example of this would be to have magnets with the same charge (so they repel) on ice. If they are sufficiently far away then the repulsion is essentially 0, but as they get closer the amount increases. The math behind how this works is not physically identical to magnetic attraction and repulsion, but the concepts are similar.

Code Example

The following code assumes 2 AxisAlignedRectangles are created:

1. AxisAlignedRectangleInstance1

2. AxisAlignedRectangleInstance2

It assumes you are using Glue so the code has been written in CustomActivity in a Screen, but it could be used outside of Glue as well.

void CustomActivity(bool firstTimeCalled)
{
    // The higher the drag the less time the
    // rectangles will spend moving when no acceleration
    // is applied to them:
    AxisAlignedRectangleInstance1.Drag = 3;
    AxisAlignedRectangleInstance2.Drag = 3;


    Keyboard keyboard = InputManager.Keyboard;
    // Increase acceleration to make the rectangle movement
    // more responsive, but you may also want to increase 
    // the drag if increasing this:
    const float acceleration = 400;
    keyboard.ControlPositionedObjectAcceleration(AxisAlignedRectangleInstance1, acceleration);

    // Increasing this value makes the rectangles push off
    // of each other more.  Making this a smaller value will
    // result in the rectangles pushing less and being able to
    // overlap more.
    const float separationValue = 25;
    AxisAlignedRectangleInstance1.CollideAgainstMoveSoft(AxisAlignedRectangleInstance2,
        1, 1, separationValue);
}

The KeepThisInsideOf method repositions the calling AxisAlignedRectangle (or its TopParent if it is attached to another PositionedObject) so that it is not outside of the argument AxisAlignedRectangle. This method will do a one-time re-position of the calling instance, so it must be called every frame if the moving AxisAlignedRectangle.

This method can only be used to keep AxisAlignedRectangles inside of other AxisAlignedRectangles - other shapes are not supported.

Introduction

The Update method performs the every-frame collision checks for all CollisionRelationships contained in the CollisionManager. This includes:

• Sorting any partitioned lists

• Assigning contained ICollidable LastFrameItemsCollidedAgainst and LastFrameObjectsCollidedAgainst

• Resetting contained ICollidable ItemsCollidedAgainst and ObjectsCollidedAgainst

• Invoking the BeforeCollision method

• Performing collision on all contained CollisionRelationships

Note that most games do not need to call this method manually - it is called automatically by FlatRedBallServices.Update, which is part of all FlatRedBall projects.

Introduction

The CollisionManager class provides methods for handling collision (the touching of game objects) in FlatRedBall games. The CollisionManager has built-in methods for handling collision between collidable entities (entities which implement the ICollidable interface). Use of the CollisionManager is not necessary, but it can reduce and standardize code for handling collisions. The CollisionManager provides a rich set of functionality for performing collision in code, but usually games do not need to write code against the CollisionManager. Instead, the FlatRedBall Editor provides support for creating CollisionRelationships without any code. For more information, see the FlatRedBall Editor CollisionRelationship page.

Collision Relationships

The CollisionManager is built around the concept of collision relationships. A collision relationship is created by specifying the two objects (or groups of objects) which are used in the relationship. The following list shows common relationships in games:

• Player vs. Enemy Bullet List

• Player Bullet List vs. Environment

• Race Car List vs. Boost Entity List

• Explosion List vs. Destructible Block List

The relationship detects collision and provides automatic and custom handling of the collision. Automatic handling includes separating objects (preventing overlapping) and adjusting the velocity of colliding objects (bouncing the objects). Custom handling is done by assigning a collision event.

Creating a Collidable Entity

The CollisionManager is built to work with collidable entities. To create a collidable entity in Glue:

1. Open Glue

2. Right-click on the Entities folder

3. Click Add Entity

4. Check one of the objects under the Collisions category, such as Circle

5. Notice that the ICollidable checkbox is automatically checked

The entity will now implement the ICollidable interface, which means it can be used as an instance or in a list with the CollisionManager.

Example - Entity vs. Entity Collision

A relationship may define that two individual entities should perform collision logic against one another. The following assumes that PlayerInstance and EnemyInstance are entities added to the screen in Glue:

private void CreateCollisionRelationships()
{
    var relationship = CollisionManager.Self.CreateRelationship(
        PlayerInstance, EnemyInstance);
    relationship.CollisionOccurred = HandlePlayerVsEnemyCollision;
}

private void HandlePlayerVsEnemyCollision(Player player, Enemy enemy)
{
    enemy.TakeDamage();
    player.TakeDamage();
}

Notice that the HandlePlayerVsEnemyCollision is used to perform custom logic whenever a collision occurs.

Example - Entity List Relationships

Entities which are dynamically created or destroyed during the life of a screen (such as bullets fired by a turret) are usually added to lists. The following code can be used to detect collision between a single Player instance and a list of Bullets:

private void CreateCollisionRelationships()
{
    var relationship = CollisionManager.Self.CreateRelationship(
        PlayerInstance, BulletList);
    relationship.CollisionOccurred = HandlePlayerVsBulletCollision;
}

private void HandlePlayerVsBulletCollision(Player player, Bullet bullet)
{
    bullet.Destroy();
    player.TakeDamage();
}

Notice that the CollisionOccurred delegate passes a single bullet even though the type passed to CreateRelationship is a list. This allows the code to handle collision on a case-by-case basis. Similarly, relationships can be created between two lists. The following example shows how to respond to collision between a list of Enemies and a list of Bullets:

private void CreateCollisionRelationships()
{
    var relationship = CollisionManager.Self.CreateRelationship(
        EnemyList, BulletList);
    relationship.CollisionOccurred = HandleEnemyVsBulletCollision;
}

private void HandleEnemyVsBulletCollision(Enemy enemy, Bullet bullet)
{
    bullet.Destroy();
    player.TakeDamage();
}

Example - Entity/Entity List vs. TileShapeCollection

Entities can be collied against TileShapeCollections through the CollisionManager. TileShapeCollections are an efficient and convenient way to store a group of rectangles for collision.

// Since this is an extension method, you must have the following
// using statement in your class:
using FlatRedBall.Math.Collision;

private void CreateCollisionRelationships()
{
    // SolidCollisions is assumed to be a TileShapeCollection
    var relationship = CollisionManager.Self.CreateTileRelationship(PlayerList, SolidCollisions);
    // Make it so the solid collisions can't be moved:
    relationship.SetMoveCollision(0, 1);
}

See the Move Collision section below for more information.

Example - Move Collision

Collision relationships can specify automatic behavior in addition to assigning the CollisionOccurred delegate. This can be achieved by calling various Set methods. For example, the following results in colliding objects being separated. The SetMoveCollision method takes the relative masses of each object. In this example the colliding player and blocks have equal mass:

private void CreateCollisionRelationships()
{
    var relationship = CollisionManager.Self.CreateRelationship(
        Player, BlockList);
    var playerMass = 1;
    var blockMass = 1;
    relationship.SetMoveCollision(playerMass, blockMass);
    // custom collision can also be handled if needed
}

The most common ways to call is either with the values of (0,1) and (1,1)

• (0,1) - The first object (typically an entity) will have a mass of 0, meaning it will not be able to move the second object.

• (1,1) - Both objects have equal masses, and will push each other

Example - Bounce Collision with Per-Entity Mass

Both Move and Bounce collisions can be performed automatically by the relationship by calling either SetMoveCollision or SetBounceCollision. While convenient, these methods require the same mass to be used for all entities in a relationship. In some cases entities may need to have a custom mass per entity. In this example a list of asteroids collides with itself (every asteroid tests for collision against every other asteroid). Each Asteroid has a different Mass value so we can't set one mass for the entire relationship. Instead, the collision is detected and an event is raised, then the bounce collision occurs inside the collision event handler.

private void CreateCollisionRelationships()
{
    var relationship = CollisionManager.Self.CreateRelationship(
        AsteroidList, AsteroidList);
    relationship.CollisionOccurred = HandleAsteroidVsAsteroidCollision;
}

private void HandleEnemyVsBulletCollision(Asteroid first, Asteroid second)
{
    const float elasticity = .5f;
    first.CollideAgainstBounce(second, first.Mass, second.Mass, elasticity);
}

Note that the example above shows how to do self-collision, but the same approach of handling the move or bounce collision in an event could be performed between two different separate lists.

Example - Partitioning

The CollisionManager can perform partitioning to improve collision performance. In most cases partitioning can make even large numbers of objects (tens of thousands) have minimal or no impact on your game's frame rate. Partitioning requires two pieces of information:

1. The axis to partition (X or Y). This should be the axis along which objects are most distributed. For example, a platformer with horizontal levels should partition on the X axis.

2. The width or height of each object involved in partitioning.

Both objects in a relationship must be partitioned on the same axis before a relationship will be able to use the partitioning to reduce collision calls. Partitioned objects must be sorted for partitioning to function properly. If the order of objects in the list can change, the CollisionManager can automatically sort the lists. If the order does not change once the list has been created, or if the order is explicitly maintained in custom code, then the sortEveryFrame parameter can be false. The following creates a partitioned collision relationship between a list of Enemies and a list of Bullets.

private void CreateCollisionRelationships()
{
    var maxEnemyWidth = 48;
    var maxBulletWidth = 12;
    CollisionManager.Self.Partition(EnemyList, FlatRedBall.Math.Axis.X, 
        maxEnemyWidth, sortEveryFrame = true);
    CollisionManager.Self.Partition(BulletList, FlatRedBall.Math.Axis.X, 
        maxBulletWidth, sortEveryFrame = true);

    var relationship = CollisionManager.Self.CreateRelationship(EnemyList, BulletList);
    relationship.CollisionOccurred += HandeEnemyVsBulletCollision;
}

private void HandeEnemyVsBulletCollision(Enemy enemy player, Bullet bullet)
{
    ...
}

Partitioning must set on both objects in a relationship even if one of the objects is a single instance - in that case the Partition call is needed to get the width or height of the object's collision.

private void CreateCollisionRelationships()
{
    var maxPlayerWidth = 30;
    var maxBulletWidth = 12;
    CollisionManager.Self.Partition(Player, FlatRedBall.Math.Axis.X, 
        maxPlayerWidth);
    CollisionManager.Self.Partition(BulletList, FlatRedBall.Math.Axis.X, 
        maxBulletWidth, sortEveryFrame = true);

    var relationship = CollisionManager.Self.CreateRelationship(Player, BulletList);
    relationship.CollisionOccurred += HandeEnemyVsBulletCollision;
}

private void HandeEnemyVsBulletCollision(Enemy enemy player, Bullet bullet)
{
    ...
}

The Partition method only needs to be called once, even if an object is used in multiple relationships.

private void CreateCollisionRelationships()
{
    var maxPlayerWidth = 30;
    var maxBulletWidth = 12;
    var maxEnemyWidth = 28;

    // Partition is only called one time on Player, even though
    // Player is used in multiple relationships.
    CollisionManager.Self.Partition(Player, FlatRedBall.Math.Axis.X, 
        maxPlayerWidth);
    CollisionManager.Self.Partition(BulletList, FlatRedBall.Math.Axis.X, 
        maxBulletWidth, sortEveryFrame = true);
    CollisionManager.Self.Partition(EnemyList, FlatRedBall.Math.Axis.X, 
        maxEnemyWidth, sortEveryFrame = true);


    var playerVsBulletRelationship = CollisionManager.Self.CreateRelationship(
        Player, BulletList);
    playerVsBulletRelationship.CollisionOccurred += HandlePlayerVsBulletCollision;

    var playerVsEnemyRelationship = CollisionManager.Self.CreateRelationship(
        Player, EnemyList);
    playerVsEnemyRelationship.CollisionOccurred += HandlePlayerVsEnemyCollision;
}

Counting Collisions

In general reducing collision count improves the performance of your game. To measure whether your efforts to reduce collision are working (such as by implementing partitioning), the CollisionManager returns the number of deep collisions performed every frame. The term deep collision refers to collision methods which rely on the actual shapes of a collidable object, as opposed to partitioned checks which can eliminate large numbers of objects very quickly. The following code shows how to count and display the number of collisions performed every frame:

void CustomActivity(bool firstTimeCalled)
{
    FlatRedBall.Debugging.Debugger.Write(
        CollisionManager.Self.DeepCollisionsThisFrame);
}

Example - SubCollision

Entities may include multiple collision objects used for different responses. For example, a SpaceShip entity may have a small collision shape for its body (for taking damage) and a larger collision shape for a radar ( to detect enemies and display them on a radar HUD). Collision relationships will use the entire entity by default, but can be configured to only use a single shape by calling SetFirstSubCollision or SetSecondSubCollision for the first or second object in the relationship, respectively. The following code shows how to handle SpaceShip body vs. a list of Bullets:

private void CreateCollisionRelationships()
{
    var relationship = CollisionManager.Self.CreateRelationship(SpaceShipInstance, BulletList);
    relationship.CollisionOccurred += HandleSpaceShipVsBulletCollision;
    relationship.SetFirstSubCollision(spaceShip => spaceShip.CircleInstance);
}

SetFirstSubCollision refers to the first argument in the CreateRelationship call, which is SpaceShipInstance in the example above. SetSecondSubCollision refers to the second argument in the CreateRelationship call, which is BulletList in the example above. Note that if the argument to CreateRelationship is a list, then the SetFirstSubCollision and SetSecondSubCollision will work with a single instance rather than a list. For example, the code above could call SetSecondSubCollision for the BulletList , but the argument would take a single bullet as shown in the following snippet:

private void CreateCollisionRelationships()
{
    var relationship = CollisionManager.Self.CreateRelationship(SpaceShipInstance, BulletList);
    ...
    // Note we use "bullet" and not the entire list in this call:
    relationship.SetSecondSubCollision(bullet => bullet.CircleInstance);
}

SubCollision and Partitioning

When using a sub collision, the partition values may be different to account for the different collision object size. For example, the body of a space ship may be much smaller than the radar. Relationships can override the width or height values used for partitioning. The following code shows how to provide different collision width values (for X axis partitioning) for radar and body collision relationships:

private void CreateCollisionRelationships()
{
    // The Partition calls will define the default width values for the ship, bullet, and enemy entities,
    // which can be overridden by calling SetPartitioningSize on relationships.
    var defaultShipWidth = 48;
    var maxBulletWidth = 12;
    var maxEnemyWidth = 54;
    CollisionManager.Self.Partition(SpaceShipInstance, FlatRedBall.Math.Axis.X, defaultShipWidth);
    CollisionManager.Self.Partition(BulletList, FlatRedBall.Math.Axis.X, maxBulletWidth);
    CollisionManager.Self.Partition(EnemyList, FlatRedBall.Math.Axis.X, maxEnemyWidth);
    
    var shipVsBulletRelationship = CollisionManager.Self.CreateRelationship(
        SpaceShipInstance, BulletList);
    shipVsBulletRelationship.SetFirstSubCollision(spaceShip => spaceShip.BodyCollision);
    // Only the enemy's partition size is overridden for this relationship. Bullets will use default width
    var spaceShipBodyCollisionWidth = 25;
    shipVsBulletRelationship.SetPartitioningSize(SpaceShipInstance, spaceShipBodyCollisionWidth);

    var spaceShipRadarVsEnemyRelationship = CollisionManager.Self.CreateRelationship(
        SpaceShipInstance, EnemyList);
    spaceShipRadarVsEnemyRelationship.SetFirstSubCollision(spaceShip => spaceShip.RadarCollision);
    // As with the relationship above, we only override the ship width for this collision. 
    // Enemies will use the default width.
    var spaceShipRadarCollisionWidth = 200;
    spaceShipRadarVsEnemyRelationship.SetPartitioningSize(SpaceShipInstance, spaceShipRadarCollisionWidth);


}

Example: Optional Collision Physics

At times collision physics needs to be applied optionally. For example, a Player may be able to transform into a ghost. Normally the player may perform solid collision (Move or Bounce) against enemies, but while in the ghost phase the player can move through enemies. This can be done by telling the collision relationship to optionally apply collision as shown in the following code:

// Assuming PlayerVsEnemy is a valid collision relationship
PlayerVsEnemy.ArePhysicsAppliedAutomatically = false;
PlayerVsEnemy.CollisionOccurred += PlayerVsEnemyCollided;
// handle the event:
void PlayerVsEnemyCollided (Entities.Player player, Entities.Enemy enemy)
{
    if(player.IsGhost == false)
    {
        PlayerVsEnemy.DoCollisionPhysics(player, enemy);
    }
}

Manual Collision with DoCollisions

The default behavior for relationships is to perform collisions every-frame. The CollisionRelationship class provides additional control for when collisions are called. The DoCollisions method can be called in custom code to perform collisions as desired. This can be useful if collisions need to happen after certain logic has executed in a frame, or only in certain situations. The following code shows how to create a CollisionRelationship which is only collided when the user holds the Space key:

CollisionRelationship relationship;

private void CreateCollisionRelationships()
{
    relationship = CollisionManager.Self.CreateRelationship(
        PlayerInstance, BulletList);

    // Tell the CollisionManager to not automatically run collision every-frame
    relationship.IsActive = false;
}

void CustomActivity()
{
    if(InputManager.Keyboard.KeyDown(Keys.Space))
    {
        relationship.DoCollisions();
    }
}

Introduction

The AxisAlignedRectangle object supports changing its Color property by assigning a Color value.

Example

The following example requires that LeftRectangle and RightRectangle are valid Rectangles. For this example the rectangles were created in Glue. The following code can be used to modify the colors of the Rectangles:

LeftRectangle.Color = Microsoft.Xna.Framework.Color.Red;

RightRectangle.Color = Microsoft.Xna.Framework.Color.Yellow;

Introduction

The LastMoveCollisionReposition is a property that exists for all . If using CollisionRelationships, this property is set on any type of collision relationship that moves an object. This includes:

• Move Collision

• Bounce Collision

• Platformer Solid Collision

• Platformer Cloud Collision

If using manual collision calls, this property is set whenever a shape calls CollideAgainstBounce or CollideAgainstMove and the method test results in an actual collision. The LastMoveCollisionReposition property can then be tested to obtain information about collision.

Code Example - Determining the Collision Side on a Manual Collision

When two AxisAlignedRectangles collide the collision side can be determined rather easily. The following code determines the side that two rectangles collided on: Add the following using statements:

Assuming rectangle1 and rectangle2 are valid AxisAlignedRectangles:

Common Usage

Manual Ground Collision in Platformers

The following code can be used in a platformer to detect if a character is on the ground.

• It adjusts the velocity of the calling object (the character in this case) so that it is no longer falling. This prevents gravity accumulation errors.

• It adjusts the calling shape's (the character.Collision in this case) LastMoveCollisionReposition.

• It returns whether a collision has occurred.

So, as we can see, this first if-statement does *a lot*. Well, the most important thing initially is knowing *if* a collision has occurred. If it does, then we proceed to the body of the if-statement to find out if the player is actually on the ground. The next line of code is:

In this code we assume that character is an Entity that you've created that has an IsOnGround property. IsOnGround is a property that you must create in your Entity - either in custom code or as a new variable in Glue. Of course, you can store this information however you'd like; we've just presented the most common way if using Entities.

Manually recording LastMoveCollisionReposition

The LastMoveCollisionReposition property gives you the reposition of the last shape that a given shape has collided against. This information may not be very useful if you are colliding against a collection of shapes. In this case, you may want to manually keep track of your collision reposition:

Introduction

An AttachableList is a list which contains instances to . Instances of added to an AttachableList share a two-way relationship with the AttachableList by default. Common AttachableLists include the and classes.

A short discussion about two-way relationships

While this article goes into extensive detail about two-way relationships, this paragraph provides a quick explanation of what it means. In short, a two-way relationship means that IAttachables (this includes such as , , and ) keep track of all that they are a part of. The reason that this relationship exists is so that objects can remove themselves from all that they are a part of automatically when removing them through the engine. Any "Remove" method offered by FlatRedBall managers will remove the argument object from all of its lists - at least for all -inheriting objects. A simple code example shows this functionality:

Two Way Relationships

Reason for Two-Way Relationships

1. Remove the Sprite from the engine

2. Remove the Sprite from bullet list

One-Way Methods

1. Methods wich return AttachableLists usually fill them using AddOneWay. The assumption is that these lists will have a short lifespan.

2. Short-lifespan AttachableLists created outside of the engine should have elements added to them using one-way methods. Any AttachableList which has a lifespan of one frame or less should usually be populated using AddOneWay.

Converting Between Two-Way and One-Way

"foreach" allocates memory

Using a foreach statement on an AttachableList will allocate memory. This is a very common gotcha when working with AttachableLists (and PositionedObjectLists). Consider the following to improve the performance of your application:

AttachableList Members

Introduction

The RepositionDirections member controls which direction colliding objects will be repositioned. Specifically,RepositionDirections is relevant when calling and . RepositionDirections is also used by CollisionRelationships when using platformer collision. By default standalone AxisAlignedRectangles have all directions active, meaning the rectangle will reposition objects in all directions (up, down, left, right). AxisAlignedRectangles which are part of TileShapeCollections automatically have their RepositionDirections adjusted to prevent snagging.

Diagram Examples

The default value is All, which means that any objects colliding with the AxisAlignedRectangle can be moved in any of the four directions (Up, Down, Left, and Right) as shown in the following diagram:

RepositionDirections can be changed to any of the four cardinal directions, as shown in the following code:

The code above results in all objects being moved upward:

RepositionDirections can be combined with the | (or) operator, as shown in the following code:

Code Example - RepositionDirections on Static Rectangle

This example shows how RepositionDirections modifies the CollideAgainstMove method. It uses two rectangles:

• RedRectangle

• BlueRectangle

These are created in Glue so the screen starts as shown in the following image:

RepositionDirections value can be adjusted in code or in Glue. Typically this property is adjusted in code, so this example uses the following code:

Notice that when the first rectangle is moved (with the keyboard), it will only be repositioned to the left.

AxisAlignedRectangle vs. AxisAlignedRectangle

If two AxisAlignedRectangle instances are colliding against each other, then the RepositionDirection of both rectangles are considered. For example, consider the following situation:

For this example the red rectangle on the left will be called RedRectangle and the blue rectangle on the right will be called BlueRectangle. We'll assume that the BlueRectangle's RepositionDirection value is set to RepositionDirection.All. We'll also use the following collision code between the two:

By default, the red rectangle will be pushed to the left so it no longer overlaps the blue rectangle. Of course, this depends on the following two conditions:

1. That BlueRectangle has a RepositionDirection including RepositionDirection.Left

2. That RedRectangle has a RepositionDirection including RepositionDirection.Right

For the default separation to occur, the blue must be able to reposition to its left and the red must be able to reposition to its right. In other words, both rectangles must have opposing RepositionDirection values for a reposition to occur. If either is missing, then other directions will be checked. For example, consider the following code:

This code would result in BlueRectangle only being able to reposition to the right when a collision occurred, resulting in RedRectangle being moved all the way to the right side of BlueRectangle.

Cloud Collision

Setting a RepositionDirection of Up can help with cloud collisions. Assuming MyPlatform is a valid AxisAlignedRectangle:

None and CollideAgainstMove/CollideAgainstBounce

RepositionDirections defines which direction objects will move in when either CollideAgainstMove or CollideAgainstBounce are called. If a value of None is set, then CollideAgainstMove and CollideAgainstBounce will not change the position or velocity of either of the colliding objects.

RepositionDirections and TileShapeCollections

The use of RepositionDirections is critical for proper collision when using TileShapeCollections. For simple situations, a developer does not need to understand the RepositionDirections behavior that is happening when creating TileShapeCollections. This section discusses the behavior of RepositionDirections in TileShapeCollections. To begin, consider a TileShapeCollection which contains a single AxisAlignedRectangle. In this case, the rectangle will have all four RepositionDirections as shown by red arrows.

If a second rectangle is added to the first, then both of them remove their inward reposition directions. This is important to prevent collision snagging - the stopping of a moving object when moving across a smooth surface created by multiple rectangles.

As more rectangles are added, the TileShapeCollection adjusts the RepositionDirections of each to prevent snagging. Usually this happens automatically and no custom code is needed.

Code Example - Detecting Corners

The RepositionDirections property on AxisAlignedRectangles in a TileShapeCollection can tell you if a rectangle is a corner or part of a flat surface. As shown above, corners have at least two adjacent reposition directions. Since RepositionDirections is a bitfield, then the logical or can be used to test if an AxisAlignedRectangle is a corner, as shown in the following code.

Introduction

The CollideAgainstBounce method can be used to have two 3D shapes collide against each other and bounce (modify their or their top parent's velocity appropriately).

This function works the same as the CollideAgainstBounce provided for 2D shapes, so for a more detailed discussion, see .

Code Example

The following code creates two AxisAlignedCubes, sets the acceleration of one so it falls towards the other, and calls CollideAgainstBounce so that the two collide.

Note that for this example the project is using a 3D camera rather than a 2D camera. For information on how to set up a 3D camera in Glue, see .

Add the following at class scope in your Screen:

Add the following to CustomInitialize:

Add the following to CustomActivity:

Introduction

GetRandomPositionInThis returns a representing a random position in the calling AxisAlignedRectangle. This value can be used for any logic, such as randomly positioning an object within an AxisAlignedRectangle.

Code Example

The following example can be used to create 50 inside an AxisAlignedRectangle.

The code assumes that the rectangle is called AxisAlignedRectangleInstance and that you have a CircleList to store all the created Circles:

Introduction

The AxisAlignedRectangle is a which is used for unrotated bounding box collision. This is preferred over collision if Sprites are not rotated due to speed and memory usage considerations. AxisAlignedRectangles share many similarities with the other shape classes (, , and ). For general information about shapes, see the . For information on using AxisAlignedRectangles in Glue, see . AxisAlignedRectangles do not support being filled-in. They can only render as an outline. To render a solid rectangle, look at using with the

What does "axis aligned" mean?

The "AxisAligned" part of AxisAlignedRectangle indicates that the sides of the rectangle are "axis aligned". In other words, the top, bottom, left, and right are all parallel to either the X or Y axes. AxisAlignedRectangles are always axis aligned for performance reasons. Therefore, if you rotate an AxisAlignedRectangle (set its RotationZ), this will have no impact on the collision behavior or its visible representation. If your game requires rotation, you should use the class. Of course, performance will suffer slightly if collision performance is a consideration for your game. For more information on axis alignment and a discussion of axis aligned object rotation and children positions, see .

AxisAlignedRectangles are

The AxisAlignedRectangle class inherits from PositionedObject. This means that all properties which are available to (excluding rotation) are available to AxisAlignedRectangles. For more information, see the .

Creating an AxisAlignedRectangle

AxisAlignedRectangles are created through the ShapeManager. The following code creates an AxisAlignedRectangle through the ShapeManager and resizes it: Add the following using statement

Create the instance:

Relationship with ShapeManager

Move (Solid) Collision

Add the following at class scope:

Add the following in Initialize after Initializing FlatRedBall:

Add the following in Update:

Determining Collision Side

AxisAlignedRectangle Members

Extra Information

Introduction

The Left, Right, Top, and Bottom properties on AxisAlignedRectangle return the absolute position of the respective side.

Code Example

The following code shows how to get the four values (Left, Right, Top, and Bottom):

Setting values

Setting Left, Right, Top, and Bottom results in the X or Y values of the AxisAlignedRectangle changing. These values will not change the Width or Height of the AxisAlignedRectangle. To change dimensions use the Width and Height.

Code Example - Setting Left

The following code makes an AxisAlignedRectangle named RectangleInstance position its bottom-left corner at the origin (0,0):

Introduction

The IsPointInside method returns whether the argument X,Y are inside the Circle. The X and Y values are absolute values.

Code Example

The following shows how to check if the Cursor is inside a Circle instance:

float worldX = GuiManager.Cursor.WorldXAt(0);
float worldY = GuiManager.Cursor.WorldYAt(0);

bool isInside = CircleInstance.IsPointInside(worldX, worldY);

Introduction

The CollideAgainst function returns whether one shape/ShapeCollection is touching another shape/ShapeCollection. CollideAgainst does not modify the positions or velocities of either of the callers, it simply returns true/false.

Common Usage

CollideAgainst is often used in the following situations:

• Damage-dealing collision such as a player entity vs. a bullet entity.

• Game triggers, such as an area marking the end of a game.

CollideAgainst and Z values

All shape collision for 2D shapes (that is, all shapes except AxisAlignedCube and Sphere) consider only X and Y values when testing for collision. This means that the Z value is ignored. Therefore two shapes which are at different Z values will trigger a collision. For example:

Circle firstCircle = new Circle();
firstCircle.Radius = 16;

Circle secondCircle = new Circle();
secondCircle.Radius = 16;

// The two circles overlap at this point.
// Even if one of the circles has a different Z value...
firstCircle.Z = -1000;

// ... collision will still occur
if(firstCircle.CollideAgainst(secondCircle))
{
    // The if-statement will evaluate to true
}

The LastCollisionTangent returns the vector that represents the surface where the collision last occurred. This can be used for custom physics implementations.

Introduction

The Circle represents a PositionedObject which can be used to draw circles or conduct efficient circular collision. Circles are created and removed through the ShapeManager.

Simple Circle Example

The following example creates two circles and controls one of them with the Keyboard.

Add the following using statement

using FlatRedBall.Math.Geometry;
using FlatRedBall.Input;

At Class Scope:

Circle controlledCircle;
Circle idleCircle;

In Initialize:

controlledCircle = ShapeManager.AddCircle();
controlledCircle.Radius = 8;
controlledCircle.X = 64;

idleCircle = ShapeManager.AddCircle();
idleCircle.Radius = 24;

In Update:

InputManager.Keyboard.ControlPositionedObject(controlledCircle);
if (controlledCircle.CollideAgainst(idleCircle))
{
   controlledCircle.Color = Microsoft.Xna.Framework.Graphics.Color.Blue;
}
else
{
   controlledCircle.Color = Microsoft.Xna.Framework.Graphics.Color.Red;
}

Introduction

The CollideAgainstBounce is a collision method which performs the following:

• Returns true if a collision has occurred.

• Repositions the calling Circle and/or the argument object depending on the argument masses.

• Changes the calling Shape's Velocity and/or the argument object's Velocity depending on the argument masses.

Note: All collision methods, including CollideAgainstBounce, are methods common to all Shapes. If you came here through a link on a page beside the Circle (such as Polygon), don't worry, the code for all shapes is identical.

Method Signature

The signature for CollideAgainstBounce is as follows:

bool CollideAgainstBounce(Circle circle, float thisMass, float otherMass, float elasticity)
bool CollideAgainstBounce(Polygon polygon, float thisMass, float otherMass, float elasticity)
bool CollideAgainstBounce(AxisAlignedRectangle axisAlignedRectangle, float thisMass, float otherMass, float elasticity)

Arguments:

• Circle circle (or other shape) - the shape to collide against. This method supports other shapes as well, and if you find a shape that you'd like to collide against which is not supported, please request this feature in the forums.

• float thisMass - the mass of this shape. This does not have to be an absolute mass since it will only be used relative to the otherMass argument.

• float otherMass - the mass of the argument shape. Just like thisMass, otherMass does not have to be absolute. It will be compared against thisMass.

• float elasticity - The amount of bounce that will result. A value of 1 results in all momentum being preserved through the collision. A value of 0 results in no momentum being preserved. Negative values should not be used. Values greater than 1 introduce extra momentum. Values greater than 1 can be used to simulate "bouncing" against a wound-up spring, or to create false physics.

Example Code

The following code creates a Plinko board.

Add the following using statements:

using FlatRedBall.Input;
using FlatRedBall.Math.Geometry;
using Microsoft.Xna.Framework.Input;

Add the following at class scope:

PositionedObjectList<Circle> mPegs = new PositionedObjectList<Circle>();
PositionedObjectList<Circle> mFallingPieces = new PositionedObjectList<Circle>();

Add the following in Initialize after initializing FlatRedBall:

 for (int i = 0; i < 8; i++)
 {
     for (int j = 0; j < 7; j++)
     {
         Circle circle = ShapeManager.AddCircle();
         circle.X = -16 + 4 * i;
         circle.Y = -14 + 4 * j;

         if (j % 2 == 0)
             circle.X += 2;

         mPegs.Add(circle);
     }
 }

Add the following in Update:

 if (InputManager.Keyboard.KeyPushed(Keys.Space))
 {
     Circle circle = ShapeManager.AddCircle();
     circle.Radius = .5f;
     circle.YAcceleration = -5;
     circle.Y = 16;

     circle.X = -16 + (float)FlatRedBallServices.Random.NextDouble() * 32;

     mFallingPieces.Add(circle);
 }

 foreach (Circle fallingPiece in mFallingPieces)
 {
     foreach (Circle peg in mPegs)
     {
         // The second argument (0) is the mass of the falling piece relative to the peg.
         // The third argument (1) is the mass of the peg relative to the falling piece.
         // The 0,1 combination makes the peg of infinite mass - it will never move.
         // The last argument (.75) makes the collision slightly inelastic so it
         // looks a little more realistic.
         fallingPiece.CollideAgainstBounce(peg, 0, 1, .75f);
     }
 }

Reacting to CollideAgainstBounce

Since CollideAgainstBounce returns a bool, your code can use the return value to modify your game when a collision occurs:

bool didCollisionOccur = circle.CollideAgainstBounce(otherCircle, 0, 1, 1);
if(didCollisionOccur)
{
   // Here you can do whatever you want, like play a sound effect, add points, or even modify the velocity
   // of either of the objects
}

Bouncing and Velocity

The Collision tutorial mentions:

"For bouncing to behave properly, we have to make sure that we're not controlling the involved Shapes' position or velocity"

Let's consider why this is the case. Imagine a situation where a shape (or parent of a shape) is moving toward the right. This is being done with the following code:

someShape.XVelocity = 1;

If this code is called every frame, that means that the XVelocity will be set to 1 every frame, regardless of what it was before. Imagine that "someShape" performs bounce collision against a wall. When collision occurs, the shape's XVelocity will get inverted (that is, set to -1) so that it moves to the left. However, if Velocity is set to 1 every frame, than the -1 would get changed back to 1. In other words, the setting of velocity every frame would cancel out the velocity change from CollideAgainstBounce. Let's look at another example: one where an object is moved with the mouse. In this example, the mouse is simply setting the position of an object:

someShape.X = InputManager.Mouse.WorldXAt(0);
someShape.Y = InputManager.Mouse.WorldYAt(0);

In this case, someShape will have a velocity of 0 (assuming there is no other code that sets its velocity. Therefore, even though someShape appears to be moving smoothly with the mouse, if another object bounces against it, it may not bounce at all.

Code Example

The following example shows a problem with using CollideAgainstBounce and Mouse control and how it can be corrected.

Add the following using statements:

using FlatRedBall;
using FlatRedBall.Input;
using FlatRedBall.Math;
using FlatRedBall.Math.Geometry;

Add the following at class scope:

PositionedObjectList<Circle> mCircles = new PositionedObjectList<Circle>();
Circle mControlledCircle;

Add the following in Initialize after initializing FlatRedball:

 mControlledCircle = ShapeManager.AddCircle();

 for (int i = 0; i < 30; i++)
 {
     Circle circle = ShapeManager.AddCircle();
     mCircles.Add(circle);
     SpriteManager.Camera.PositionRandomlyInView(circle, 40, 40);
 }

Add the following in Update:

 // true will result in no bouncing
 // false will result in bouncing (probably expected behavior)
 bool controlByPositionInsteadOfVelocity = false;

 if (controlByPositionInsteadOfVelocity)
 {
     mControlledCircle.X = InputManager.Mouse.WorldXAt(0);
     mControlledCircle.Y = InputManager.Mouse.WorldYAt(0);
 }
 else
 {
     // Increasing this reduces lag, but increases potential jittery
     // velocity values.
     const float coefficient = 20;

     mControlledCircle.XVelocity = coefficient * 
         (InputManager.Mouse.WorldXAt(0) - mControlledCircle.X);
     mControlledCircle.YVelocity = coefficient *
         (InputManager.Mouse.WorldYAt(0) - mControlledCircle.Y);
 }
 foreach (Circle circle in mCircles)
 {
     // Make this mass 1, the other mass 0 so that this is
     // immovable and it will bounce and push all other objects.
     mControlledCircle.CollideAgainstBounce(circle, 1, 0, 1);
 }

CollideAgainstBounce for platformers

The CollideAgainstBounce method is effective for performing bouncing physics, but it can also be used in situations where you'd like collision to reset velocity, such as in platformers. It's very common to have acceleration in platformers, and the easiest way to do this is to set the player Entity to have a negative YAcceleration. However, if the player collides with the ground using CollideAgainstMove, the YAcceleration will continue to accumulate the YVelocity value. Eventually this value will build up to be so large that the player will fall through the level. Even if this doesn't occur, the player will show weird behavior if it walks off of a ledge. To solve this, you can simply use CollideAgainstBounce instead of CollideAgainstMove. An elasticity of 0 will result in the same behavior as CollideAgainstMove, but the velocity will be modified according to the velocity to solve accumulation errors. You can try this in the demo above by setting the elasticity argument to 0.

Introduction

A Capsule2D is a PositionedObject which can be used to perform collision tests. Since Capsule2Ds provide the same collision interface as other shapes, it is also considered a "shape". A Capsule2D is a shape that can be any length, but has rounded edges and a straight segment connecting the two points.

When are Capsules used?

Capsules are often used to determine if a collision has occurred between a moving Circle and another object. Since capsules use rounded edges, they can represent the area that a Circle occupies during and between two subsequent frames.

Capsule Size

Capsule size is controlled by two variables:

• Scale

• EndpointRadius

The following diagram shows hwo these values are used in a Capsule2D:

Did this article leave any questions unanswered? Post any question in our forums for a rapid response.

The FloatRectangle struct is a light-weight object which can be used to represent a rectangle using float coordinates. For example, the FloatRectangle can be used to store texture coordinates.

Did this article leave any questions unanswered? Post any question in our for a rapid response.

For more information see the .

Redirect to:

The Visible property on a Circle controls whether the Circle is rendered or not. Invisible Circles will still perform collision properly, so this property does not need to be set if using Circles purely for collision. Rendered circles will render their outline using their property. Circles cannot be filled-in, only their outline will render. Setting Visible to true may result in a Circle being added to the . For more information about how Visible results in membership, see the .

Storing shapes (or Entities which have collision shapes) in a list is very common. You can collide all objects in a list all other objects using doubly-nested for loops:

The ProjectParentVelocityOnLastMoveCollisionTangent method can be used to create realistic collisions between a Circle and any other . The Circle's version of ProjectParentVelocityOnLastMoveCollisionTangent behaves the same as the 's version. For more information, see the .

Introduction

The ICollidable interface provides a standard collision implementation. Objects which implement ICollidable can collide with all FlatRedBall shapes and other ICollidables. The ICollidable interface requires a ShapeCollection property named Collision. FlatRedBall also offers the following extension methods for ICollidable:

• CollideAgainst - Simply returns true/false to indicate whether a collision has occured

• CollideAgainstMove - Returns true/false and separates the two objects involved in the collision

• CollideAgainstBounce - Returns true/false, separates the two objects involved, and adjusts the velocity of the objects involved to simulate bouncing

ICollidable Entities

Entities in the FRB Editor can be marked as ICollidable. For more information on ICollidable in the FRB Editor, see this page.

ICollidable and Collision

ICollidables provide the same three functions for collision as FlatRedBall shapes. The details of the collision behavior depend on the specific shape, but the concpts are similar in all cases. For more information on how shapes respond to collision methods, check the following pages:

Circle

• CollideAgainst

• CollideAgainstBounce

ShapeCollection

• CollideAgainst

ItemsCollidedAgainst and ObjectsCollidedAgainst

Collidables must implement the following four properties:

• ItemsCollidedAgainst

• LastFrameItemsCollidedAgainst

• ObjectsCollidedAgainst

• LastFrameObjectsCollidedAgainst

These serve as an alternative to doing custom collision-related logic, and provide some additional functionality such as detecting when an entity exits collision.

The Items property contains the name of items that the IColliable has collided with, while the Objects contains a reference to the objects that the ICollidable has collided with. If you are using the FlatRedBall Editor, these properties are automatically generated in your entities, and these are automatically filled through collision relationships. For example, if the Player collides with SolidCollision in the GameScreen, then the items properties would contain the string "SolidCollision". The objects properties contains a reference to the TileShapeCollection.

The following code shows how to check whether the player has exited a collision area with the name PoisonCollision:

// assuming IsInPoison is a property that is set to true when collision happens
if(IsInPoison and this.ItemsCollidedAgainst.Contains("PoisonCollision") == false)
{
    HandleExitingPoison();
}

Alternatively, the Last properties can be used to identify if a changed was made this frame. For example, the following would detect both entering and exiting poison, and does not require the use of additional properties:

var poisonName = "PoisonCollision";
if(this.ItemsCollidedAgainst.Contains(poisonName) && 
    !this.LastFrameItemsCollidedAgainst.Contains(poisonName))
{
    HandleEnteringPoison();
}
else if(this.LastFrameItemsCollidedAgainst.Contains(poisonName) && 
    !this.ItemsCollidedAgainst.Contains(poisonName))
{
    HandleExitingPoison();
}

Introduction

The SetFromAbsoluteEndpoints method can be used to set a line so that its endpoints are located at the argument locations. This method assigns:

• RelativePoint1

• RelativePoint2

• Position

• RotationZ

Conceptual Example

Consider the following code:

Vector3 firstPoint = new Vector3(0, 0, 0);
Vector3 secondPoint = new Vector3(100, 0, 0)
line.SetFromAbsoluteEndpoints(firstPoint, secondPoint);

The code above shows how to create a line using the SetFromAbsoluteEndpoints. To help explain what SetAbsoluteEndpoints does, we can consider how to create the same line without using SetFromAbsoluteEndpoints. To do the same as above, the following assignments would be necessary:

• RelativePoint1 = (-50, 0, 0)

• RelativePoint2 = (50, 0, 0)

• Position = (50, 0, 0)

• RotationZ = 0

Code Example

The following code creates a line which connects the points X=0,Y=0 and X=100,Y=200:

Line line = ShapeManager.AddLine();
Vector3 firstPoint = new Vector3(0, 0, 0);
Vector3 secondPoint = new Vector3(100, 200, 0)
line.SetFromAbsoluteEndpoints(firstPoint, secondPoint);

FlatRedBall.Math.Geometry.Line

Introduction

The LastCollisionPoint is a property which can tell you the last location where collision occurred. This can be used if you would like to play effects or perform custom physics where collision has occurred.

Code Example

The following example creates two Lines and calls CollideAgainst between them. It then uses the LastCollisionPoint (if it is valid) to position a circle. One of the lines (Line1) can be controlled with the keyboard, resulting in a changing LastColliisionPoint.

This example is structured for Glue, but can be duplicated in a code-only FlatRedBall project:

Add the following to class scope in a Screen:

Circle circle;
Line line1;
Line line2;

Add the following to CustomInitialize in a Screen:

void CustomInitialize()
{
    circle = ShapeManager.AddCircle();
    circle.Radius = 10;

    line1 = ShapeManager.AddLine();

    line2 = ShapeManager.AddLine();
    line2.RelativePoint2 = new Point3D(100, 100);
}

Add the following to CustomActivity in a Screen:

void CustomActivity(bool firstTimeCalled)
{
    InputManager.Keyboard.ControlPositionedObject(line1, 100);

    line1.CollideAgainst(line2);

    // If no collision occurred, then LastCollisionPoint's X and Y values will be NaN:
    if (!double.IsNaN(line1.LastCollisionPoint.X) &&
        !double.IsNaN(line1.LastCollisionPoint.Y))
    {
        circle.X = (float)line1.LastCollisionPoint.X;
        circle.Y = (float)line1.LastCollisionPoint.Y;
    }
}

Introduction

A line is defined by two endpoints, so in mathematical terms it is actually a segment. Lines can be used to perform 2D collisions against any other shapes.

Line Sample

The following sample creates a line, a Circle, and an AxisAlignedRectangle. The line is controlled with the keyboard and it changes colors when it collides with the other two shapes. Add the following using statements:

using Microsoft.Xna.Framework.Graphics;
using FlatRedBall.Math.Geometry;

Add the following at class scope:

AxisAlignedRectangle rectangle;
Circle circle;
Line line;

Add the following in Initialize after Initializing FlatRedBall:

rectangle = ShapeManager.AddAxisAlignedRectangle();
rectangle.X = 50;
rectangle.Color = Color.Red;

circle = ShapeManager.AddCircle();
circle.X = -50;
circle.Color = Color.Blue;

// Creates a horizontal line of length 2 by default.
line = ShapeManager.AddLine();

Add the following in Update:

InputManager.Keyboard.ControlPositionedObject(line);

if (line.CollideAgainst(rectangle))
{
    line.Color = rectangle.Color;
}
else if (line.CollideAgainst(circle))
{
    line.Color = circle.Color;
}
else
{
    line.Color = Color.White;
}

RelativePoint Properties

A line can be modified by changing both its PositionedObject properties as well as through the RelativePoint property. The following code connects two rectangles with a line. Add the following in Update:

using Microsoft.Xna.Framework.Graphics;
using FlatRedBall.Math.Geometry;

Add the following in Initialize after Initializing FlatRedBall:

AxisAlignedRectangle rectangle1 = ShapeManager.AddAxisAlignedRectangle();
rectangle1.Position = new Vector3(-2, 4, 0);
rectangle1.Color = Color.Green;

AxisAlignedRectangle rectangle2 = ShapeManager.AddAxisAlignedRectangle();
rectangle2.Position = new Vector3(4, -1, 0);
rectangle2.Color = Color.Red;

// The most common way to make a connecting line is to set the line's
// positions at one of the end points, then simply calculate the relative
// position of the other endpoint.  That is, the position of the line does
// not have to be the midpoint.
Line connectingLine = ShapeManager.AddLine();
connectingLine.Position = rectangle1.Position;
connectingLine.RelativePoint1 = new Point3D(0, 0, 0);

// Now just get the position of rectangle2 relative to rectangle1
// and put that in RelativePoint2.
connectingLine.RelativePoint2 = new Point3D(
    rectangle2.X - rectangle1.X,
    rectangle2.Y - rectangle1.Y,
    rectangle2.Z - rectangle1.Z); // will be 0 in our case

Line limitations

• Lines, just like any other Shapes, can either be drawn on top of or below types that can sort with each other, such as Sprites and Texts. They will not sort according to their Z value.

• Lines must be one pixel thick. Thicker lines are not supported.

• Lines can only draw solid colors - patterns and gradients are not supported.

Introduction

The IScalable interface provides an interface for 2D objects which can be resized. IScalable objects have two properties which control size:

• ScaleX

• ScaleY

Note: By default, scale has nothing to do with the Texture that an object is displaying. Two objects showing different Textures of different dimensions will be the same size if they have the same scale values.

What is Scale?

Scale defines the distance from the center of an object to its edge. Scale values are used used instead of "width" and "height" because it simplifies collision and object placement. In other words, the following relationships exist:

ScaleX = Width / 2;
ScaleY = Height / 2;

OR

Width = ScaleX * 2;
Height = ScaleY * 2;

Scale Example

The following code creates 3 Sprites with different scales.

 Sprite regularSizedSprite = SpriteManager.AddSprite("redball.bmp");
 regularSizedSprite.Y = 4;

 Sprite scaledOnXSprite = SpriteManager.AddSprite("redball.bmp");
 scaledOnXSprite.ScaleX = 3;

 Sprite scaledOnXAndYSprite = SpriteManager.AddSprite("redball.bmp");
 scaledOnXAndYSprite.Y = -7;
 scaledOnXAndYSprite.ScaleX = 3;
 scaledOnXAndYSprite.ScaleY = 3;

Scale is independent of Texture

The ScaleX and ScaleY values on objects such as Sprites is (by default) independent of the Sprite's Texture property. Therefore, if two Sprites both have the same ScaleX and ScaleY values, they will appear as the same size on screen regardless of the size of the Textures that they are displaying.

Tutorials

• Understanding the 3D Camera tutorial - Information on Scale and it's relationship to on-screen size

• Setting a Sprite to Pixel Size - Shows how to set a Sprite's scale so that it appears the same dimensions as its source Texture.

• Justifying IScalables

More Information

• FlatRedBall.Graphics.Model.PositionedModel.ScaleX - Scale and PositionedModels.

IScalable Members

• FlatRedBall.Math.Geometry.IScalable.ScaleXVelocity

• FlatRedBall.Math.Geometry.IScalable.ScaleYVelocity

Did this article leave any questions unanswered? Post any question in our forums for a rapid response.

Introduction

Scale is a common measurement of size in the FlatRedBall Engine. Most sizable objects implement the IScalable interface and have ScaleX and ScaleY variables. This includes the Sprite class. Scale measures the distance from the center of an object to its edge. Therefore, the following relationships exist:

width = object.ScaleX * 2;
leftEdge = object.X - object.ScaleX;
rightEdge = object.X + object.ScaleX;

In other words, ScaleX is half of width and ScaleY is half of height.

Textures and Size

FlatRedBall can be rendered using a 2D or 3D camera. Games using a 2D camera typically render their sprites according to the size of their source texture (using the TextureScale property). Games using a 3D camera may not rely on a texture's size. In this case, scale values may be manually set. Therefore, two Sprites which reference textures of different size or aspect ratios may have sizes completely unrelated to their texture. Fortunately, sprite's Texture property exposes its dimensions so if you desire to control the size of a Sprite according to its texture, you can set the X and Y scales according to the size of the texture. The following code creates three Sprites - one with a default ScaleX and ScaleY of 1, one with its size relative to the size of its source texture, and one drawn drawn to-the-pixel.

Sprite defaultScaleSprite = SpriteManager.AddSprite(@"Assets\Scenes\frblogo.png");
defaultScaleSprite.Y = 8;

// The size is relative to its source texture.  Increase
// sizeCoefficient to increase size.
float sizeCoefficient = .02f;
Sprite correctAspectRatio = SpriteManager.AddSprite(@"Assets\Scenes\frblogo.png");
correctAspectRatio.Y = 0;
correctAspectRatio.ScaleX = correctAspectRatio.Texture.Width * sizeCoefficient;
correctAspectRatio.ScaleY = correctAspectRatio.Texture.Height * sizeCoefficient;

// This makes the Sprite drawn to-the-pixel.
Sprite pixelPerfectSprite = SpriteManager.AddSprite(@"Assets\Scenes\frblogo.png");
pixelPerfectSprite.Y = -11;
float pixelsPerUnit = SpriteManager.Camera.PixelsPerUnitAt(pixelPerfectSprite.Z);
pixelPerfectSprite.ScaleX = .5f * pixelPerfectSprite.Texture.Width / pixelsPerUnit;
pixelPerfectSprite.ScaleY = .5f * pixelPerfectSprite.Texture.Height / pixelsPerUnit;

Sizing and Positioning Objects

When first creating a level in FlatRedBall, it may seem as if there is nothing to help you indicate how large objects should be. You may be asking "How big should my character be?" or "How do I determine how large objects in my game should be?" What follows are a few suggestions to help you size your objects.

Identify the Most Influential Objects

One of the most common approaches is to identify an object as the determining factor for the scale of the other objects. This object (or group of objects) will be used as a reference point when scaling other objects. Two common choices are the player-controlled character and the tile size of the level. The character is a good choice because often times levels are built around the size of the character. Areas must be tall enough for the character to walk through, pits must be the right size so that players can jump over them, and ledges must be low enough so the player can jump up or grab onto them. Using the character as the reference object for scale is generally recommended in games where the player and environment will interact frequently, like in platformers. Another option is to decide on a tile size for the level. The tile size will determine the size of most Sprites used in the level. In this case, objects will generally be scaled to fit with the size of the rest of the level. For example, in a top down role playing game (RPG), the character is usually one or two tiles tall.

Use Unit Sizes

Although the SpriteEditor provides a lot of support in assembling levels without having to manually set size and position values, it is very helpful to use scales that are whole numbers - especially for tilemaps. That is, when creating a tilemap, consider having your Sprites have a scale of 1. This makes the math very simple - all objects will be exactly 2 units away from neighbors. This will also help you position objects when you manually have to place them. Furthermore, moving on a tilemap with a unit size simplifies code and can help optimize pathfinding.

Look at Visible Area

The visible screen area can help you decide how large objects should be. In code, the visible area can be determined as follows:

Camera camera = SpriteManager.Camera;

float leftBound = camera.X - camera.RelativeXEdgeAt(absoluteZValue);
float rightBound = camera.X + camera.RelativeXEdgeAt(absoluteZValue);

float topBound = camera.Y + camera.RelativeYEdgeAt(absoluteZValue);
float bottomBound = camera.Y - camera.RelativeYEdgeAt(absoluteZValue);

Of course, adding a Sprite and running the code can give you a visual indication of the size. Another good option is to run the SpriteEditor, add a Sprite, and turn on the camera bounds, as explained here.

Did this article leave any questions unanswered? Post any question in our forums for a rapid response.

Introduction

The Color property controls the color value used when drawing a visible Line.

Code Exampe - Creating a red line

The following code creates a visible red line:

var line = ShapeManager.AddLine();
line.Color = Color.Red;
line.Visible = true;
line.SetFromAbsoluteEndpoints(Camera.Main.Position.AtZ(0), 
    Camera.Main.Position.AtZ(0) + new Vector3(100, 100, 0));

Code Example - Transparent Lines

The following shows a transparent white line. Note that colors are pre-multiplied so all color values must be multiplied by the alpha value.

The following code creates a half-transparent red line:

var line = ShapeManager.AddLine();
var alpha = 0.5f;
line.Color = new Color(1 * alpha, 0 * alpha, 0 * alpha, alpha);
line.Visible = true;
line.SetFromAbsoluteEndpoints(Camera.Main.Position.AtZ(0), 
    Camera.Main.Position.AtZ(0) + new Vector3(100, 100, 0));

The transparency can be difficult to see without zooming in. The following image shows the corner of the blue rectangle zoomed in.

Introduction

The RelativePoint1 and RelativePoint2 values define the shape of a line relative to its absolute position. These values can be set to modify how a line will draw - specifically its angle and length. For simplicity the RelativePoint1 can be set to (0,0), so simply modifying the second point will adjust the line.

Relative Point Positions vs Position

RelativePoint1 and RelativePoint2 are used to define the line in combination with the absolute point. The most common, and recommended, approach to create a line is to have RelativePoint1 be (0,0) and have RelativePoint2 define the direction of the line relative to its position. For example, consider the following code and image:

Line line = new Line();
line.RelativePoint1 = new Point3D(0,0);
line.RelativePoint2 = new Point3D(300,300);

Although not recommended, RelativePoint1 and RelativePoint2 can be set such that the Line's position is not the Line.

Line line = new Line();
line.RelativePoint1 = new Point3D(0,100);
line.RelativePoint2 = new Point3D(300,300);

Although FlatRedBall allows this kind of Line, and in some cases it may be beneficial for custom logic, it is not recommended for standard collision, and some methods (such as CollideAgainstClosest) will throw exceptions if the Position does not coincide with RelativePoint1. Therefore, unless your game has special requirements, RelativePoint1 should always have a Value of (0,0).

Examples

The following code creates a vertical line. The bottom-end of the line will be located at the line's absolute Position. The top-end of the line will be located 100 units up.

Line line = ShapeManager.AddLine();
line.RelativePoint1.X = 0;
line.RelativePoint2.X = 0;

float verticalLineLength = 100;
line.RelativePoint1.X = 0;
line.RelativePoint2.X = 100;

The following code creates a horizontal line. The left-end of the line will be located at the line's absolute Position. The right-end of the line will be located 100 units up.

Line line = ShapeManager.AddLine();
line.RelativePoint1.X = 0; 
line.RelativePoint2.X = 0; 
float verticalLineLength = 100; 
line.RelativePoint1.X = 100; 
line.RelativePoint2.X = 0;

3D Lines

The Line class supports 3D lines (lines with non-zero relative points or absolute positions). The following shows how to create a grid of 3D lines. Note that it requires a 3D camera:

for(int x = 0; x < 10; x++)
{
    for(int y = 0; y < 10; y++)
    {
        var line = ShapeManager.AddLine();

        line.RelativePoint1 = new Point3D(0, 0, 0);

        line.RelativePoint2 = new Point3D(0, 0, -10);
        line.X = -20 + x*4;
        line.Y = -20 + y*4;
    }

}

Introduction

The AbsolutePointPosition method returns the absolute position of the point on the polygon matching the argument index. Passing an index outside of the list of points will result in an exception.

Code Example

The following code shows how to create a bullet at the 2nd point on a polygon (index 1):

Defines an absolute position in 2D space (using X and Y). The Point class is used in collision. Since precision is important when performing collision operations the Point class uses doubles for its X and Y fields.

Did this article leave any questions unanswered? Post any question in our for a rapid response.

Introduction

The CollideAgainstBounce is a collision method which performs the following:

• Returns true if a collision has occurred.

• Repositions the calling Circle and/or the argument object depending on the argument masses.

• Changes the calling Shape's Velocity and/or the argument object's Velocity depending on the argument masses.

Note: All collision methods, including CollideAgainstBounce, are methods common to all Shapes. If you came here through a link on a page beside the Circle (such as Polygon), don't worry, the code for all shapes is identical.

Method Signature

The signature for CollideAgainstBounce is as follows:

Arguments:

• Circle circle (or other shape) - the shape to collide against. This method supports other shapes as well, and if you find a shape that you'd like to collide against which is not supported, please request this feature in the forums.

• float thisMass - the mass of this shape. This does not have to be an absolute mass since it will only be used relative to the otherMass argument.

• float otherMass - the mass of the argument shape. Just like thisMass, otherMass does not have to be absolute. It will be compared against thisMass.

• float elasticity - The amount of bounce that will result. A value of 1 results in all momentum being preserved through the collision. A value of 0 results in no momentum being preserved. Negative values should not be used. Values greater than 1 introduce extra momentum. Values greater than 1 can be used to simulate "bouncing" against a wound-up spring, or to create false physics. For more information on the elasticity variable, see the Elasticity Examples section below.

Example Code

Add the following using statements:

Add the following at class scope:

Add the following in Initialize after initializing FlatRedBall:

Add the following in Update:

Reacting to CollideAgainstBounce

Since CollideAgainstBounce returns a bool, your code can use the return value to modify your game when a collision occurs:

Bouncing and Velocity

Let's consider why this is the case. Imagine a situation where a shape (or parent of a shape) is moving toward the right. This is being done with the following code:

If this code is called every frame, that means that the XVelocity will be set to 1 every frame, regardless of what it was before. Imagine that "someShape" performs bounce collision against a wall. When collision occurs, the shape's XVelocity will get inverted (that is, set to -1) so that it moves to the left. However, if Velocity is set to 1 every frame, than the -1 would get changed back to 1. In other words, the setting of velocity every frame would cancel out the velocity change from CollideAgainstBounce. Let's look at another example: one where an object is moved with the mouse. In this example, the mouse is simply setting the position of an object:

In this case, someShape will have a velocity of 0 (assuming there is no other code that sets its velocity. Therefore, even though someShape appears to be moving smoothly with the mouse, if another object bounces against it, it may not bounce at all.

Code Example

Add the following using statements:

Add the following at class scope:

Add the following in Initialize after initializing FlatRedball:

Add the following in Update:

CollideAgainstBounce for platformers

Introduction

Due to the popularity of the , it is very common to have shapes attached to other . Because of this common setup, all shapes have special behavior in their collision methods to reposition or change the velocity of their .

The Attachment Hierarchy

The attachment hierarchy is a collection of and their attachments - or child/parent relationships - which define which objects control the position and rotation of other objects. The following shows a typical attachment hierarchy for an .

Shapes and the Attachment Hierarchy

Methods like CollideAgainstMove and CollideAgainstBounce are commonly used to prevent overlapping and modify velocity in response to collisions. CollideAgainstMove modifies the absolute Position of the calling shape and the shape it is colliding with to prevent overlapping. CollideAgainstBounce prevents overlapping just like CollideAgainstMove, but also modifies the velocity of the two shapes involved.

This may seem to present a problem; shapes have their absolute properties modified through the CollideAgainstMove and CollideAgainstBounce methods; however, as shown in the entity pattern above, shapes are often not at the root of the attachment hierarchy. Therefore it would seem as if these methods will only work when the shapes involved are the roots of their respective attachment hierarchies.

Shared Root Conflicts

As mentioned above, the CollideAgainstMove and CollideAgainstBounce methods will update the root's absolute properties. However, if two shapes share the same root, the collision methods will not be able to reposition the objects properly. The following image shows the conflict:

Notice that in this situation both children will be modifying the parents' property. However, the parent's absolute values control the absolute values of the attached shapes.

In these situations the regular CollideAgainst methods will work correctly, but the Move and Bounce versions of the method will not be able to properly modify values. Keep this in mind if you are using a shared root for multiple shapes.

Introduction

The Polygon class is used to define collidable shapes. Polygons can contain any number of points and can be either convex or concave. Polygons can be drawn to the screen by adding them to the ShapeManager or by setting their Visible property to true.

Polygons are typically used for objects which need complex collision. Polygons can collide with other Polygons as well as other FlatRedBall shapes such as Circle and AxisAlignedRectangle.

Polygon collision is significantly slower than Circle and Rectangle collision, so if your game can use simpler shapes those are recommended for performance reasons.

The Polygon class sits is in the FlatRedBall.Math.Geometry namespace, so adding

can simplify your code. Also, Polygons use the FlatRedBall.Math.Geometry.Point struct, so the following code can help solve ambiguities:

Example: Creating a Rectangle Polygon in Code

The Polygon class provides the CreateRectangle shortcut methods for creating rectangular Polygons:

You can also assign the Points object. For more information, see the .

Example: Creating a Polygon From Points in Code

Polygons can be constructed by assigning the points. Note that points are relative to the center of a polygon, not in absolute coordinates.

Clockwise Points

Polygons support points in any order, but adding points clockwise is recommended for performance reasons. Internally, FlatRedBall is able to perform faster collision checks between polygons if both have points added clockwise.

The example above adds points clockwise. We can see this by overlaying the polygon's origin and drawing the order in which points have been added as shown in the following image:

Polygons provide an IsClockwise method which checks if the points are in clockwise order, as shown in the following code:

Polygon Collision

Efficiency of Polygon Collision

Each Polygon has a BoundingRadius method which is set when the point list reference is updated. This BoundingRadius is used internally in collision methods. When two Polygons collide, their distances are compared to their BoundingRadius. If the two are too far away to possibly have a collision, then no deeper checks are performed.

This helps reduce the cost of performing polygon collision, especially when polygons are often separated by larger distances.

SimulateCollideAgainstMove

This method repositions a Polygon or its TopParent if it has one, changes the LastMoveCollisionReposition property, and finally updates all attachments. This code performs all of the updates which would happen on a successful CollideAgainstMove call. This method is rarely used. It can be used if collision is handled outside of the polygon class but the LastMoveCollisionReposition property is still used in other parts of code. If collision that repositions a polygon calls this method rather than simply changing its Position values, then code that uses the LastMoveCollisionReposition property (such as ProjectParentVelocityOnLastMoveCollisionTangent) will still work correctly.