Types

Methods

highlightRing( config [, options ] ) → {Array.<{x: Number, y: Number, ring: Number}>}

Description

For gridded scenes, will highlight a corresponding number of concentric rings spreading outward from the provided starting point (which is given a negative ring index).

By default, the number of rings to highlight is zero and the layer is cleared before drawing, which results in erasing any highlighted rings on the canvas.

Parameters

Name Type Attributes Description

config

object

Name	Type	Attributes	Default	Description
`x`	Number
`y`	Number
`rings`	Number \| Array.<Number>	<optional>	0	Number of concentric rings to highlight. If an array is provided, it is treated as a "schedule" where each entry represents `value` number of `size`-width rings.
`name`	String	<optional>	'warpgate-ring'	Highlight layer name to be used for drawing/clearing

options

object

Name	Type	Attributes	Default	Description
`size`	Number	<optional>	1	Width of each ring, in grid spaces
`colors`	Color \| Array.<Color> \| ColorFn	<optional>	game.user.color	Colors for each ring 'band' (based on `size` option). If a `Color` is passed, all highlights will use that color. If an `Array<Color>` is passed each `size`-width ring will be colored according to the provided list, which is iterated circularly (i.e. repeats if short). If a `ColorFn` is passed, it will be used to generate the color on a per-square/hex basis (see `ColorFn` for more details). Any falsey value provided (either in list or as ColorFn return) will not highlight the given location (e.g. "transparent highlight").
`clear`	boolean	<optional>	true	Clear any current highlights on named layer before drawing more.
`lifetime`	Number	<optional>	0	Time (in milliseconds) before the highlighted ring is automatically cleared. A negative value or zero indicates "indefinitely". Ignored if `config.rings` is less than 1.

Returns

Examples

const name = 'rangefinder';
			const size = 2;
			const rings = 5;
			const colors = ['red', '#00FF00', 0x0000FF, false];
			
			// Draw a simple ring on the default layer
			warpgate.grid.highlightRing({x: token.x, y:token.y, rings:1});
			
			// Draw a larger temporary ring on the rangerfinder layer
			const highlights = warpgate.grid.highlightRing(
			    {x: token.x, y:token.y, rings, name}, 
			    {size, colors, clear: true, lifetime:2000});
			    
			ui.notifications.info(`Highlighted ${highlights.length} grid positions.`);

Details

Type Definitions

ColorFn( ringData, options )

Parameters

Name	Type	Description
`ringData`	object	Contains information about the current grid square/hex being highlighted.`x, y, ring` as <x,y> position and ring index (first is ring 0)
`options`	object	Highlight options passed to the initial call.

Returns

Details

ComparisonKeys

Description

string-string key-value pairs indicating which field to use for comparisons for each needed embeddedDocument type.

Examples

const comparisonKeys = {
			 ActiveEffect: 'label',
			 Item: 'name'
			}

Details

CrosshairsConfig

Description

This object controls how the crosshairs will be displayed and decorated. Each field is optional with its default value listed.

Properties

