weaponPreview

`weaponPreview`

A library with methods that can be used in non-queued skills' GetTargetArea and GetSkillEffect methods; and in queued skills' GetSkillEffect method.

The methods adds preview marks on the in-game board when activating the skills. Since they only adds to the preview, the effects they display will not alter the board state when the skill is used. This can be useful to for example add back lost information due to having coded parts of the skill within scripts, which won't display by default.

It can also be used to add animations, emitters or other cool effects to the attack preview.

When using several methods (like two animations) for the same skill, it is possible to run them on top of each other, or to run them in sequence, depending on how you set it up.

The library also comes with a set of functions and events that can be used to get information about the current state of which unit is marking the board and with what weapon.

Terminology:

`preview`

The collection of all marks added during a GetTargetArea or GetSkillEffect

`mark`

Calling any of the methods starting with Add- adds a mark to the preview

`length`

marks can have a length. Most marks has a length of zero (0). The total length of the preview will be the smallest length needed to contain all mark's lengths. If all marks starts at the same time, the total length will be the largest length of any mark.

Methods that can add length:

method
AddDelay
AddAnimation

`duration`

marks can have a duration. If not specified, it is infinite. The duration is what specifies how long the mark will be displayed from when it starts playing. duration does not change length.

`delay`

delay can be added to the preview to space out when the next mark added will begin playing. This will also space out marks so the total length of the preview will increase.

Methods that can add delay:

method
AddDelay
AddAnimation

`loop`

By default the preview will be looping. This can be disabled with SetLooping(false). Animations with the animation field Loop set to true will loop for the entire preview regardless however.

`AddAnimation`

void weaponPreview:AddAnimation(point, animation, delay)

Argument name	Type	Description
`point`	Point	The location on the board to add the animation
`animation`	string	The name of the animation in the `ANIMS` table
`delay`	number	(Optional) Pass `ANIM_DELAY` to add a delay equal to the duration of this animation

Adds a mark to the preview, playing an animation on a point on the board. Most animations should work out of the box.

If the animation's field Loop is equal to true, the animation will play for the entire preview.

The duration and length of this mark is defined by the total length of the animation in the ANIMS table.

If ANIM_DELAY is passed as Argument #3, then a delay will be added before the next mark

Example:

local point = Point(0, 0) 
local anim = "FireBack" 
weaponPreview:AddAnimation(point, anim)

`AddColor`

void weaponPreview:AddColor(point, gl_color, duration)

Argument name	Type	Description
`point`	Point	The location on the board to display the color
`gl_color`	GL_Color	The color to display
`duration`	number	(Optional) The duration to display the color. Defaults to `infinite`

Adds a mark to the preview, displaying a color on a point on the board.

Example:

local point = Point(0, 0) 
local color = GL_Color(255, 255, 255, 255) 
weaponPreview:AddColor(point, anim)

`AddDamage`

void weaponPreview:AddDamage(spaceDamage, duration)

Argument name	Type	Description
`spaceDamage`	SpaceDamage	The SpaceDamage object to display
`duration`	number	(Optional) The duration to display the SpaceDamage object. Defaults to `infinite`

Adds a mark to the preview, displaying a SpaceDamage object on the board.

Example:

local point = Point(0, 0) 
local damage = 2 
local spaceDamage = SpaceDamage(point, damage) 
weaponPreview:AddDamage(spaceDamage)

`AddDelay`

void weaponPreview:AddDelay(delay)

Argument name	Type	Description
`delay`	number	The delay to wait before displaying the next mark

Adds a mark to the preview, adding a delay before the next mark, and has a length of the same amount.

Example:

local delayInSeconds = 1 
weaponPreview:AddDelay(delayInSeconds)

`AddDesc`

void weaponPreview:AddDesc(point, desc, isDeadly, duration)

Argument name	Type	Description
`point`	Point	The location on the board to display the tile description
`desc`	string	The description to display for the tile
`isDeadly`	boolean	(Optional) Whether to mark the tile as deadly or not. Defaults to `true`
`duration`	number	(Optional) The duration to display the description object. Defaults to `infinite`

Adds a mark to the preview, displaying a description for the specified tile.

Example:

local point = Point(0, 0) 
local description = "This is a dangerous tile" 
weaponPreview:AddDesc(point, description)

`AddEmitter`

void weaponPreview:AddEmitter(point, emitter, duration)

Argument name	Type	Description
`point`	Point	The location on the board to display the emitter
`emitter`	string	The internal name for the emitter
`duration`	number	(Optional) The duration to display the emitter. Defaults to `infinite`

