Menu
Lumberyard
Developer Guide (Version 1.12)

Entity Pool Creation

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

When loading a level, an entity pool is created for each entity pool definition. On creation, the pool is filled with empty containers (instances of CEntity using the emptyClass attribute value as the entity class. These empty containers come with some expectations that must be satisfied:

  • Containers should be minimal in size. This means you should not load any assets or large amounts of data into them. For example, in the sample Lua script (\Game\Scripts\Entities\AI\NullAI.lua), the NullAI entity does not define a character model, animation graph, body damage definition, etc.

  • Containers should have the same entity proxies and game object extensions created for them as compared to a CEntity fully instantiated using each of the mapped entity classes.

Once the pool is created, an entity pool signature is generated using one of the empty containers. An entity pool's signature is a simple container that maps the dynamic class hierarchy of an entity.

One of the functions of the entity pool system is to avoid as much as possible dynamic allocation for delegate classes used by entities. Key examples of these are the entity proxies and game object extensions used by entities. When an entity pool's empty containers are first created, the delegate classes that will be used by the real entities contained in them are also supposed to be created. To ensure that this is the case, the entity pool signature is used. It works as follows:

  1. A TSerialize writer is created. It is passed to each entity proxy and game object extension that exists in the entity.

  2. Each proxy and extension is expected to write some info to the TSerialize writer. This information should be unique.

  3. Two signatures can then be compared to see if they contain the same written information, verifying they contain the same dynamic class hierarchy.

All of the entity proxies have already been set up to write their information to the TSerialize writer. However, if you create a new game object extension (or a new entity proxy), then you will need to set the class up to respond to the Signature helper when needed. To do this, implement the virtual method (Entity Proxy: GetSignature; Game Object Extension: GetEntityPoolSignature) and write information about the class to the TSerialize writer. Generally, all that is needed is to just begin/end a group with the class name. The function should then return TRUE to mark that the signature is valid thus far.

CActor::GetEntityPoolSignature Example bool CActor::GetEntityPoolSignature( TSerialize signature ) { signature.BeginGroup("Actor"); signature.EndGroup(); return true; }

The section Debugging Utilities discusses how to view the results of entity pool signature tests in order to verify that everything is working as expected.