Setting up the camera

Basic Overview

The Camera component determines what area of the game world that the player sees. In addition, the camera's view port can limit logic and collision processing to make the game run faster and more efficiently.

There are two sets of options that determine how the game appears on the screen and how the in-game camera behaves. The first scope is determined by the global game settings as listed in Create-Config-JSON and the second is set in the camera component's definition.

#Game View Port Settings There are two key fields that will determine how the game view port appears: rootElement and aspectRatio.

##Setting the Game's Root Element The global setting rootElement is an optional string defining the id attribute of the root DOM element. This element will contain all other DOM elements created by the game engine. If a rootElement id is not provided, it is set to “root” and this element is created as a div if it does not already exist.

This element can be styled using CSS to determine the size and shape of the game world and scenes, giving the developer simple control over the size of the game view port. Alternatively, the game engine can use a letter-boxing method if the next property is set.

##Setting the Game's Aspect Ratio The global setting aspectRatio is an optional number determining whether the rootElement above should be automatically resized to maintain a certain aspect ratio. The aspect ratio is width divided by height, so 1.5 will be a game area of 3 units in width for every 2 units in height.

If you don’t set this property and set width and height style to 100%, the game will fill the entire screen, otherwise the desired aspect ratio will be maintained by filling the available screen space to the maximum width or height as necessary.

#Setting up the Camera Component Including the camera component in a Scene layer will look something like this: { "id": "action-layer", "components": [ {"type": "handler-controller"}, {"type": "handler-logic"}, {"type": "collision-group"}, { "type": "camera", "width": 3200 }, {"type": "handler-render-createjs"}, {"type": "tiled-loader"} ] } There are several settings that determine the position and amount of game world shown:

• top and left determine the initial camera position in world coordinates.
• width and height determine how much of the world is visible. Ideally the ratio of width to height will match the aspect ratio set above, otherwise the world may appear stretched. If stretch (below) is set to false, the width will override the height to maintain visibly square world units.
• stretch determines whether the x and y axes can be proportionately different. The default is false, causing width and height settings that are not resolvable to use the width to determine the appropriate height.
• scaleWidth determines at what size in world coordinates that the camera should scale to another pixel multiple. If not set, the game world scales smoothly as the rootElement is resized, but if this value is set, the game world will only scale in size if the rootElement size reaches a multiple of this number. This is primarily useful for pixel art where in-between anti-aliased resolutions may not be preferable.

In the above example, only the width is explicitly set, relying on stretch being a default false to determine the height. The position is also of no concern, because we will be using the Tiled-Loader component to set up the position and behavior of the camera and described below.

##Camera Behavior There are several options that determine the behavior of the camera. The camera has three view modes: "locked", "bounding", and "static".

The default basic mode is "static". While in this mode, the camera is set to show a particular view port position of the world and will not change unless explicitly moved.

The "locked" mode is given an entity to "lock" on. Once set, the camera keeps the chosen entity centered in the view port. Thus, if the entity moves through the world, so does the camera. This mode is useful for top-down or isometric games to keep the hero in the center of the action.

Lastly, the "bounding" mode also follows an entity, but only moves if the chosen entity leaves a given bounding box around the entity. This is useful for 2d platforms where the hero may jump, but the camera shouldn't move up immediately - only if the hero continues to move up beyond the initial jump.

The camera component listens for a follow message on the scene layer to set the mode and follow an entity as described in Camera. One component that broadcasts this message is the Tiled-Loader, if one of the entities it loads has a 'camera' property. For example, we may have a hero that looks something like this: { "id": "hero", "components":[...], "properties":{ "alwaysOn": true, "camera": "bounding" } }

Thus, when the tiled-loader component finds a hero entity spawn point on the map, it also knows to trigger a 'follow' event so the camera will follow the hero entity using the 'bounding' mode once the game begins.

Also of some note in the above example is the 'alwaysOn' property: this setting informs the handler-logic and handler-collision components that this entity's logic and collision components should run even if the entity is outside the collision area. This is covered a bit more thoroughly in All-About-Collision.