Developer Guide (Version 1.12)

Entity Pool Definitions

The Entity system is currently on a path to deprecation in favor of the Lumberyard Component Entity System.

Entity pools must be defined in the file \Game\Scripts\Entities\EntityPoolDefinitons.xml. An entity pool definition is responsible for defining the following:

  • the empty class that will be used by entity containers when they're not in use

  • the entity classes mapped to the pool

  • other properties that describe the pool and how it is used.

In general, a pool is initially filled with a defined number of entity containers; that is, empty CEntity classes with all the required entity proxies and game object extensions that are normally created when an entity belonging to an entity class mapped to the definition is fully instantiated. For example, a normal AI entity will have the following entity proxies: sound extension, script extension, render extension, and the game object as its user extension; as its game object extension, it will have the CPlayer class. All of these classes are instantiated for each empty CEntity instance, and is reused by the entities as they are created from the pool.

The following illustrates an entity pool definition:

EntityPoolDefinitions.xml <Definition name="AI" emptyClass="NullAI" maxSize="16" hasAI="1" defaultBookmarked="0" forcedBookmarked="0"> <Contains> <Class>Grunt</Class> <Class>Flyer</Class> </Contains> </Definition>

Empty Class

The empty class is defined using the emptyClass attribute, which takes the name of a valid entity class. The purpose of the empty class is to:

  • satisfy the engine's requirement to have an entity class associated with an entity at all times; an empty container is initialized/reused to this entity class

  • prepare all needed entity proxies and game object extensions needed for the entities

For example, building on the definition shown in the previous section, you would create an empty class called "NullAI" and register it the same way as the other AI classes above. Then:

  1. Declare the entity class and map it to its Lua script via the game factory.

    GameFactory.cpp REGISTER_FACTORY(pFramework, "NullAI", CPlayer, true);
  2. Create the Lua script for it. View sample code at \Game\Scripts\Entities\AI\NullAI.lua.

These steps will allow Lumberyard to see "NullAI" as a valid entity class. In addition, by mapping CPlayer to it, you ensure that the correct game object extension is instantiated for the entity containers. The Lua script needs to create all the entity proxies for the entity containers. In the sample code, a render proxy is created, even though we aren't loading an asset model for this entity. For more details, see the discussion of entity pool signatures in Entity Pool Creation.

Entity Class Mapping

In an entity pool definition file, the <Contains> section should include maps to all the entity classes that an entity must belong to when it is created through this pool. You can map as many as you want by adding a new <Class> node within this section. It is important that each entity have the same dynamic class hierarchy as the empty class when fully instantiated. See Debugging Utilitiesfor useful debugging tools to verify that this is the case.

Other Properties

An entity pool definition can define the following additional properties.


Unique identity given to an entity pool, useful for debugging purposes. The name should be unique across all definitions.


Largest pool size this pool can reach. By default, this is also the number of entity containers created to fill the pool when loading a level. This value can be overwritten for a level by including an EntityPools.xml file inside the level's root directory. This file can only be used to decrease the number of entity containers created per pool; it cannot exceed the maxSize value defined here. This is useful when you need to reduce the memory footprint of the entity pools per level. The following example file adjusts the size of an AI entity pool to "2".

LevelEntityPools.xml <EntityPools> <AI count="2" /> </EntityPools>

Boolean value that indicates whether or not the entity pool will contain entities that have AI associated with them. It is important to set this property to TRUE if you are pooling entities with AI.


Boolean value that indicates whether or not an entity belonging to one of the entity classes mapped to this pool is flagged as "created through pool" (see Creating and Destroying Static Entities with Pools). This flag determines whether or not, during a level load, an entity pool bookmark is created for the entity instead of being instantiated.


Boolean value that indicates whether or not an entity belonging to one of the entity classes mapped to this pool must be created through the pool. This property overrides an entity's "created through pool" flag (see Creating and Destroying Static Entities with Pools).