Adds a mark to the preview, playing an emitter on a point on the board.

Example:

local point = Point(0, 0) 
local emitter = "Emitter_tiles_grass" 
weaponPreview:AddEmitter(point, emitter)

`AddFlashing`

void weaponPreview:AddFlashing(point, flash, duration)

Argument name	Type	Description
`point`	Point	The location on the board to cause to flash
`flash`	boolean	(Optional) Whether to cause the grid icons on a tile to start flashing or not. Defaults to `true`
`duration`	number	(Optional) The duration to play the flashing. Defaults to `infinite`

Adds a mark to the preview, causing grid icons of buildings to flash on a point on the board.

Example:

local point = Point(0, 0) 
weaponPreview:AddFlashing(point)

`AddImage`

void weaponPreview:AddImage(point, path, gl_color, duration)

Argument name	Type	Description
`point`	Point	The location on the board to display the image
`path`	string	The path to the image to display
`gl_color`	GL_Color	The color tint added to the image
`duration`	number	(Optional) The duration to display the image. Defaults to `infinite`

Adds a mark to the preview, displaying an image on a point on the board.

Example:

local point = Point(0, 0) 
local path = "img/combat/tile_icon/tile_rock.png" 
local gl_color = GL_Color(255, 255, 255, 255) 
weaponPreview:AddImage(point, path, gl_color)

`AddSimpleColor`

void weaponPreview:AddSimpleColor(point, gl_color, duration)

Argument name	Type	Description
`point`	Point	The location on the board to display the color
`gl_color`	GL_Color	The color to display
`duration`	number	(Optional) The duration to display the color. Defaults to `infinite`

Adds a mark to the preview, displaying a color on a point on the board. Simple colors can not stack.

Example:

local point = Point(0, 0) 
local gl_color = GL_Color(255, 255, 255, 255) 
weaponPreview:AddSimpleColor(point, gl_color)

`ClearMarks`

void weaponPreview:ClearMarks()

Clears all marks added to the preview. Added for brevity.

Example:

weaponPreview:ClearMarks()

`GetQueuedSkillEffectMarker`

number, string, number weaponPreview:GetQueuedSkillEffectMarker()

Returns 3 variables describing the queued weapon currently marking the board. A queued weapon will mark the board when a unit that is queueing a weapon is highlighted, and there is no armed weapon marking the board with GetSkillEffect. If there's currently no queued weapon marking the board, this function will return -1, "", -1.

Variable name	Type	Description
pawnId	number	The id of the pawn marking the board
weapon	string	The queued weapon marking the board
weaponIndex	number	The weapon index of the weapon marking the board

Weapon Index	Description
-1	No Weapon
0	Move
1	Primary Weapon
2	Secondary Weapon
50	Repair Skill

Example:

LOGF("Pawn with id %q, with weapon %s in weapon index %s is currently marking the board", weaponPreview:GetQueuedSkillEffectMarker())

`GetSkillEffectMarker`

number, string, number weaponPreview:GetSkillEffectMarker()

Returns 3 variables describing the armed weapon currently marking the board with its GetSkillEffect. An armed weapon will mark the board with its GetSkillEffect when it's armed and highlighting a valid tile as defined by its GetTargetArea. If there's no armed weapon currently marking the board with its GetSkillEffect, this function will return -1, "", -1.

Variable name	Type	Description
pawnId	number	The id of the pawn marking the board
weapon	string	The armed weapon marking the board
weaponIndex	number	The weapon index of the weapon marking the board

Weapon Index	Description
-1	No Weapon
0	Move
1	Primary Weapon
2	Secondary Weapon
50	Repair Skill

Example:

LOGF("Pawn with id %q, with weapon %s in weapon index %s is currently marking the board", weaponPreview:GetSkillEffectMarker())

`GetTargetAreaMarker`

number, string, number weaponPreview:GetTargetAreaMarker()

Returns 3 variables describing the armed weapon currently marking the board with its GetTargetArea. An armed weapon will continuously mark the board with its GetTargetArea whenever it's armed. If there's no armed weapon currently marking the board, this function will return -1, "", -1.

Variable name	Type	Description
pawnId	number	The id of the pawn marking the board
weapon	string	The armed weapon marking the board
weaponIndex	number	The weapon index of the weapon marking the board

Weapon Index	Description
-1	No Weapon
0	Move
1	Primary Weapon
2	Secondary Weapon
50	Repair Skill

Example:

LOGF("Pawn with id %q, with weapon %s in weapon index %s is currently marking the board", weaponPreview:GetTargetAreaMarker())

