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 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 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

The AxisAlignedRectangle object supports changing its Color property by assigning a 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:

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

GetRandomPositionInThis returns a Vector3 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 Circles inside an AxisAlignedRectangle.

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

int numberOfCirclesToCreate = 50;
for(int i = 0; i < numberOfCirclesToCreate; i++)
{
    Circle circle = ShapeManager.AddCircle();
    circle.Position = AxisAlignedRectangleInstance.GetRandomPositionInThis();
    CircleList.Add(circle);
}

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
}

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):

// This assumes your rectangle is called RectangleInstance
float left = RectangleInstance.Left;
float right = RectangleInstance.Right;
float top = RectangleInstance.Top;
float bottom = RectangleInstance.Bottom;

// Now you can use these four values for whatever you need in your code

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):

RectangleInstance.Left = 0;
RectangleInstance.Bottom = 0;

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

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 this page.

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 this page.

Add the following at class scope in your Screen:

 AxisAlignedCube first;
 AxisAlignedCube second;

Add the following to CustomInitialize:

first = ShapeManager.AddAxisAlignedCube();

second = ShapeManager.AddAxisAlignedCube();
second.Y = 5;
second.YAcceleration = -7;

// Move the rectangles to the right a little so we can get some
// perspective on them
first.X = 5;
second.X = 5;

// Move the camera closer to make them bigger:
Camera.Main.Z = 20;

Add the following to CustomActivity:

second.CollideAgainstBounce(first, 0, 1, 1);

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.

Introduction

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

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 Polygon 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 this page.

AxisAlignedRectangles are PositionedObjects

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

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

using FlatRedBall.Math.Geometry;

Create the instance:

// AxisAlignedRectangles added this way are Visible by default and also managed
// by the ShapeManager.
AxisAlignedRectangle rectangle = ShapeManager.AddAxisAlignedRectangle();
rectangle.ScaleX = 5;
rectangle.ScaleY = 7;

Relationship with ShapeManager

See ShapeManager wiki entry.

Move (Solid) Collision

Solid or moving collision can be performed with AxisAlignedRectangles as well as Polygons and Circles. The following code creates three AxisAlignedRectangles - one controlled by the player, one which can be pushed, and one which is is immovable. Add the following using statements:

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

Add the following at class scope:

AxisAlignedRectangle playerRectangle;
AxisAlignedRectangle movableBlockRectangle;
AxisAlignedRectangle solidRectangle;

Add the following in Initialize after Initializing FlatRedBall:

 playerRectangle = ShapeManager.AddAxisAlignedRectangle();
 playerRectangle.X = -3;
 playerRectangle.Color = Color.Yellow;

 movableBlockRectangle = ShapeManager.AddAxisAlignedRectangle();
 movableBlockRectangle.Color = Color.Red;

 solidRectangle = ShapeManager.AddAxisAlignedRectangle();
 solidRectangle.ScaleX = solidRectangle.ScaleY = 4;
 solidRectangle.X = 7;

Add the following in Update:

 InputManager.Keyboard.ControlPositionedObject(playerRectangle);

 // player and movable have the same mass
 playerRectangle.CollideAgainstMove(movableBlockRectangle, .5f, .5f);
 // make the solid infinitely more massive than the player
 playerRectangle.CollideAgainstMove(solidRectangle, 0, 1);
 // make the solid infinitely more massive than the movable
 movableBlockRectangle.CollideAgainstMove(solidRectangle, 0, 1);

Determining Collision Side

For information on determining which side an object has collided on, see this page on LastMoveCollisionReposition.

AxisAlignedRectangle Members

• FlatRedBall.Math.Geometry.AxisAlignedRectangle.Bottom

• FlatRedBall.Math.Geometry.AxisAlignedRectangle.CollideAgainst

• FlatRedBall.Math.Geometry.AxisAlignedRectangle.CollideAgainstBounce

• FlatRedBall.Math.Geometry.AxisAlignedRectangle.CollideAgainstMove

• FlatRedBall.Math.Geometry.AxisAlignedRectangle.CollideAgainstMoveSoft

• FlatRedBall.Math.Geometry.AxisAlignedRectangle.Color

• FlatRedBall.Math.Geometry.AxisAlignedRectangle.GetRandomPositionInThis

• FlatRedBall.Math.Geometry.AxisAlignedRectangle.Height

• FlatRedBall.Math.Geometry.AxisAlignedRectangle.KeepThisInsideOf

• FlatRedBall.Math.Geometry.AxisAlignedRectangle.LastMoveCollisionReposition

• FlatRedBall.Math.Geometry.AxisAlignedRectangle.Left

• FlatRedBall.Math.Geometry.AxisAlignedRectangle.RepositionDirections

• FlatRedBall.Math.Geometry.AxisAlignedRectangle.Right

• FlatRedBall.Math.Geometry.AxisAlignedRectangle.Top

• FlatRedBall.Math.Geometry.AxisAlignedRectangle.Width

• FlatRedBall.Math.Geometry.AxisAlignedRectangle.Z

Extra Information

• Axis Alignment and Rotation

• Tile Collision

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

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 is inside a Circle instance:

