Concept Graph

Actors & Controllers

An Actor is an Entity able to take initiative on her own i.e., her course of action is not described in the game logic.

For each Actor, there is a single corresponding Controller, choosing her actions.
There is a variety of Controller implementations such as Mouse/Keyboard, Random and Machine Learning Ai.

The behaviour of the Controller depends on its implementation; however, controllers can be configured with metadata.


A Being is an Entity that does not have will on its own, i.e. it cannot take initiative.

Beings can be created (and destroyed):

  1. During the game start phase
  2. At any given step as an impact of an action performed by an Actor.

The Scene

The Scene (singleton) is the Entity that contains the Actors and the Beings.


The Actors, the Beings and the Scene are the Entities.

Entities have:

  • Attributes: Data that are part of the game logic
  • Metadata: Data that are not part of the game logic
    • They are instructions for the Renderer, the Controllers and other mechanisms outside the game logic
    • Game logic is only able to write metadata but not read them back

Example attributes would be: the utility of an actor, the price of an object, the position of a creature in the world.
Example metadata would be: the picture or 3D model to render, the position in the screen, a heuristic function to be used by an Ai Controller.

Furthermore, each entity has a Unique ID.

Take Actions
Create in-game

Summary of the three entity types.

Actions & Impacts

Unlike real life where our actions are unrestricted and our choices are boundless, in games there are rules restricting Actors to a specific set of actions and choices.

To describe an action, answer the following questions.

  1. When is an action available and for which Actors?
  2. Which choices do you have to make?
  3. What will be the impact of this action?

Note: Satisfying the "when" constraint does not mean you have to perform the action; it merely means that you can.

Example Action

Here is an example code for a simple action.

This action has 2 impacts:

  1. Update the Actor
  2. Update the CoffeeShop


Metadata are arbitrary data that can be attached to Entities, actions and other game elements.

Game logic is able to write metadata but is not able to read them back.
Other components such as the renderer and the controllers can read and also write metadata.

metadata graph

Metadata provide a mechanism for components to store information and communicate in a way that is guaranteed to not interfere with game logic.


Worlds are different environments where the Scene may unfold, such as planets, mazes, networks, economic environments.

Check the worlds' documentation for more.

GameRunner & Game Execution

A prominent component of the engine is the GameRunner. The GameRunner is responsible for:

  • Starting the game
  • Communicating with the Controllers
  • Performing action impacts
  • Determining when the game has ended

Game execution goes through 3 phases: Start, Running, End.


When the game starts, the GameRunner performs the start impacts.
Start impacts are like action impacts only they are performed once when the game starts.

Overall, during game start, the following steps take place:

  1. Create declared actors
  2. Perform start impacts
  3. Create controllers and connect them with their actors


While the game is running -on every game step- the following steps take place:

  1. Check which actors have available actions
    1. If any actor has an available action: Prompt their controllers to act
    2. else: Game End
  2. Receive the selected action and choices from the controllers and validate them
  3. Perform the impacts of the selected action (if validation succeeded)
  4. Repeat from step 1


The game ends when no actor has an available action.

Note: If a world is loading, then GameRunner will wait for it to load before checking for game over.

Game Flow Chart

An example game

Let's see the elements of the game Tic-Tac-Toe.


The game will have 2 actors:

  1. X Player
  2. O Player


The game will have 9 beings: the 9 squares.


The only action an Actor can take is "Mark Square".

Constraint: It's the Actor's turn and we don't yet have a winner.

Choice: A square that is empty


  1. Mark the chosen square with the Actor's mark
  2. Determine if there is a winner
  3. Set the turn to the next actor (if there is no winner)

Game End

The game ends when no actor has available actions.

  • If an actor wins, the game will end because the action "Mark Square" will not be available (by definition).
  • If all the squares are marked, the game will end because the action "Mark Square" will not have available choices and therefore will not be available.