Useful Functions

You can use any of these functions from within an evaluable in an event directly.

class app.engine.query_engine.GameQueryEngine

get_item(unit, item) → ItemObject | None

Returns a item object by nid or uid.

Parameters:

• unit – unit to check

• item – item to check

Returns:

Item if exists on unit, otherwise None

Return type:

Optional[ItemObject]

get_subitem(unit, parent_item, child_item) → ItemObject | None

Returns a item object by nid.

Parameters:

• unit – unit to check

• parent_item – parent item (multi-item) to check

• child_item – child item (subitem) to check

Returns:

Item if exists on unit, otherwise None

Return type:

Optional[ItemObject]

has_item(item, nid=None, team=None, tag=None, party=None) → bool

Check if any unit matching criteria has item.

Example usage: * has_item(“Iron Sword”, team=”player”) will check if any player unit is holding an iron sword * has_item(“Sacred Stone”, party=’Eirika’) will check if Eirika’s party has the item “Sacred Stone”

Parameters:

• item – item to check

• nid (optional) – use to check specific unit nid

• team (optional) – used to match for team.

• tag (optional) – used to match for tag.

• party (optional) – used to match for party

Returns:

True if unit has item, else False

Return type:

bool

get_skill(unit, skill) → SkillObject | None

Returns a skill object by nid.

Parameters:

• unit – unit in question

• skill – nid of skill

Returns:

Skill, if exists on unit, else None.

Return type:

Optional[SkillObject] | None

has_skill(unit, skill) → bool

checks if unit has skill

Parameters:

• unit – unit to check

• skill – skill to check

Returns:

True if unit has skill, else false

Return type:

bool

get_klass(unit) → Klass | None

Returns the klass prefab of the unit.

Parameters:

unit – unit in question

Returns:

Klass object if the unit exists and has a valid klass, otherwise None

get_class(unit) → Klass | None

Returns the klass prefab of the unit.

Parameters:

unit – unit in question

Returns:

Klass object if the unit exists and has a valid klass, otherwise None

get_closest_allies(position, num: int = 1) → List[Tuple[UnitObject, int]]

Return a list containing the closest player units and their distances.

Parameters:

• position – position or unit

• num (int, optional) – How many allies to search for. Defaults to 1.

Returns:

Returns num pairs of (unit, distance) to the position. Will return fewer if there are fewer player units than num.

Return type:

List[Tuple[UnitObject, int]]

get_units_within_distance(position, dist: int = 1, nid=None, team=None, tag=None, party=None) → List[Tuple[UnitObject, int]]

Return a list containing all units within dist distance to the specific position that match specific criteria

Parameters:

• position – position or unit

• dist (int, optional) – How far to search. Defaults to 1.

• nid (optional) – use to check specific unit nid

• team (optional) – used to match for team.

• tag (optional) – used to match for tag.

• party (optional) – used to match for party

Returns:

Returns all pairs of (unit, distance) within the specified dist that match criteria.

Return type:

List[Tuple[UnitObject, int]]

get_allies_within_distance(position, dist: int = 1) → List[Tuple[UnitObject, int]]

Return a list containing all player units within dist distance to the specific position.

Parameters:

• position – position or unit

• dist (int, optional) – How far to search. Defaults to 1.

Returns:

Returns all pairs of (unit, distance) within the specified dist.

Return type:

List[Tuple[UnitObject, int]]

get_units_in_area(position_corner_1: Tuple[int, int], position_corner_2: Tuple[int, int]) → List[UnitObject]

Returns a list of units within a rectangular area.

Parameters:

• position_corner_1 (Tuple[int, int]) – (x, y) coordinates for one corner of the area

• position_corner_2 (Tuple[int, int]) – (x, y) coordinates for the opposite corner

Returns:

Returns all units with positions with values between those specified by the corners (inclusive), or an empty list if no units exist in that area

Return type:

List[UnitObject]

get_debuff_count(unit) → int

Checks how many negative skills the unit has.

Parameters:

unit – Unit in question

Returns:

Number of unique negative skills on the unit

Return type:

int

get_units_in_region(region, nid=None, team=None, tag=None) → List[UnitObject]

returns all units matching the criteria in the given region

Example usage: * get_units_in_region(‘NorthReinforcements’, team=’player’) will return all player units in the region * get_units_in_region(‘NorthReinforcements’, nid=’Eirika’) will return Eirika if Eirika is in the region * get_units_in_region(‘NorthReinforcements’) will return all units in the region

Parameters:

• region – region in question

• nid (optional) – used to match for NID

• team (optional) – used to match for team.

• tag (optional) – used to match for tag.

Returns:

all units matching the criteria in the region

Return type:

List[UnitObject]

any_unit_in_region(region, nid=None, team=None, tag=None) → bool

checks if any unit matching the criteria is in the region

Example usage: * any_unit_in_region(‘NorthReinforcements’, team=’player’) will check if any player unit is in the region * any_unit_in_region(‘NorthReinforcements’, nid=’Eirika’) will check if Eirika is in the region * any_unit_in_region(‘NorthReinforcements’) will check if ANY unit is in the region

Parameters:

• region – region in question

• nid (optional) – used to match for NID

• team (optional) – used to match for team.

• tag (optional) – used to match for tag.

Returns:

if any unit matching criteria is in the region

Return type:

bool

is_dead(unit) → bool

checks if unit is dead

Parameters:

unit – unit to check

Returns:

if the unit has died

Return type:

bool

u(unit) → UnitObject | None

Shorthand for game.get_unit. Fetches the unit object.

Parameters:

unit – unit nid

Returns:

the actual unit object, if exists, else None

Return type:

Optional[UnitObject]

v(varname, fallback=None) → Any

shorthand for game.level_vars.get and game.game_vars.get. Fetches the variable if game.level_vars and game.game_vars share an identical name, game.level_vars takes priority

Parameters:

• varname – name of the variable

• fallback – fallback value, if any. Defaults to None

Returns:

the value of the variable

Return type:

Any

get_support_rank(unit1, unit2) → NID | None

Returns the most recently obtained support rank between two units.

Parameters:

• unit1 – unit in the support pair

• unit2 – the other unit in the support pair

Returns:

if the two units have achieved a support rank. none: if the support pair is invalid or no rank has been obtained

Return type:

Rank nid

get_terrain(pos) → NID | None

Returns the terrain at position, or, if unit is provided, the terrain underneath the unit.

Parameters:

pos – Position tuple or unit

Returns:

the nid of the region, or None if the position is invalid

Return type:

Optional[NID]

has_achievement(nid) → bool

Checks if an achievement is completed

Parameters:

nid – nid to check for completion

Returns:

if the achievement exists

Return type:

bool

check_shove(target, anchor_pos, magnitude) → Pos | None

Calculates where a unit would go if pushed <magnitude> tiles, respecting obstacles.

Parameters:

• target – GlobalUnit

• anchor_pos – Position of the source of the push

• magnitude – Distance to push

Returns:

the destination or None If you’d like the final magnitude, use utils.calculate_distance()

Return type:

Optional[Pos]

check_bypass_shove(target, anchor_pos, magnitude) → Pos | None

Checks a destination <magnitude> tiles away for obstacles.

Parameters:

• target – GlobalUnit

• anchor_pos – Position of the source of the push

• magnitude – Distance to push

Returns:

the destination or None

Return type:

Optional[Pos]