Module Unit
Unit API for BadRotations
Usage:
local unit = br.player.unit
Functions
| unit.aberration (thisUnit) | Check if a unit is an Aberration |
| unit.beast (thisUnit) | Check if a unit is a Beast |
| unit.canAttack (thisUnit, playerUnit) | Check if a unit can be attacked |
| unit.canFly () | Check if player can fly |
| unit.cancelForm () | Cancel current shapeshift form |
| unit.formBreakManaRequired (outOfFormSpell, returnFormSpell, treatOutSpellAsFree) | Calculate mana required to safely break form for a spell and shift back. |
| unit.canCancelFormFor (outOfFormSpell, returnFormSpell, treatOutSpellAsFree) | Check if it's safe to cancel form (enough mana to cast the spell and shift back). |
| unit.cancelFormFor (outOfFormSpell, returnFormSpell, treatOutSpellAsFree) | Cancel form only if safe to do so. |
| unit.casting (thisUnit, spellID) | Check if a unit is casting or channeling a spell |
| unit.combatTime () | Get combat time |
| unit.ooCombatTime () | Get time out of combat |
| unit.charmed (thisUnit) | Check if a unit is charmed |
| unit.clearTarget () | Clear current target |
| unit.deadOrGhost (thisUnit) | Check if a unit is dead or ghost |
| unit.demon (thisUnit) | Check if a unit is a Demon |
| unit.distance (thisUnit, otherUnit) | Get distance between units |
| unit.dualWielding () | Check if player is dual wielding weapons |
| unit.rangedAttackSpeed () | Get the player's current ranged attack speed in seconds. |
| unit.enemy (thisUnit, playerUnit) | Check if a unit is an enemy |
| unit.exists (thisUnit) | Check if a unit exists |
| unit.facing (thisUnit, otherUnit, degrees) | Check if a unit is facing another unit |
| unit.isBehind (thisUnit, otherUnit, degrees) | Check if a unit is behind another unit |
| unit.falling () | Check if a unit is falling |
| unit.fallTime () | Get time the player has been falling |
| unit.fallDist () | Get the distance the player has fallen |
| unit.flying () | Check if player is flying |
| unit.form () | Get current shapeshift form |
| unit.formCount () | Get number of available shapeshift forms |
| unit.formInfo (formIndex) | Get information about a specific shapeshift form |
| unit.formActive (spellID) | Check if a specific form is active or if any form is active |
| unit.friend (thisUnit, playerUnit) | Check if a unit is friendly to another unit |
| unit.gcd (max) | Get global cooldown duration |
| unit.guid (thisUnit) | Get unit's GUID (Globally Unique Identifier) |
| unit.health (thisUnit) | Get unit's current health |
| unit.healthMax (thisUnit) | Get unit's maximum health |
| unit.hp (thisUnit) | Get unit's health percentage |
| unit.humanoid (thisUnit) | Check if a unit is a Humanoid |
| unit.id (thisUnit) | Get unit's ID |
| unit.inCombat (thisUnit) | Check if a unit is in combat |
| unit.instance (thisInstance) | Check instance type or if in a specific instance type |
| unit.interruptable (thisUnit, castPercent) | Check if a unit's cast can be interrupted |
| unit.isBoss (thisUnit) | Check if a unit is a boss |
| unit.isCasting (thisUnit) | Check if a unit is casting |
| unit.isDummy (thisUnit) | Check if a unit is a training dummy |
| unit.isElemental (thisUnit) | Check if a unit is an Elemental |
| unit.isExplosive (thisUnit) | Check if a unit is an explosive orb (M+ affix) |
| unit.isFleeing (thisUnit) | Check if a unit is fleeing |
| unit.isTanking (thisUnit) | Check if a unit is tanking |
| unit.isTankInRange () | Check if a tank is in range |
| unit.isUnit (thisUnit, otherUnit) | Check if two units are the same |
| unit.level (thisUnit) | Get unit's level |
| unit.lowest (range) | Get the lowest health friendly unit in range |
| unit.mounted () | Check if player is mounted |
| unit.moving (thisUnit) | Check if a unit is moving |
| unit.movingTime () | Get time a unit has been moving |
| unit.name (thisUnit) | Get unit's name |
| unit.player (thisUnit) | Check if a unit is a player |
| unit.outdoors () | Check if player is outdoors |
| unit.race (thisUnit) | Get unit's race |
| unit.reaction (thisUnit, playerUnit) | Get unit's reaction level towards another unit |
| unit.resting () | Check if player is resting |
| unit.role (thisUnit) | Get unit's assigned role in group |
| unit.solo () | Check if player is solo (no group) |
| unit.inGroup () | Check if player is in a group (party or raid) |
| unit.groupCount () | Get number of members in the current group (including player; 0 if solo) |
| unit.spellHaste () | Get player's spell haste percentage |
| unit.standingTime () | Get time a unit has been standing still |
| unit.startAttack () | Start auto-attack |
| unit.stopAttack () | Stop auto-attack |
| unit.swimming () | Check if player is swimming |
| unit.taxi (thisUnit) | Check if a unit is on a taxi |
| unit.target (thisUnit) | Get the current target of a unit |
| unit.threat (thisUnit) | Check if a unit has threat |
| unit.threatStatus () | Get the player's current threat status |
| unit.ttd (thisUnit, percent) | Estimate time until unit dies |
| unit.ttdGroup (range, percent) | Get combined time to death for all enemies in range |
| unit.undead (thisUnit) | Check if a unit is Undead |
| unit.valid (thisUnit) | Check if a unit is valid for targeting |
| unit.weaponImbue.exists (imbueId, offHand) | Check if a weapon imbue exists |
| unit.weaponImbue.needed (imbueId, offHand) | Check if a weapon imbue is missing (needs to be applied) |
| unit.weaponImbue.spellName (spellKey) | Get the display name of a weapon imbue spell |
| unit.weaponImbue.remain (imbueId, offHand) | Get weapon imbue remaining time |
| unit.weaponImbue.charges (imbueId, offHand) | Get weapon imbue charges |
| unit.attackPower (thisUnit) | Get player's attack power |
| unit.critChance (thisUnit) | Get player's critical strike chance |
| unit.weaponDamage (thisUnit) | Get player's average weapon damage |
Functions
- unit.aberration (thisUnit)
-
Check if a unit is an Aberration
Parameters:
- thisUnit The unit to check, defaults to "target" if nil
Returns:
-
boolean True if the unit is an Aberration
- unit.beast (thisUnit)
-
Check if a unit is a Beast
Parameters:
- thisUnit The unit to check, defaults to "target" if nil
Returns:
-
boolean True if the unit is a Beast
- unit.canAttack (thisUnit, playerUnit)
-
Check if a unit can be attacked
Parameters:
- thisUnit The unit to check
- playerUnit The attacking unit, defaults to "player" if nil
Returns:
-
boolean True if playerUnit can attack thisUnit
- unit.canFly ()
-
Check if player can fly
Returns:
-
boolean True if the player can fly in the current area
- unit.cancelForm ()
-
Cancel current shapeshift form
Returns:
-
nil
- unit.formBreakManaRequired (outOfFormSpell, returnFormSpell, treatOutSpellAsFree)
-
Calculate mana required to safely break form for a spell and shift back.
Parameters:
- outOfFormSpell Spell reference (id/name/spell table) you intend to cast after breaking form.
- returnFormSpell Spell reference (id/name/spell table) to shift back into.
- treatOutSpellAsFree If true, treat out-of-form spell cost as 0 (e.g., Clearcasting).
Returns:
- number requiredMana Total mana needed (out spell + return form).
- number currentMana Current player mana.
- unit.canCancelFormFor (outOfFormSpell, returnFormSpell, treatOutSpellAsFree)
-
Check if it's safe to cancel form (enough mana to cast the spell and shift back).
Parameters:
- outOfFormSpell Spell reference (id/name/spell table) you intend to cast after breaking form.
- returnFormSpell Spell reference (id/name/spell table) to shift back into.
- treatOutSpellAsFree If true, treat out-of-form spell cost as 0 (e.g., Clearcasting).
Returns:
-
boolean
- unit.cancelFormFor (outOfFormSpell, returnFormSpell, treatOutSpellAsFree)
-
Cancel form only if safe to do so.
Parameters:
- outOfFormSpell Spell reference (id/name/spell table) you intend to cast after breaking form.
- returnFormSpell Spell reference (id/name/spell table) to shift back into.
- treatOutSpellAsFree If true, treat out-of-form spell cost as 0 (e.g., Clearcasting).
Returns:
-
boolean
True if the form was cancelled.
- unit.casting (thisUnit, spellID)
-
Check if a unit is casting or channeling a spell
Parameters:
- thisUnit The unit to check, defaults to "player" if nil
- spellID Optional spellID to check for
Returns:
-
boolean True if the unit is casting, or casting the specific spell if spellID provided
- unit.combatTime ()
-
Get combat time
Returns:
-
number Time in combat in seconds
- unit.ooCombatTime ()
-
Get time out of combat
Returns:
-
number Time out of combat in seconds
- unit.charmed (thisUnit)
-
Check if a unit is charmed
Parameters:
- thisUnit The unit to check
Returns:
-
boolean True if the unit is charmed
- unit.clearTarget ()
-
Clear current target
Returns:
-
nil
- unit.deadOrGhost (thisUnit)
-
Check if a unit is dead or ghost
Parameters:
- thisUnit The unit to check
Returns:
-
boolean True if the unit is dead or a ghost
- unit.demon (thisUnit)
-
Check if a unit is a Demon
Parameters:
- thisUnit The unit to check, defaults to "target" if nil
Returns:
-
boolean True if the unit is a Demon
- unit.distance (thisUnit, otherUnit)
-
Get distance between units
Parameters:
- thisUnit First unit
- otherUnit Second unit (if nil, first unit is assumed to be the target and player is used)
Returns:
-
number Distance between units in yards
- unit.dualWielding ()
-
Check if player is dual wielding weapons
Returns:
-
boolean True if player is dual wielding
- unit.rangedAttackSpeed ()
-
Get the player's current ranged attack speed in seconds.
Reads the live haste-modified speed from UnitRangedDamage so it reflects
Rapid Fire, Quiver haste, and other modifiers automatically.
Returns:
-
number Ranged weapon speed in seconds, or 0 if unavailable
- unit.enemy (thisUnit, playerUnit)
-
Check if a unit is an enemy
Parameters:
- thisUnit The unit to check
- playerUnit The reference unit, defaults to "player" if nil
Returns:
-
boolean True if thisUnit is an enemy to playerUnit
- unit.exists (thisUnit)
-
Check if a unit exists
Parameters:
- thisUnit The unit to check
Returns:
-
boolean True if the unit exists
- unit.facing (thisUnit, otherUnit, degrees)
-
Check if a unit is facing another unit
Parameters:
- thisUnit The unit to check facing from, defaults to "player" if only one parameter provided
- otherUnit The unit to check facing towards
- degrees Optional angle in degrees to consider "facing", defaults to normal game value
Returns:
-
boolean True if thisUnit is facing otherUnit within the specified degrees
- unit.isBehind (thisUnit, otherUnit, degrees)
-
Check if a unit is behind another unit
Parameters:
- thisUnit The unit being checked for facing (typically the target), defaults to "target" if nil
- otherUnit The reference unit (typically "player"), defaults to "player" if nil
- degrees Optional angle in degrees for the facing cone, defaults to normal game value
Returns:
-
boolean True if thisUnit is NOT facing otherUnit within the given degrees
- unit.falling ()
-
Check if a unit is falling
Returns:
-
boolean True if player is falling
- unit.fallTime ()
-
Get time the player has been falling
Returns:
-
number Time in seconds player has been falling
- unit.fallDist ()
-
Get the distance the player has fallen
Returns:
-
number Distance in yards the player has fallen
- unit.flying ()
-
Check if player is flying
Returns:
-
boolean True if player is flying
- unit.form ()
-
Get current shapeshift form
Returns:
-
number Current shapeshift form ID
- unit.formCount ()
-
Get number of available shapeshift forms
Returns:
-
number Count of available shapeshift forms
- unit.formInfo (formIndex)
-
Get information about a specific shapeshift form
Parameters:
- formIndex The index of the form (1-based)
Returns:
-
texture, isActive, isCastable, spellID
- unit.formActive (spellID)
-
Check if a specific form is active or if any form is active
Parameters:
- spellID Optional spell ID to check for a specific form. If nil, checks if any form is active
Returns:
-
boolean True if the specified form (or any form if no spellID provided) is active
- unit.friend (thisUnit, playerUnit)
-
Check if a unit is friendly to another unit
Parameters:
- thisUnit The unit to check
- playerUnit The reference unit, defaults to "player" if nil
Returns:
-
boolean True if thisUnit is friendly to playerUnit
- unit.gcd (max)
-
Get global cooldown duration
Parameters:
- max Optional boolean to return maximum possible GCD instead of current
Returns:
-
number Global cooldown in seconds
- unit.guid (thisUnit)
-
Get unit's GUID (Globally Unique Identifier)
Parameters:
- thisUnit The unit to get GUID for
Returns:
-
string Unit's GUID
- unit.health (thisUnit)
-
Get unit's current health
Parameters:
- thisUnit The unit to check, defaults to "player" if nil
Returns:
-
number Current health of the unit
- unit.healthMax (thisUnit)
-
Get unit's maximum health
Parameters:
- thisUnit The unit to check, defaults to "player" if nil
Returns:
-
number Maximum health of the unit
- unit.hp (thisUnit)
-
Get unit's health percentage
Parameters:
- thisUnit The unit to check, defaults to "player" if nil
Returns:
-
number Health percentage of the unit (0-100)
- unit.humanoid (thisUnit)
-
Check if a unit is a Humanoid
Parameters:
- thisUnit The unit to check, defaults to "target" if nil
Returns:
-
boolean True if the unit is a Humanoid
- unit.id (thisUnit)
-
Get unit's ID
Parameters:
- thisUnit The unit to get ID for
Returns:
-
number Unit's ID
- unit.inCombat (thisUnit)
-
Check if a unit is in combat
Parameters:
- thisUnit The unit to check, defaults to "player" if nil
Returns:
-
boolean True if the unit is in combat or special conditions are met
- unit.instance (thisInstance)
-
Check instance type or if in a specific instance type
Parameters:
- thisInstance Optional specific instance type to check for
Returns:
-
string|boolean Returns instance type if no parameter, or boolean if matching specific instance
- unit.interruptable (thisUnit, castPercent)
-
Check if a unit's cast can be interrupted
Parameters:
- thisUnit The unit to check, defaults to "target" if nil
- castPercent Optional cast percentage threshold
Returns:
-
boolean True if the unit's cast can be interrupted
- unit.isBoss (thisUnit)
-
Check if a unit is a boss
Parameters:
- thisUnit The unit to check, defaults to "target" if nil
Returns:
-
boolean True if the unit is a boss
- unit.isCasting (thisUnit)
-
Check if a unit is casting
Parameters:
- thisUnit The unit to check, defaults to "player" if nil
Returns:
-
boolean True if the unit is casting
- unit.isDummy (thisUnit)
-
Check if a unit is a training dummy
Parameters:
- thisUnit The unit to check
Returns:
-
boolean True if the unit is a training dummy
- unit.isElemental (thisUnit)
-
Check if a unit is an Elemental
Parameters:
- thisUnit The unit to check, defaults to "target" if nil
Returns:
-
boolean True if the unit is an Elemental
- unit.isExplosive (thisUnit)
-
Check if a unit is an explosive orb (M+ affix)
Parameters:
- thisUnit The unit to check
Returns:
-
boolean True if the unit is an explosive orb
- unit.isFleeing (thisUnit)
-
Check if a unit is fleeing
Parameters:
- thisUnit The unit to check
Returns:
-
boolean True if the unit is fleeing
- unit.isTanking (thisUnit)
-
Check if a unit is tanking
Parameters:
- thisUnit The unit to check, defaults to "player" if nil
Returns:
-
boolean True if the unit is tanking
- unit.isTankInRange ()
-
Check if a tank is in range
Returns:
-
boolean True if a tank is in range
- unit.isUnit (thisUnit, otherUnit)
-
Check if two units are the same
Parameters:
- thisUnit First unit to compare
- otherUnit Second unit to compare
Returns:
-
boolean True if both units are the same
- unit.level (thisUnit)
-
Get unit's level
Parameters:
- thisUnit The unit to check, defaults to "player" if nil
Returns:
-
number The level of the unit
- unit.lowest (range)
-
Get the lowest health friendly unit in range
Parameters:
- range The range to check for units, defaults to 5 if nil
Returns:
-
unit The friendly unit with lowest health in range
- unit.mounted ()
-
Check if player is mounted
Returns:
-
boolean True if player is mounted
- unit.moving (thisUnit)
-
Check if a unit is moving
Parameters:
- thisUnit The unit to check, defaults to "player" if nil
Returns:
-
boolean True if the unit is moving
- unit.movingTime ()
-
Get time a unit has been moving
Returns:
-
number Time in seconds the unit has been moving
- unit.name (thisUnit)
-
Get unit's name
Parameters:
- thisUnit The unit to get name of
Returns:
-
string The name of the unit
- unit.player (thisUnit)
-
Check if a unit is a player
Parameters:
- thisUnit The unit to check
Returns:
-
boolean True if the unit is a player
- unit.outdoors ()
-
Check if player is outdoors
Returns:
-
boolean True if player is outdoors
- unit.race (thisUnit)
-
Get unit's race
Parameters:
- thisUnit The unit to check, defaults to "player" if nil
Returns:
-
string The race of the unit
- unit.reaction (thisUnit, playerUnit)
-
Get unit's reaction level towards another unit
Parameters:
- thisUnit The unit to check reaction of
- playerUnit The reference unit, defaults to "player" if nil
Returns:
-
number Reaction level (1-hostile to 8-friendly)
- unit.resting ()
-
Check if player is resting
Returns:
-
boolean True if player is resting
- unit.role (thisUnit)
-
Get unit's assigned role in group
Parameters:
- thisUnit The unit to check, defaults to "target" if nil
Returns:
-
string The role assigned to the unit ("TANK", "HEALER", "DAMAGER", "NONE")
- unit.solo ()
-
Check if player is solo (no group)
Returns:
-
boolean True if player is solo
- unit.inGroup ()
-
Check if player is in a group (party or raid)
Returns:
-
boolean True if player is in a group
- unit.groupCount ()
-
Get number of members in the current group (including player; 0 if solo)
Returns:
-
number Total group member count
- unit.spellHaste ()
-
Get player's spell haste percentage
Returns:
-
number Spell haste percentage
- unit.standingTime ()
-
Get time a unit has been standing still
Returns:
-
number Time in seconds the unit has been standing still
- unit.startAttack ()
-
Start auto-attack
Returns:
-
nil
- unit.stopAttack ()
-
Stop auto-attack
Returns:
-
nil
- unit.swimming ()
-
Check if player is swimming
Returns:
-
boolean True if player is swimming
- unit.taxi (thisUnit)
-
Check if a unit is on a taxi
Parameters:
- thisUnit The unit to check, defaults to "player" if nil
Returns:
-
boolean True if the unit is on a taxi
- unit.target (thisUnit)
-
Get the current target of a unit
Parameters:
- thisUnit The unit whose target to get
Returns:
-
string|nil Unit token of thisUnit's current target, or nil if none
- unit.threat (thisUnit)
-
Check if a unit has threat
Parameters:
- thisUnit The unit to check, defaults to "target" if nil
Returns:
-
boolean True if the unit has threat
- unit.threatStatus ()
-
Get the player's current threat status
Returns:
-
number Threat status: 0=no/low threat, 1=high threat (not primary target),
2=primary target (another unit has 100%+ threat), 3=primary target (sole aggro)
- unit.ttd (thisUnit, percent)
-
Estimate time until unit dies
Parameters:
- thisUnit The unit to check, defaults to "target" if nil
- percent Optional health percentage to calculate time to
Returns:
-
number Estimated time until death in seconds
- unit.ttdGroup (range, percent)
-
Get combined time to death for all enemies in range
Parameters:
- range Range to check for enemies, defaults to 5 yards if nil
- percent Optional health percentage to calculate time to
Returns:
-
number Combined estimated time until death for all enemies in range
- unit.undead (thisUnit)
-
Check if a unit is Undead
Parameters:
- thisUnit The unit to check
Returns:
-
boolean True if the unit is Undead
- unit.valid (thisUnit)
-
Check if a unit is valid for targeting
Parameters:
- thisUnit The unit to check
Returns:
-
boolean True if the unit is valid
- unit.weaponImbue.exists (imbueId, offHand)
-
Check if a weapon imbue exists
Parameters:
- imbueId The ID of the imbue to check for
- offHand Boolean whether to check offhand (true) or main hand (false, default)
Returns:
-
boolean True if the imbue exists on the specified weapon
- unit.weaponImbue.needed (imbueId, offHand)
-
Check if a weapon imbue is missing (needs to be applied)
Parameters:
- imbueId The ID of the imbue to check for
- offHand Boolean whether to check offhand (true) or main hand (false, default)
Returns:
-
boolean True if the imbue is NOT currently applied to the specified weapon
- unit.weaponImbue.spellName (spellKey)
-
Get the display name of a weapon imbue spell
Parameters:
- spellKey The spell key string (e.g. "rockbiterWeapon") used in br.player.spells
Returns:
-
string The localised spell name, or the key as a fallback
- unit.weaponImbue.remain (imbueId, offHand)
-
Get weapon imbue remaining time
Parameters:
- imbueId The ID of the imbue to check
- offHand Boolean whether to check offhand (true) or main hand (false, default)
Returns:
-
number Time remaining on the weapon imbue in seconds
- unit.weaponImbue.charges (imbueId, offHand)
-
Get weapon imbue charges
Parameters:
- imbueId The ID of the imbue to check
- offHand Boolean whether to check offhand (true) or main hand (false, default)
Returns:
-
number Number of charges remaining on the weapon imbue
- unit.attackPower (thisUnit)
-
Get player's attack power
Parameters:
- thisUnit The unit to check, defaults to "player" if nil
Returns:
-
number Total attack power (base + positive buffs + negative buffs)
- unit.critChance (thisUnit)
-
Get player's critical strike chance
Parameters:
- thisUnit The unit to check, defaults to "player" if nil
Returns:
-
number Critical strike chance percentage
- unit.weaponDamage (thisUnit)
-
Get player's average weapon damage
Parameters:
- thisUnit The unit to check, defaults to "player" if nil
Returns:
-
number Average weapon damage