Image
addLayer
function addLayer(dbnode/dbpath, layertype, layerdata)Attempts to add a layer on the specified image value database node. Only scripts running on the session host can run this API.
If the specified database node does not exist or is not an image value database node, then an error is generated.
Valid layer types are: image, paint (default), text
Image layer type fields: name (string), asset (string), x (number), y (number), w (number), h (number), color (string), angle (number), invisible (boolean), gmonly (boolean), locked (boolean)
Note: w and h attributes are specified in grid units.Paint layer type fields: name (string)
Text layer type fields: text (string), font (string), fontsize (number)
Parameters
dbnode/dbpath (databasenode/string)
Specifies the database node whose state is being queried.
layertype (string)
The desired layer type to add
layerdata (table)
A table containing string-based keys to denote layer type specific parameters (see above).
Return values
(number/nil)
Returns the layer ID of the created layer, or nil if no layer created.
addLayerPaintStamp
function addLayerPaintStamp(dbnode/dbpath, layerid, stampdata)Attempts to add a layer on the specified image value database node. Only scripts running on the session host can run this API.
If the specified database node does not exist or is not an image value database node, then an error is generated.
Paint stamp data fields: asset (string), x (number), y (number), w (number), h (number), color (string), angle (number)
Note: w and h attributes are specified in grid units.
Parameters
dbnode/dbpath (databasenode/string)
Specifies the database node whose state is being queried.
layerid (number)
The desired layer to edit.
stampdata (table)
A table containing string-based keys to denote paint stamp specific parameters (see above).
Return values
(number/nil)
Returns the layer ID of the created layer, or nil if no layer created.
deleteLayer
function addLayer(dbnode/dbpath, layerid)Attempts to delete the specified layer ID on the specified image value database node. Only scripts running on the session host can run this API.
If the specified database node does not exist or is not an image value database node, then an error is generated.
Parameters
dbnode/dbpath (databasenode/string)
Specifies the database node whose state is being queried.
layerid (number)
The desired layer to delete
getDistanceBaseUnits
function getDistanceBaseUnits(dbnode/dbpath)Retrieves the distance base units of the specified image value database node.
If the specified database node does not exist or is not an image value database node, then an error is generated.
Parameters
dbnode/dbpath (databasenode/string)
Specifies the database node whose state is being queried.
Return values
(number)
Returns the distance base units.
getDistanceBetween
function getDistanceBetween(dbnode/dbpath, token/tokenid/point, token/tokenid/point)Returns the distance (in game system units) between two tokens (and/or points) of the specified image value database node.
If the specified database node does not exist or is not an image value database node, then an error is generated. If a token parameter specifies a token not on the image value, then zero will be returned.
Parameters
dbnode/dbpath (databasenode/string)
Specifies the database node whose state is being queried.
token/tokenid/point (tokeninstance/number/table)
A tokeninstance object,
OR the ID of a tokeninstance,
OR a Lua table of the form { 1 = #, 2 = # } or { x = #, y = # }, indicating a point on the image.
Return values
(number)
Returns the distance between the two specified tokens and/or points in game system units.
(or returns nil, if both parameters are token objects and they are not on the same map)
getDistanceDiagMult
function getDistanceDiagMult(dbnode/dbpath)Retrieves the distance diagonal multiplier of the specified image value database node.
If the specified database node does not exist or is not an image value database node, then an error is generated.
Parameters
dbnode/dbpath (databasenode/string)
Specifies the database node whose state is being queried.
Return values
(number)
Returns the distance diag multiplier of the specified image value.
[>0 for grid-based multiple; 0 for raw calculation]
getDistanceSuffix
function getDistanceSuffix(dbnode/dbpath)Retrieves the distance display suffix of the specified image value database node.
If the specified database node does not exist or is not an image value database node, then an error is generated.
Parameters
dbnode/dbpath (databasenode/string)
Specifies the database node whose state is being queried.
Return values
(number)
Returns the distance display suffix of the specified image value.
getGridOffset
function getGridOffset(dbnode/dbpath)Returns the offset of the first grid square in the top left corner on the specified image value database node. The offsets will be different from zero as a result of the grid not being perfectly aligned with the top left corner of the image itself. The values will vary from zero to -((grid size) - 1).
If the specified database node does not exist or is not an image value database node, then an error is generated.
Parameters
dbnode/dbpath (databasenode/string)
Specifies the database node whose state is being queried.
Return values
(number)
Returns the horizontal offset of the grid
(number)
Returns the vertical offset of the grid
getGridSize
function getGridSize(dbnode/dbpath)Returns the size of a grid square on the specified image value database node. The grid is rectangular, i.e. the height and width of the squares is the same.
If the specified database node does not exist or is not an image value database node, then an error is generated.
Parameters
dbnode/dbpath (databasenode/string)
Specifies the database node whose state is being queried.
Return values
(number)
Returns the size of a grid square.
getGridSnap
function getGridSnap(dbnode/dbpath)Returns whether grid snapping is enabled on the specified image value database node.
If the specified database node does not exist or is not an image value database node, then an error is generated.
Parameters
dbnode/dbpath (databasenode/string)
Specifies the database node whose state is being queried.
Return values
(number/nil)
Returns 1 if enabled, 0 if disabled, or nil if undefined.
getGridType
function getGridType(dbnode/dbpath)Returns the type of grid currently active on the specified image value database node. Valid types are "square", "hexcolumn" (hexes stacked vertically) and "hexrow" (hexes stacked horizontally).
If the specified database node does not exist or is not an image value database node, then an error is generated.
Parameters
dbnode/dbpath (databasenode/string)
Specifies the database node whose state is being queried.
Return values
(string)
Returns the grid type.
getLayerByName
function getLayerByName(dbnode/dbpath, name)Attempts to get the layer ID matching the specified name on the specified image value database node.
If the specified database node does not exist or is not an image value database node, then an error is generated.
Parameters
dbnode/dbpath (databasenode/string)
Specifies the database node whose state is being queried.
name (string)
The desired layer name to query
Return values
(number/nil)
Returns the layer ID of the desired layer, or nil if no matching layer found.
getSize
function getSize(dbnode/dbpath)Returns the overall size of the specified image value database node.
If the specified database node does not exist or is not an image value database node, then an error is generated.
Parameters
dbnode/dbpath (databasenode/string)
Specifies the database node whose state is being queried.
Return values
(number)
Returns the image width.
(number)
Returns the image height.
getTokenLockState
function getTokenLockState(dbnode/dbpath)Returns whether token movement has been locked for clients on the specified image value database node.
If the specified database node does not exist or is not an image value database node, then an error is generated.
Parameters
dbnode/dbpath (databasenode/string)
Specifies the database node whose state is being queried.
Return values
(boolean)
Returns the current lock state.
getTokens
function getTokens(dbnode/dbpath)Retrieve a list of all tokens on the specified image value database node.
If the specified database node does not exist or is not an image value database node, then an error is generated.
Parameters
dbnode/dbpath (databasenode/string)
Specifies the database node whose state is being queried.
Return values
(table)
A table with integer index values containing references to tokeninstance objects.
getTokensWithinDistance
function getTokensWithinDistance(dbnode/dbpath, token/tokenid/point, distance)Returns a list of all tokens within the given game system unit distance from the specified token or point on the specified image value database node.
If the specified database node does not exist or is not an image value database node, then an error is generated. If a token parameter specifies a token not on the image value, then an empty list will be returned.
Parameters
dbnode/dbpath (databasenode/string)
Specifies the database node whose state is being queried.
token/tokenid/point (tokeninstance/number/table)
A tokeninstance object,
OR the ID of a tokeninstance,
OR a Lua table of the form { 1 = #, 2 = # } or { x = #, y = # }, indicating a point on the image.
distance (number)
The range in game system units that should be considered for distance calculations.
Return values
(table)
A table with integer index values containing references to tokeninstance objects.
hasGrid
function hasGrid(dbnode/dbpath)Returns whether the grid is visible on the specified image value database node.
If the specified database node does not exist or is not an image value database node, then an error is generated.
Parameters
dbnode/dbpath (databasenode/string)
Specifies the database node whose state is being queried.
Return values
(boolean)
Returns true if the grid is visible, or false if not.
hasTokens
function hasTokens(dbnode/dbpath)Returns whether there are any tokens placed on the specified image value database node.
If the specified database node does not exist or is not an image value database node, then an error is generated.
Parameters
dbnode/dbpath (databasenode/string)
Specifies the database node whose state is being queried.
Return values
(boolean)
Returns true if there is at least one token placed, or false if not.
isImage
function isImage(dbnode/dbpath)Returns whether the specified image value database node is an image value database node.
Parameters
dbnode/dbpath (databasenode/string)
Specifies the database node whose state is being queried.
Return values
(boolean)
Returns true if the database node exists and is an image value database node, or false if not.
setDistanceBaseUnits
function setDistanceBaseUnits(dbnode/dbpath, units)Sets the distance base units of the specified image value database node.
If the specified database node does not exist or is not an image value database node, then an error is generated.
Parameters
dbnode/dbpath (databasenode/string)
Specifies the database node whose state is being queried.
units (number)
Specifies the desired units.
setDistanceDiagMult
function setDistanceDiagMult(dbnode/dbpath, multiplier)Sets the distance diagonal multiplier of the specified image value database node.
If the specified database node does not exist or is not an image value database node, then an error is generated.
Parameters
dbnode/dbpath (databasenode/string)
Specifies the database node whose state is being queried.
multiplier (number)
Specifies the desired multiplier.
[>0 for grid-based multiple; 0 for raw calculation]
setDistanceSuffix
function setDistanceSuffix(dbnode/dbpath, suffix)Sets the distance distance suffix of the specified image value database node.
If the specified database node does not exist or is not an image value database node, then an error is generated.
Parameters
dbnode/dbpath (databasenode/string)
Specifies the database node whose state is being queried.
suffix (number)
Specifies the desired suffix.
setGridOffset
function setGridOffset(dbnode/dbpath, offsetx, offsety)Sets the offset of the first grid square in the top left corner of the specified image value database node. The valid values for the offsets range from zero to -((grid size) - 1), any values not in this range will be converted to fit the interval.
If the specified database node does not exist or is not an image value database node, then an error is generated.
Parameters
dbnode/dbpath (databasenode/string)
Specifies the database node whose state is being queried.
offsetx (number)
The desired horizontal grid offset
offsety (number)
The desired vertical grid offset
setGridSize
function setGridSize(dbnode/dbpath, size)Set the grid size of the specified image value database node.
If the specified database node does not exist or is not an image value database node, then an error is generated.
Parameters
dbnode/dbpath (databasenode/string)
Specifies the database node whose state is being queried.
size (number)
The desired grid size
setGridSnap
function setGridSnap(dbnode/dbpath, snapenable)Sets whether grid snapping is enabled on the specified image value database node.
If the specified database node does not exist or is not an image value database node, then an error is generated.
Parameters
dbnode/dbpath (databasenode/string)
Specifies the database node whose state is being queried.
snapenable (number)
If 0 then disable grid snapping; otherwise, enable grid snapping.
setGridType
function setGridType(dbnode/dbpath, type)Sets the grid type on the specified image value database node. Valid types are "square", "hexcolumn" (hexes stacked vertically) and "hexrow" (hexes stacked horizontally). The token orientation will be automatically set to 8 (square) or 12 (hex), based on the new grid type.
If the specified database node does not exist or is not an image value database node, then an error is generated.
Parameters
dbnode/dbpath (databasenode/string)
Specifies the database node whose state is being queried.
type (string)
The desired grid type
setTokenLockState
function setTokenLockState(dbnode/dbpath, state)Sets whether clients can move tokens on the specified image value database node. Only scripts running on the session host can set this property.
If the specified database node does not exist or is not an image value database node, then an error is generated.
Parameters
dbnode/dbpath (databasenode/string)
Specifies the database node whose state is being queried.
state (boolean)
The desired lock state
snapToGrid
function snapToGrid(dbnode/dbpath, x, y)Returns the nearest snap point on the specified image value database node of the specified X and Y coordinate point, either vertex or center.
If the specified database node does not exist or is not an image value database node, then an error is generated.
Parameters
dbnode/dbpath (databasenode/string)
Specifies the database node whose state is being queried.
x (number)
The X coordinate to snap
y (number)
The Y coordinate to snap
Return values
(number)
Returns the snapped X coordinate.
(number)
Returns the snapped Y coordinate.