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.


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
Sign up for Free and start developing right away!
I want to make Games
I want to make Apps
Game Development
Cross-Platform, Any Resolution

Use one IDE to deploy to all supported platforms, including iOS and Android, from a single code base.

Support all screen resolutions, aspect ratios and sizes with auto-adapting UI elements, smart scene scaling and memory efficient asset selection.

Learn More

V-Play ranked #1 at research2guidance cross-platform tool benchmarking 2014 by 2188 developers comparing 40 leading tools.

Multiplayer

V-Play Multiplayer supports both real-time and turn-based gameplay, so you can use it to make many different types of cross-platform multiplayer games. It's perfect for making player-vs-player games like 'Words with Friends' or games for a large amount of players, such as 'Clash of Clans'.

Learn More Video

Highscores & Achievements

The V-Play Game Network is a cross-platform gaming service that allows players around the world to compare game highscores and achievements. Players can also challenge each other across multiple platforms and share their progress on Facebook.

Learn More

QML & JavaScript

Qt Meta Language is a highly intuitive reactive language, which is super easy to learn, yet it's extremely powerful and flexible. Mix it with JavaScript to create awesome stuff, with just a few lines of code.

import QtQuick 2.0
import VPlay 2.0

GameWindow {
  Scene {
    
    SimpleButton {
      anchors.centerIn: parent
      text: "Press Me"
      onClicked: {
        console.debug("Wow you pressed me!")
      }
    }
  }
}

Learn More

Monetize & Analyze

With V-Play, you can use many 3rd party services for ads, in-app purchases, analytics and more, with just a few lines of code. All of these plugins work cross-platform, which allows you to maintain a single code base.

Learn More

Level Editor

The LevelEditor can be used during development to create and modify levels for your game, which you can then bundle in your final publishing build. Additionally, you can also integrate the in-game level editor to your published game and let your gamers create new levels.

Learn More Video

Card Game like UNO, Hearthstone or Poker

We got a demo game for you!

The V-Play SDK includes an open-source demo for this game genre. You can use its source code and build your game in record time. After installing V-Play, you can simply open the .pro file with Qt Creator, the development environment used for V-Play.

<Path to V-PlaySDK>/Examples/V-Play/demos/OneCard/OneCard.pro

Match-3 like Candy Crush Saga

We got a demo game for you!

The V-Play SDK includes an open-source demo for this game genre. You can use its source code and build your game in record time. After installing V-Play, you can simply open the .pro file with Qt Creator, the development environment used for V-Play.

<Path to V-PlaySDK>/Examples/V-Play/demos/JuicySquash/JuicySquash.pro

<Path to V-PlaySDK>/Examples/V-Play/demos/JuicySquashAdvanced/JuicySquashAdvanced.pro

Puzzle like 2048 or Threes!

We got a demo game for you!

The V-Play SDK includes an open-source demo for this game genre. You can use its source code and build your game in record time. After installing V-Play, you can simply open the .pro file with Qt Creator, the development environment used for V-Play.

<Path to V-PlaySDK>/Examples/V-Play/demos/2048/2048.pro

Casino like Big Win Slots

We got a demo game for you!

The V-Play SDK includes an open-source demo for this game genre. You can use its source code and build your game in record time. After installing V-Play, you can simply open the .pro file with Qt Creator, the development environment used for V-Play.

<Path to V-PlaySDK>/Examples/V-Play/demos/FlaskOfRum/FlaskOfRum.pro

Side Scroller like Jetpack Joyride or Flappy Bird

We got a demo game for you!

The V-Play SDK includes an open-source demo for this game genre. You can use its source code and build your game in record time. After installing V-Play, you can simply open the .pro file with Qt Creator, the development environment used for V-Play.

<Path to V-PlaySDK>/Examples/V-Play/demos/FlappyBird/FlappyBird.pro

Tower Defense like Castle Defense or Bloons TD

We got a demo game for you!

