EntityManager

Manages all entities derived from the EntityBase component. More...

Import Statement: import VPlay 2.0
Inherits:

QtObject

Properties

Methods

Detailed Description

The EntityManager takes ownership of all entities in a game. You can use it for dynamic creation, removal, filtered querying based on entityTypes and accessing based on the EntityBase::entityId.

Add the EntityManager as child of the root GameWindow item to have access to it with the id from all other QML files. Then set the entityContainer property to your game Scene. Use the following as the foundation for a V-Play game:

 import VPlay 2.0
 import QtQuick 2.0

 GameWindow {

   EntityManager {
     id: entityManager
     entityContainer: scene
   }

   Scene {
     id: scene

     // .. all game code goes in here ..
   }
 }

Performance Improvement with Entity Pooling

To increase runtime performance, it is advised to enable entity pooling. See EntityBase::poolingEnabled how to activate and use entity pooling in V-Play.

Example Usage

Dynamic Entity Creation Example

The following example shows how to create an entity with entityType redRectangle, and an entity with entityType greenRectangle. For these entity types to be known to the EntityManager, the dynamicCreationEntityList property contains a list of the available entities. The entities can be defined by using the Component element, or by adding the url to the qml file of the entity.

 import VPlay 2.0
 import QtQuick 2.0
 import "entities" // the RedRectangle.qml is contained in this folder

 GameWindow {

   EntityManager {
     id: entityManager
     entityContainer: scene

     // this property is required to enter all entities that should be loadable dynamically into the level here
     // the entities added here are also the ones that can be created with createEntityFromEntityTypeAndVariationType()
     dynamicCreationEntityList: [
       greenEntityComponent,
       Qt.resolvedUrl("entities/RedRectangle.qml")
     ]
   }

   Component {
     id: greenEntityComponent

     EntityBase {
     // this entityType can be used for createEntityFromEntityTypeAndVariationType()
       entityType: "greenRectangle"

       Rectangle {
         width: 100
         height: 50
         color: "green"
       }
     }
   }

   Scene {
     id: scene

     // this is a statically defined entity
     // it is not sufficient to create it statically - without setting the dynamicCreationEntityList property in EntityManager, the call of createEntityFromEntityTypeAndVariationType() below would not work!
     RedRectangle {
       x: 70
       y: 40
     }

     Column {

       SimpleButton {
         text: "Add green RectangleEntity"
         onClicked: {
           entityManager.createEntityFromEntityTypeAndVariationType( {entityType: "greenEntity"} )
         }
       }

       SimpleButton {
         text: "Add red RectangleEntity"
         onClicked: {
           entityManager.createEntityFromEntityTypeAndVariationType( {entityType: "redEntity"} )
         }
       }
     }// Column

   }// Scene

 }// GameWindow

Property Documentation

dynamicCreationEntityList : variant

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.

Note: It is important that the components added in this list never get removed, because otherwise the component would not be accessible any more. So make sure to not destroy the qml file where you put your component definitions!

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().


entityContainer : variant

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 VPlay 2.0
 import QtQuick 2.0

 GameWindow {

   EntityManager {
     id: entityManager
     entityContainer: scene
   }

   Scene {
     id: scene

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

poolingEnabled : bool

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.


Method Documentation

createEntityFromComponent(component)

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.


createEntityFromComponentWithProperties(component, properties)

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 VPlay 2.0
 import QtQuick 2.0

 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.


createEntityFromEntityTypeAndVariationType(properties)

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().

Note: It is NOT sufficient, to create a "static entity" before. A static entity is an entity defined directly in a QML file. So this function only works for entityTypes that got created at least once dynamically before.

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.


createEntityFromUrl(entityUrl)

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.


createEntityFromUrlWithProperties(entityUrl, properties)

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.


createPooledEntitiesFromComponent(component, amount)

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.


createPooledEntitiesFromUrl(url, amount)

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.


getEntityArrayByType(entityType)

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

See also EntityBase::entityType.


getEntityById(entityId)

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.


getLastAddedEntity()

Returns the last entity that was created with the EntityManager.


removeAllEntities()

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.


removeAllPooledEntities()

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.


removeEntitiesByFilter(toRemoveEntityTypes)

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);

removeEntityById(entityId)

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.


removeLastAddedEntity()

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.


storeEntitiesAsJson(toStoreEntityTypes)

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().


storeEntitiesAsJsonWithProperties(toStoreEntityTypes, toStorePropertiesForAllEntities)

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.


Videos

Voted #1 for:

  • Easiest to learn
  • Most time saving
  • Best support

Develop Cross-Platform Apps and Games 50% Faster!

  • Voted the best supported, most time-saving and easiest to learn cross-platform development tool
  • Based on the Qt framework, with native performance and appearance on all platforms including iOS and Android
  • Offers a variety of plugins to monetize, analyze and engage users
FREE!
create apps
create games
cross platform
native performance
3rd party services
game network
multiplayer
level editor
easiest to learn
biggest time saving
best support