Constructors

Fields Summary

Functions Summary

wade.iso.addSceneObject (sceneObject, gridCoords)

Add a SceneObject to the isometric world. Note that if the object has got a grid property (with type == 'isometric') this function is called automatically when the object is added to the wade scene.
wade.iso.addTileHeight (x, z, dh)

Add an height offset to a tile
wade.iso.canAddSceneObject (sceneObject, gridCoords)

Check whether a SceneObject can be added to the scene, taking into account collisions that are currently set on the isometric grid and the SceneObject's 'grid' property
wade.iso.checkCollisionsAtTile (x, z)

Check to see if there are any objects with collision in a specific tile
wade.iso.clearCollisions (x, z)

Clear the collision flag on a specific cell. If x and z are omitted, clear collisions everywhere on the map
wade.iso.constrainCamera (toggle)

Restrict the camera so that it never shows anything outside of the isometric terrain boundaries. Note that this can only work if your terrain is big enough (depending on the zoom level), and when you do this some areas of the map (near the corners and edges) may never be visible, depending on your aspect ratio.
wade.iso.createObject (objectData, gridCoords, instanceData)

Create an isometric object (deprecated)
wade.iso.deleteObject (sceneObject)

Deprecated. Delete an object that was previously created with a call to createObject(), or as part of an isometric map file.
wade.iso.deleteObjectByName (name)

Delete the object with the specified name
wade.iso.deleteObjectsInTile (x, z)

Delete all the objects in a tile
wade.iso.drawGrid (toggle)

Draw a grid on the isometric terrain. Very useful during development and for debugging.
wade.iso.draw_ (borderColor, fillColor)

Get a draw function (to use with Sprite.setDrawFunction()) that drawa an isometric tile, that can optionally be filled with a solid color and have borders of a different color
wade.iso.exportMap (stringify)

Export the current map and its state to a JSON object that can be passed into the map parameter of wade.iso.init()
wade.iso.findPath (gridStart, gridGoal, movementType, maxStepHeight, maxPathLength)

Find a path from a starting point on the isometric grid to a target point on the isometric grid.
wade.iso.getDetailData (tileX, tileZ)

Get the data associated with a specific terrain detail
wade.iso.getDetailSprite (tileX, tileZ)

Get the sprite being used as a terrain detail at the specified tile coordinates
wade.iso.getFlatTileCoordinates (worldX, worldY)

Get the tile coordinates (indices) corresponding to the spefified world-space positions ignoring the height offsets of all tiles
wade.iso.getFlatWorldCoordinates (tileX, tileZ)

Get the coordinates, in world space, corresponding to an isometric tile ignoring the height offsets of all tiles
wade.iso.getHighlightObjects ()

Get the scene objects that are currently used to higlight terrain tiles, if any
wade.iso.getNumTiles ()

Get the number of terrain tiles being used
wade.iso.getObjectsInTile (x, z)

Get all the objects in the specified terrain tile
wade.iso.getObjectsLayerId ()

Get the layer Id that is being used by isometric objects
wade.iso.getTerrain ()

Get the isometric terrain object
wade.iso.getTerrainLayerId ()

Get the layer Id that is being used by terrain sprites
wade.iso.getTileCoordinates (worldX, worldY)

Get the tile coordinates (indices) corresponding to the spefified world-space positions
wade.iso.getTileData (tileX, tileZ)

Get the data associated with a specific tile
wade.iso.getTileHeight (x, z)

Get the height offset of a tile
wade.iso.getTileScaleFactor ()

Get the scale factor that is being applied to each terrain tile (often to compensate for floating-point errors).
wade.iso.getTileSize ()

Get the size (in world units) of a terrain tile
wade.iso.getTileSprite (tileX, tileZ)

Get the sprite being used as a terrain tile at the specified tile coordinates
wade.iso.getTileTexture (x, z)

Get the name of the image file (or virtual path) that is being used for the tile at the specified tile coordinates
wade.iso.getTransitionData (tileX, tileZ)

Get the data associated with a specific terrain transition
wade.iso.getTransitionSprite (tileX, tileZ)

Get the sprite being used as a terrain transition at the specified tile coordinates
wade.iso.getValidMovementDirections ()

