EntityManager

An array of components of entities and urls to entities that should be create-able with createEntityFromEntityTypeAndVariationType(). That means all entities added here, can be created by just providing the entityType and an optional variationType.

This property is also important for the LevelEditor component: only entities that are entered in this list can be stored and loaded dynamically from a level file.

An example value is

 dynamicCreationEntityList: [
   greenEntityComponent,
   Qt.resolvedUrl("entities/RedRectangle.qml")
 ]

For a complete example how to use this property, see the Dynamic Entity Creation Example.

See also createEntityFromEntityTypeAndVariationType().

This is a required property that specifies which QML item is the parent of the entities that get created with EntityManager. Typically, this will be the Scene item.

Here is an example:

 import Felgo
 import QtQuick

 GameWindow {

   EntityManager {
     id: entityManager
     entityContainer: scene
   }

   Scene {
     id: scene

     EntityBase {
       entityType: "box"
       Image {
         source: "../assets/img/box.png"
       }
     }
   }
 }

Set this property to enable entity pooling. Entity pooling means, that entities do not get removed from memory when you call removeEntityById() or EntityBase::removeEntity(), but are used for later and get set to invisible.

You need to mark each entity that should be pooled explicitly by setting the EntityBase::poolingEnabled property to true. By default, pooling is disabled. However, it is highly recommended you use entity pooling, especially when you are dynamically creating and removing many entities during your game.

Creates an entity from the given component and returns the entityId of the created entity. The component is a derived EntityBase item. This function is preferable over createEntityFromUrl() when you do not have the entity definition in a separate QML file but within the same file.

If you want to access the entity after creation, use getEntityById(). For removal use removeEntityById().

See also createEntityFromComponentWithProperties.

Creates an entity from the given component and returns the entityId of the created entity. The component is a derived EntityBase item. This function is preferable over createEntityFromUrlWithProperties() when you do not have the entity definition in a separate QML file but within the same file.

Consider the following example:

 import Felgo
 import QtQuick

 GameWindow {

     EntityManager {
         id: entityManager
         entityContainer: scene
     }

     Scene {
         id: scene

         Componet {
             id: boxEntityComponent
             EntityBase {
                 entityId: "box1"
                 entityType: "box"

                 Image {
                     source: "../assets/img/box.png"
                 }
             }
         }

         MouseArea {
             anchors.fill: parent
             onClicked: {
                 // if you click the scene, a new entity is created
                 var newEntityProperties = {
                     x: Math.random()*scene.width,
                     y: Math.random()*scene.height,
                     rotation: Math.random()*360
                 }

                 entityManager.createEntityFromComponentWithProperties(
                             boxEntityComponent,
                             newEntityProperties);
             }
         }
     }
 }

If you want to access the entity after creation, use getEntityById(). For removal use removeEntityById().

See also createEntityFromUrlWithProperties.

Creates an entity from the EntityBase::entityType value and an optional EntityBase::variationType value in the properties map. For this method to succeed, a dynamic entity must have been created before, either with createEntityFromUrl() or createEntityFromComponent().

The properties map requires a string value for the entityType key, and an optional variationType value.

This is an example how to create an entity with a variation

The following example shows how to create an entity with entityType waypoint, and an entity with entityType obstacle and variationType pillow. For these entities to be known, they must have been registered in the dynamicCreationEntityList property.

 createEntityFromEntityTypeAndVariationType( {entityType: "waypoint"} );
 createEntityFromEntityTypeAndVariationType( {entityType: "obstacle", variationType: "pillow"} );

For a complete example how to use this method, see the Dynamic Entity Creation Example.

See also dynamicCreationEntityList.

Creates an entity from the given entityUrl and returns the entityId of the created entity. The entityUrl must be the full path to the entity, so use Qt.resolvedUrl() for that.

For example this creates an entity in the entities folder, called from the main directory:

 entityManager.createEntityFromUrl(Qt.resolvedUrl("entities/Box.qml"));

If you want to set properties to the entity at creation (like the x and y position), use createEntityFromUrlWithProperties().

If you want to access the entity after creation, use getEntityById(). For removal use removeEntityById().

See also createEntityFromUrlWithProperties and createEntityFromComponent.

Creates an entity from the given entityUrl and returns the entityId of the created entity. The entityUrl must be the full path to the entity, so use Qt.resolvedUrl() for that.

