[Vanilla] Pawn - itb-community/ITB-ModLoader GitHub Wiki
Pawn
A Pawn
is what the game calls every unit on the game board. The mechs the player controls, the Vek they fight, and neutral entities like tanks are all Pawns. This page describes the functions of "Board Pawn", which is the pawns that exist on the board, as opposed to "Pawn Type" which is the pawns created during initialization.
- For a page about the
Pawn
class functions added by the mod loader, see Pawn. - For a page about the
Pawn
class functions added by the memedit, see Pawn.
Table of Contents
- AddMoveBonus
- AddWeapon
- ClearQueued
- Fall
- FireWeapon
- FlyAway
- GetArmedWeaponId
- GetBaseMove
- GetCustomPositionScore
- GetDangerScore
- GetDeathEffect
- GetFirstClick
- GetHealth
- GetId
- GetMechName
- GetMoveSpeed
- GetPathProf
- GetPersonality
- GetPilotLanguage
- GetPilotName
- GetSelectedWeapon
- GetSpace
- GetTarget
- GetTeam
- GetTurnCount
- GetType
- GuardPawn
- IsAbility
- IsAcid
- IsActive
- IsAvoidingMines
- IsBoosted
- IsBurrower
- IsBusy
- IsCorpse
- IsDamaged
- IsDead
- IsDeadly
- IsEnemy
- IsFire
- IsFlying
- IsFrozen
- IsGrappled
- IsGuarding
- IsInfected
- IsJumper
- IsMech
- IsNonGridStructure
- IsPlayer
- IsPowered
- IsRanged
- IsSelected
- IsShield
- IsTeleporter
- IsUndoPossible
- IsWeaponArmed
- Kill
- ModifyHealth
- Move
- ResetUses
- Retreat
- SetAcid
- SetActive
- SetCustomAnim
- SetFrozen
- SetHealth
- SetInfected
- SetInvisible
- SetMech
- SetMissionCritical
- SetMoveSpeed
- SetMutation
- SetNeutral
- SetPowered
- SetPriorityTarget
- SetShield
- SetSpace
- SetTeam
- SpawnAnimation
Functions
AddMoveBonus
Signature: void AddMoveBonus(int)
Gives the Pawn bonus movement speed. When called with positive values, also puts the "Kickoff Boosters" status effect on the Pawn. Calling this function with 0 removes the status effect, and bonus movement. Can be called with negative values to temporarily reduce the Pawn's movement speed.
Calling this after the Pawn has already moved does not allow it to move again this turn.
AddWeapon
Signature: void AddWeapon(string)
Adds the specified weapon to the pawn.
ClearQueued
Signature: void ClearQueued()
Clears (cancels) all attacks this Pawn has queued, as if it were affected by smoke.
Fall
Signature: void Fall(int)
Acts differently depending on the value it is called with. -1 and below makes the pawn visually fall down for about one tile worth of height, then reappear where it was.
0 makes the pawn fall from the sky, like a mech's spawning animation, except it starts about one tile above the pawn and not at the top of the screen.
1 is like -1 except the pawn rises from below instead of falling. It looks jarring because the pawn is displayed on top of the tiles regardless.
2 makes the pawn fall as though its tile were a chasm, killing it.
3 makes the pawn ascend to the top of the screen, killing it.
4 is like 2 except the animation seems faster.
5 does nothing.
6 and above act like -1 and below.
To test:
- sounds? I tested this on mute.
- does it work on Vek? I tested this on mechs because it was easier to find them with the console.
- does 5 really do nothing?
- test on flying mechs and flying Vek as well
FireWeapon
Signature: boolean FireWeapon(Point, int)
Orders the Pawn to fire its weapon in the specified index at the specified location. This ends the Pawn's turn, but can be used to fire the Pawn's weapon even if its turn is over. Returns false
if the weapon cannot be fired at the specified point, or the Pawn doesn't have a weapon equipped at the specified index. true
if the weapon has been successfully fired.
Index is 1-based: value of 1 corresponds to the first weapon the Pawn has equipped; 2 to the second weapon.
Note: if the weapon in the specified index is a passive, the Pawn's turn is ended and the screen shakes, but no damage is done.
FlyAway
Signature: void FlyAway()
Causes the Pawn to fly away upwards, and die instantly.
GetArmedWeaponId
Signature: int GetArmedWeaponId()
For player-controlled Pawns and while in targeting mode, returns index of the weapon that the player is currently aiming. Returns -1
otherwise.
GetBaseMove
Signature: int GetBaseMove()
Returns the current move speed of this Pawn, including any boosts received from pilot abilities or passives such as Kickoff Boosters
. Essentially, it returns the number shown in the move speed icon when selecting a pawn.
GetCustomPositionScore
Signature: int GetCustomPositionScore(Point)
Calculates custom score for the pawn's positioning for the given point.
GetDangerScore
Signature: int GetDangerScore()
Returns danger score for the pawn. Appears to return -10 for all pawns. Oddly enough, used in positioning scoring algorithm to determine score of tiles that are targeted by a queued attack. So you can use that to make suicidal enemies, or ones that prioritize attacking over their own safety.
GetFirstClick
Signature: Point GetFirstClick()
Returns the point of the first click selected by a player in a two click weapon. In more detail; If a two click weapon is selected and the first click has been made, but not the second, it returns the point corresponding to the first click. Otherwise, returns Point(1000,1000)
.
GetDeathEffect
Signature: SkillEffect GetDeathEffect()
Returns a SkillEffect that's supposed to be executed once the pawn dies. This is a function defined on the Pawn table, not userdata.
GetHealth
Signature: int GetHealth()
Returns a number indicating the amount of remaining health this Pawn has.
GetId
Signature: int GetId()
Returns a number the game uses to uniquely identify this particular Pawn.
GetMechName
Signature: string GetMechName()
Returns the Pawn's display name. Works for Vek as well. Examples: for PunchMech
returns Punch Mech
; for Leaper1
returns Leaper
.
GetMoveSpeed
Signature: int GetMoveSpeed()
Returns the number of squares the Pawn can move (ie. its move speed).
GetPathProf
Signature: boolean GetPathProf()
Returns the pawn's pathing profile - bitmask with the following values:
-- 0 - 00000000 - PATH_GROUND - pass over empty tiles (every unit can do this)
-- 1 - 00000001 - PATH_FLYER - pass over units, buildings, mountains, water, chasms
-- 2 - 00000010 - PATH_MASSIVE - pass over water-like tiles
-- 4 - 00000100 - PATH_PHASING - pass through units, even if they're from another team
-- 8 - 00001000 - PATH_ROADRUNNER - appears to have no special features over PATH_GROUND?
-- 16 - 00010000 - TEAM_PLAYER - block passage for units from other teams
-- 32 - 00100000 - TEAM_ANY - block passage for units from other teams
-- 64 - 01000000 - TEAM_ENEMY - block passage for units from other teams
-- 128 - 10000000 - TEAM_BOTS - block passage for units from other teams
There's also PATH_PROJECTILE
, which is a constant with value of 3
, ie. PATH_MASSIVE
+ PATH_FLYER
GetPersonality
Signature: string GetPersonality()
Returns the name of the Personality associated with the pilot of the Pawn. Returns Artificial
for unpiloted Mechs, Pawns with no pilot and Vek.
GetPilotLanguage
Signature: int GetPilotLanguage()
I have no idea what this does. It has only ever returned zero for me.
GetPilotName
Signature: string GetPilotName(int)
Returns the last name of the Pawn's pilot. For Vek, returns their display name.
GetSelectedWeapon
Signature: int GetSelectedWeapon()
For Pawns with a queued attack, returns index of the weapon whose attack has been queued.
GetSpace
Signature: Point GetSpace()
Returns the position of this Pawn on the game board as a Point.
GetTarget
Signature: Point GetTarget()
Appears to always return a Point with both x
and y
set to -1.
GetTeam
Signature: int GetTeam()
Returns number representing the team this Pawn belongs to:
- TEAM_ANY
- TEAM_BOTS
- TEAM_ENEMY
- TEAM_ENEMY_MAJOR
- TEAM_MECH
- TEAM_NONE
- TEAM_PLAYER
GetTurnCount
Signature: int GetTurnCount()
Returns the number of turns the Pawn has been alive for.
GetType
Signature: string GetType()
Returns the name of the pawn in Lua files. For example, for the Rift Walker's Prime mech, this function returns PunchMech
; for the basic Leaper Vek, this function returns Leaper1
, and so on.
GuardPawn
Signature: void GuardPawn(boolean)
Doesn't make the Pawn unpushable. Appears to have no effect, regardless of the argument.
IsAbility
Signature: boolean IsAbility(string)
Checks whether this Pawn has the specified pilot skill, and if that skill requires power to function, checks if it is powered. If so, returns true
; otherwise returns false
.
IsAcid
Signature: boolean IsAcid()
Returns true
if this Pawn is affected by ACID. false
otherwise.
IsActive
Signature: boolean IsActive()
Returns true
if this Pawn can still move this turn. false
if this Pawn has already moved this turn.
IsAvoidingMines
Signature: boolean IsAvoidingMines()
Returns true
if this Pawn tries to avoid mines when selecting tiles for movement. This is generally set to false for all pawns, except mine-laying bots on Pinnacle island.
IsBoosted
Returns true
if this Pawn is boosted. false
otherwise.
IsBurrower
Returns true
if this Pawn is a burrower. false
otherwise.
IsBusy
Signature: boolean IsBusy()
Probably behaves similarly to Board:IsBusy()
, which returns true as long as there's an action happening on the board, such as a pawn moving, vek burrowing out, weapon firing, etc.
IsCorpse
Signature: boolean IsCorpse()
Returns true
if this Pawn can become a corpse, NOT if it currently is a corpse. Corpses will also return true
. false
otherwise. Essentially, if Corpse = true
in the Pawns definition.
IsDamaged
Signature: boolean IsDamaged()
Returns true
if this Pawn has been damaged and is no longer at full HP. Returns false
otherwise. If this Pawn has taken damage and then regained the lost health, this function returns false
.
IsDead
Signature: boolean IsDead()
Returs true
if Pawn's health is at 0. false
otherwise.
IsDeadly
Signature: boolean IsDeadly(SpaceDamage)
Same as Board:IsDeadly()
but with a Pawn instead. Returns true
if the given SpaceDamage would kill this Pawn.
NOTE: This method does not account for push damage, chasms, water, etc. and will only consider direct damage and cracked ground.
IsEnemy
Signature: boolean IsEnemy()
Returns true
if the Pawn is hostile to the player. false
if it is friendly or neutral.
IsFire
Signature: boolean IsFire()
Returns true
if the Pawn is afflicted by the Fire status. false
otherwise.
IsFlying
Signature: boolean IsFlying()
Returns true
if this Pawn is flying. false
otherwise.
IsFrozen
Signature: boolean IsFrozen()
Returns true
if this Pawn is frozen. false
otherwise.
IsGrappled
Signature: boolean IsGrappled()
Returns true
if the Pawn is caught in webbing, and unable to move. false
otherwise.
IsGuarding
Signature: boolean IsGuarding()
Returns true
if this Pawn is immune to push effects. false
otherwise
IsInfected
Signature: boolean IsInfected()
Returns true
if this Pawn is infected with the Vek Mite Infection
aka Mites. false
otherwise.
IsJumper
Signature: boolean IsJumper()
Returns true
if this Pawn moves by leaping to its destination. false
otherwise.
IsMech
Signature: boolean IsMech()
Returns true
if this Pawn is a mech, ie. has the Repair
skill. false
otherwise.
IsNonGridStructure
Signature: boolean IsNonGridStructure()
Returns true
if this Pawn is considered a non-grid structure (seemingly random). false
otherwise.
Examples of true
: Decoy Building
s from RST, A.C.I.D. Storm Generator
from Detritus
Examples of false
: Earth Mover
from RST, Detritus Contraption
from Detritus, Satellite Rocket
from Archive.
IsPlayer
Signature: boolean IsPlayer()
Appears to returns true
if this Pawn is not hostile to the player, regardless of whether the player can actually control the pawn or not. false
for enemy pawns.
IsPowered
Signature: boolean IsPowered()
Returns false
if this Pawn is Not Powered
, a status effect that prevents all movement and attack. true
otherwise. Mostly just used in certain missions to disable Pawns for a period of time.
IsRanged
Signature: boolean IsRanged()
Returns true
if this Pawn is marked with the Ranged
tag (Ranged = 1
). false
otherwise. This function is inconsistent, as not all ranged Vek are marked with the Ranged
tag, as it is used to determine whether the AI should try to get close or not. For example. Moths have an artillery attack, but are marked as not ranged to encourage them to get more value from their push back. Fireflies, Scarabs etc. are marked with Ranged
though.
IsSelected
Signature: boolean IsSelected()
Returns true
if the Pawn is currently selected by the player. false
otherwise.
Note: during enemy turn, Pawns taking action are automatically selected.
IsShield
Signature: boolean IsShield()
Returns true
if the Pawn is shielded. false
otherwise.
IsTeleporter
Signature: boolean IsTeleporter()
Returns true
if this Pawn moves by teleporting directly to its destination. false
otherwise.
IsUndoPossible
Signature: boolean IsUndoPossible()
Returns true
if the Pawn's action can be undone. False otherwise.
IsWeaponArmed
Signature: boolean IsWeaponArmed()
Returns true
if the Pawn is selected, and:
- it hasn't moved yet (in this case, Move skill's aiming preview is always visible on the board)
- a weapon is selected and being aimed
- the repair skill is selected and being aimed
Appears to always return false
for non-player pawns.
Kill
Signature: void Kill(boolean)
Instantly kills this Pawn. Passing true
as argument suppreses the death animation. Passing false
plays the death animation as if the pawn was killed during normal gameplay.
Note: this function failed to kill a Pawn that had 999 HP.
ModifyHealth
Signature: void ModifyHealth(int, boolean, int)
I have absolutely no idea what this does, it seems to do nothing.
Move
Signature: boolean Move(Point)
Orders the Pawn to move towards the specified point. This function ignores the Pawn's normal move speed, meaning that as long as there is a path to the specified point, the Pawn will reach it. If the point is occupied by another Pawn, building, mountain, or another obstacle, the Pawn will move to the nearest available point. If no path is available (eg. blocked by Vek), then the Pawn will not move. If the Pawn's turn is over, this function does nothing and returns false
. Otherwise appears to always return true
(even for points outside of the game board).
ResetUses
Signature: void ResetUses()
Resets the uses counter on weapons with a limited number of uses.
Retreat
Signature: void Retreat()
Appears to just kill the Pawn. Normal death animation is played, Vek do not burrow away.
SetAcid
Signature: void SetAcid(boolean)
Setting this to true
makes the Pawn affected by ACID. Setting to false
removes it.
SetActive
Signature: void SetActive(boolean)
Setting this to false
marks the Pawn as having already made its move this turn. Can be set back to true
to mark the Pawn as if it hasn't made its move this turn yet.
Setting this to true
after the Pawn has already made its move this turn will allow it to attack again. If the Pawn has attacked without moving, this allows the Pawn to move again.
SetCustomAnim
Signature: void SetCustomAnim(string)
Sets the animation of the pawn to the animation with the specified name.
This allows to change the appearance of a pawn for the remainder of the mission. The argument can be either an animation namespace (eg. MechPunch
) - in which case the pawn will use all animations within that namespace (a
, _broken
, death
, etc.) or a specific animation (eg. MechPunch_broken
). Any animation defined in animations.lua
is a valid argument.
The appearance persists after the mission is over, displaying the custom animation in island view. However, it is reset back to the mech's normal appearance when a new mission is started.
To revert back to the pawn's default animation, use pawn:SetCustomAnim(_G[pawn:GetType()].Image)
SetFrozen
Signature: void SetFrozen(boolean)
Setting this to true
freezes the Pawn, encasing it in ice. Setting this to false
frees the Pawn from ice. Animations play as expected.
SetHealth
Signature: void SetHealth(int)
Makes this Pawn have the health indicated by the int. If the int is equal to or less than zero, this Pawn dies. If the int is equal to or greater than max health, it goes to max, but can not go above max. If anywhere in between, it sets its health to that value.
SetInfected
Signature: void SetInfected(boolean)
Makes this Pawn infected with the Vek Mites Infection
aka Mites. Only known use of the infections is in the Clear All Mites off of your Mechs
mission.
SetInvisible
Signature: void SetInvisible(boolean)
Makes this Pawn invisible. Invisible pawns still occupy spaces they stand on, and can be selected by the player. Invisible enemies still execute their attacks, and their attack predictions are still visible to the player.
SetMech
Signature: void SetMech()
Sets the type of the unit to mech. Gives the pawn the Repair
skill.
SetMissionCritical
Signature: void SetMissionCritical(boolean)
Appears to have no effect.
SetMoveSpeed
Signature: void SetMoveSpeed(int)
Sets the move speed of this Pawn to the specified value. Negative values are capped to 0.
SetMutation
Signature: void SetMutation(int)
Appears to be used to apply effects of Psions' auras to the Pawn. Visual and sound effects associated with each status effect are played, and the status effect is applied to the Pawn. If there's no Psion associated with the given effect currently on the board and on the Pawn's team, the effect is immediately removed.
Calling this function when the Pawn is affected by the specified aura has no effect. Calling it with a different argument when the Pawn is already affected by another aura clears the old aura's effect.
Argument value | Description |
---|---|
0 | Removes existing mutation (no effect if not affected by any mutation) |
1 | Extra health |
2 | Unknown (missing effect icon) |
3 | Unknown (missing effect icon) |
4 | Regeneration |
5 | Armored |
6 | Explosive |
7 | Overpowered |
8 | Tentacle (damage every turn) |
SetNeutral
Signature: void SetNeutral(boolean)
Has no apparent effect for player's mechs and enemy pawns. For non-mech pawns under the player's control, setting this to true
allows to revoke the player's control over the Pawn. Setting to false
restores player's control over the pawn. Neutral units are controlled by the computer during enemy turn.
SetPowered
Signature: void SetPowered(boolean)
Settings this to false
causes the Pawn to become permanently inactive, until set back to true
. The Pawn will not become active during its turn, and its animation will be suspended.
SetPriorityTarget
Signature: void SetPriorityTarget(Point)
Limits targeting area of the Pawn to the specified point. Appears to have no effect on player-controlled units.
SetShield
Signature: void SetShield(boolean)
Setting this to true
puts a shield bubble on the Pawn. Setting to false
removes the shield. Animation plays as expected, but there's no sound.
SetSpace
Signature: void SetSpace(Point)
Forcibly moves the Pawn to the specified point, ignoring all game limitations. Can be used to move the Pawn on top of another pawn, a building, or mountain -- even outside the game board.
SetTeam
Signature: void SetTeam(int)
Sets the team of the Pawn. This changes ownership of the Pawn, making it hostile to the player or controllable by them. Team constants:
- TEAM_ANY
- TEAM_BOTS
- TEAM_ENEMY
- TEAM_ENEMY_MAJOR
- TEAM_MECH
- TEAM_NONE
- TEAM_PLAYER
SpawnAnimation
Signature: void SpawnAnimation()
Plays the Pawn's spawning animation. Mechs fall down the sky, Vek burrow out of the ground.