Name	Type	Attributes	Default	Description
`x`	number	<optional>	currentMousePosX	Initial x location for display
`y`	number	<optional>	currentMousePosY	Initial y location for display
`size`	number	<optional>	1	The initial diameter of the crosshairs outline in grid squares
`icon`	string	<optional>	'icons/svg/dice-target.svg'	The icon displayed in the center of the crosshairs
`direction`	number	<optional>	0	Initial rotation angle (in degrees) of the displayed icon (if any). 0 degrees corresponds to <0, 1> unit vector (y+ in screen space, or 'down' in "monitor space"). If this is included within a `WarpOptions` object, it is treated as a delta change to the token/update's current rotation value. Positive values rotate clockwise; negative values rotate counter-clockwise.
`label`	string	<optional>	''	The text to display below the crosshairs outline
`labelOffset`	Object	<optional>	{x:0,y:0}	Pixel offset from the label's initial relative position below the outline
`tag`	*	<optional>	'crosshairs'	Arbitrary value used to identify this crosshairs object
`drawIcon`	boolean	<optional>	true	Controls the display of the center icon of the crosshairs
`drawOutline`	boolean	<optional>	true	Controls the display of the outline circle of the crosshairs
`interval`	number	<optional>	2	Sub-grid granularity per square. Snap points will be created every 1/`interval` grid spaces. Positive values begin snapping at grid intersections. Negative values begin snapping at the center of the square. Ex. the default value of 2 produces two snap points -- one at the edge and one at the center; `interval` of 1 will snap to grid intersections; `interval` of -1 will snap to grid centers. Additionally, a value of `0` will turn off grid snapping completely for this instance of crosshairs.
`fillAlpha`	number	<optional>	0	Alpha (opacity) of the template's fill color (if any).
`fillColor`	string	<optional>	game.user.color	Color of the template's fill when no texture is used.
`rememberControlled`	boolean	<optional>	false	Will restore the previously selected tokens after using crosshairs.
`tileTexture`	boolean	<optional>	false	Indicates if the texture is tileable and does not need specific offset/scaling to be drawn correctly. By default, the chosen texture will be position and scaled such that the center of the texture image resides at the center of the crosshairs template.
`lockSize`	boolean	<optional>	true	Controls the ability of the user to scale the size of the crosshairs using shift+scroll. When locked, shift+scroll acts as a "coarse rotation" step for rotating the center icon.
`lockPosition`	boolean	<optional>	false	Prevents updating the position of the crosshair based on mouse movement. Typically used in combination with the `show` callback to lock position conditionally.
`texture`	string	<optional>		Asset path of the texture to draw inside the crosshairs border.

Details

CrosshairsData

Description

Contains all fields from MeasuredTemplate#toObject, plus the following.

Properties

Name	Type	Description
`cancelled`	boolean	Workflow cancelled via right click (true)
`scene`	Scene	Scene on this crosshairs was last active
`radius`	number	Final radius of template, in pixels
`size`	number	Final diameter of template, in grid units

Details

MenuButton

Properties

Name	Type	Attributes	Description
`label`	string		Display text for this button, accepts HTML.
`value`	*		Arbitrary object to return if selected.
`callback`	MenuCallback	<optional>	Additional callback to be executed when this button is selected. Can be used to modify the menu's results object.
`default`	boolean	<optional>	Any truthy value sets this button as default for the 'submit' or 'ENTER' dialog event. If none provided, the last button provided will be used.

Details

MenuCallback( result, html )

Parameters

Name	Type	Description
`result`	MenuResult	User's chosen values (by reference) for this menu. Can modify or expand return value.
`html`	HTMLElement	Menu DOM element.

Details

MenuConfig

Properties

Name	Type	Default	Description
`title`	string	'Prompt'	Title of dialog
`defaultButton`	string	'Ok'	Button label if no buttons otherwise provided
`checkedText`	boolean	false	Return the associated label's `innerText` (no html) of `'checkbox'` or `'radio'` type inputs as opposed to its checked state.
`close`	function	((resolve)=>resolve({buttons:false}))	Override default behavior and return value if the menu is closed without a button selected.
`render`	function	()=>{}
`options`	object		Passed to the Dialog options argument.

Details

MenuInput

Description

options property details

Input Type	Options Type	Default Value	Description
header, info	`none`	`undefined`	Ignored
text, password, number	`string`	`''`	Initial value of input
checkbox	`boolean`	`false`	Initial checked state
radio	`[string, boolean]`	`['radio', false]`	Group name and initial checked state, respectively
select	`{html: string, value: any, selected: boolean}[]` or `string[]`	`[]`	HTML string for select option element, the value to be return if selected, and initial state. If only a string is provided, it will be used as both the HTML and return value.

Properties

Name	Type	Attributes	Description
`type`	string		Type of input, controlling display and return values. See "options property details," above, and `MenuResult.button`.
`label`	string		Display text for this inputs label element. Accepts HTML.
`options`	boolean \| string \| Array.<(string\|boolean)>	<optional>	See "options property details," above.

Details

MenuResult

Description

inputs return details

Input Type	Return Type	Description
header, info	`undefined`
text, password, number	`string`	Final input value
checkbox, radio	`boolean\|string`	Final checked state. Using `checkedText` results in `""` for unchecked and `label` for checked.
select	`any`	`value` of the chosen select option, as provided by `MenuInput.options[i].value`

Properties