For example this creates an entity in the entities folder at position 100/50, called from the main directory:

 entityManager.createEntityFromUrlWithProperties(Qt.resolvedUrl("entities/Box.qml"), {"x": 100, "y": 50});

If your entities have a variationType, specify it in the properties.

If you want to access the entity after creation, use getEntityById(). For removal use removeEntityById().

See also createEntityFromComponentWithProperties.

Use this function for creating amount pooled entities. This amount will immediately be removed and is thus usable for pooling later.

This is useful if you want to improve the performance by avoiding entity creation at runtime, but instead pre-create the entities when the level is loaded. You could call this function for example in Component.onCompleted() of your Game Scene.

Use this function for creating amount pooled entities. This amount will immediately be removed and is thus usable for pooling later.

This is useful if you want to improve the performance by avoiding entity creation at runtime, but instead pre-create the entities when the level is loaded. You could call this function for example in Component.onCompleted() of your Game Scene.

Returns an array of entities with the provided entityType or an empty array if no entity with the entityType exists.

See also EntityBase::entityType.

Returns the entity if the entityId could be found or undefined if the entityId was not found. The entityId is a unique string in the EntityManager also used for the objectName.

See also EntityBase::entityId.

Returns the last entity that was created with the EntityManager.

Remove all entities except the ones with EntityBase::preventFromRemovalFromEntityManager set. If poolingEnabled is set, all entities that have their EntityBase::poolingEnabled property set do get moved to the entity pool.

Destroys all pooled entities from memory. This only makes sense when poolingEnabled is set to true.

This function can be used to delete all pooled entities, if memory gets low.

Remove all entities with the EntityBase::entityType or EntityBase::variationType contained in the toRemoveEntityTypes array.

All entities in the EntityManager get called their EntityBase::isOfType() function with the types added in the toRemoveEntityTypes array.

For example use the following code to remove all rocket and mine entityTypes:

 var toRemoveEntityTypes = ["rocket", "mine"];
 entityManager.removeEntitiesByFilter(toRemoveEntityTypes);

Removes the entity with the provided entityId from the EntityManager and uses the entity for pooling based on the poolingEnabled property.

The EntityBase::entityDestroyed signal will be emitted when this function is called.

Alternatively, the EntityBase::removeEntity() function can be called, which is internally calling this function for convenience.

Note: If the EntityBase::preventFromRemovalFromEntityManager is set, a call of removeEntityById() will not have any effect!

See also EntityBase::entityId and EntityBase::removeEntity.

Removes the last created entity with createEntityFromUrl() or createEntityFromComponent().

Use this function only if you know that the last created entity is safe to be removed.

Returns a JSON map of all entities, with the entityId as index and the following data: entityType, entityId, x, y, variationType. If toStoreEntityTypes is provided as an array containing the entityTypes (or variationTypes) to store, only the entities where isOfType() returns true are returned. If no toStoreEntityTypes is provided, all entities get stored.

toStoreEntityTypes must be an array, e.g. ["choco", "teddy"].

An example of the returned map would be:

 { choco_0: {entityType: "obstacle", variationType: "choco", entityId: "choco_0", x: 10, y: 20, rotation: 0 },
   choco_1: {entityType: "obstacle", variationType: "choco", entityId: "choco_1", x: 30, y: 60, rotation: 90 },
   teddy_2: {entityType: "obstacle", variationType: "teddy", entityId: "teddy_2", x: 10, y: 60, rotation: 270 }
 }

The default properties that get stored for all entities are x, y, rotation, entityId, entityType and variationType.

Also, all properties defined in the EntityBase::toStoreProperties array are stored.

Note: You can currently not store the children and their properties of an entity! If you need to store them, you can add the property for the entity and add it to their toStoreProperties array.

Note: If you set the EntityBase::preventFromRemovalFromEntityManager to true, the entity will not be stored as it is considered as a "singleton entity", i.e. it only exists once in the whole game as it is never removed.

If you want to store further properties for all entities, consider using storeEntitiesAsJsonWithProperties().

It returns undefined, if no entities could be stored because there were no ones found.

See also storeEntitiesAsJsonWithProperties().

Use this function to store an additional set of properties for all entities.

This is handy, when you have some properties that all of your entity types should store. The entities that do not have one of the properties defined in toStorePropertiesForAllEntities array, simply ignore to save it.

An example call looks like the following:

 entityManager.storeEntitiesAsJsonWithProperties( ["choco", "teddy"], ["myProperty"] );

See also storeEntitiesAsJson.