Redirect to:

For more information see the .

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 .

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 .

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 forums for a rapid response.

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();
}

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 forums for a rapid response.

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.

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

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 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):

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. For more information on the elasticity variable, see the Elasticity Examples section below.

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

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.

The Clone method can be used to create a copy of a given Polygon. A cloned polygon will be identical to the original polygon. Cloned polygons can be used if you are loading Polygons from a file and want to create multiple instances of a given Polygon. For example, you may create a Polygon (which we'll call attack Polygon) in the PolygonEditor. Whenever your character attacks, you may want to clone the attack Polygon and add the newly-created Polygon to a list of polygons in your Screen, which can be used to test collision against enemies.

Introduction

The Color property lets you set the color of a Polygon.

Code Example

The following code shows how to set a Polygon to a color:

// Assuming PolygonInstance is a valid Polygon
PolygonInstance.Color = Color.Red;

Premultiplied Colors

If the engine uses premultiplied alpha, then you must provide premultiplied alpha colors if using transparency.

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:

// Assuming myList is a valid List of shapes
for(int firstIndex = 0; firstIndex < myList.Count; firstIndex++)
{
   for(int secondIndex = 0; secondIndex < myList.Count; secondIndex++)
   {
      // Make sure a shape doesn't collide against itself
      if(firstIndex != secondIndex && 
         myList[firstIndex].CollideAgainst(myList[secondIndex]))
      {
         // do whatever you need to do to respond to collisions here
      }
   }
}

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);

Introduction

CollideAgainstMove can be used to test whether two shapes are touching. If the shapes are overlapping this method also moves one or both so that they no longer overlap. CollideAgainstMove also works between all types of shapes.

CollideAgainstMove is a common method used in games which include solid collision. Sometimes the collision is between two movable objects (such as a player and a box which can be pushed), and sometimes the collision is between a movable and static object (such as a player and a wall).

CollideAgainstMove values

CollideAgainstMove lets you specify how objects should behave when colliding. The first argument is the object to collide against, the second is the mass of the caller, and the third is the mass of the object colliding against.

For example, to collide a Player entity against a wall (assuming the entity implements ICollidable):

// Player has a mass of 0, wall has a mass of 1
PlayerInstance.CollideAgainstMove(WallCollision, 0, 1);

// If your Player object does not implement ICollidable, then you will need to use the shape on the Entity:
PlayerInstance.CollisionObject.CollideAgainstMove(WallCollision, 0, 1);

Inversely to have a player push a block, and have the player not slow down at all when pushing the block:

// Player has a mass of 1, wall has a mass of 0
PlayerInstance.CollideAgainstMove(BlockInstance, 1, 0);

To have both objects impacted equally by the collision, the same mass can be used. For example, if two cars collide (again assuming that the cars implement ICollidable)

CarInstance1.CollideAgainstMove(CarInstance2, 1, 1);

Any value can be used for the mass of the two objects - you're not limited to using 0 and 1. We use 0 and 1 above to express intent - that one object should be mass-less, or that the two objects should have the same mass. For example, a heavier object could collide against a lighter object:

// In this case the truck's mass is 3 times as great as the car
HeavyTruckInstance.CollideAgainstMove(LightCarInstance, 3, 1);

Code Example

The following code loads a .plylstx to create a PositionedObjectList containing Polygons. Another Polygon is created which is controlled by the Keyboard. Move collision is used to keep the moving Polygon and the Polygons loaded from the .plylstx from overlapping. Notice that the mass variables can be modified to allow for different collision behavior.

Files Used: Smiley.plylstx

Add the following using statements:

using FlatRedBall.Math;
using FlatRedBall.Math.Geometry;
using FlatRedBall.Content.Polygon;
using FlatRedBall.Input;

Add the following at class scope:

Polygon mControlledPolygon;
PositionedObjectList<Polygon> mLoadedPolygons;

Add the following in Initialize after initializing FlatRedBall:

 mControlledPolygon = Polygon.CreateEquilateral(6, 1, 0);
 mControlledPolygon.Color = Microsoft.Xna.Framework.Graphics.Color.Orange;
 ShapeManager.AddPolygon(mControlledPolygon);

 PolygonSaveList polygonSaveList = PolygonSaveList.FromFile(@"Smiley.plylstx");
 mLoadedPolygons = polygonSaveList.ToPolygonList();

 ShapeManager.AddPolygonList(mLoadedPolygons);

Add the following in Update:

InputManager.Keyboard.ControlPositionedObject(mControlledPolygon);
foreach (Polygon polygon in mLoadedPolygons)
{
    mControlledPolygon.CollideAgainstMove(
        polygon, 0, 1);
}

Understanding the CollideAgainstMove Implementation

In brief mathematical terms, the CollideAgainstMove repositions the calling shape and the argument shape along the vector that is normal to the surface vector at the point of collision. The amount that each object moves when colliding depends on the two masses passed in to the method.

For example, consider the following situation. There are two Polygons - ball and surface. The ball has a positive XVelocity and negative YVelocity, causing it to fall down and to the right toward the surface Polygon:

