PositionedObjectList
Last updated
Was this helpful?
Last updated
Was this helpful?
PositionedObjectLists (also referred to as lists) in the FlatRedBall Editor hold lists of objects which inherit from the PositionedObject type. Positioned objects include:
Any Entity (the most common types of lists)
Circles
AxisAlignedRectangles
Texts
Sprites
In code all of the objects mentioned above inherit from the class.
The most common place for lists is in GameScreen, although lists can exist in any screen and even in other entities.
As shown below, when an entity is created, the FlatRedBall suggests creating a list in GameScreen as well as adding a factory for the list. This configuration enables the following common and useful behaviors and relationships:
Entity lists automatically associated themselves with factories, so that creating a new instance through a factory in code results in the instance being added to the list.
Entity lists call Activity on all contained instances, keeping activity behavior consistent whether the instance is created in the FRB editor or at runtime (such as through a factory)
Entity lists automatically destroy all instances when the screen ends, making screen cleanup easy
By default the FRB Editor creates lists for newly-created entities if the default options are left unchanged. For example, the following animation shows the creation of an entity called Enemy which also results in an EnemyList added to GameScreen.
The FlatRedBall Editor provides a number of ways to create new lists.
If your game has a GameScreen, and if your GameScreen does not already contain a list for an entity, then the Quick Actions tab shows a button to add a list to the GameScreen. Clicking this button creates a new list in the GameScreen.
Entity lists can be created by right-click drag+dropping an entity into a screen. This is useful if you are adding lists of entities to screens other than the GameScreen.
PositionedObjectLists can also be created through the regular right-click menu in an screen or entity's Objects node:
Right-click on Objects
Select Add Object
Make sure FlatRedBall or Custom Type is selected
Select PositionedObjectList<T>
Select the type of list to create using the dropdown
Enter the name of the list
Once a list has been created, instances of the list's type can be added through the FRB Editor using a number of methods.
Option 1 - Drag+drop onto Screen, Objects folder or List
If a list contains a screen, it becomes the default container for newly-created instances that are added by drag+drop. For example, the following shows enemies being added to the EnemyList by drag+dropping an enemy on Level1, Level1's Objects folder, and directly on the EnemyList.
Option 2 - Right-click, Add Object
Objects can be directly added to the list by right-clicking on the list. Notice that the Add Object window restricts the types of entities which can be added to the types that are supported by the list. For example, the following animation shows how to add an Enemy to an Enemy list with the right-click menu.
If the list is of a base type, then the right-click option provides all available options for the list. For example, the following is a screenshot from a game which has multiple entity types inheriting from Enemy:
The CallActivity property controls whether the FRB Editor should generate Activity calls for a PositionedObjectList. By default this value is set to true. For example, the following shows a BulletList inside a screen which has its CallActivity set to true:
If this value is changed to false, then the Bullet instances inside of BulletList would not have their Activity (and CustomActivity) methods called automatically in generated code.
The most common reason to set this value to false is when dealing with derived entity lists. For example, consider a game which has a base Enemy entity as well as Skeleton entity which inherits from Enemy (Skeleton is an Enemy variant). If the game needs to perform custom logic on Skeleton instances then it may need both an EnemyList and SkeletonList in GameScreen.
In this case, Skeletons which are created through the Skeleton factory would be added to both the EnemyList and the SkeletonList. If both EnemyList and SkeletonList called Activity, then Skeleton instances would have activity called twice per frame. This can result in unexpected behavior such as movement logic being applied twice per frame.
If a derived entity type list is added to a screen through the quick action button, FlatRedBall automatically sets CallActivity to false.
If an entity list is added through the right-click option on a screen, FlatRedBall provides suggestions about whether to call Activity.
Entity lists automatically set AssociateWithFactory to true, which means that the list registers itself with the relevant factories when the Screen is first initialized.
If an entity is a base type, or if it is not part of an inheritance chain, then its list registers itself with only one factory. For example, in a default project the PlayerList associates itself with PlayerFactory.
If an entity is a derived entity, such as a Skeleton deriving from a base Enemy entity, then typically Skeleton also has a SkeletonFactory. By default Skeletons which are created by the SkeletonFactory are added to the base EnemyList.
If the GameScreen contains a SkeletonList, and if SkeletonList has AssociateWithFactory set to true, then SkeletonFactory adds newly-created Skeleton instances to both SkeletonList and EnemyList. This only occurs if a SkeletonList is manually created. Your game may need to have derived entities, like Skeleton, as part of two lists.
The EnemyList serves as a list for behavior common to all types of enemies. This may include:
Collision against the environment
Taking damage from the Player
Destruction at the end of the level
Game-specific checks, such as see if all Enemy instances are destroyed before moving on to the next level
The SkeletonList can be used for logic specific to the entity type. Entity-specific logic may include:
Custom logic when performing collision, such as applying a status effect to the player when colliding with a skeleton
Playing sound effects or music if a particular entity type exists, such as a bone rattling sound every few seconds if the screen contains any skeletons
Announcing if an enemy raid has ended once the player has defeated all enemies of a particular type
Keep in mind that all of the entity-specific logic listed above can be performed by using the is keyword and checking for specific types. Of course, this can be slower than checking if a list is empty.
