Class Wade_iso
Version
3.0.
Constructor Attributes | Constructor Name and Description |
---|---|
Wade_iso()
This is an isometric plug-in for the Wade Game Engine by Clockwork Chilli.
|
Method Attributes | Method Name and Description |
---|---|
checkCollisionsAtTile(x, z)
Check to see if there are any objects with collision in a specific tile
|
|
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.
|
|
deleteObjectByName(name)
Delete the object with the specified name
|
|
deleteObjectsInTile(x, z)
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)
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 number of terrain tiles being used
|
|
getObjectsInTile(x, z)
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
|
|
getTileHeight(x, z)
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
|
|
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
|
|
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
|
|
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
|
Method Detail
{boolean}
checkCollisionsAtTile(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
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.
- Parameters:
- {boolean} toggle Optional
- Whether to constrain the camera or not. If omitted, it is assumed to be true.
{SceneObject}
createObject(objectData, gridCoords, instanceData)
Create an isometric object
- Parameters:
- {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.
- {{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 '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 to be used in the isometric world
deleteObject(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
deleteObjectByName(name)
Delete the object with the specified name
- Parameters:
- {string} name
- The name of the object to delete
{boolean}
deleteObjectsInTile(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
{Function}
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
- Parameters:
- {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()
drawGrid(toggle)
Draw a grid on the isometric terrain. Very useful during development and for debugging.
- Parameters:
- {boolean} toggle Optional
- Whether to draw the grid or not. If omitted, it's assumed to be true.
{object|string}
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()
- Parameters:
- {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
{Array}
findPath(gridStart, gridGoal, movementType, maxStepHeight)
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} 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
- 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.
{Object}
getDetailData(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() ).
{Sprite}
getDetailSprite(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
{{x: number|z: number|valid: boolean}}
getFlatTileCoordinates(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.
{{x: number|y: number}}
getFlatWorldCoordinates(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.
{{x: number|z: number}}
getNumTiles()
Get the number of terrain tiles being used
- Returns:
- {{x: number|z: number}} The current number of tiles
{Array}
getObjectsInTile(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
{number}
getObjectsLayerId()
Get the layer Id that is being used by isometric objects
- Returns:
- {number} The id of the layer used by isometric objects
{SceneObject}
getTerrain()
Get the isometric terrain object
- Returns:
- {SceneObject} The isometric terrain object
{number}
getTerrainLayerId()
Get the layer Id that is being used by terrain sprites
- Returns:
- {number} The id of the layer used by terrain sprites
{{x: number|z: number|valid: boolean}}
getTileCoordinates(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.
{Object}
getTileData(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() ).
{number}
getTileHeight(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
{number}
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
{{x: number|y: number}}
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
{Sprite}
getTileSprite(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
{string}
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
- 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
{Object}
getTransitionData(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() ).
{Sprite}
getTransitionSprite(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
{Array}
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
{{x: number|y: number}}
getWorldCoordinates(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.
importScene(data, callback)
Import isometric objects (including terrain) from a data object
- Parameters:
- {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
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.
- Parameters:
- {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
{boolean}
moveObjectToTile(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} 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
reset()
Remove all objects, clear all collision data, and restore the state to what it would be just after initialization
setDetail(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} 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
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.
- Parameters:
- {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}]
setNumTiles(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
setTile(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} 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, 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:
- 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.
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.
- 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} 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.
setTransition(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} 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
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.
{SceneObject}
spawnObjectNearObject(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} minOffsetX Optional, Default: -1
- The minimum offset on the isometric X axis, relative to otherObject, where the new object should be created
- {number} minOffsetZ Optional, Default: -1
- The minimum offset on the isometric Z axis, relative to otherObject, where the new object should be created
- {number} maxOffsetX Optional, Default: 1
- The maximum offset on the isometric X axis, relative to otherObject, where the new object should be created
- {number} maxOffsetZ Optional, 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)
swapObjects(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.