Get a list of directions that object on the isometric grid are allowed to use (this is used by Characters and for pathfinding). Depending on the 'movementDirection' parameter specified in the init function, this could be an array of 4 or 8 elements.
wade.iso.getWorldCoordinates (tileX, tileZ)

Get the coordinates, in world space, corresponding to an isometric tile
wade.iso.importScene (data, callback)

Import isometric objects (including terrain) from a data object
wade.iso.init (params)

Initialize the isometric engine. This is typically done automatically and in normal circumstances you don't need to call this function from your code.
wade.iso.moveObjectToTile (object, targetX, targetZ, speed)

Move an isometric object to a specific tile, with a custom speed or instantly
wade.iso.removeSceneObject (sceneObject)

Remove a SceneObject from the isometric world. This implies clearing any the collision and grid map tiles that the object was occupying.
wade.iso.reset ()

Remove all objects, clear all collision data, and restore the state to what it would be just after initialization
wade.iso.setCollisionAtTile (x, z, isoObject)

Set collision information for a tile, specifying which object occupies the tile
wade.iso.setDetail (x, z, data)

Change a terrain detail on the isometric terrain
wade.iso.setHighlight (texture, offsets)

Set an image to be displayed on the terrain tile where the mouse is being moved. This can be extended to multiple tiles by using the offsets parameter.
wade.iso.setNumTiles (x, z)

Set the current number of tiles
wade.iso.setTile (x, z, tileData, heightOffset)

Change a tile on the isometric terrain
wade.iso.setTileHeight (x, z, height)

Set a height offset for a tile. This affects the position in the world for the tile and any isometric object on that tile.
wade.iso.setTransition (x, z, data)

Change a terrain transition on the isometric terrain
wade.iso.sortTerrainTiles ()

Force wade.iso to sort the terrain tiles. This may be useful if you are adding and removing tiles and transitions dynamically at run-time.
wade.iso.swapObjects (a, b)

Swap the positions of two isometric objects

Fields Details

Function Details

wade.iso.addSceneObject (sceneObject, gridCoords)

Add a SceneObject to the isometric world. Note that if the object has got a grid property (with type == 'isometric') this function is called automatically when the object is added to the wade scene.

SceneObject sceneObject : the object to add to the scene


{x: number, z: number} gridCoords : The isometric grid coordinates identifying the tile where the object should be added


Returns boolean : Whether it was possible to add the object to the scene, taking into account collisions that are currently set on the isometric grid

^
wade.iso.addTileHeight (x, z, dh)

Add an height offset to a tile

number x : The index of the tile on the isometric X axis


number z : The index of the tile on the isometric X axis


number dh : The height offset to add

^
wade.iso.canAddSceneObject (sceneObject, gridCoords)

Check whether a SceneObject can be added to the scene, taking into account collisions that are currently set on the isometric grid and the SceneObject's 'grid' property

SceneObject sceneObject : The SceneObject to test


{x: number, z: number} gridCoords : The isometric grid coordinates identifying the tile where the object should be added


Returns boolean : Whether it is possible to add the object to the isometric map

^
wade.iso.checkCollisionsAtTile (x, z)

Check to see if there are any objects with collision in a specific tile

number x : The isometric X coordinate of the tile


number z : The isometric Z coordinate of the tile


Returns boolean : Whether there are any objects with collision in the tile

^
wade.iso.clearCollisions (x, z)

Clear the collision flag on a specific cell. If x and z are omitted, clear collisions everywhere on the map

number x (optional): The isometric X coordinate of the tile


number z (optional): The isometric Z coordinate of the tile

^
wade.iso.constrainCamera (toggle)

Restrict the camera so that it never shows anything outside of the isometric terrain boundaries. Note that this can only work if your terrain is big enough (depending on the zoom level), and when you do this some areas of the map (near the corners and edges) may never be visible, depending on your aspect ratio.

boolean toggle (optional): Whether to constrain the camera or not. If omitted, it is assumed to be true.

^
wade.iso.createObject (objectData, gridCoords, instanceData)

Create an isometric object (deprecated)

