• Home
• Felgo
• EntityBase

EntityBase

The base class for custom game entities. More...

• List of all members, including inherited members

Properties

• collidersActive : bool
• entityId : string
• entityType : string
• poolingEnabled : bool
• preventFromRemovalFromEntityManager : bool
• toStoreProperties : variant
• variationType : string

Signals

• entityCreated()
• entityDestroyed()
• movedToPool()
• usedFromPool()

Methods

• getComponent(objectName)
• isOfType(type)
• removeEntity()

Detailed Description

The EntityBase component is the base class for all game entities in a Felgo game. It is a container of other components for the game logic, visual representation, physics or audio components. Entities are used together with the EntityManager, which handles creation, removal and receiving of entities.

The EntityBase has 2 major properties: entityType and entityId.

Entity Type

The entityType property is the same for all entities of the same EntityBase, i.e. for all EntityBase instances. In contrast, the entityId is unique for each entity. The entityType property is useful e.g. for collision detection, when you would like to know with which kind of entity you collided with.

If you never need to make any decisions in your game logic based on the entityType, you do not need to set it. However, it is considered good practice to always define an entityType, because the type shows up in the debug outputs and thus makes the application flow easier to follow.

Variation Type

In some cases, the entityType might not be sufficient to distinguish between entities. One such case is when you define an EntityBase and provide properties for the outside that define what kind of entity it is. E.g. a stronger version with more health than the default entity version, but with the exact same code except this property modification. To distinguish between these "variations" of the same entityType without having to copy existing QML code, the variationType property is available.

It serves as the "extended type" of an entity. Consider the following example:

Enemy.qml:

 EntityBase {
     entityType: "enemy"
     variationType: "defaultEnemy"

     property int health: 100
 }

VariationTypeMain.qml:

 Item {
   Enemy {
       x:100
       y: 100
       // the variationType will be defaultEnemy, health is 100
   }

   Enemy {
       x: 200
       y: 100
       // make this enemy stronger - to be able to distinguish them at a collision
       health: 200
       variationType: "strongEnemy"
   }
 }

So with the variationType set to strongEnemy, a call of isOfType("strongEnemy") will only return true for the second entity. Whereas isOfType("enemy") returns true for both, the defaultEnemy and strongEnemy variations.

Entity Id

Every entity in a game has a unique entityId, which helps in distinguishing them and finding them from the EntityManager. If you do not set an entityId explicitly, it will automatically be generated from the EntityManager. The auto-generated entityId string is the entityType concatenated with the variationType and the current number of created entities in EntityManager.

The entityId is different than the QML id property in several ways. First, the QML id is only available within the same QML file where it was assigned and in their children components. Thus it does not allow you to access dynamically created entities which is possible with the entityId property. The type of the entityId is a String, compared to the typeless id property.

You can access other entities by their id property like in this example:

 Item {
   EntityBase {
       id: player1 // for access within the same QML file
       entityId: "player1" // for dynamic access with entityManager.getEntityId()
   }

   EntityBase {
       id: player2
       entityId: "player2"
   }
 }

However, this approach is not sufficient when you create entities dynamically at runtime, because you can only set id for entities declared in QML files. For that purpose, you can use the EntityManager function EntityManager::getEntityById().

The entityId is also useful for collision detection. E.g. if you want to handle collisions between 2 entity types, but only for a specific entityId.

Entity Creation And Removal with EntityManager

You can create and destroy entities at runtime with the EntityManager. Here is an example of a simple entity that consists of a simple (non-animated) Image.

 import Felgo
 import QtQuick

 GameWindow {

     EntityManager {
         id: entityManager
         entityContainer: scene
     }

     Scene {
         id: scene

         EntityBase {
             id: boxEntity
             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(
                             boxEntity,
                             newEntityProperties);
             }
         }
     }
 }

In this example, the entity was defined within the same QML file like the GameWindow and Scene. It is good practice, to write entity definitions in an own QML file. That has the advantage that it is logically separated from other code. So instead of having a single file EntityTestMain.qml, we split the previous example into 2 files:

Box.qml:

 import Felgo
 import QtQuick

 EntityBase {
     id: boxEntity
     // the entityId will be set from outer components!
     entityType: "box"

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

and EntityTestMain.qml:

 import Felgo
 import QtQuick

 GameWindow {

     EntityManager {
         id: entityManager
         entityContainer: scene
     }

     Scene {
         id: scene

         Box {
             id: boxEntity
             entityId: "box1"
         }

         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.createEntityFromUrlWithProperties(
                             Qt.resolvedUrl("entities/Box.qml"),
                             newEntityProperties);
             }
         }
     }
 }

