Constructors

- Wade.iso

Constructor Summary

This is an isometric plug-in for the Wade Game Engine by Clockwork Chilli.

Functions Summary

Check to see if there are any objects with collision in a specific tile
Clear the collision flag on a specific cell.
constrainCamera
(toggle)
Restrict the camera so that it never shows anything outside of the isometric terrain boundaries.
createObject
(objectData,
gridCoords,
instanceData)
Create an isometric object
deleteObject
(sceneObject)
Delete an object that was previously created with a call to createObject(), or as part of an isometric map file.
Delete the object with the specified name
Delete all the objects in a tile
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
drawGrid
(toggle)
Draw a grid on the isometric terrain.
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()
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.
getDetailData
(tileX,
tileZ)
Get the data associated with a specific terrain detail
getDetailSprite
(tileX,
tileZ)
Get the sprite being used as a terrain detail at the specified tile coordinates
getFlatTileCoordinates
(worldX,
worldY)
Get the tile coordinates (indices) corresponding to the spefified world-space positions ignoring the height offsets of all tiles
getFlatWorldCoordinates
(tileX,
tileZ)
Get the coordinates, in world space, corresponding to an isometric tile ignoring the height offsets of all tiles
Get the scene objects that are currently used to higlight terrain tiles, if any
Get the number of terrain tiles being used
Get all the objects in the specified terrain tile
Get the layer Id that is being used by isometric objects
Get the isometric terrain object
Get the layer Id that is being used by terrain sprites
getTileCoordinates
(worldX,
worldY)
Get the tile coordinates (indices) corresponding to the spefified world-space positions
getTileData
(tileX,
tileZ)
Get the data associated with a specific tile
Get the height offset of a tile
Get the scale factor that is being applied to each terrain tile (often to compensate for floating-point errors).
Get the size (in world units) of a terrain tile
getTileSprite
(tileX,
tileZ)
Get the sprite being used as a terrain tile at the specified tile coordinates
Get the name of the image file (or virtual path) that is being used for the tile at the specified tile coordinates
getTransitionData
(tileX,
tileZ)
Get the data associated with a specific terrain transition
getTransitionSprite
(tileX,
tileZ)
Get the sprite being used as a terrain transition at the specified tile coordinates
Get a list of directions that object on the isometric grid are allowed to use (this is used by Characters and for pathfinding).
getWorldCoordinates
(tileX,
tileZ)
Get the coordinates, in world space, corresponding to an isometric tile
importScene
(data,
callback)
Import isometric objects (including terrain) from a data object
init
(params)
Initialize the isometric engine.
moveObjectToTile
(object,
targetX,
targetZ,
speed)
Move an isometric object to a specific tile, with a custom speed or instantly
reset()
Remove all objects, clear all collision data, and restore the state to what it would be just after initialization
setCollisionAtTile
(x,
z,
isoObject)
Set collision information for a tile, specifying which object occupies the tile
setDetail
(x,
z,
data)
Change a terrain detail on the isometric terrain
setHighlight
(texture,
offsets)
Set an image to be displayed on the terrain tile where the mouse is being moved.
setNumTiles
(x,
z)
Set the current number of tiles
setTile
(x,
z,
tileData,
heightOffset)
Change a tile on the isometric terrain
setTileHeight
(x,
z,
height)
Set a height offset for a tile.
setTransition
(x,
z,
data)
Change a terrain transition on the isometric terrain
Force wade.iso to sort the terrain tiles.
spawnObjectNearObject
(otherObject,
objectData,
instanceData,
minOffsetX,
minOffsetZ,
maxOffsetX,
maxOffsetZ)
Create an object near another object
swapObjects
(a,
b)
Swap the positions of two isometric objects

Constructor Details

()
This is an isometric plug-in for the Wade Game Engine by Clockwork Chilli.

Function Details


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

Parameters:


{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

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

Parameters:


{number}xOptional
The isometric X coordinate of the tile
{number}zOptional
The isometric Z coordinate of the tile

(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.

Parameters:


{boolean}toggleOptional
Whether to constrain the camera or not. If omitted, it is assumed to be true.

(objectData,
gridCoords,
instanceData)
Create an isometric object

Parameters:


{Object}objectDataOptional
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}}gridCoordsOptional
An object representing the tile coordinates of the object on the isometric grid. Default is {x:0, z: 0}
{Object}instanceDataOptional
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

(sceneObject)
Delete an object that was previously created with a call to createObject(), or as part of an isometric map file.

Parameters:


{SceneObject}sceneObject
The object to delete

(name)
Delete the object with the specified name

Parameters:


{string}name
The name of the object to delete

(x,
z)
Delete all the objects in a tile

Parameters:


{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

(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

Parameters:


{string}borderColorOptional
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}fillColorOptional
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()

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

Parameters:


{boolean}toggleOptional
Whether to draw the grid or not. If omitted, it's assumed to be true.

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

Parameters:


{boolean}stringifyOptional
Whether to serialize the resulting JSON object to a string

Returns:


{object|string}
The JSON object (or JSON string) representing the current map

(gridStart,
gridGoal,
movementType,
maxStepHeight,
maxPathLength)
Find a path from a starting point on the isometric grid to a target point on the isometric grid.

Parameters:


{{x: number|z: number}}gridStart
An object representing the starting point
{{x: number|z: number}}gridGoal
An object representing the target point
{string}movementTypeOptional
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}maxStepHeightOptional
If defined, this determines the maximum height difference between two tiles that will not block movement
{number}maxPathLengthOptional
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.