Name	Type	Description
`inputs`	Array	See "inputs return details," above.
`buttons`	*	`value` of the selected menu button, as provided by `MenuButton.value`

Details

MutationData

Properties

Name	Type	Description
`delta`	Shorthand
`user`	string
`comparisonKeys`	ComparisonKeys
`updateOpts`	Shorthand
`overrides`	object
`name`	string

Details

MutationOptions

Properties

Name	Type	Attributes	Default	Description
`permanent`	boolean	<optional>	false	Indicates if this should be treated as a permanent change to the actor, which does not store the update delta information required to revert mutation.
`name`	string	<optional>	randomId()	User provided name, or identifier, for this particular mutation operation. Used for reverting mutations by name, as opposed to popping last applied.
`delta`	Object	<optional>
`comparisonKeys`	ComparisonKeys	<optional>

Details

NoticeConfig

Description

Configuration obect for pan and ping (i.e. Notice) operations

Properties

Name	Type	Attributes	Default	Description
`ping`	boolean \| string	<optional>	false	Creates an animated ping at designated location if a valid ping style from the values contained in `CONFIG.Canvas.pings.types` is provided, or `'pulse'` if `true`
`pan`	boolean \| Number	<optional>	false	Pans all receivers to designated location if value is `true` using the configured default pan duration of `CONFIG.Canvas.pings.pullSpeed`. If a Number is provided, it is used as the duration of the pan.
`zoom`	Number	<optional>		Alters zoom level of all receivers, independent of pan/ping
`sender`	string	<optional>	game.userId	The user who triggered the notice
`receivers`	Array.<string>	<optional>	warpgate.USERS.SELF	An array of user IDs to send the notice to. If not provided, the notice is only sent to the current user.

Details

ParallelShow( crosshairs ) → {any}

Description

Callback started just prior to the crosshairs template being drawn. Is not awaited. Used for modifying how the crosshairs is displayed and for responding to its displayed position

All of the fields in the CrosshairsConfig object can be modified directly. Any fields owned by MeasuredTemplate must be changed via update|updateSource as other DocumentData|DataModel classes. Async functions will run in parallel while the user is moving the crosshairs. Serial functions will block detection of the left and right click operations until return.

Parameters

Name	Type	Description
`crosshairs`	Crosshairs	The live Crosshairs instance associated with this callback

Returns

Details

PostDelta( delta, tokenDoc ) → {Promise.<any>|any}

Description