The V-Play SDK includes an open-source demo for this game genre. You can use its source code and build your game in record time. After installing V-Play, you can simply open the .pro file with Qt Creator, the development environment used for V-Play.

<Path to V-PlaySDK>/Examples/V-Play/demos/Squaby/Squaby.pro

Falldown & Jump like Doodle Jump or Mega Jump

We got a demo game for you!

The V-Play SDK includes an open-source demo for this game genre. You can use its source code and build your game in record time. After installing V-Play, you can simply open the .pro file with Qt Creator, the development environment used for V-Play.

<Path to V-PlaySDK>/Examples/V-Play/demos/ChickenOutbreak/ChickenOutbreak.pro

<Path to V-PlaySDK>/Examples/V-Play/demos/ChickenOutbreak2/ChickenOutbreak2.pro

<Path to V-PlaySDK>/Examples/V-Play/demos/DoodleJump/DoodleJump.pro

Platformer like Super Mario or Lep's World

We got a demo game for you!

The V-Play SDK includes an open-source demo for this game genre. You can use its source code and build your game in record time. After installing V-Play, you can simply open the .pro file with Qt Creator, the development environment used for V-Play.

<Path to V-PlaySDK>/Examples/V-Play/demos/Platformer/Platformer.pro

<Path to V-PlaySDK>/Examples/V-Play/demos/PlatformerWithLevelEditor/PlatformerWithLevelEditor.pro

Action like Angry Birds, Fruit Ninja, Cut the Rope

We got a demo game for you!

The V-Play SDK includes an open-source demo for this game genre. You can use its source code and build your game in record time. After installing V-Play, you can simply open the .pro file with Qt Creator, the development environment used for V-Play.

<Path to V-PlaySDK>/Examples/V-Play/demos/StackTheBoxWithCommunityEditor/StackTheBoxWithCommunityEditor.pro

<Path to V-PlaySDK>/Examples/V-Play/demos/BalloonPop/BalloonPop.pro

<Path to V-PlaySDK>/Examples/V-Play/demos/CarChallenge/CarChallenge.pro

Arcade like Arkanoid or Space Invaders

We got a demo game for you!

The V-Play SDK includes an open-source demo for this game genre. You can use its source code and build your game in record time. After installing V-Play, you can simply open the .pro file with Qt Creator, the development environment used for V-Play.

<Path to V-PlaySDK>/Examples/V-Play/demos/ZombieBreak/ZombieBreak.pro

Community like Super Mario Maker or Minecraft

We got a demo game for you!

The V-Play SDK includes an open-source demo for this game genre. You can use its source code and build your game in record time. After installing V-Play, you can simply open the .pro file with Qt Creator, the development environment used for V-Play.

<Path to V-PlaySDK>/examples/Squaby/Squaby.pro

<Path to V-PlaySDK>/Examples/V-Play/demos/StackTheBoxWithCommunityEditor/StackTheBoxWithCommunityEditor.pro

<Path to V-PlaySDK>/Examples/V-Play/demos/PlatformerWithLevelEditor/PlatformerWithLevelEditor.pro

Any other Idea? let us know how we can help you

You are looking for another demo?

The V-Play SDK includes many open-source demos for different game genres. You can use their source code and build your game in record time. After installing V-Play, you can simply open the .pro file with Qt Creator, the development environment used for V-Play.

If you do not find your game genre in this list and wonder if V-Play is the right choice, just contact us, we are happy to help!

Contact Us

App Development
Better Apps, Less Effort

Develop feature-rich, cross-platform mobile apps from a single code base.

V-Play apps look, feel and perform exactly like native iOS, Android and Desktop apps. With less code & much faster development time.

Learn More Highlights Video

V-Play ranked #1 at research2guidance cross-platform tool benchmarking 2014 by 2188 developers comparing 40 leading tools.

Save Time, Code & Money

Save up to 90% source code with V-Play, compared to frameworks like Xamarin, Titanium, React Native and others.