(tileX,
tileZ)
Get the data associated with a specific terrain detail

Parameters:


{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() ).

(tileX,
tileZ)
Get the sprite being used as a terrain detail at the specified tile coordinates

Parameters:


{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

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

Parameters:


{number}worldX
The X coordinate of the world-space position
{number}worldY
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.

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

Parameters:


{number}tileX
The tile index on the isometric X axis
{number}tileZ
The tile index on the isometric Z axis

Returns:


{{x: number|y: number}}
An object representing the world space position corresponding to the tile.
()
Get the scene objects that are currently used to higlight terrain tiles, if any

Returns:


{Array}
An array of SceneObjects
()
Get the number of terrain tiles being used

Returns:


{{x: number|z: number}}
The current number of tiles

(x,
z)
Get all the objects in the specified terrain tile

Parameters:


{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
()
Get the layer Id that is being used by isometric objects

Returns:


{number}
The id of the layer used by isometric objects
()
Get the isometric terrain object

Returns:


{SceneObject}
The isometric terrain object
()
Get the layer Id that is being used by terrain sprites

Returns:


{number}
The id of the layer used by terrain sprites

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

Parameters:


{number}worldX
The X coordinate of the world-space position
{number}worldY
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.

(tileX,
tileZ)
Get the data associated with a specific tile

Parameters:


{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() ).

(x,
z)
Get the height offset of a tile

Parameters:


{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
()
Get the scale factor that is being applied to each terrain tile (often to compensate for floating-point errors).

Returns:


{number}
The scale factor
()
Get the size (in world units) of a terrain tile

Returns:


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

(tileX,
tileZ)
Get the sprite being used as a terrain tile at the specified tile coordinates

Parameters:


{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

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

Parameters:


{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

(tileX,
tileZ)
Get the data associated with a specific terrain transition

Parameters:


{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() ).

(tileX,
tileZ)
Get the sprite being used as a terrain transition at the specified tile coordinates

Parameters:


{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
()
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

(tileX,
tileZ)
Get the coordinates, in world space, corresponding to an isometric tile

Parameters:


{number}tileX
The tile index on the isometric X axis
{number}tileZ
The tile index on the isometric Z axis

Returns:


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

(data,
callback)
Import isometric objects (including terrain) from a data object

Parameters:


{Object}data
The isometric scene data object
{function}callbackOptional
A function to call when the assets referenced in the data have been fully loaded and added to the scene

(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.

Parameters:


{object}paramsOptional
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

(object,
targetX,
targetZ,
speed)
Move an isometric object to a specific tile, with a custom speed or instantly

Parameters:


{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}speedOptional
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
()
Remove all objects, clear all collision data, and restore the state to what it would be just after initialization


(x,
z,
isoObject)
Set collision information for a tile, specifying which object occupies the tile

Parameters:


{number}x
The isometric X coordinate of the tile
{number}z
The isometric Z coordinate of the tile
{Object}isoObjectOptional
The isometric object that occupies the tile

(x,
z,
data)
Change a terrain detail on the isometric terrain

Parameters:


{number}x
The tile index on the isometric X axis
{number}z
The tile index on the isometric Z axis
{Object}dataOptional
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

(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.

Parameters:


{string}texture
The name of the image file (or virtual path) to use
{Array}offsetsOptional
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}]

(x,
z)
Set the current number of tiles

Parameters:


{number}x
How many tiles on the isometric X axis
{number}z
How many tiles on the isometric Z axis

(x,
z,
tileData,
heightOffset)
Change a tile on the isometric terrain

Parameters:


{number}x
The tile index on the isometric X axis
{number}z
The tile index on the isometric Z axis
{Object}tileDataOptional
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}heightOffsetOptional, Default: 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:


undefined

(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.

Parameters:


{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}heightOptional
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.

(x,
z,
data)
Change a terrain transition on the isometric terrain

Parameters:


{number}x
The tile index on the isometric X axis
{number}z
The tile index on the isometric Z axis
{Object}dataOptional
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
()
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.


(otherObject,
objectData,
instanceData,
minOffsetX,
minOffsetZ,
maxOffsetX,
maxOffsetZ)
Create an object near another object

Parameters:


{string|SceneObject}otherObject
The isometric scene object (or a string with the name of the object) near which the new object will be created
{object}objectData
The object data for the object to create. Please refer to the documentation of createObject() for the details.
{object}instanceData
The instance data for the object to create. Please refer to the documentation of createObject() for the details.
{number}minOffsetXOptional, Default: -1
The minimum offset on the isometric X axis, relative to otherObject, where the new object should be created
{number}minOffsetZOptional, Default: -1
The minimum offset on the isometric Z axis, relative to otherObject, where the new object should be created
{number}maxOffsetXOptional, Default: 1
The maximum offset on the isometric X axis, relative to otherObject, where the new object should be created
{number}maxOffsetZOptional, Default: 1
The maximum offset on the isometric Z axis, relative to otherObject, where the new object should be created

Returns:


{SceneObject}
The new scene object that has been created, or null if it wasn't possible to create it (because all the tiles near the target object where occupied)

(a,
b)
Swap the positions of two isometric objects

Parameters:


{SceneObject}a
One of the objects to swap.
{SceneObject}b
The other object to swap.