Menu
Lumberyard
Developer Guide (Version 1.11)

Entity Pool System

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

The topics in this section describe the entity pool system, including how it is implemented, how to register a new entity class to be pooled, and how to debug it. For more information on using entity pools in the Lumberyard Editor, see the Amazon Lumberyard User Guide.

This section includes the following topics:

The following processes must take place when creating an entity pool and preparing it for use. Each of these processes is described in more detail.

  1. An entity pool is created by using the information in an entity pool definition.

  2. An entity pool is populated with entity containers.

  3. An entity pool is validated by testing the entity pool signature of one of the entity containers against the entity pool signature of each Entity class mapped to the pool.

  4. All entities marked to be created through the pool have an entity pool bookmark created for them.

  5. An entity pool bookmark is prepared from or returned to the entity pool, which is mapped to its Entity class on demand.

Editor Usage

When running in the Lumberyard Editor, the entity pool system is not fully enabled. All entities are created outside the pools when playing in-game in the Editor. However, all flow node actions with entity pools will still work in the Lumberyard Editor, mimicking the final results that you will see in-game.

Note

The entity pool listeners OnEntityPreparedFromPool and OnEntityReturnedToPool are still called in the Editor, even though the entity itself is not removed/reused.

Static versus Dynamic Entities

Entities can be either static or dynamic. A static entity is placed in the Editor and exported with the level. This entity always exists. A property associated with the exported information determines whether it should be pooled (and not created during level load) or instead have an entity pool bookmark made for it. A dynamic entity is created at run-time, usually from game code. The information is constructed at run-time, usually just before it is created, and passed on to the Entity system for handling. This information also indicates whether or not it should go through an entity pool.