Introduction

The Clear function is a function that will empty a PositionedObjectList of all contained references - it operates the same way as calling Clear on a normal List. However, although Clear is a very common function when dealing with regular Lists, it is not often used on PositionedObjectLists.

If you are using Clear, make sure you understand the information discussed in this wiki.

Why should Clear (usually) not be used on PositionedObjectLists made in Glue?

The Clear function should usually not be used when dealing with lists in Glue. Let's investigate why this is the case. For this discussion we'll assume that your game has an Entity called Bullet, and that your Screen has a PositionedObjectList of Bullets which will is called BulletList.

In this example the BulletList will have bullets added to it. Sample code for this might look like:

if(InputManager.Keyboard.KeyPushed(Keys.Space))
{
    Entities.Bullet bullet = new Entities.Bullet();
    BulletList.AddBullet(bullet);
}

You might expect that simply calling BulletList.Clear will remove all bullets from your game; however, this is not the case. To understand this, let's add some comments to the code listed above so we can understand what is happening:

// The if-statement checks to see if the user pressed the space bar:
if(InputManager.Keyboard.KeyPushed(Keys.Space))
{
    // The following line of code creates a bullet.  Note that
    // when a new Bullet is created, it is instantiated and also added
    // to the engine.  That means that if the bullet has a Sprite, it will
    // be drawn, and if the bullet has velocity, it will move.  You do not have
    // to add the bullet to the BulletList for the Engine to have a reference to
    // this new Bullet.
    Entities.Bullet bullet = new Entities.Bullet();
    // The following line of code adds the bullet to the BulletList stored in your
    // Screen.  There are two reasons why this is typically done:
    // 1.  So that you can use the BulletList in your screen to check for collision
    //     or any other custom logic.
    // 2.  So that Glue can generate code to automatically clean up all Bullets when
    //     the Screen is destroyed.
    BulletList.AddBullet(bullet);
}

The important thing to note here is that calling BulletList.AddBullet is not required for the bullet to be drawn and updated. The reason is because the reference to your new bullet is stored in two places:

1. The FlatRedBall Engine

2. The BulletList

Since the new Bullet is stored by both the FlatRedBall Engine as well as the BulletList, then to fully-destroy the Bullet it must be removed from both the FlatRedBall Engine as well as the BulletList.

However, the Clear function will only remove the Bullet from the BulletList. Calling Clear will result in the BulletList being empty, but the Bullets will still be a part of the engine.

Since this is such common behavior in FlatRedBall, all Entities have a Destroy method. When Destroy is called, the Entity removes itself from both the FlatRedBall Engine and any PositionedObjectList it is a part of. This is why the preferred method of clearing a list is to call Destroy on the contained objects:

for(int i = ButtonList.Count - 1; i > -1; i--)
{
    ButtonList[i].Destroy();
}

GetFirstAfterPosition is obsolete. The upper bound for GetFirstAfterPosition is inclusive. GetFirstAfter uses an exclusive upper bound to match other range-accepting methods in C#. Please use FlatRedBall.Math.PositionedObjectList.GetFirstAfter.

The AttachTo method is a shortcut method for attaching all contained elements in the list to the argument. The method's contents are as follows:

public void AttachTo(PositionedObject newParent, bool changeRelative)
{
    for (int i = 0; i < Count; i++)
    {
        this[i].AttachTo(newParent, changeRelative);
    }
}

For more information on the AttachTo method, see the IAttachable page.

The Add method adds the argument PositionedObject to the PositionedObjectList. The argument object will create a two-way relationship with the list. Null arguments are not allowed.

Introduction

The GetFirstAfter value can be used to get the index of the next object after a given position value. For example, if you are working with a group of Entities (such as Enemy) and are implementing some partitioning logic, you can use GetFirstAfter to find the index of the first instance in a list to begin your loop for partitioning.

Note that if you are using CollisionRelationships and you have set up partitioning on your list, this method is automatically used internally to improve collision performance.

Code Example

Assuming you have an already-sorted list of PositionedObjects, the following code can be used to get the first index after X = 0.