`IsQueuedSkillEffectMarker`

boolean weaponPreview:IsQueuedSkillEffectMarker()

Returns true if there is currently a queued weapon marking the board; otherwise false. A queued weapon will mark the board when a unit that is queueing a weapon is highlighted, and there is no armed weapon marking the board with GetSkillEffect.

Example:

LOGF("A queued weapon is currently marking the board: %s", weaponPreview:IsQueuedSkillEffectMarker())

`IsSkillEffectMarker`

boolean weaponPreview:IsSkillEffectMarker()

Returns true if there's currently an armed weapon marking the board with its GetSkillEffect; otherwise false. An armed weapon will mark the board with its GetSkillEffect when it's armed and highlighting a valid tile as defined by its GetTargetArea.

Example:

LOGF("An armed weapon is currently marking the board with 'GetSkillEffect': %s", weaponPreview:IsSkillEffectMarker())

`IsTargetAreaMarker`

boolean weaponPreview:IsTargetAreaMarker()

Returns true if there's currently an armed weapon marking the board with its GetTargetArea; otherwise false. An armed weapon will continuously mark the board with its GetTargetArea whenever it's armed.

Example:

LOGF("An armed weapon is currently marking the board with 'GetTargetArea': %s", weaponPreview:IsTargetAreaMarker())

`ResetQueuedSkillEffectTimer`

void weaponPreview:ResetQueuedSkillEffectTimer()

Resets the timer used to keep track of which mark to play during a preview of a queued weapon's GetSkillEffect.

Example:

weaponPreview:ResetQueuedSkillEffectTimer()

`ResetSkillEffectTimer`

void weaponPreview:ResetSkillEffectTimer()

Resets the timer used to keep track of which mark to play during a preview of an armed weapon's GetSkillEffect. Can for instance be used in the beginning of GetSkillEffect to force a preview to always start from the beginning when targetting a new tile.

Example:

weaponPreview:ResetSkillEffectTimer()

`ResetTargetAreaTimer`

void weaponPreview:ResetTargetAreaTimer()

Resets the timer used to keep track of which mark to play during a preview of an armed weapon's GetTargetArea.

Example:

weaponPreview:ResetTargetAreaTimer()

`SetLooping`

void weaponPreview:SetLooping(loop)

Argument name	Type	Description
`loop`	boolean	Whether to enable or disable looping. Defaults to `true`

Disables looping if false. Otherwise enables looping.

Example:

weaponPreview:SetLooping(false)

events

The following events can be subscribed to, in order to be informed when the current marker changes.

Documentation on how to use events: Event System

`onQueuedSkillEffectHidden`

void onQueuedSkillEffectHidden:subscribe(eventHandler)

Argument name	Type	Description
`pawnId`	number	The id of the pawn queueing the weapon
`weapon`	string	The weapon being queued
`weaponIndex`	number	The weapon index of the weapon being queued

Dispatched when a queued weapon stops marking the board. A queued weapon will mark the board when a unit that is queueing a weapon is highlighted, and there is no armed weapon marking the board with GetSkillEffect.

Example:

local handler = function(pawnId, weapon, weaponIndex)
	LOGF(
		"Pawn with pawnId %s stopped marking with "..
		"its queued weapon %q with weapon index %s",
		pawnId,
		weapon,
		weaponIndex
	)
end

weaponPreview.events.onQueuedSkillEffectHidden:subscribe(handler)

`onQueuedSkillEffectShown`

void onQueuedSkillEffectShown:subscribe(eventHandler)

Argument name	Type	Description
`pawnId`	number	The id of the pawn queueing the weapon
`weapon`	string	The weapon being queued
`weaponIndex`	number	The weapon index of the weapon being queued

Dispatched when a queued weapon begins marking the board. A queued weapon will mark the board when a unit that is queueing a weapon is highlighted, and there is no armed weapon marking the board with GetSkillEffect.

Example:

local handler = function(pawnId, weapon, weaponIndex)
	LOGF(
		"Pawn with pawnId %s started marking with "..
		"its queued weapon %q with weapon index %s",
		pawnId,
		weapon,
		weaponIndex
	)
end

weaponPreview.events.onQueuedSkillEffectShown:subscribe(handler)

`onSkillEffectHidden`

void onSkillEffectHidden:subscribe(eventHandler)

Argument name	Type	Description
`pawnId`	number	The id of the pawn arming the weapon
`weapon`	string	The weapon being armed
`weaponIndex`	number	The weapon index of the weapon being armed