Object objectData (optional): An object containing some the following fields (they are all optional) describing the properties of the object type. This is a sort of object template, that is shared by all instances of this type of object:


  • gridMap: An array of objects with x and z fields describing offsets (with respect to the object's main tile) of which terrain tiles are being used by the object. This is done so you can use getObjectsInTile(). Default [{x:0, z:0}].

  • collisionMap: An array of objects (in the same way as gridMap), that describes which tiles have collisions (with respect to the object's main tile). By default this is not set, meaning no collisions.

  • gridSize: An object with x and z fields representing the size of the gridMap. When a gridMap represents a regular (rectangular) area, it's often more convenient to us this parameter rather than gridMap.

  • collisionSize: An object with x and z fields representing the size of the collisionMap. When a collisionMap represents a regular (rectangular) area, it's often more convenient to us this parameter rather than collisionMap.

  • behaviors: An array (or a single Behavior) with any Behaviors to be attached to the object.

  • dontAddToScene: A flag that can be set to true if you want to create the object without adding it to the scene.

  • sprites: An object, or an array of objects, describing one or more sprites. See the documentation for the Sprite object for a complete description of all the properties that you can define for each Sprite and its Animations.

  • properties: An object containing any custom properties that you want to copy into the new isometric object



{x: number, z: number} gridCoords (optional): An object representing the tile coordinates of the object on the isometric grid. Default is {x:0, z: 0}


Object instanceData (optional): An object with data to be attached to the newly created object. You can use the special 'name' field of this object to give your object a name, but it must be unique. You can use the special 'flowChart' field to run a flow chart when the object is added to the scene

You can use the special 'functions' object to assign functions to the object. The 'functions' object be in the format {functionName1: functionCode1, functionName2: functionCode2, ...} where functionCode is always a string.

Returns SceneObject : A scene object that has been set up for use in the isometric world

^
wade.iso.deleteObject (sceneObject)

Deprecated. Delete an object that was previously created with a call to createObject(), or as part of an isometric map file.
Use wade.iso.removeSceneObject instead (it does the same thing)

SceneObject sceneObject : The object to delete

^
wade.iso.deleteObjectByName (name)

Delete the object with the specified name

string name : The name of the object to delete

^
wade.iso.deleteObjectsInTile (x, z)

Delete all the objects in a tile

number x : The isometric X coordinate of the tile


number z : The isometric Z coordinate of the tile


Returns boolean : Whether any object was found and deleted

^
wade.iso.drawGrid (toggle)

Draw a grid on the isometric terrain. Very useful during development and for debugging.

boolean toggle (optional): Whether to draw the grid or not. If omitted, it's assumed to be true.

^
wade.iso.draw_ (borderColor, fillColor)

Get a draw function (to use with Sprite.setDrawFunction()) that drawa an isometric tile, that can optionally be filled with a solid color and have borders of a different color

string borderColor (optional): An HTML color string to use for the borders, for example 'white', '#ffffff', 'rgba(255, 255, 255, 1)' and so on. If omitted or falsy, no borders will be drawn.


string fillColor (optional): An HTML color string to use for the fill color, for example 'white', '#ffffff', 'rgba(255, 255, 255, 1)' and so on. If omitted or falsy, the tile image won't be filled.


Returns Function : The function to use with Sprite.setDrawFunction()

^
wade.iso.exportMap (stringify)

Export the current map and its state to a JSON object that can be passed into the map parameter of wade.iso.init()

boolean stringify (optional): Whether to serialize the resulting JSON object to a string


Returns object|string : The JSON object (or JSON string) representing the current map

^
wade.iso.findPath (gridStart, gridGoal, movementType, maxStepHeight, maxPathLength)

Find a path from a starting point on the isometric grid to a target point on the isometric grid.

{x: number, z: number} gridStart : An object representing the starting point


{x: number, z: number} gridGoal : An object representing the target point


string movementType (optional): A string describing the allowed movement type. It can be 'diagonal', 'straight' or 'both'. If omitted, the default movement type will be used (or the one that was set when wade.iso.init() was called).


number maxStepHeight (optional): If defined, this determines the maximum height difference between two tiles that will not block movement


number maxPathLength (optional): If defined, this determines the maximum length of the path that can be returned


Returns Array : An array of objects with x and z fields representing the tiles that make up the path from the starting point to the goal. Note that the starting point is not included. This may be an empty array if it wasn't possible to find a valid path.

^
wade.iso.getDetailData (tileX, tileZ)

Get the data associated with a specific terrain detail

number tileX : The index of the tile on the isometric X axis


number tileZ : The index of the tile on the isometric Z axis


Returns Object : An object containing any data associated with a specific terrain detail ( such as which image file it's using, if it has animations, and any other data set with setDetail() ).

^
wade.iso.getDetailSprite (tileX, tileZ)

Get the sprite being used as a terrain detail at the specified tile coordinates

number tileX : The index of the tile on the isometric X axis


number tileZ : The index of the tile on the isometric Z axis


Returns Sprite : The sprite at the current tile coordinates

^
wade.iso.getFlatTileCoordinates (worldX, worldY)

Get the tile coordinates (indices) corresponding to the spefified world-space positions ignoring the height offsets of all tiles

number|object worldX : The X coordinate of the world-space position. This first parameter can also be an object with x and y fields.


number worldY (optional): The Y coordinate of the world-space position


Returns {x: number, z: number, valid: boolean} : An object with the tile x and z indices. There is also a valid flag indicating whether the tile is inside the current terrain boundaries.

^
wade.iso.getFlatWorldCoordinates (tileX, tileZ)

Get the coordinates, in world space, corresponding to an isometric tile ignoring the height offsets of all tiles

number|object tileX : The tile index on the isometric X axis. This first parameter can also be an object with x and z fields.


number tileZ (optional): The tile index on the isometric Z axis


Returns {x: number, y: number} : An object representing the world space position corresponding to the tile.

^
wade.iso.getHighlightObjects ()

Get the scene objects that are currently used to higlight terrain tiles, if any

Returns Array : An array of SceneObjects

^
wade.iso.getNumTiles ()

Get the number of terrain tiles being used

Returns {x: number, z: number} : The current number of tiles

^
wade.iso.getObjectsInTile (x, z)

Get all the objects in the specified terrain tile

number x : The index of the tile on the isometric X axis


number z : The index of the tile on the isometric Z axis


Returns Array : An array containing all the objects in the tile

^
wade.iso.getObjectsLayerId ()

Get the layer Id that is being used by isometric objects

Returns number : The id of the layer used by isometric objects

^
wade.iso.getTerrain ()

Get the isometric terrain object

Returns SceneObject : The isometric terrain object

^
wade.iso.getTerrainLayerId ()

Get the layer Id that is being used by terrain sprites

Returns number : The id of the layer used by terrain sprites

^
wade.iso.getTileCoordinates (worldX, worldY)

Get the tile coordinates (indices) corresponding to the spefified world-space positions

number|object worldX : The X coordinate of the world-space position. This first parameter can also be an object with x and y fields.


number worldY (optional): The Y coordinate of the world-space position


Returns {x: number, z: number, valid: boolean} : An object with the tile x and z indices. There is also a valid flag indicating whether the tile is inside the current terrain boundaries.

^
wade.iso.getTileData (tileX, tileZ)

Get the data associated with a specific tile

number tileX : The index of the tile on the isometric X axis


number tileZ : The index of the tile on the isometric Z axis


Returns Object : An object containing any data associated with a specific tile ( such as which image file it's using, if it has animations, and any other data set with setTile() ).

^
wade.iso.getTileHeight (x, z)

Get the height offset of a tile

number x : The index of the tile on the isometric X axis


number z : The index of the tile on the isometric X axis


Returns number : The current height offset for the specified tile

^
wade.iso.getTileScaleFactor ()

Get the scale factor that is being applied to each terrain tile (often to compensate for floating-point errors).

Returns number : The scale factor

^
wade.iso.getTileSize ()

Get the size (in world units) of a terrain tile

Returns {x: number, y: number} : An object representing the size of a terrain tile

^
wade.iso.getTileSprite (tileX, tileZ)

Get the sprite being used as a terrain tile at the specified tile coordinates

number tileX : The index of the tile on the isometric X axis


number tileZ : The index of the tile on the isometric Z axis


Returns Sprite : The sprite at the current tile coordinates

^
wade.iso.getTileTexture (x, z)

Get the name of the image file (or virtual path) that is being used for the tile at the specified tile coordinates

number x : The index of the tile on the isometric X axis


number z : The index of the tile on the isometric Z axis


Returns string : The image file name, or an empty string if there are no tiles at the specified tile coordinates

^
wade.iso.getTransitionData (tileX, tileZ)

Get the data associated with a specific terrain transition

number tileX : The index of the tile on the isometric X axis


number tileZ : The index of the tile on the isometric Z axis


Returns Object : An object containing any data associated with a specific terrain transition ( such as which image file it's using, if it has animations, and any other data set with setTransition() ).

^
wade.iso.getTransitionSprite (tileX, tileZ)

Get the sprite being used as a terrain transition at the specified tile coordinates

number tileX : The index of the tile on the isometric X axis


number tileZ : The index of the tile on the isometric Z axis


Returns Sprite : The sprite at the current tile coordinates

^
wade.iso.getValidMovementDirections ()

Get a list of directions that object on the isometric grid are allowed to use (this is used by Characters and for pathfinding). Depending on the 'movementDirection' parameter specified in the init function, this could be an array of 4 or 8 elements.

Returns Array : An array of objects with x and z fields representing the valid movement directions

^
wade.iso.getWorldCoordinates (tileX, tileZ)

Get the coordinates, in world space, corresponding to an isometric tile

number|object tileX : The tile index on the isometric X axis. This first parameter can also be an object with x and z fields.


number tileZ (optional): The tile index on the isometric Z axis


Returns {x: number, y: number} : An object representing the world space position corresponding to the tile.

^
wade.iso.importScene (data, callback)

Import isometric objects (including terrain) from a data object

Object data : The isometric scene data object


function callback (optional): A function to call when the assets referenced in the data have been fully loaded and added to the scene

^
wade.iso.init (params)

Initialize the isometric engine. This is typically done automatically and in normal circumstances you don't need to call this function from your code.

object params (optional): An object with some of the following fields (they are all optional), describing the properties of the isometric world:


  • tileScaleFactor: A scale factor for all terrain tiles, to compensate for floating-point precision and rounding errors. Default is 1.018 (meaning that tiles are 1.8% bigger than what they should theoretically be)

  • terrainLayerId: The layer id to use for the terrain. Default is 30

  • objectsLayerId: The layer id to use for isometric objects. Default is 25

  • dontClearCanvas: Set this to true as an optimization to avoid clearing the terrain canvas every frame (you can do this when the camera is constrained to the terrain, i.e when the terrain occupies the whole screen at all times). Default is false.

  • tileSize: The size (in world units) of each tile. This is an object with x and y fields, default is {x: 512, y: 256}

  • numTiles: An object with x and z fields describing the number of tiles in the isometric world. Default is {x: 1, z: 1}

  • movementDirection: A string describing the movement direction (used for character animations and pathfinding). It can be 'diagonal', 'straight', or 'both'. Default is 'diagonal'

  • map: A string pointing to a JSON file that contains a map to load

  • callback: If a map has been specified, this is the function to call when the map has been fully loaded


^
wade.iso.moveObjectToTile (object, targetX, targetZ, speed)

Move an isometric object to a specific tile, with a custom speed or instantly

SceneObject|string object : The object to move (or the name of the object to move)


number targetX : The isometric X coordinate of the target tile


number targetZ : The isometric Z coordinate of the target tile


number speed (optional): The movement speed, in world units. If omitted or false, the object is moved instantly to the target position


Returns boolean : Whether it was possible to move the object

^
wade.iso.removeSceneObject (sceneObject)

Remove a SceneObject from the isometric world. This implies clearing any the collision and grid map tiles that the object was occupying.
The object is not removed by the wade scene. For that you may want to use wade.removeSceneObject instead, that removes the object from the wade scene and internally calls this function.

SceneObject sceneObject : The object to remove

^
wade.iso.reset ()

Remove all objects, clear all collision data, and restore the state to what it would be just after initialization
^
wade.iso.setCollisionAtTile (x, z, isoObject)

Set collision information for a tile, specifying which object occupies the tile

number x : The isometric X coordinate of the tile


number z : The isometric Z coordinate of the tile


Object isoObject (optional): The isometric object that occupies the tile

^
wade.iso.setDetail (x, z, data)

Change a terrain detail on the isometric terrain

number x : The tile index on the isometric X axis


number z : The tile index on the isometric Z axis


Object data (optional): An object with the following fields (they are all optional) representing the detail data. If this is omitted or falsy, the detail is removed:


  • texture: An image file name (or virtual path) to use for the detail

  • scale: A scale factor to apply to the detail sprite (default is 1)

  • rotation: This can be an integer number between 0 and 3 included, that indicates how many times the source texture should be rotated by 90 degrees clockwise

  • animation: An animation object to use for the detail, with some of the following fields. The animation is always played in forward looping mode.


    • numFrames: An object with x and y fields representing the number of frames in the spritesheet

    • speed: The number of frames per second



^
wade.iso.setHighlight (texture, offsets)

Set an image to be displayed on the terrain tile where the mouse is being moved. This can be extended to multiple tiles by using the offsets parameter.

string texture : The name of the image file (or virtual path) to use


Array offsets (optional): An array of objects with x and z fields representing the offsets (relative to the tile where the mouse is) of the tiles to highlight. Default is [{x:0, z:0}]

^
wade.iso.setNumTiles (x, z)

Set the current number of tiles

number x : How many tiles on the isometric X axis


number z : How many tiles on the isometric Z axis

^
wade.iso.setTile (x, z, tileData, heightOffset)

Change a tile on the isometric terrain

number x : The tile index on the isometric X axis


number z : The tile index on the isometric Z axis


Object tileData (optional): An object with the following fields (they are all optional) representing the tile data. If this is omitted or falsy, the tile is effectively removed, leaving a hole in the terrain. Note that you cannot remove tiles where there are objects with collisions. Parameters:


  • texture: An image file name (or virtual path) to use for the tile

  • scale: A scale factor to apply to the tile sprite (default is 1)

  • rotation: This can be an integer number between 0 and 3 included, that indicates how many times the source texture should be rotated by 90 degrees clockwise

  • animation: An animation object to use for the tile, with some of the following fields. The animation is always played in forward looping mode

  • customHeight: A boolean describing whether the height of this tile should be inferred from the texture size rather than being set to the current isometric tile height

  • collision: A boolean describing whether this tile should block object movement and affect the result of findPath


    • numFrames: An object with x and y fields representing the number of frames in the spritesheet

    • speed: The number of frames per second




number heightOffset (optional, defaults to 0): A height offset for this tile that will affect the world position of the tile and any objects on the tile. By default this is 0.


Returns : boolean Whether it was possible to set the tile. It may not be possible if the tile has got a collision flag and there are other objects with collision maps on the tile.

^
wade.iso.setTileHeight (x, z, height)

Set a height offset for a tile. This affects the position in the world for the tile and any isometric object on that tile.

number x : The index of the tile on the isometric X axis


number z : The index of the tile on the isometric X axis


number height (optional): A height offset in world units. Positive numbers will cause the tile to appear higher, negarive numbers will make it appear lower than ground level.

^
wade.iso.setTransition (x, z, data)

Change a terrain transition on the isometric terrain

number x : The tile index on the isometric X axis


number z : The tile index on the isometric Z axis


Object data (optional): An object with the following fields (they are all optional) representing the transition data. If this is omitted or falsy, the transition is removed:


  • texture: An image file name (or virtual path) to use for the transition

  • scale: A scale factor to apply to the transition sprite (default is 1)

  • rotation: This can be an integer number between 0 and 3 included, that indicates how many times the source texture should be rotated by 90 degrees clockwise

  • animation: An animation object to use for the transition, with some of the following fields. The animation is always played in forward looping mode.


    • numFrames: An object with x and y fields representing the number of frames in the spritesheet

    • speed: The number of frames per second



^
wade.iso.sortTerrainTiles ()

Force wade.iso to sort the terrain tiles. This may be useful if you are adding and removing tiles and transitions dynamically at run-time.
^
wade.iso.swapObjects (a, b)

Swap the positions of two isometric objects

SceneObject a : One of the objects to swap.


SceneObject b : The other object to swap.

^