Eventually the ball will overlap the surface. Let's assume that the following method is being called every frame:

ball.CollideAgainstMove(surface, 0, 1);

In this case the ball is given a 0 mass and the surface is given a 1 mass. In other words, surface will never be moved by this method while ball will.

When a collision occurs, the vector of the edge where the collision happened is determined. Then the normal (perpendicular) vector is calculated and the shape(s) is (are) moved along the normal vector the required distance to separate them. For example, the first time ball penetrates surface, the following edge vector and reposition vector are calculated:

Since the ball has 0 mass, it will be moved by the full reposition vector. If the value were different, say .5 and .5, then ball and surface would each move half of the reposition vector. Of course, surface would move in the opposite direction as ball so that the two separate after the call.

Since this CollideAgainstMove resolves this penetration, it is never seen when the engine draws the shapes. But if the velocity of ball is not changed, then it will continue to penetrate surface every frame, then get pushed back out every frame. The result is what appears to be a smooth sliding movement across as follows:

RepositionDirections

If one of the colliding shapes is an AxisAlignedRectangle then the direction of the "move" (the reposition) is subject to this value. For more information, see the RepositionDirections page.

Introduction

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

The Attachment Hierarchy

The attachment hierarchy is a collection of IAttachables 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 Entity.

In this hierarchy the entity itself is considered the "root" or TopParent. This means that by default absolute changes to position and rotation will affect ONLY the root object. In other words, if the VisibleRepresentation's X is changed in code, the change will not be drawn or persist next frame. To change the VisibleRepresentation's absolute position or rotation, code must either change the root's absolute values, or the relative values of the VisibleRepresentation.

This characteristic is not unique to Sprites - it applies to all IAttachables including all shapes.

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.

Fortunately, this is not the case. Since shapes are often children of other IAttachables, any modification to position or velocity gets "pushed up" to the root of the attachment hierarchy.

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 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 IsPointInside method returns whether an absolute X/Y position is inside the calling Polygon. This function takes 3D position objects (such as Vector3) but ignores the Z value. Only X and Y are considered.

Code Example

The following code creates a Polygon that is in the shape of a rectangle. When the user moves the cursor in the polygon it turns red; otherwise it is yellow.

Add the following using statements:

Define the Polygon at class scope:

Add the following in Initializing after initializing FlatRedBall (or CustomInitialize if using Screens):

Add the following in Update (or CustomActivity if using Screens):

IsPointInside and ForceUpdateDependencies

The IsPointInside method requires that the Polygon has constructed its internal vertices. This means that you must either:

If neither of the above has happened, then the internal vertices will not be set and this function will always return false.

Introduction

The CreateEquilateral static method is a method in the Polygon class which can be used to quickly create equilateral (same-length sides) Polygons.

Code Example

The following code creates two Polygons. One is a 4-sided polygon. The other one is a very high-vertex count Polygon which can be used to draw smooth Circles. Keep in mind that high-vertex polygons like the one created in this example can be expensive when performing collisions.

Add the following using statement:

Add the following to Initialize after initializing FlatRedBall:

For more information see the .

Introduction

The Polygon class overrides the . The Polygon's ForceUpdateDependencies method does the same thing as the (updates the instance's absolute Position and Rotation values according to attachments); however, it *also* updates the Polygon's internal vertices.

When should ForceUpdateDependencies be called?

In most situations you will not need to call ForceUpdateDependencies. Polygons will automatically update the internal vertices when performing any collision methods (such as CollideAgainst), or right before rendering a Polygon.

