Game Structure

There are a few objects types that make up the Platypus engine. What are they and how do they work? Glad you asked!

Game

The Game object is the root object used when creating a game with the Platypus Engine. There should only be one game object. It is created in /engine/main.js once all the assets are loaded. The game object receives ticks from the CreateJS timer which it passes on to the scene. The game handles loading the scene object and transitioning between scenes. The first scene that the game will load as well as other global game settings are set in a configuration file (see Create Config JSON).

Scene

Scenes created from the Scene class are the next object in the hierarchy of the game. Scenes are best thought of as the mutually exclusive phases of the game (e.g. main menu, gameplay, etc.). There is only one scene active at a time and when a scene is not active, it is unloaded. A scene contains one or more layers and sends a ‘tick’ to each layer when it receives a ‘tick’ from the game. Scene definitions consist of a list of layer entities. These layers will load or not depending on the filters in the layer definition (see the Layer section below for more information).

Examples of scene definitions can be found in game/scenes/ . For more on making a scene, check out Create A Scene.

Entity

Entities created from the Entity class make up the rest of the game structure. Entities are objects that contain a collection of components. The entity object does very little other than bind the components together and handle communication between them. The entity broadcasts any messages it receives to all of its components.

Examples of entity definitions can be found in /game/entities/. Check out Create-An-Entity for more information.

Components

Components make up the functionality of an entity. Components of an entity each handle discrete portions of functionality that make up the entity. Components communicate with each other by sending messages to the entity, which redistributes them.

Examples of components include camera, change-scene, logic-gravity, and render-sprite. See the full listing of components in the Component Reference.

Layer

Layers are a category of entities that have a common component structure and are designed to contain other entities. Layers are contained in the Scene and act as the third layer in the hierarchy of the game. Layers contain an entity-container component to hold the entities added to the layer and one or more handler components that ‘handle’ processes such as rendering, collision, etc. The layer entity receives the tick from the scene and passes it to all of its components. Note that the components receive the tick in the order they are listed in the layer’s JSON definition. This is important because you may want certain processes (e.g. logic) to happen before others (e.g. rendering).

Layer definitions are unique in that they include a ‘filter’. The filter determines whether a layer entity will load when the scene is created. This is used to load certain layers based on the browser that is being used (e.g. we load a multi-touch interface when the user’s browser supports it). The filtering system uses ‘includes’ and ‘excludes’ parameters set in engine/browser.js to determine whether the layer should be loaded. If the current browser matches at least one of the items in the layer entity ‘includes’ parameters and doesn’t match any of the ‘excludes’ parameters, that layer entity is added to the scene.

Examples of layer definitions include can be found in embedded in scene definitions like game/scenes/menu.json and included separately as unique entity definitions in game/entities/ such as action-layer.json, desktop-interface-layer.json, multitouch-interface-layer.json, and touch-interface-layer.json.

Handler

Handlers are components that regulate the functionality of an entity (e.g. making sure all the logic components are updated). When an entity is added to a layer, handlers receive notice of the new entity and check to see if it accepts certain messages that the handler controls. If so, the handler keeps a reference of the entity to communicate with it later. The order of the handlers in the layer entity definition determine the order in which they receive ticks.

An example of a handler is handler-render-createjs. The handler-render component looks for entities that accept the ‘handle-render’ and ‘handle-render-load’ messages. If an entity does, this handler keeps an internal reference to the entity. Then, each time the handler-render component receives a tick from the layer, it sends a ‘handle-render’ message to the entities for which it has a reference.

Other examples of handlers include the handler-logic and handler-controller components.