Note: the entity creation from the entityManager is done differently now, as we are creating a new entity from a qml file. Thus we are using EntityManager::createEntityFromUrlWithProperties.

Entity Pooling

You can use entity pooling to increase the performance of your game. Usually, a call of removeEntity() or one of the removal functions in EntityManager like EntityManager::removeEntityById() immediately destroy the entity from memory. This has the advantage that memory consumption is at a minimum. However, creating entities during the game may be a very slow operation, depending how complex your entity is. That means, the more components you have as children of the entity, the longer the creation takes, which can build up to tens of milliseconds. This creation process would then stall the game and produce a perceived slowlyness of your game.

To prevent this performance drain at creating new entities, you can use entity pooling. Entity pooling does not immediately destroy the entity after a call to removeEntity(), but instead just marks it as invisible. When an entity of the same entityType should be created later with EntityManger::createEntityFromUrl() or similar creation functions, the invisible entity is reused. Thus there is no negative performance impact of creation. So with pooling, you trade higher memory consumption for better runtime performance.

To enable entity pooling, both the EntityManager::poolingEnabled and the poolingEnabled property of the entity must be enabled. If you want to prevent some entities from being pooled, you can leave the default setting of poolingEnabled, which is false.

The best strategy to gain maximum performance is to enable entity pooling for all entity types that get removed and created frequently. To make sure there already are pooled entities available when the user first starts the game, you can pre-create pooled entities with EntityManager::createPooledEntitiesFromUrl() or EntityManager::createPooledEntitiesFromComponent().

Entity Pooling Example

See this example how to pre-create 10 entities at game startup, which are then used from the entit pool later in the game:

 import Felgo
 import QtQuick

 GameWindow {

   EntityManager {
     id: entityManager
     // creates the entities in the game scene
     entityContainer: scene

     // enables pooling, also set in the Entity that shall be pooled to true
     poolingEnabled: true

     Component.onCompleted: {
       // creates 10 pooled entities at startup, which are then made invisible
       createPooledEntitiesFromComponent(entityComponent, 10)
     }
   }

   Scene {
     id: scene

     Row {
       spacing: 5

       SimpleButton {
         text: "Create Entitiy"
         onClicked: {
           entityManager.createEntityFromComponentWithProperties(entityComponent, {x: utils.generateRandomValueBetween(0, scene.width), y: utils.generateRandomValueBetween(0, scene.height) })
         }
       }
       SimpleButton {
         text: "Remove Last Added Entity"
         onClicked: {
           entityManager.removeLastAddedEntity()
         }
       }
       // toggle pooling - when disabled, a call of Entity.removeEntity() leads to destruction of the entity
       SimpleButton {
         text: "PoolingEnabled: " + entityManager.poolingEnabled
         onClicked: {
           entityManager.poolingEnabled = !entityManager.poolingEnabled
         }
       }
     }
   }

   // in a real game, make an own qml file out of this and use createEntityFromUrl() instead of createEntityFromComponent()
   Component {
     id: entityComponent
     EntityBase {
       id: poolingTestEntity
       entityType: "poolingTest"

       // enable this entity type for pooling (also set EntityManager::poolingEnabled to true)
       // other entity types might not be set for pooling, thus this needs to be enabled per-entity-type
       poolingEnabled: true

       width: 20
       height: 30

       Rectangle {
         color: "green"
         anchors.fill: parent
       }

       MouseArea {
         anchors.fill: parent
         // click on the rectangle to remove it
         onClicked: poolingTestEntity.removeEntity()
       }

       onEntityCreated: console.debug("entity created with id", entityId)
       onEntityDestroyed: console.debug("entity destroyed with id", entityId)

       Component.onCompleted: console.debug("entity constructor with id", entityId)
       // onDestruction is NOT called when removeEntity is called, because poolingEnabled is set to true
       // this speeds up multiple creation/removal of entities
       Component.onDestruction: console.debug("entity destructor with id", entityId)
     }
   }

 }

Property Documentation

 var entityId = entityManager.createEntityFromUrlWithProperties( Qt.resolvedUrl("entities/MyEntity.qml"), { entityId: "myEntityId"})

 // do NOT query the entityManager with the id "myEntityId" directly
 // because it might have changed the entityId if an entity with the same id already exists to "myEntityId_"
 var entity = entityManager.getEntityById(entityId)

 EntityBase {
   // these properties are modified at runtime, and should be stored when the level is stored
   property int myCustomProperty
   property string myOtherProperty

   toStoreProperties: ["myCustomProperty", "myOtherProperty"]
 }

Signal Documentation

Method Documentation