Skip to content

Battle

Battlefield query interface. The handle scripts receive whenever they are passed a battle context — enumerate units and obstacles, test hex accessibility and shooting penalties, inspect wall state on siege maps. Read-only; mutations go through Server.

getTacticDistance

Returns the available tactic phase distance, or 0 if the tactic phase has ended.

  • returns integer

getAvailableHex

Returns an empty hex next to desired location that the creature can be placed on.

  • param creature: Creature — Creature template whose footprint is being placed.
  • param side: BattleSide — Side whose deployment area to search.

  • param hex: BattleHex? — Preferred origin hex; nil falls back to a side-appropriate default.

  • returns BattleHex — Empty hex closest to the desired location that fits the creature, or INVALID if none.

getUnitsIf

Returns all units for which the predicate returns true.

  • param predicate: fun(u: Unit): boolean — Selector — called for each unit on the battlefield; unit is kept when it returns true.

  • returns Unit[] — Units for which the predicate returned true.

isAccessibleForUnit

True if the given hex is reachable by the given unit either on current turn or on any future turns.

  • param unit: Unit — Unit whose movement model is consulted.

  • param hex: BattleHex — Hex to test for reachability.

  • returns boolean

isAccessibleForNewUnit

True if a unit of the given creature could be placed on the given hex. Use before summoning a unit; unlike isAccessibleForUnit it needs no existing unit to ask about.

  • param hex: BattleHex — Hex the unit would be placed on. For a double-wide creature this is its front hex.
  • param creature: Creature — Creature that would be placed there.

  • param side: BattleSide — Battle side the unit would belong to, which decides where its second hex goes.

  • returns boolean

getFieldWidth

Returns the number of hex columns on the battlefield, including the two edge columns that units cannot stand on.

  • returns integer

hasPenaltyOnLine

True if a ranged attack along this line crosses a wall or moat (per the flags).

  • param from: BattleHex — Origin hex of the ranged attack.
  • param dest: BattleHex — Target hex of the ranged attack.
  • param checkWall: boolean — Pass true to count crossing a wall as a penalty source.

  • param checkMoat: boolean — Pass true to count crossing a moat as a penalty source.

  • returns boolean

isMeleeAttackPossible

True if the attacker stands where it could hit the defender in melee. False for units that an area attack reached without being adjacent to them, such as a dragon breath's second target.

  • param attacker: Unit — Unit that would strike.

  • param defender: Unit — Unit that would be struck.

  • returns boolean

hasDistancePenalty

True if the shooter is too far from the target for a full-strength shot. Optionally, perform calculation assuming that units are at specified positions instead of their current ones.

  • param shooter: Unit — Unit making the ranged attack.
  • param target: Unit — Unit being shot at.
  • param shooterHex: BattleHex? — Hex to shoot from; nil uses where the shooter stands.

  • param targetHex: BattleHex? — Hex to shoot at; nil uses where the target stands.

  • returns boolean

hasWallPenalty

True if a town wall stands between the shooter and the target. Optionally, perform calculation assuming that units are at specified positions instead of their current ones.

  • param shooter: Unit — Unit making the ranged attack.
  • param target: Unit — Unit being shot at.
  • param shooterHex: BattleHex? — Hex to shoot from; nil uses where the shooter stands.

  • param targetHex: BattleHex? — Hex to shoot at; nil uses where the target stands.

  • returns boolean

isToReverse

True if the attacker would have to turn around to strike the defender. Optionally, perform calculation assuming that units are at specified positions instead of their current ones.

  • param attacker: Unit — Unit that would strike.
  • param defender: Unit — Unit that would be struck.
  • param attackerHex: BattleHex? — Hex to strike from; nil uses where the attacker stands.

  • param defenderHex: BattleHex? — Hex to strike at; nil uses where the defender stands.

  • returns boolean

getDefendedTown

Returns the town being defended in this battle.

  • returns TownInstance — The besieged town, or nil when the battle is no siege.

getUnitByPos

Returns the unit covering the given hex, or nil.

  • param hex: BattleHex — Hex to inspect for a unit.

  • param onlyAlive: boolean — Pass true to skip dead-but-resurrectable stacks.

  • returns Unit

getAllObstacles

Returns all obstacles on the battlefield.

getObstaclesOnPos

Returns the obstacles on the given hex.

  • param hex: BattleHex — Hex whose obstacles are queried.

  • param onlyBlocking: boolean — Pass true to limit results to obstacles that block movement.

  • returns Obstacle[]

hasFortifications

True if the battle is a siege with fortifications present.

  • returns boolean

hasMoat

True if the battlefield has a moat.

  • returns boolean

hasNativeStack

True if the given side has at least one native-terrain stack.

  • param side: BattleSide — Battle side to inspect (attacker or defender).

  • returns boolean

getAllPossibleHexes

Returns every valid battlefield hex.

getWallState

Returns the current state of the given wall section, or nil if absent.

  • param part: WallPart — Wall section to query.

  • returns integer?

isWallPartAttackable

True if the given wall section can be targeted by an attack.

  • param part: WallPart — Wall section to test.

  • returns boolean

wallPartToBattleHex

Returns the battle hex corresponding to the given wall section.

hexToWallPart

Returns the wall section corresponding to the given battle hex.

getTowerShooterHex

Returns the hex used by the tower shooter for the given wall section.

  • param part: WallPart — Wall section whose tower-shooter hex is queried.

  • returns BattleHex