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 specified 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 highlight terrain tiles, if any
wade.iso.getHighlightOffsets ()
Get the offsets that are currently used to display terrain highlights
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 specified 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
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 specified 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 highlight terrain tiles, if any
Returns Array : An array of SceneObjects
^
wade.iso.getHighlightOffsets ()
Get the offsets that are currently used to display terrain highlights
Returns Array : An array of objects with x and y properties
^
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|object x : The index of the tile on the isometric X axis. Alternatively you can use an object with {x: number, z: number}
number z (optional): 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 specified 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.
^
