[Lib] BoardUtils

Overview

Board related helpers for pathing, terrain movement rules, forced moves, crack handling, spawn safety, and last acted pawn tracking. Used by WorldBuilders, movement pilot skills, and other mods that need consistent board math beyond vanilla APIs.

Any issues or concerns? Join the Redacted Rice Discord and @Das Keifer

API

• BoardUtils
  • isPawnFlying
  • isPawnHijackedFlying
  • setHijackedFlying
  • setHijackedPath / getHijackedPath / clearHijackedPath
  • CanMoveOn*/CanMoveThrough*
  • makeAllowIf
  • makeAllowIfHasSkill
  • makeMoveLandableMatcher
  • makeMovePassableMatcher
  • makeTerrainBasedMatcher
  • makeInSubsetMatcher
  • getMoveReachableInRange
  • findMovePath
  • getReachableInRange
  • findBfsPath
  • clearMoveCaches
  • makeMoveCacheKey
  • getSpaceHash / unhashSpace
  • hashesToPointList / pointListToHashes
  • addForcedMove
  • addForcedSingleMove
  • skillEffectUsesPathMovement
  • skillEffectUsesPointToPointMovement
  • isLiquid
  • isCrackHealthTerrain
  • canCrack
  • undoCrack
  • isUnallowedCustomTerrain
  • isSafeCustomTile
  • isSafeSpawnTile
  • getSafeSpawnTiles
  • isAdjacent
  • getAdjacent
  • addCancelEffect
  • setLastActed / unsetLastActed
  • isAPlayerTeam / isAnEnemyTeam
  • canPassThroughEnemyPawns

 

BoardUtils

A library providing board, pathing, and movement utilities. Override the CanMoveOn*/CanMoveThrough* hooks (chaining the previous function) so pathing helpers respect custom skills.

 

isPawnFlying

Argument name	Type	Description
pawn	Pawn	Pawn to check

Returns true if the pawn is flying and not marked hijacked flying (skills that grant temporary flight without counting as true flight for some rules).

Example:

if BoardUtils.isPawnFlying(pawn) then
    -- treat as true flight
end

 

isPawnHijackedFlying

Argument name	Type	Description
pawn	Pawn	Pawn to check

Returns true if the pawn is currently marked as hijacked flying.

 

setHijackedFlying

Argument name	Type	Description
pawn	Pawn	Pawn to update
enabled	boolean	Whether hijacked flight should be enabled

Tracks temporary flight granted by skills (e.g. amphibious). When enabling, sets pawn:SetFlying(true) and records the pawn id. When disabling a previously hijacked pawn, clears the mark and sets pawn:SetFlying(false).

Example:

BoardUtils.setHijackedFlying(pawn, true)
-- later:
BoardUtils.setHijackedFlying(pawn, false)

 

setHijackedPath

Argument name	Type	Description
path	PointList	Path to store for other systems

Stores the last forced path so other systems (e.g. Momentum) can read or modify it. Also set automatically by addForcedMove. Cleared on undo move via clearHijackedPath.

 

getHijackedPath

Returns the currently stored hijacked path, or nil.

 

clearHijackedPath

Clears the stored hijacked path.

 

CanMoveOn*/CanMoveThrough*

Landing (CanMoveOn*) vs passing through without landing (CanMoveThrough*). Jumpers/teleporters can pass through many unlandable terrains. Fliers are already covered via matching CanMoveOn* fallbacks.

Each hook has signature fn(pawn) -> boolean. Override by replacing and calling the previous function (see makeAllowIf).

Field	Type	Description
CanMoveOnMountains	function	Default false
CanMoveOnBuildings	function	Default false
CanMoveOnHoles	function	Default: non-hijacked flying
CanMoveOnWater	function	Default: flying or massive
CanMoveThroughHoles	function	Default: jumper/teleporter or CanMoveOnHoles
CanMoveThroughWater	function	Default: jumper/teleporter or CanMoveOnWater
CanMoveThroughBuildings	function	Default: jumper/teleporter or CanMoveOnBuildings
CanMoveThroughMountains	function	Default: jumper/teleporter or CanMoveOnMountains

Skills that only override CanMoveOn* typically get matching CanMoveThrough* behavior for free.

 

makeAllowIf

Argument name	Type	Description
original	function/nil	Previous CanMoveOn*/CanMoveThrough* function to defer to
allowIfFn	function	Predicate fn(pawn) -> boolean. If true, allow. Otherwise call original

Returns a new function for the common "allow if condition, else defer to previous" override chain.

Example:

BoardUtils.CanMoveOnWater = BoardUtils.makeAllowIf(BoardUtils.CanMoveOnWater, function(pawn)
    return pawn:GetType() == "MyAmphibiousMech"
end)

 

makeAllowIfHasSkill

Argument name	Type	Description
original	function / nil	Previous hook function to defer to
skillId	string	CPLUS+ Ex skill id to check via cplus_plus_ex:isSkillOnPawn

Convenience wrapper around makeAllowIf that allows when the skill is on the pawn.

Example:

BoardUtils.CanMoveOnWater = BoardUtils.makeAllowIfHasSkill(BoardUtils.CanMoveOnWater, customSkill.id)

 

makeMoveLandableMatcher

Argument name	Type	Description
pawn	Pawn	Moving pawn
pawnCheckType	string	Pawn blocking mode: "none", "default", or "any"

Returns a matcher fn(point, hash) -> boolean for ending a move. Respects CanMoveOnHoles/CanMoveOnWater/CanMoveOnBuildings/CanMoveOnMountains.

pawnCheckType:

• "none" — ignore other pawns
• "default" — block opposing teams unless Road Runner/flier/jumper/teleporter
• "any" — block any pawn

Example:

local landable = BoardUtils.makeMoveLandableMatcher(pawn, "any")

 

makeMovePassableMatcher

Argument name	Type	Description
pawn	Pawn	Moving pawn
pawnCheckType	string	Pawn blocking mode: "none", "default", or "any"

Returns a matcher fn(point, hash) -> boolean for traversing a path. Respects CanMoveThrough* (which each respect matching CanMoveOn*).

Example:

local passable = BoardUtils.makeMovePassableMatcher(pawn, "default")

 

makeTerrainBasedMatcher

Argument name	Type	Description
pawn	Pawn	Moving pawn
pawnCheckType	string	Pawn blocking mode: "none", "default", or "any"
exclTerrainCheckFn	function	fn(point) -> boolean. Return true to exclude the tile

Low level matcher builder used by makeMoveLandableMatcher and makeMovePassableMatcher.

 

makeInSubsetMatcher

Argument name	Type	Description
tiles	table	Map of space hash -> truthy for allowed tiles

Returns a matcher that is true only when tiles[hash] is set.

Example:

local matcher = BoardUtils.makeInSubsetMatcher(allowedHashes)

 

getMoveReachableInRange

Argument name	Type	Description
pawn	Pawn	Moving pawn
range	number	Move range
start	Point	Start tile
passThroughMode	string	(optional) Passed to passable matcher. Defaults to "default"

Returns a PointList of reachable tiles within range using standard move matchers. Results are cached. Cleared by clearMoveCaches.

Note: Destination tiles always use makeMoveLandableMatcher(pawn, "any"). passThroughMode only affects traversal via makeMovePassableMatcher.

Example:

local reachable = BoardUtils.getMoveReachableInRange(pawn, pawn:GetMoveSpeed(), pawn:GetSpace())

 

findMovePath

Argument name	Type	Description
pawn	Pawn	Moving pawn
p1	Point	Start
p2	Point	Destination
passThroughMode	string	(optional) Defaults to "default"
asPointList	boolean	(optional) If truthy, return PointList. If omitted/nil/false, return a Lua array of Points

Returns a BFS path using the same passable/landable matchers as getMoveReachableInRange, or nil if unreachable. Cached.

Note: Destination tiles always use makeMoveLandableMatcher(pawn, "any"). passThroughMode only affects traversal via makeMovePassableMatcher.

Example:

local path = BoardUtils.findMovePath(pawn, p1, p2)
if path then
    BoardUtils.addForcedMove(ret, path, NO_DELAY)
end

 

getReachableInRange

Argument name	Type	Description
reachable	PointList	Output list to push reachable points into (start excluded)
range	number	Max distance
start	Point	Start tile
predicatePassable	function / nil	(optional) fn(point, hash) -> boolean for traversal
predicateStoppable	function / nil	(optional) fn(point, hash) -> boolean for landing/including a tile

Lower level BFS reachable fill with custom predicates. Mutates reachable.

 

findBfsPath

Argument name	Type	Description
p1	Point	Start
p2	Point	Destination
predicatePassable	function / nil	(optional) Traversal predicate
predicateStoppable	function / nil	(optional) Destination must also pass this
asPointList	boolean	(optional) If true, return PointList. Otherwise Lua array

Lower level BFS path with custom predicates. Returns nil if no path.

 

clearMoveCaches

Clears path and reachable caches. Also hooked automatically on undo move, pawn position change, mission start, and mission end.

Example:

BoardUtils.clearMoveCaches()

 

makeMoveCacheKey

Argument name	Type	Description
pawnId	number	Pawn id
startHash	number	Start space hash
extraHash	number	Extra discriminator (e.g. range or dest hash)
passThroughMode	string	Pass through mode string used in the cache key

Returns the string key used by movePathCache / reachableCache. Primarily intended for internal use

 

getSpaceHash

Argument name	Type	Description
spaceOrX	Point/number	Point, or X coordinate when y is provided
y	number	(optional) Y coordinate when hashing raw components

Returns a compact hash y * 10 + x for board spaces.

Example:

local hash = BoardUtils.getSpaceHash(point)
local hash2 = BoardUtils.getSpaceHash(3, 4)

 

unhashSpace

Argument name	Type	Description
hash	number	Value from getSpaceHash

Returns x, y for the hash.

Example:

local x, y = BoardUtils.unhashSpace(hash)

 

hashesToPointList

Argument name	Type	Description
hashes	table	Array of space hashes
asPointList	boolean	(optional) If not false, return PointList. If false, return Lua array of Points

 

pointListToHashes