float xToLookAfter = 0;
Axis axis = Axis.X;
int lowBound = 0;
int highBound = EnemyList.Count;
int indexOfObject = EnemyList.GetFirstAfter(xToLookAfter, axis, lowBound, highBound);

Typically GetFirstAfter is used to determine the starting index in a loop, such as in a collision loop. In this case you may want to adjust the lowBound value by half of the width of the type of object in the list. If your list has objects of varying size, you will want to use half of the width of the largest item.

Inserting in sorted lists

GetFirstAfter is used in already-sorted lists, and it is usually used to insert new items in a PositionedObjectList such that the PositionedObjectList remains sorted after the insertion. The following code can be used to create 15 Sprites which will be inserted in order of their X value:

Add the following using statements:

using FlatRedBall.Math;

Add the following to Initialize after initializing FlatRedBall:

string valueRecord = "";
PositionedObjectList<Sprite> sortedList = new PositionedObjectList<Sprite>();

for (int i = 0; i < 15; i++)
{
    Sprite sprite = SpriteManager.AddSprite("redball.bmp");
    SpriteManager.Camera.PositionRandomlyInView(sprite, 40, 40);

    int indexToInsertAt = sortedList.GetFirstAfter(sprite.X, Axis.X, 0, sortedList.Count);
    sortedList.Insert(indexToInsertAt, sprite);
}

for (int i = 0; i < sortedList.Count; i++)
{
    if (i != 0)
    {
        valueRecord += ",\n";
    }
    valueRecord += sortedList[i].X;
}

FlatRedBall.Debugging.Debugger.CommandLineWrite(valueRecord);

Introduction

The PositionedObjectList is an object which can store lists of . It is commonly used to store lists of and shapes such as . The PositionedObjectList inherits from the and it establishes with objects that are added to it.

Common Usage

Most FlatRedBall games use the PositionedObjectList. The PositionedObjectList is common both in custom code as well as in generated code.

What types are stored in PositionedObjectLists

The PositionedObjectList is a dynamic list which is made to specifically store and any classes which inherit from . The most common types stored in PositionedObjectLists are:

• - Any entity created in the FRB Editor can be stored in a PositionedObjectList. Lists added to Screens or other Entities inside the FRB Editor are PositionedObjects. All entity lists in GameScreen (created by default when a new entity is created) are of type PositionedObjectList.

Example - Instantiating a PositionedObjectList in Code

Most PositionedObjectList instances are created through the FRB Editor. You can also create instances in custom code.

The PositionedObjectList class is a generic class. So, to instantiate one, you need to use the type that the PositionedObjectList will contain:

Removing items from lists

Most of the time items in PositionedObjectLists are added automatically in generated code. These include:

• Enitity instances added explicitly through the FlatRedBall Editor, such as a Player being in the PlayerList in GameScreen

• Entity instances added through factories at runtime, such as a Bullet entity being created when the player presses the shoot button. If the Bullet is created using its factory, then it will automatically be added to the BulletList in the current Screen (usually GameScreen)

• Sprites and shapes added to an Entity's Children property - this happens automatically when an object is added to an Entity.

In all of these cases, there is no need to explicitly remove objects from the list - when the Entity or Screen is destroyed then the object gets removed from its lists.

Note that if an entity is created at runtime (such as a Bullet), it may be destroyed at runtime as well. For example, your game may include bullets which only survive for a few seconds after being fired. In this case you need to explicitly call Destroy on the bullet. By calling Destroy, the bullet is automatically removed from the PositionedObjectLists that it belongs to, including the (likely) BulletList in GameScreen.

At times you may need to perform removal of entities explicitly by accessing the list of objects. For example, your game may destroy Enemy instances when they move outside of the screen. If you do this, you will want to use a reverse loop so that any removals do not result in skipping checks that frame, as shown in the following code:

Introduction

The SortXInsertionAscending (and SortYInsertionAscending/SortZInsertionAscending) function can be used to sort all contained PositionedObjects in a list by their X (or Y/Z) value.

Code Example

The following code creates 3 and places them in a PositionedObjectList in descending X order. Then SortXInsertionAscending is called, and the positions of the Circles are printed out: