Unit Helper Functions

You can access any of these functions from within an evaluable in an event with unit_funcs.name_of_func(args)

app.engine.unit_funcs.growth_rate(unit: UnitObject, nid: NID) → int

Calculates the growth rate of a unit for a given stat.

Parameters:

  • unit (UnitObject) – The unit for which to calculate the growth rate.

  • nid (NID) – The NID (Name IDentifier) of the stat.

Returns:

The calculated growth rate.

Return type:

int

app.engine.unit_funcs.growth_contribution(unit: UnitObject, nid: NID) → Dict[str, int]

Calculates the growth rate of a unit for a given stat and returns it individually as dict elements.

Parameters:

  • unit (UnitObject) – The unit for which to calculate the growth rate.

  • nid (NID) – The NID (Name IDentifier) of the stat.

Returns:

The calculated growth rates

Return type:

Dict[str, int]

app.engine.unit_funcs.base_growth_rate(unit: UnitObject, nid: NID) → int

Calculates the base growth rate of a unit for a given stat. Base growth rate can either be unit growths or unit growths + klass growths depending on DB settings.

Parameters:

  • unit (UnitObject) – The unit for which to calculate the base growth rate.

  • nid (NID) – The NID (Name IDentifier) of the stat.

Returns:

The calculated base growth rate.

Return type:

int

app.engine.unit_funcs.difficulty_growth_rate(unit: UnitObject, nid: NID) → int

Calculates the additional growth rate that comes from the difficulty mode for a unit for a given stat.

Parameters:

  • unit (UnitObject) – The unit for which to calculate the difficulty growth rate.

  • nid (NID) – The NID (Name IDentifier) of the stat.

Returns:

The calculated difficulty growth rate.

Return type:

int

app.engine.unit_funcs.get_next_level_up(unit: UnitObject, level: int, custom_method: str | None = None) → Dict[NID, int]

Determines the unit’s next level-up stat changes based on its current level and the leveling method.

If you are using ‘Dynamic’ leveling method, does modify the state of the unit’s growth points. Otherwise, this function does not actually change anything about the unit

Parameters:

  • unit (UnitObject) – The unit for which to determine the next level-up stat changes.

  • level (int) – The current level of the unit.

  • custom_method (Optional[str]) – A custom leveling method to use. Defaults to None.

Returns:

A dictionary containing the next level-up stat changes for the unit.

Return type:

dict (Dict[NID, int])

app.engine.unit_funcs.auto_level(unit: UnitObject, base_level: int, num_levels: int, custom_method: str | None = None) → Dict[NID, int]

Levels up a unit’s stats for a specified number of levels. Primarily used for generics.

This does modify the stats and growth points of the unit. After this runs, it resets the unit’s current hp and current mana to their full value.

Parameters:

  • unit (UnitObject) – The unit to level up.

  • base_level (int) – The base level of the unit.

  • num_levels (int) – The number of levels to increase or decrease.

  • custom_method (Optional[str]) – A custom leveling method to use. Defaults to None.

Returns:

A dictionary containing the total stat changes after auto-leveling.

Return type:

dict (Dict[NID, int])

app.engine.unit_funcs.difficulty_auto_level(unit: UnitObject, base_level: int, num_levels: int) → Dict[NID, int]

Levels up a unit’s stats for a specified number of levels based on the growth points that the current difficulty adds to the unit.

This does modify the stats and growth points of the unit. After this runs, it resets the unit’s current hp and current mana to their full value.

Parameters:

  • unit (UnitObject) – The unit to level up.

  • base_level (int) – The base level of the unit.

  • num_levels (int) – The number of levels to increase or decrease.

Returns:

A dictionary containing the total stat changes after auto-leveling.

Return type:

dict (Dict[NID, int])

app.engine.unit_funcs.apply_stat_changes(unit: UnitObject, stat_changes: Dict[NID, int], increase_current_stats: bool = True) → None

Applies the given stat changes to the unit’s stats.

Parameters:

  • unit (UnitObject) – The unit to which the stat changes should be applied.

  • stat_changes (Dict[NID, int]) – A dictionary containing the stat changes to apply.

  • increase_current_stats (bool, optional) – Whether to adjusts the unit’s current HP and mana if their maximum values increase. Defaults to True.

Notes

  • Assumes that the stat changes are valid. No checks are done for maximum stats, stat caps, etc.

app.engine.unit_funcs.apply_growth_changes(unit: UnitObject, growth_changes: Dict[NID, int]) → None

Applies the given changes to the unit’s growths.

Parameters:

  • unit (UnitObject) – The unit to which the stat changes should be applied.

  • growth_changes (Dict[NID, int]) – A dictionary containing the stat changes to apply.

app.engine.unit_funcs.get_starting_skills(unit: UnitObject, starting_level: int | None = 0) → List[SkillObject]

Retrieves the starting skills for a unit based on its class and level.

Parameters:

  • unit (UnitObject) – The unit for which to retrieve starting skills.

  • starting_level (int, optional) – The starting level of the unit. Defaults to 0.

Returns:

The starting skills of the unit.

Return type:

List[SkillObject]

Notes

  • If promote_skill_inheritance constant is enabled, skills from lower-tier classes are also considered (up to 5 tiers back).

  • If generic_feats constant is enabled and a learned skill is a ‘Feat’, a random feat skill is added.

app.engine.unit_funcs.get_personal_skills(unit: UnitObject, prefab: UnitPrefab, starting_level: int | None = 0) → List[SkillObject]

Retrieves the personal skills for a unit based on its prefab and level.

Parameters:

  • unit (UnitObject) – The unit for which to retrieve personal skills.

  • prefab (UnitPrefab) – The unit’s prefab which contains information about the unit’s personal skills.

  • starting_level (int, optional) – The starting level of the unit. Defaults to 0.

Returns:

A list of SkillObject instances representing the personal skills of the unit.

Return type:

List[SkillObject]

Notes

  • Only skills that the unit has learned at or below its current level are included.

app.engine.unit_funcs.get_global_skills(unit: UnitObject) → List[SkillObject]

Retrieves the global skills for the unit. These are the skills that every unit should have. They are used to change your game mechanics globally.

Parameters:

unit (UnitObject) – The unit for which to retrieve global skills.

Returns:

A list of SkillObject instances representing the global skills.

Return type:

List[SkillObject]

Notes

  • The function retrieves global skills that the unit does not already possess.

app.engine.unit_funcs.can_unlock(unit: UnitObject, region: RegionObject) → bool

Checks if a unit can unlock a region.

Parameters:
Returns:

True if the unit can unlock the region, False otherwise.

Return type:

bool

app.engine.unit_funcs.can_pairup(rescuer: UnitObject, rescuee: UnitObject) → bool

Determines whether a pair-up can occur between a rescuer unit and a rescuee unit.

Parameters:

  • rescuer (UnitObject) – The unit that is attempting to initiate the pair-up.

  • rescuee (UnitObject) – The unit that is being considered as a potential partner for pair-up.

Returns:

True if a pair-up can occur between the rescuer and rescuee units; False otherwise.

Return type:

bool

Notes

  • A pair-up can occur if pair-up mechanics are enabled in the game and attack stance only is not enforced.

  • If player pair-up is restricted, the function checks whether both the rescuer and rescuee units belong to the player’s team.

app.engine.unit_funcs.check_focus(unit: UnitObject, limit: int | None = 3) → int

Counts the number of allied units within a specified distance from a given unit.

Parameters:

  • unit (UnitObject) – The unit whose surroundings are being checked for allied units.

  • limit (int, optional) – The maximum distance within which allied units are considered. Defaults to 3.

Returns:

The count of allied units within the specified distance from the given unit.

Return type:

int

Notes

  • Does not count self as an ally.

app.engine.unit_funcs.check_flanked(unit: UnitObject) → bool

Checks if the given unit is flanked by enemy units.

Parameters:

unit (UnitObject) – The unit to check for flanking.

Returns:

True if the unit is flanked by enemy units, False otherwise.

Return type:

bool

Notes

  • If both the up and down adjacent units are enemies or the same is true for the left and right adjacent units, the unit is considered flanked.

app.engine.unit_funcs.check_flanking(unit: UnitObject) → bool

Checks if the given unit is flanked by enemy units.

Parameters:

unit (UnitObject) – The unit to check for flanking.

Returns:

True if the unit is flanked by enemy units, False otherwise.

Return type:

bool

Notes

  • If both the up and down adjacent units are enemies or the same is true for the left and right adjacent units, the unit is considered flanked.

app.engine.unit_funcs.wait(unit: UnitObject, actively_chosen: bool = False)

Makes the unit wait, ending its turn.

Parameters:

  • unit (UnitObject) – The unit that will wait.

  • actively_chosen (bool, optional) – Indicates whether the wait action was actively chosen by the player. Defaults to False, which means the unit just automatically waited when it ran out of actions to do (finished a combat, etc.)

Notes

  • the function triggers a UnitWait event, indicating that the unit is waiting.

  • If the unit’s turn is already finished, the function does nothing.

app.engine.unit_funcs.usable_wtypes(unit: UnitObject) → Set[NID]

Retrieves the set of weapon types usable by the unit.

Parameters:

unit (UnitObject) – The unit for which to determine usable weapon types.

Returns:

A set containing the NIDs of weapon types that the unit can use.

Return type:

Set[NID]

Notes

  • The unit’s class determines its base weapon proficiency.

  • Usable weapon types include those defined by the unit’s class as well as any additional types granted by skills or other effects.

app.engine.unit_funcs.get_weapon_cap(unit: UnitObject, weapon_type: NID) → int

Retrieves the weapon proficiency cap for a specific weapon type and unit. For instance, if the unit can only get up to B rank in a weapon type, will return the WEXP value for B rank.

Parameters:

  • unit (UnitObject) – The unit for which to retrieve the weapon proficiency cap.

  • weapon_type (NID) – The NID of the weapon type for which to retrieve the cap.

Returns:

The proficiency cap for the specified weapon type and unit.

Return type:

int

Notes

  • If no cap is specified for the weapon type, the highest weapon rank requirement from the database is used as the cap.