Argument name	Type	Description
pointList	PointList	Points to convert

Returns an array of space hashes.

 

addForcedMove

Argument name	Type	Description
skillEffect	SkillEffect	Skill effect whose movement to replace
path	PointList	Display/forced path
delay	number	(optional) Delay for AddMove. Defaults to FULL_DELAY

Replaces the skill effect's movement with a display path plus a forced teleport to the destination (for moving onto normally illegal tiles). Preserves non first damage entries, stores the path via setHijackedPath.

Example:

BoardUtils.addForcedMove(ret, path, NO_DELAY)

 

addForcedSingleMove

Argument name	Type	Description
skillEffect	SkillEffect	Skill effect to append to
pawnId	number	Pawn id to teleport
dest	Point	Destination tile

Adds a scripted SetSpace damage for a single teleport step.

Example:

BoardUtils.addForcedSingleMove(ret, pawnId, newPos)

 

skillEffectUsesPathMovement

Argument name	Type	Description
skillEffect	SkillEffect	Skill effect to inspect

Returns true if movement in the effect is path/burrow style (or unknown/no move). Uses memedit move type constants when available.

 

skillEffectUsesPointToPointMovement

Argument name	Type	Description
skillEffect	SkillEffect	Skill effect to inspect

Returns the inverse of skillEffectUsesPathMovement.

 

isLiquid

Argument name	Type	Description
terrain	number	Terrain constant

Returns true for TERRAIN_WATER, TERRAIN_LAVA, or TERRAIN_ACID.

 

isCrackHealthTerrain

Argument name	Type	Description
loc	Point	Tile to check

Returns true for mountain or ice (crack damages HP instead of becoming cracked terrain).

 

canCrack

Argument name	Type	Description
loc	Point	Tile to check

Returns whether crack is valid. Excludes invalid tiles, buildings, pods, items, already cracked, liquid, and holes. Mountains/ice only if currently at max health.

Example:

if BoardUtils.canCrack(loc) then
    -- apply crack
end

 

undoCrack

Argument name	Type	Description
loc	Point	Tile to restore

Clears crack, or restores mountain/ice to max HP. Returns true if something was undone.

Example:

BoardUtils.undoCrack(loc)

 

isUnallowedCustomTerrain

Argument name	Type	Description
customTile	string / nil	Custom tile id from Board:GetCustomTile

Returns true if customTile starts with any prefix in BoardUtils.UNSAFE_CUSTOM_TILE_PREFIXES (rails, silos, conveyors, known mod tiles, etc.). Empty/nil returns false.

 

isSafeCustomTile

Argument name	Type	Description
point	Point	Tile to check

Returns true if the tile is valid and not unallowed custom terrain.

 

isSafeSpawnTile

Argument name	Type	Description
point	Point	Tile to check
pathing	number	(optional) Pathing type for Board:IsBlocked

Returns true if the tile is empty, safe custom terrain, not blocked/dangerous/spawning/acid/etc.

Example:

if BoardUtils.isSafeSpawnTile(point, PATH_GROUND) then
    -- ok to spawn
end

 

getSafeSpawnTiles

Argument name	Type	Description
pathing	number	(optional) Pathing type forwarded to isSafeSpawnTile

Returns a Lua array of all safe spawn candidate Points on the board.

Example:

local candidates = BoardUtils.getSafeSpawnTiles(PATH_GROUND)

 

isAdjacent

Argument name	Type	Description
loc	Point	Center tile
matcher	function	fn(point) -> boolean

Returns true if any valid adjacent tile matches matcher.

Example:

local nearForest = BoardUtils.isAdjacent(loc, function(p)
    return Board:GetTerrain(p) == TERRAIN_FOREST
end)

 

getAdjacent

Argument name	Type	Description
loc	Point	Center tile
matcher	function	fn(point) -> boolean

Returns a Lua array of adjacent Points that match matcher.

Example:

local forests = BoardUtils.getAdjacent(loc, function(p)
    return Board:GetTerrain(p) == TERRAIN_FOREST
end)

 

addCancelEffect

Argument name	Type	Description
p	Point	Tile to apply the cancel trick on
effect	SkillEffect	Skill effect to append cancel scripts/damages to

Adds a one frame smoke trick used to cancel an attack (restores prior fire/smoke state afterward).

 

setLastActed

Argument name	Type	Description
pawn	Pawn	Pawn that just started a skill/final/queued effect

Stores BoardUtils.lastActed. Wired automatically on skill/final/queued start events.

 

unsetLastActed

Clears BoardUtils.lastActed. Wired automatically on save game.

 

isAPlayerTeam

Argument name	Type	Description
team	number	Team constant

Returns true for TEAM_PLAYER or TEAM_MECH.

 

isAnEnemyTeam

Argument name	Type	Description
team	number	Team constant

Returns true for TEAM_BOTS, TEAM_ENEMY, or TEAM_ENEMY_MAJOR.

 

canPassThroughEnemyPawns

Argument name	Type	Description
pawn	Pawn	Moving pawn

Returns true if the pawn's pilot skill is Road Runner (Kwan), allowing passage through enemy units while moving.