Dispatched when an armed weapon stops marking the board with its GetSkillEffect. An armed weapon will mark the board with its GetSkillEffect when it's armed and highlighting a valid tile as defined by its GetTargetArea.

Example:

local handler = function(pawnId, weapon, weaponIndex)
	LOGF(
		"Pawn with pawnId %s stopped marking with "..
		"GetSkillEffect with its armed weapon %q "..
		"with weapon index %s",
		pawnId,
		weapon,
		weaponIndex
	)
end

weaponPreview.events.onSkillEffectHidden:subscribe(handler)

`onSkillEffectShown`

void onSkillEffectShown:subscribe(eventHandler)

Argument name	Type	Description
`pawnId`	number	The id of the pawn arming the weapon
`weapon`	string	The weapon being armed
`weaponIndex`	number	The weapon index of the weapon being armed

Dispatched when an armed weapon begins marking the board with its GetSkillEffect. An armed weapon will mark the board with its GetSkillEffect when it's armed and highlighting a valid tile as defined by its GetTargetArea.

Example:

local handler = function(pawnId, weapon, weaponIndex)
	LOGF(
		"Pawn with pawnId %s started marking with "..
		"GetSkillEffect with its armed weapon %q "..
		"with weapon index %s",
		pawnId,
		weapon,
		weaponIndex
	)
end

weaponPreview.events.onSkillEffectShown:subscribe(handler)

`onTargetAreaHidden`

void onTargetAreaHidden:subscribe(eventHandler)

Argument name	Type	Description
`pawnId`	number	The id of the pawn arming the weapon
`weapon`	string	The weapon being armed
`weaponIndex`	number	The weapon index of the weapon being armed

Dispatched when an armed weapon stops marking the board with its GetTargetArea. An armed weapon will continuously mark the board with its GetTargetArea whenever it's armed.

Example:

local handler = function(pawnId, weapon, weaponIndex)
	LOGF(
		"Pawn with pawnId %s stopped marking with "..
		"GetTargetArea with its armed weapon %q "..
		"with weapon index %s",
		pawnId,
		weapon,
		weaponIndex
	)
end

weaponPreview.events.onTargetAreaHidden:subscribe(handler)

`onTargetAreaShown`

void onTargetAreaShown:subscribe(eventHandler)

Argument name	Type	Description
`pawnId`	number	The id of the pawn arming the weapon
`weapon`	string	The weapon being armed
`weaponIndex`	number	The weapon index of the weapon being armed

Dispatched when an armed weapon starts marking the board with its GetTargetArea. An armed weapon will continuously mark the board with its GetTargetArea whenever it's armed.

Example:

local handler = function(pawnId, weapon, weaponIndex)
	LOGF(
		"Pawn with pawnId %s started marking with "..
		"GetTargetArea with its armed weapon %q "..
		"with weapon index %s",
		pawnId,
		weapon,
		weaponIndex
	)
end

weaponPreview.events.onTargetAreaShown:subscribe(handler)

weaponPreview

Table of Contents

weaponPreview

Terminology:

preview

mark

length

duration

delay

loop

AddAnimation

AddColor

AddDamage

AddDelay

AddDesc

AddEmitter

AddFlashing

AddImage

AddSimpleColor

ClearMarks

GetQueuedSkillEffectMarker

GetSkillEffectMarker

GetTargetAreaMarker

IsQueuedSkillEffectMarker

IsSkillEffectMarker

IsTargetAreaMarker

ResetQueuedSkillEffectTimer

ResetSkillEffectTimer

ResetTargetAreaTimer

SetLooping

events

onQueuedSkillEffectHidden

onQueuedSkillEffectShown

onSkillEffectHidden

onSkillEffectShown

onTargetAreaHidden

onTargetAreaShown

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally

`weaponPreview`

`preview`

`mark`

`length`

`duration`

`delay`

`loop`

`AddAnimation`

`AddColor`

`AddDamage`

`AddDelay`

`AddDesc`

`AddEmitter`

`AddFlashing`

`AddImage`

`AddSimpleColor`

`ClearMarks`

`GetQueuedSkillEffectMarker`

`GetSkillEffectMarker`

`GetTargetAreaMarker`

`IsQueuedSkillEffectMarker`

`IsSkillEffectMarker`

`IsTargetAreaMarker`

`ResetQueuedSkillEffectTimer`

`ResetSkillEffectTimer`

`ResetTargetAreaTimer`

`SetLooping`

`onQueuedSkillEffectHidden`

`onQueuedSkillEffectShown`

`onSkillEffectHidden`

`onSkillEffectShown`

`onTargetAreaHidden`

`onTargetAreaShown`