Since these two situations are common whenever a Polygon is used, you will usually not need to worry about calling ForceUpdateDependencies. However, if you are creating a Polygon and immediately wanting to use it with any method that may need to use its absolute vertices (such as , then you will need to manually call ForceUpdateDependencies after instantiation.

Introduction

The OptimizeRadius method can be called to adjust the relative points of a Polygon to reduce its radius. The radius of a polygon is used internally to improve the performance of collision methods.

Usage

The OptimizeRadius method should be called if a Polygon's points are set or changed. This method will adjust the values of each relative point to optimize the radius of the Polygon. This method will also modify the position of the Polygon to keep the absolute position of each vertex constant. In other words, this method can be called after Polygons are positioned and it should have no impact on the final appearance or behavior of the Polygon - aside from improved performance.

Code Example

The following code creates two Polygons. The Points are assigned such that the Polygon is not symmetric about its center. The Polygon called optimizedPolygon has its OptimizeRadius method called to make it symmetric. Finally, two circles are created to show the position and radius of both Polygons.

Add the following using statement:

Add the following to Initialize after initializing FlatRedBall:

Introduction

The Points property is an array of values which contain the position of each point on the polygon. These values are in "object space". In other words, they are relative to the containing Polygon's position and rotation values.

The Points property can be assigned - this essentially changes the shape of the Polygon. This is a more-efficient and often more-convenient way to change a Polygon rather than to construct a new one if your game requires dynamic shapes. For more information, see .

Code Example - Setting Points

Code Example - Getting absolute Point positions

The values in the Points array are all relative to the containing Polygon. This means that if the Polygon moves or rotates, the values stored in the Points property will remain the same.

Add the following using statements:

Add the following at class scope:

Add the following in Initialize after initializing FlatRedBall:

Add the following in Update:

Introduction

The ProjectParentVelocityOnLastMoveCollisionTangent method is a very powerful and useful method for creating realistic collision. This method can be used in many types of games to help reduce "tunneling" - that is, objects hopping through other objects because of high speeds.

What does this actually mean?

The ProjectParentVelocityOnLastMoveCollisionTangent property is a very long property name which takes a little bit of understanding. Let's break it down.

To explain what this property means, we'll start from the back and go to the front. First, we'll start with:

OnLastMoveCollision

This phrase indicates that the property that we are investigating will give us information about the last time a "Move" collision was called. In other words, the last time CollideAgainstMove was called. That's all!

OnLastMoveCollision + Tangent

Next, we'll add the Tangent property. In math, a tangent is a line which moves parallel (in the same direction) as a surface. The following image shows a blue line which is a tangent on the yellow circle

The phrase "on last move collision tangent" means that we are going to do something with the line (or Vector in more precise terms) that is tangential to the point where the collision happened the last time CollideAgainstMove was called.

Project...Velocity + OnLastMoveCollisionTangent

Next we'll look at the phrase Project Velocity. The "..." appears in the title because we're going to explain why the word "Parent" appears after this section. A projection in Linear Algebra is the operation done between two Vectors where one Vector is modified so that it is parallel to the second vector, and its length is set to be its length along the second vector. This is a difficult concept to explain in words, so observe the following picture:

In this picture Vector A is projected onto Vector B, resulting in Vector 3. Notice that the result will always be parallel to the projected-on Vector.

Assuming there is no bouncing, friction, or energy loss from the collision, this projection realistically represents the behavior of a moving object as it collides with another object. In other words, projecting the velocity on the tangent of the last collision will make the object appear to collide with the object and keep moving in a realistic manner after the collision.

Project + Parent + VelocityOnLastMoveCollisionTangent

Finally we introduce the word "Parent". The reason Parent appears in this method name is because most shapes are never used alone, but rather are used as children of another object (usually Entities). Therefore, the shape shouldn't modify its own Velocity, but rather the Velocity of its parent.

CollideAgainstBounce

This method is only used in more complex situations. You can usually accomplish the exact same behavior by simply calling CollideAgainstBounce with an elasticity of 0.

Method Signature

ProjectParentVelocityOnLastMoveCollisionTangent provides the following overloads:

ProjectParentVelocityOnLastMoveCollisionTangent()
ProjectParentVelocityOnLastMoveCollisionTangent(float minimumVectorLengthSquared)

minimumVectorLengthSquared

The minimumVectorLengthSquared argument is an argument that can control whether velocity modifications should be performed. Shapes which have the ProjectParentVelocityOnLastMoveCollisionTangent method store the vector that they were moved along in the last CollideAgainstMove call. This property is the called LastMoveCollisionReposition. The minimumVectorLengthSquared is a value which is compared against the square of the length of LastMoveCollisionReposition. This can be used to prevent the projection of velocity.

Most of the time this is not needed, and calling the no-argument version of ProjectParentVelocityOnLastMoveCollisionTangent uses a default value of 0 for minimumVectorLengthSquared. This argument can be used in very rare cases where large numbers can result in precision loss.

Code example

The following code creates two Polygons. The smaller polygon will move down and to the right, then slide along the larger polygon. Once the smaller polygon reaches the end of the larger polygon, it will continue to move to the right. In other words, it will lose its "downward" component of its velocity vector.

Add the following using statement:

using FlatRedBall.Math.Geometry;

Add the following at class scope:

Polygon mLargePolygon;
Polygon mSmallPolygon;

Add the following to Initialize after initializing FlatRedBall:

mLargePolygon = Polygon.CreateRectangle(10, 3);
mLargePolygon.Y = -8;
ShapeManager.AddPolygon(mLargePolygon);

mSmallPolygon = Polygon.CreateEquilateral(10, 1, 0);
mSmallPolygon.X = -4;
mSmallPolygon.XVelocity = 2;
mSmallPolygon.YVelocity = -2;
ShapeManager.AddPolygon(mSmallPolygon);

Add the following to Update

if (mSmallPolygon.CollideAgainstMove(mLargePolygon, 0, 1))
{
    mSmallPolygon.ProjectParentVelocityOnLastMoveCollisionTangent();
}

Things to try: If you remove the call to

mSmallPolygon.ProjectParentVelocityOnLastMoveCollisionTangent();

you will notice that the moving Polygon will continue to move downward after reaching the end of the larger Polygon. Give it a shot to see the difference.

Creating a Basic Platforming Engine

ProjectParentVelocityOnLastMoveCollisionTangent is useful both for realistic physics, as well as semi-realistic physics as found in many platformers (such as Super Mario Bros.)

The following is a block of code which can serve as an example for how to handle collision in a platformer:

// Assume that myPolygon and polygonList are valid references to a Polygon and 
// a PositionedObjectList<Polygon>, respectively

bool onGround = false;

foreach (Polygon polygon in polygonList)
{
    // The 0 is the relative mass of myPolygon and 1 is the relative 
    // mass of the argument polygon.  In this case, the ground is infinitely
    // more massive than myPolygon.
    if (myPolygon.CollideAgainstMove(polygon, 0, 1))
    {
        // Adjust the velocity of myPolygon
        myPolygon.ProjectParentVelocityOnLastMoveCollisionTangent();

        // If myPolygon was moved upward then it is resting on the ground
        // Keep in mind this could be a sharp slope as well.
        onGround|= myPolygon.LastMoveCollisionReposition.Y > 0;
     }
}

Introduction

The "thin Polygon problem", also known as collision tunneling, is a collision bug that is very commonly collision problem. As the name suggests, this bug occurs when dealing with thin shapes. Although we use Polygons in this discussion, it applies to AxisAlignedRectangles as well. This bug manifests itself in one of three ways:

1. Moving objects completely pass through Polygons. This is known as "tunneling".

2. Moving objects becoming stuck inside polygons.

3. Moving objects touching and being moved to an unexpected location on the surface of the Polygon.

Tunneling also exists with other shapes: Although this article talks specifically about Polygons, tunneling is a problem that exists with all other shape types and is not limited to Polygons. In fact, the incremental movement that is used in FlatRedBall which leads to tunneling is a general problem in game development, and the term "tunneling" is not a term which is simply used in FlatRedBall. If you are experiencing objects falling-through or passing-through other objects, this article may help you solve your problems - even if you're not using Polygons.

Of course you may be wondering "what defines thin?" Whether a Polygon is thin or not depends on the distance between lines of a Polygon relative to the velocity of objects that will collide against the Polygon. For example, if you have have a rectangle-shaped Polygon that is 1 unit thick, you probably will not experience any collision problems when an object moving at .1 units per second collides against your Polygon. If, on the other hand, the moving object is moving at 60 units per second, you will almost certainly see this bug.

Why the thin Polygon problem exists

The FlatRedBall collision system is a "historyless" collision system. This means that the collision performed at any given time does not consider the previous positions of objects. This approach has its benefits - it uses less memory, is slightly faster, and is very flexible. Of course, this can result in the bug discussed in this article. Let's look at an example of why a historyless collision system can result in tunneling Frame A shows a yellow ball (could be any shape really) falling towards a light-blue surface. In this example we'll assume that the ball is traveling at a very high speed. There is no collision for frame A, so the ball continues to fall normally. Because the ball traveled so quickly, it has nearly moved completely through the surface in one frame. Since FlatRedBall does look at the ball's position in frame A (it's historyless), the collision that it performs results in what we see in frame C: If you were to look only at frame B without looking at frame A, you may also prefer the end-position resulting in C.

