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?

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.

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

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

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

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

Introduction

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

Example

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

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

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

Introduction

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

Code Example

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

Setting values

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

Code Example - Setting Left

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

Introduction

• 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 RepositionDirections member controls which direction colliding objects will be repositioned. Specifially RepositionDirections is relevant when calling CollideAgainstMove and CollideAgainstBounce. 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:

RectangleInstance.RepositionDirections = RepositionDirections.Up;

The code above results in all objects being moved upward:

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

RectangleInstance.RepositionDirections = RepositionDirections.Left | RepositionDirections.Down;

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:

void CustomInitialize()
{
    BlueRectangle.RepositionDirections = RepositionDirections.Left;
}

void CustomActivity(bool firstTimeCalled)
{
    var keyboard = InputManager.Keyboard;
    keyboard.ControlPositionedObject(RedRectangle);
    RedRectangle.CollideAgainstMove(BlueRectangle, 0, 1);
}

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:

// The red has a mass of 0, so it will get pushed, blue will stay in the same place
RedRectangle.CollideAgainstMove(BlueRectangle, 0, 1);

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

BlueRectangle.RepositionDirection = RepositionDirection.Right;

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:

MyPlatform.RepositionDirections = RepositionDirections.Up;

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

bool IsCorner(AxisAlignedRectangle rectangle)
{
    var repositionDirections = rectangle.RepositionDirections;

    return 
        // Top-left corner:
        (repositionDirections.HasFlag(RepositionDirections.Up) && repositionDirections.HasFlag(RepositionDirections.Left)) ||
        // Bottom-left corner:
        (repositionDirections.HasFlag(RepositionDirections.Left) && repositionDirections.HasFlag(RepositionDirections.Down)) ||
        // Bottom-right corner:
        (repositionDirections.HasFlag(RepositionDirections.Down) && repositionDirections.HasFlag(RepositionDirections.Right)) ||
        // Top-right corner:
        (repositionDirections.HasFlag(RepositionDirections.Right) && repositionDirections.HasFlag(RepositionDirections.Up));
}