Isometric engine

The isometric engine enables you to easily create 'fake 3d' isometric perspective games.

Configuration

The isometric engine has a lot of features which can be configured through a number of options passed to the constructor of the Isometric class.

Examples

• Map: a grid with random areas on it
• Selecting: selecting points, lines or areas
• Drawing: drawing lines on the grid
• Drawing rules: rules for drawing lines on the grid
• Items: putting items on the grid
• Item selecting: Selecting an item
• Path finding: Finding a path with aStar
• Save, load: Saving and loading a map
• Walking: Items walking random paths
• Particles: Particle systems
• Item images: Setting images on dynamic items

Tile conditions

A lot of items test the validity of a move or a draw action; all these checks are done by the Map class. Details about the condition validator can be found here.

Isometric Class

The isometric class wraps the models and views of the isometric engine. It exposes a number of methods and emits events informing the user about state changes.

More details about settings can be found here:

• Grid settings, defining the size of the grid, the size of the tiles and the layers
• Map settings, tile rules, map generating and tile randomization
• Tile settings, configuring the images
• Editor settings, properties defining tools for modifying the grid, links models to tiles
• Item settings, view properties for dynamic items on the grid
• Particle settings, settings for particle systems on the grid

Parameters

• superview {View} ---The view which contains the isometric view.
• gridSettings {object} ---General grid settings like width, height, and number of layers.
• tileSettings {object} ---Definitions for tile images.
• mapSettings {object} = {} ---(Optional) Definitions to generate a map, random images, tile rules.
• editorSettings {object} = {} ---(Optional) Tools for modifying the grid.
• itemSettings {object} = {} ---(Optional) View properties for items on the grid.
• particleSettings {object} = {} ---(Optional) Settings for particle systems on the grid.

Installation

Install the isometric module in your game with devkit install https://github.com/gameclosure/isometric

Usage

import isometric.Isometric as Isometric;

var isometric = new Isometric({
    superview: this,
    gridSettings: gridSettings,
    tileSettings: tileSettings,
    mapSettings: mapSettings
});
isometric.generate();
isometric.show();

Methods

getGridModel()

Get the GridModel instance.

Returns {GridModel} ---GridModel instance.

getStaticModels()

Get the StaticModels instance wich contains a list of all models on the grid with a fixed position.

Returns {StaticModels} ---StaticModels instance.

getDynamicModels()

Get the ModelViewConnection instance which contains a list of dynamic models.

Returns {ModelViewConnector} ---ModelViewConnector instance.

getMap()

Get the Map instance.

Returns {Map} ---Map instance.

setBackgroundColor(backgroundColor)

Set the background color of the grid view. This is only visible through tiles which contain transparent parts.

Parameters

• backgroundColor {string} ---Set the background color.

setTool(tool)

Set the tool. If the tool parameter is false then the grid is put into drag mode If the tool parameter is a string then the value should match one of the keys in the editorSettings.

Parameters

• tool {string|boolean} ---Set the tool.

clear(dontGenerate)

Clear the map.

Parameters

• dontGenerate {boolean} = false ---Don't generate a new map.

putItem(modelType, tileX, tileY, opts)

Put a new static item on the map.

Parameters

• modelType {string} ---This value should match one of the keys in the editorSettings.
• tileX {number} ---The x-position.
• tileY {number} ---The y-position.
• opts {object} ---Constructor opts for the new item.

putDynamicItem(ctor, opts, layer)

Put a new dynamic item on the map.

Parameters

• ctor {DynamicModel} ---A constructor which subclasses DynamicModel.
• opts {object} ---Constructor options, should contain the following properties:
• tileX {number} = 0 ---The x-position.
• tileY {number} = 0 ---The y-position.
• x {number} = 0.5 ---The x-position within the tile.
• y {number} = 0.5 ---The y-position within the tile.
• layer {number} ---The layer to put the model on

refreshMap(tileX, tileY)

Refresh the screen.

Parameters

• tileX {number} ---Optional, the x-position, if not provided then the entire view will be refreshed.
• tileY {number} ---The y-position.

show()

Show the isometic view.

hide()

Hide the isometric view.

hideSelectedItem()

Hide the selected item.

generate()

Start generating a new map, clears the map first. The map is generated based on settings in mapSettings.

toJSON()

Get a JSON object representing the current state of the map. This does not include dynamic items. The data has the following structure:

• grid {object} ---The current position of the viewport:
• tileX {number} ---The x-position.
• tileY {number} ---The y-position.
• x {number} ---The x-position within the tile.
• y {number} ---The y-position within the tile.
• map {object} ---The map data.
• staticModels {array} ---A list of all static models on the map.

Returns {object} ---JSON representing the current state.

fromJSON(data)

Load a map, see toJSON() for the structure.

Parameters

• data {object} ---The previously serialized map.

Events

'Ready', callback()

Called when the map is generated.

'SelectionCount', callback(selected)

The SelectionCount event is emitted while the user is selecting an eara and the size of the area changes. If the area is accepted (the editor condition evaluates to true) then the parameter contains info about the selection.

The data structure of the selected value if the area is accepted is an object with the following properties:

• total {number} ---The total number of tile affected.
• changed {number} ---The number of tiles which will be changed if the selection is applied.
• accept {boolean} = true ---By setting this value to false the cursor will change to the deny state and the action will not be applied to the grid.

Parameters

• selected {boolean|object} ---False or selection info.

'Edit', callback(selected)

This event is emitted when an area on the grid was selected and changed.

The data structure of the selected value has the following properties:

• total {number} ---The total number of tile affected.
• changed {number} ---The number of tiles which will be changed if the selection is applied.
• rect {object} ---An object representing the selected rectangle with the following properties:
• x {number} ---The x-position.
• y {number} ---The y-position.
• w {number} ---The width.
• h {number} ---The height.

'Scrolled', callback()

Called when tileX or tileY changes.

'InputStart', callback(evt)

Called when the grid view is clicked or touched.

'InputEnd', callback(evt)

Published when mouse up, touch up or drag end.

'SelectItem', callback(model)

Called when an item is selected.

Parameters

• model {StaticModel} ---An instance of a StaticModel subclass.

'UnselectItem', callback()

Called when an item was selected and that selection is hidden by clicking somewhere on the grid which is not an item.

'AddStaticModel', callback(model)

Called when a static model was added to the map.

Parameters

• model {StaticModel} ---An instance of StaticModel which was added.

'AddDynamicModel', callback(model, layer)

Called when a dynamic model was added to the map.

Parameters

• model {DynamicModel} ---An instance of DynamicModel which was added.
• layer {number} --- The layer to put the DynamicModel on

'WakeupDynamicModel', callback(model)

Called when a model is activated, the tick function will be called again and when the model is visible a view is connected again.

Parameters

• model {DynamicModel} ---An instance of DynamicModel which was activated again.

'SleepDynamicModel', callback(model)

Called when a model is deactivated, the model instance still exists but there's no view linked and the tick function is no longer called.

Parameters

• model {DynamicModel} ---An instance of DynamicModel which is deactivated.