Solutions to the thin Polygon problem

Fortunately there are a number of solutions to the thin polygon problem. Which you employ depends on the type of problem you're seeing and what kind of options you have from the genre of game you're developing.

Wider Polygons

The first solution to the thin polygon problem is to simply make your objects not move as fast. This will resolve tunneling in almost every situation. However, this may not be an option for you because of the type of game you are developing. If you are making a racing game, then you may not want to slow the cars down just to resolve this issue (and you shouldn't either!). Of course, as we mentioned above, these problems occur when the speed of the colliding object is high relative to the *width* of the polygon. In other words, you can usually solve these problems by simply making your collision areas wider. This is especially effective if the borders of your game mark the absolute boundaries that the player can occupy. In other words, if your game takes place inside a room and the player can't walk outside of the room, then you can widen the walls to virtually any size you'd like to prevent tunneling.

Increasing the frame rate

Increasing the frame rate of your game by reducing the Game's TargetElapsedTime is an effective but very expensive approach to solving this problem. More information on this can be found here.

Multiple collision calls per frame

One solution which simulates increasing the frame rate, but isolates the performance impact to the code you are working with is to have your colliding objects (Entities) keep track of their last-frame position, then subdivide the distance they've traveled in one frame into smaller segments, and performing collision tests at each point. At a high level here are steps on how to do the collision tests:

1. In your Entity object which must perform multiple collisions, mark its position at the end of the Update method.

2. At the beginning of the frame, compare subtract the last position from the current position to identify the distance traveled.

3. Determine how much you want to subdivide your frame.

4. Write a loop as follows:

for(int i = 0; i < numberOfSubdivisions; i++)
{
  float ratioIntoFrame = i / (float) numberOfSubdivisions;
  Vector3 positionAtRatio = entityTesting.LastFramePosition + ratioIntoFrame * distanceTraveled;
  entityTesting.Position = positionAtRatio;
  // perform your collision now  
}

Limiting movement speed

One of the most common situations where tunneling exists is in platformers that use YAcceleration for gravity. The reason this can cause so many problems is because the speed that the distance that the game character falls impacts how fast the character hits the ground. If your game includes large drops, you may notice that the character sometimes falls through the world when falling long distances. Most professionally-made platformers include a maximum falling speed for game play reasons. Implementing this maximum falling speed (also known as "terminal velocity") can both improve the feel of your game as well as possibly solve tunneling. For a discussion on how to limit falling speed, see this article.

Sweeping Shape Collision

Depending on the shape of your object you may be able to create a swept shape. The Capsule2D class is a useful shape for testing collisions of circles. You can also create your own Polygons or Lines to check if a collision occurred between two frames. If a collision did occur you may need to "rewind time" and subdivide the last frame to get more accurate results.

Subdividing your Polygon

So far we've talked about tunneling issues, but there are also situations where two polygons may report a collision, but not separate correctly. This occurs in the example that uses the smiley polygon if you move the moving Polygon to the edges of the mouth polygon. To solve this, you can add additional points to the smiley polygon in the PolygonEditor as described here.

Using simpler shapes

The section above describes a situation where polygon collision error occurs even if the speed of the moving Polygon is very low. In general the simpler shapes have more accurate collision than Polygons. Therefore, replacing the moving Polygon with a Circle will improve the accuracy of collision - while improving performance at the same time.

Introduction

The ScaleBy method can be used to adjust a Polygon's points to make it larger or smaller. The ScaleBy method is relative to the current state of the polygon. This means that calling ScaleBy with any number other than 1 multiple times will continually change the polygon.

Scaling multiple times

Calling ScaleBy multiple times will continually change the polygon. For example:

myPolygon.ScaleBy(2); 

will double the relative value of each point. Calling the method again will double it once more.

Ignoring floating point inaccuracy, the following line of code will result in no changes to a Polygon:

myPolygon.ScaleBy(2); 
myPolygon.ScaleBy(.5f); 

Preserving original shape

Since ScaleBy modifies the points on a Polygon, the Polygon has no built-in way to preserve the original shape of the polygon. To do so, you will have to keep track of that information yourself:

// Assuming PolygonInstance is a valid Polygon:
float scaleAmount = 1;
PolygonInstance.ScaleBy(2);
scaleAmount *= 2;

PolygonInstance.ScaleBy(4);
scaleAmount *= 4;

// Now let's bring it back to its original shape:
PolygonInstance.ScaleBy( 1 / scaleAmount);
scaleAmount = 1;

BoundingRadius

ScaleBy will modify the BoundingRadius of the calling Polygon is used internally for collisions. There is no need to call OptimizeRadius after calling ScaleBy.

Introduction

All FlatRedBall shapes inherit from the class, so they inherit the X, Y, Z, and Position properties.

The Z value of shapes impacts their rendering, but not collision. In other words, shapes will render differently according to their Z value when rendering on a 3D camera, but they will collide as if their Z values are all the same.

Position relative to the Polygon

The Position of the Polygon is a bit of an abstract concept because it may or may not represent the center of a Polygon. In fact, it may not even lie inside of a Polygon depending on how the Points values are set.

If you use the or functions, then the Position will represent the center of the Polygon. If you have constructed the Polygon yourself by setting the Polygon's , then the Position value relative to points depends on the values you've assigned to .

Shape vs. non-Shape sorting

Shapes and non-Shapes which are on the same Layer (or which are all un-Layered) will not sort with each other. For more information see .

Introduction

All FlatRedBall shapes inherit from the class, so they inherit the X, Y, Z, and Position properties. The Z value of shapes impacts their rendering, but not collision. In other words, shapes will render differently according to their Z value when rendering on a 3D camera, but they will collide as if their Z values are all the same.

Position relative to the Polygon

The Position of the Polygon is a bit of an abstract concept because it may or may not represent the center of a Polygon. In fact, it may not even lie inside of a Polygon depending on how the Points values are set. If you use the or functions, then the Position will represent the center of the Polygon. If you have constructed the Polygon yourself by setting the Polygon's , then the Position value relative to points depends on the values you've assigned to .

Shape vs. non-Shape sorting

Shapes and non-Shapes which are on the same Layer (or which are all un-Layered) will not sort with each other. For more information see .

Introduction

The CreateRectangle method creates a Polygon that is in the shape of a rectangle. Polygons created through the CreateRectangle method are no different than any other Polygon - the CreateRectangle method is simply a method that simplifies a common task.

Since Polygons and have the same methods for performing collision and both inherit from the class, the decision of whether to use the Polygon or depends on whether you need rotation support.

If you need to have rotation support, you should use the Polygon class. do not consider rotation when drawn or when performing collision. However, because of this, collision is faster than Polygon collision. If rotation is not needed, you should consider using the class for performance reasons.

Code Example

The following code creates a Polygon using the CreateRectangle method. The Polygon is then added to the ShapeManager to be visible.

Add the following using statements:

Add the following to Initialize after initializing FlatRedBall:

Value Explanation

Notice that the values used in the above line of code are "scale" values. Scale values in FlatRedBall represent the distnace from the center to the edge of an object. For example, an object which has a ScaleX of 2 will have a width of 4. Therefore, the rectangle created in the code above will have a width of 4 units and a height of 6 units.

Introduction

The Visible property controls whether a particular shape is drawn. Setting Visible to false will make a shape no longer be drawn. Setting Visible to true will make the shape drawn - even if it is not part of the ShapeManager.

Under the hood

All visible shapes are stored in lists in the ShapeManager for drawing. If a visible shape is made invisible (its Visible is set to false) then it is removed from the shape that stores all to-be-drawn shapes of that particular type. This characteristic of the Visible property improves the speed of drawing shapes, but can have a small performance impact on the Visible property.

Introduction

A segment is a object defined by two Points. It is not a PositionedObject and its points are absolute, which differentiates it from the Line class.

Segment Intersection

The following code creates two Lines. One line rotates automatically while the other is controlled by input from the Keyboard. The two Lines call the AsSegment method to create Segments that represent the calling Lines. The segment can then be used to find the point of collision between the two Lines. If the resulting intersection point has valid coordinates then a collision has occurred. A red ball Sprite marks the intersection point between the two Lines.

Add the following using statements:

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

Add the following at class scope:

Line firstLine;
Line secondLine;
Sprite sprite;

Add the following in Initialize after initializing FlatRedBall:

firstLine = ShapeManager.AddLine();
firstLine.RelativePoint1 = new Point3D(-5, 0);
firstLine.RelativePoint2 = new Point3D(5, 0);
firstLine.RotationZVelocity = 1;

secondLine = ShapeManager.AddLine();
secondLine.RelativePoint1 = new Point3D(-3, 0);
secondLine.RelativePoint2 = new Point3D(3, 0);

sprite = SpriteManager.AddSprite("redball.bmp");
sprite.ScaleX = sprite.ScaleY = .5f;

Add the following in Update:

InputManager.Keyboard.ControlPositionedObject(secondLine);

// To get the collision points, use Segments
Segment firstSegment = firstLine.AsSegment();
Segment secondSegment = secondLine.AsSegment();

// Qualify Point since there is a Microsoft.Xna.Framework.Point
FlatRedBall.Math.Geometry.Point intersectionPoint;

firstSegment.IntersectionPoint(ref secondSegment, out intersectionPoint);

if (double.IsNaN(intersectionPoint.X))
{
    sprite.Visible = false;
}
else
{
    sprite.Visible = true;
    sprite.X = (float)intersectionPoint.X;
    sprite.Y = (float)intersectionPoint.Y;
}

Segment Members

• FlatRedBall.Math.Geometry.Segment.ClosestPointTo

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

Introduction

The ShapeManager is responsible for managing "Shapes". Shapes are most often used for collision between objects. Objects which belong to the Shape categorization are:

• AxisAlignedCube

• AxisAlignedRectangle

• Capsule2D

• Circle

• Line

• Polygon

• Sphere

All of these objects share the PositionedObject base class. These are the only objects which the ShapeManager manages. Although there is no "Shape" class, these objects are often referred to as shapes.

Adding Shapes

The ShapeManager can add any shape through its Add methods. The following code creates a Circle. Add the following using statement:

using FlatRedBall.Math.Geometry;

Add the following using statement:

Circle circle = ShapeManager.AddCircle();

Shapes and Visibility

Adding a Shape to the ShapeManager will automatically make the shape visible. For example, the following code will result in a visible Circle:

Circle circle = new Circle();
circle.Visible = false; // this will get overridden
ShapeManager.AddCircle(circle); // now our Circle's visible

To properly control visibility, set the value after a shape to the ShapeManager:

Circle circle = new Circle();
ShapeManager.AddCircle(circle); // now our Circle's visible
circle.Visible = false; // this will get overridden

Removing Shapes

The ShapeManager can remove shapes that have been previously added to it through its Remove method. Assuming circle is an instance of a Circle that has been created through the ShapeManager:

ShapeManager.Remove(circle);

Management Tasks

Aside from addition and removal of shapes, the ShapeManager is responsible for drawing and managing Sprites. Calling AddPolygon, AddAxisAlignedRectangle, and AddCircle results in the ShapeManager managing and drawing the Sprite added or created by the method. It is possible to create manage-only or draw-only as shown by the following code:

 // This using statement reduces the amount of code necessary
 using FlatRedBall.Math.Geometry;

 // The following circle is both managed and drawn:
 Circle circle1 = ShapeManager.AddCircle();

 // The following circle is only drawn:
 Circle circle2 = new Circle();
 circle2.Visible = true;

 // The following circle is only managed:
 Circle circle3 = ShapeManager.AddCircle();
 circle3.Visible = false;

Why Limit Shape Management?

Making shapes visible can be beneficial for debugging collisions. For the final version most games will want shapes to be invisible. Invisible shapes will collide the same as visible ones so in most cases visibility is useful simply during development. Of course, shapes can also be used to draw on-screen line graphics. Clearly, visibility control is important, but why not include shapes in the ShapeManager? The ShapeManager provides some behavior that can be helpful, but in many cases this behavior is not necessary. Shapes should be added to the ShapeManager if any of the following behavior is needed:

• Attachment updates when collision methods are not called. See Note

• Absolute or relative velocity.

• Absolute or relative acceleration.

• Absolute or relative rotation velocity;

• Instructions

• ScaleVelocity (AxisAlignedRectangle only)

• Radius Velocity (Circle only)

Note about attachments: Shapes which are attached to parents can have their absolute positions updated one of two ways:

1. By being added to the ShapeManager

2. By calling one of their collision methods or passing them as arguments to a collision method.

If a shape is to be used only for collision and is not visible, then it is not necessary to add it to the ShapeManager. When the collision method is called then it will automatically have its position updated. If a shape is visible, has a parent, and does not have collision methods being called, then it will need to be added to the ShapeManager to have its absolute position updated. If a shape is to be completely static - like a grid in a tool - then there is no reason to add it to the ShapeManager.

Unmanaged Shape Behavior

The source of some confusion is what happens when a Shape is attached to a PositionedObject (like a Sprite), but not added to the ShapeManager. If you write code which attaches a shape to a Sprite, make the shape visible, then move the parent Sprite you will notice that the shape does not move. Why is this the case? Well, again, there are two ways to update a shape's attachments:

1. By being added to the ShapeManager

2. By calling one of their collision methods or passing them as arguments to a collision method.

Since the shape is neither part of the ShapeManager nor having any Collision methods called, then its dependencies are never updated - so the position of the parent has no affect on the child Shape. If you are interested in seeing the shape move with its parent, simply add it to the ShapeManager. If this shape is going to be used for collisions, then there is no need to add it to the ShapeManager - calling collision methods will automatically manage the dependency. This behavior will also be present if the shape is not visible, but you depend on the shape's absolute position. If you're depending on the shape's position outside of collision, be sure to add it to the ShapeManager.

Additional Information

• Colliding a list of shapes against itself

• Shapes and 2D Collision

ShapeManager Members

• FlatRedBall.Math.Geometry.ShapeManager.AddAxisAlignedRectangle

• FlatRedBall.Math.Geometry.ShapeManager.AddToLayer

• FlatRedBall.Math.Geometry.ShapeManager.Remove

• FlatRedBall.Math.Geometry.ShapeManager.ShapeDrawingOrder

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

Introduction

The VectorFrom returns a vector from the argument position to the calling instance. This method returns the shortest vector which can be traveled along to reach the surface of the calling instance. This method does not return the distance from the calling point to the center of the shape.

Code Example

The following code creates a concave Polygon and a Line. The Line draws the shortest line from the tip of the cursor to the Polygon. Add the following using statements:

Add the following at class scope:

Add the following in Initialize after initializing FlatRedball:

Add the following to Update:

Introduction

The AxisAlignedRectangles property is a property of type PositionedObjectList. Therefore, you can use this member the same way you would use a PositionedObjectList<AxisAlignedRectangle>.

Code Example

The following shows how to loop through all rectangles in a ShapeCollection and perform collision between the rectangles and a Circle named CircleInstance:

for(int i = 0; i < ShapeCollectionInstance.AxisAlignedRectangles.Count; i++)
{
    circle.CollideAgainstMove(ShapeCollectionInstance.AxisAlignedRectangles[i], 0, 1);
}

Introduction

The ShapeCollection provides a CollideAgainst method which tests if any shape contained in the calling ShapeCollection collides the argument shape. The CollideAgainst method can also be called to test if two ShapeCollections have any shapes that collide between the two.

Arguments

The CollideAgainst method can be used to test collision against argument shapes. At the time of this writing, some shapes are not completely supported, but this is changing. If you encounter a NotImplementedException, please post on the forums requesting the implementation needed for your project.

The following overloads are available:

bool ShapeCollection.CollideAgainst(AxisAlignedCube axisAlignedCube)
bool ShapeCollection.CollideAgainst(AxisAlignedRectangle axisAlignedRectangle)
bool ShapeCollection.CollideAgainst(Capsule2D capsule2D)
bool ShapeCollection.CollideAgainst(Circle circle)
bool ShapeCollection.CollideAgainst(Line line)
bool ShapeCollection.CollideAgainst(Polygon polygon)
bool ShapeCollection.CollideAgainst(Sphere sphere)

The ShapeCollection class can also collide against other ShapeCollections:

bool CollideAgainst(ShapeCollection otherShapeCollection)

Introduction

The ShapeCollection provides a CollideAgainstMoveWithoutSnag method which tests if any shape contained in the calling ShapeCollection collides the argument shape and moves the argument shape accordingly. This method is different from CollideAgainstMove where CollideAgainstMoveWithoutSnag is an order independent operation where CollideAgainstMove is a order dependent operation. CollideAgainstMoveWithouSnag may be slightly slower than CollideAgainstMove and is recommended only if the order of the collisions matters.

Arguments

The CollideAgainstMoveWithoutSnag method can be used to test collision against argument shapes. At the time of this writing, some shapes are not completely supported, but this is changing. If you encounter a NotImplementedException, please post on the forums requesting the implementation needed for your project.

The following overloads are available:

bool ShapeCollection.CollideAgainstMoveWithoutSnag(AxisAlignedRectangle axisAlignedRectangle)
bool ShapeCollection.CollideAgainstMoveWithoutSnag(Circle circle)
bool ShapeCollection.CollideAgainstMoveWithoutSnag(Polygon polygon)