[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

 

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 Buildings 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.