Learn More

QML & JavaScript

Qt Meta Language is a highly intuitive reactive language, which is super easy to learn, yet it's extremely powerful and flexible. Mix it with JavaScript to create awesome stuff, with just a few lines of code. QML also allows you to easily create smooth and complex animations.

import QtQuick 2.0
import VPlayApps 2.0

App {
  Page {
    
    AppButton {
      anchors.centerIn: parent
      text: "Press Me"
      onClicked: {
        console.debug("Wow you pressed me!")
      }
    }
  }
}

Learn More

Monetize & Analyze

With V-Play, you can use many 3rd party services for ads, in-app purchases, analytics and more, with just a few lines of code. All of these plugins work cross-platform, which allows you to maintain a single code base.

Learn More

Native Sensors & More

V-Play Apps harness the power of Qt, the leading cross-platform development framework used by over 1,000,000 developers.

This gives your access to native device features like sensors, camera, file system as well as multimedia, networking, localization and much more.

Learn More

Responsive Design

V-Play has built in responsive design capabilities, you can target phones and tablets with the same source code.

Learn More

Highly Extensible

You have existing JavaScript, C++ or native code? You want to add any 3rd party SDK that we do not offer already?

No worries, you can add any JS, C++, Java or Objective-C code to your project.

Learn More

Component Showcase App shows the most important V-Play features and components

We got a demo app for you!

The V-Play SDK includes an open-source demo for this app type. You can use its source code and build your app in record time. After installing V-Play, you can simply open the .pro file with Qt Creator, the development environment used for V-Play.

<Path to V-PlaySDK>/Examples/V-Play/appdemos/showcase/Showcase.pro

Qt World Summit Conference App a full-featured conference management app made by V-Play

We got a demo app for you!

The V-Play SDK includes an open-source demo for this app type. You can use its source code and build your app in record time. After installing V-Play, you can simply open the .pro file with Qt Creator, the development environment used for V-Play.

<Path to V-PlaySDK>/Examples/V-Play/appdemos/qtws2016/QtWS2016.pro

Twitter App how to build layouts like in the official Twitter app for iOS and Android

We got a demo app for you!

The V-Play SDK includes an open-source demo for this app type. You can use its source code and build your app in record time. After installing V-Play, you can simply open the .pro file with Qt Creator, the development environment used for V-Play.

<Path to V-PlaySDK>/Examples/V-Play/appdemos/twitter/Twitter.pro

Maps App displays free bikes or boxes at bike stations for Vienna's bike sharing service Citybike Wien

We got a demo app for you!

The V-Play SDK includes an open-source demo for this app type. You can use its source code and build your app in record time. After installing V-Play, you can simply open the .pro file with Qt Creator, the development environment used for V-Play.

<Path to V-PlaySDK>/Examples/V-Play/appdemos/maps/Maps.pro

Messaging App demonstrates how to create the UI of a Facebook Messenger like app

We got a demo app for you!

The V-Play SDK includes an open-source demo for this app type. You can use its source code and build your app in record time. After installing V-Play, you can simply open the .pro file with Qt Creator, the development environment used for V-Play.

<Path to V-PlaySDK>/Examples/V-Play/appdemos/messaging/Messaging.pro

Weather App how to include powerful animations into your user interface

We got a demo app for you!

The V-Play SDK includes an open-source demo for this app type. You can use its source code and build your app in record time. After installing V-Play, you can simply open the .pro file with Qt Creator, the development environment used for V-Play.

<Path to V-PlaySDK>/Examples/V-Play/appdemos/waether/Weather.pro

Any other Idea? let us know how we can help you

You are looking for another app demo?

The V-Play SDK includes many open-source demos for different app types. You can use their source code and build your app in record time. After installing V-Play, you can simply open the .pro file with Qt Creator, the development environment used for V-Play..

If you do not find your app type in this list and wonder if V-Play is the right choice, just contact us, we are happy to help!

Contact Us