The post delta creation, pre mutate callback. Called after the update delta has been generated, but before it is stored on the actor. Can be used to modify this delta for storage (ex. Current and Max HP are increased by 10, but when reverted, you want to keep the extra Current HP applied. Update the delta object with the desired HP to return to after revert, or remove it entirely.

Parameters

Name	Type	Description
`delta`	Shorthand	Computed change of the actor based on `updates`. Used to "unroll" this mutation when reverted.
`tokenDoc`	TokenDocument	Token being modified.

Returns

Details

PostMutate( tokenDoc, updates, accepted ) → {Promise.<any>|any}

Description

The post mutate callback prototype. Called after the actor has been mutated and after the mutate event has triggered. Useful for animations or changes that should not be tracked by the mutation system.

Parameters

Name	Type	Description
`tokenDoc`	TokenDocument	Token that has been modified.
`updates`	Shorthand	Current permutation of the original shorthand updates object provided, as applied for this mutation
`accepted`	boolean	Whether or not the mutation was accepted by the first owner.

Returns

Details

PostSpawn( location, spawnedToken, updates, iteration ) → {Promise.<boolean>|boolean}

Description

Post spawn callback. After the spawning and updating for this iteration occurs. Used for modifying the spawning for the next iteration, operations on the TokenDocument directly (such as animations or chat messages), and potentially aborting the spawning process entirely.

Parameters

Name	Type	Description
`location`	Object	Actual centerpoint of spawned token (affected by collision options).
`spawnedToken`	TokenDocument	Resulting token created for this spawning iteration
`updates`	Object	Current working "updates" object, which is modified for every iteration
`iteration`	number	Current iteration number (0-indexed) in the case of 'duplicates'

Returns

Details

PreSpawn( location, updates, iteration ) → {Promise.<boolean>|boolean}

Description

Pre spawn callback. After a location is chosen or provided, but before any spawning for this iteration occurs. Used for modifying the spawning data prior to each spawning iteration and for potentially skipping certain iterations.

Parameters

Name	Type	Description
`location`	Object	Desired centerpoint of spawned token.
`updates`	Object	Current working "updates" object, which is modified for every iteration
`iteration`	number	Current iteration number (0-indexed) in the case of 'duplicates'

Returns

Details

Shorthand

Description

Common 'shorthand' notation describing arbitrary data related to a spawn/mutate/revert process.

The token and actor key values are standard update or options objects as one would use in Actor#update and TokenDocument#update.

The embedded key uses a shorthand notation to make creating the updates for embedded documents (such as items) easier. Notably, it does not require the _id field to be part of the update object for a given embedded document type.

Properties

Name Type Attributes Description

token

object

Data related to the workflow TokenDocument.

actor

object

Data related to the workflow Actor.

embedded

Object.<string, (object|string)>

Keyed by embedded document class name (e.g. "Item" or "ActiveEffect"), there are three operations that this object controls -- adding, updating, deleting (in that order).

Operation	Value Interpretation
Add	Given the identifier of a non-existing embedded document, the value contains the data object for document creation compatible with `createEmbeddedDocuments`. This object can be constructed in-place by hand, or gotten from a template document and modified using `"Item To Add": game.items.getName("Name of Item").data`. As an example. Note: the name contained in the key will override the corresponding identifier field in the final creation data.
Update	Given a key of an existing document, the value contains the data object compatible with `updateEmbeddedDocuments`
Delete	A value of `warpgate.CONST.DELETE` will remove this document (if it exists) from the spawned actor. e.g. `{"Item Name To Delete": warpgate.CONST.DELETE}`

Details

SpawningOptions

Properties

Name Type Attributes Default Description

comparisonKeys

ComparisonKeys

Data paths relative to root document data used for comparisons of embedded shorthand identifiers

updateOpts

Shorthand

Options for the creation/deletion/updating of (embedded) documents related to this spawning

controllingActor

Actor

will minimize this actor's open sheet (if any) for a clearer view of the canvas during placement. Also flags the created token with this actor's id. Default null

duplicates

number

will spawn multiple tokens from a single placement. See also SpawningOptions.collision

collision

boolean

duplicates>1

controls whether the placement of a token collides with any other token or wall and finds a nearby unobstructed point (via a radial search) to place the token. If duplicates is greater than 1, default is true; otherwise false.

notice

NoticeConfig

will pan or ping the canvas to the token's position after spawning.

overrides

object

See corresponding property descriptions in WorkflowOptions

Name	Type	Attributes	Default	Description
`includeRawData`	boolean	<optional>	false
`preserveData`	boolean	<optional>	false

Details

WarpOptions

Properties

Name	Type	Attributes	Description
`crosshairs`	CrosshairsConfig	<optional>	A crosshairs configuration object to be used for this spawning process

Details

WorkflowOptions

Description

Workflow options

Properties

Name Type Attributes Default Description

updateOpts

Shorthand

Options for the creation/deletion/updating of (embedded) documents related to this mutation

description

string

Description of this mutation for potential display to the remote owning user.

notice

NoticeConfig

Options for placing a ping or panning to the token after mutation

noMoveWait

boolean

false

If true, will not wait for potential token movement animation to complete before proceeding with remaining actor/embedded updates.

overrides

Object

Name	Type	Attributes	Default	Description
`alwaysAccept`	boolean	<optional>	false	Force the receiving clients "auto-accept" state, regardless of world/client settings
`suppressToast`	boolean	<optional>	false	Force the initiating and receiving clients to suppress the "call and response" UI toasts indicating the requests accepted/rejected response.
`includeRawData`	boolean	<optional>	false	Force events produced from this operation to include the raw data used for its operation (such as the final mutation data to be applied, or the resulting packed actor data from a spawn). Caution, use judiciously -- enabling this option can result in potentially large socket data transfers during warpgate operation.
`preserveData`	boolean	<optional>	false	If enabled, the provided updates data object will be modified in-place as needed for internal Warp Gate operations and will NOT be re-usable for a subsequent operation. Otherwise, the provided data is copied and modified internally, preserving the original input for subsequent re-use.