Image

addLayer

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

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

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

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

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.

getDistanceDiagMult

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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.