Module Unit
Unit API for BadRotations
Functions
| unit.aberration (thisUnit) | Check if a unit is an Aberration |
| unit.aggroRange (thisUnit) | Get a unit's aggro radius against the player |
| unit.anyInAggroRange (offset, radius, hostileOnly, accept) | Check if any nearby enemy would aggro on the player |
| unit.attackingOthers (thisUnit) | Check if an enemy is attacking someone other than you |
| unit.attackPower (thisUnit) | Get player's attack power |
| unit.beast (thisUnit) | Check if a unit is a Beast |
| unit.canAttack (thisUnit, playerUnit) | Check if a unit can be attacked |
| unit.cancelForm () | Cancel current shapeshift form. |
| unit.cancelFormFor (outOfFormSpell, treatOutSpellAsFree, emergency) | Leave the current shapeshift form to cast a spell, when a player would: not while stealthed, not while tanking in a bear form, and only with the mana to cast it and shift back. |
| unit.canLeaveFormFor (outOfFormSpell, treatOutSpellAsFree, emergency) | Whether unit.cancelFormFor would leave the current form for this spell now (same rules), without leaving it: for steps that come before the spell, such as a stun ahead of a heal. |
| unit.canFly () | Check if player can fly |
| unit.casting (thisUnit, spellID) | Check if a unit is casting or channeling a spell |
| unit.castingTankBuster (thisUnit) | True while the unit casts a spell from the tank buster list (System/Lists/TankBusters.lua) |
| unit.charmed (thisUnit) | Check if a unit is charmed |
| unit.chased ([range=10]) | Check if you're running away from an enemy that is chasing you |
| unit.clearTarget () | Clear current target |
| unit.combatTime () | Get combat time |
| unit.critChance () | Get the player's melee critical strike chance |
| unit.deadGroupMember (range, ...) | Get a dead player in your group, to resurrect |
| 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.dragonkin (thisUnit) | Check if a unit is Dragonkin |
| unit.dualWielding () | Check if player is dual wielding weapons |
| unit.enemy (thisUnit, playerUnit) | Check if a unit is an enemy |
| unit.enemyNear (range) | Check if an enemy is close enough to start a fight |
| unit.bleedImmune (thisUnit) | Whether the unit's kind of mob (NPC ID) has shown immune to your bleeds: five of them in a row went out and the bleed never showed on it (unit:isBleedImmune; learned, and kept across sessions). |
| unit.evading (thisUnit) | Whether the unit evades your attacks (an evade bug, or leashing home): an attack of yours came back "EVADE" and none has landed since (10 s at most, or until you move 2 yd). |
| unit.exists (thisUnit) | Check if a unit exists |
| unit.facing (thisUnit, otherUnit, degrees) | Check if a unit is facing another unit |
| unit.facingAngle (thisUnit) | The direction the unit faces, in radians |
| unit.facingDistance () | How far to the side of the player's facing line the target stands (negative behind the player, 1000 when either can't be seen) |
| unit.fallDist () | How far the player has fallen |
| unit.falling () | Check if a unit is falling |
| unit.fallTime () | Get time the player has been falling |
| unit.fightStyle.dungeonRoute () | Returns true when inside an active Mythic+ key run. |
| unit.fightStyle.dungeonSlice () | Returns true when inside a regular (non-Mythic+) 5-man dungeon. |
| unit.fightStyle.patchwerk () | Returns true when not in a 5-man party instance (raid, outdoor, etc.). |
| unit.fightLength (thisUnit) | Seconds the fight against thisUnit should last: its time to die once BR has measured it, else a guess (a mob 4+ levels below you: 0, any other: 999). |
| unit.flying () | Check if player is flying |
| unit.form () | Get current shapeshift form |
| unit.formActive (spellID) | Check if a specific form is active or if any form is active |
| unit.formCount () | Get number of available shapeshift forms |
| unit.formInfo (formIndex) | Get information about a specific shapeshift form |
| unit.friend (thisUnit, playerUnit) | Check if a unit is friendly to another unit |
| unit.gcd (max) | Get global cooldown duration |
| unit.getCurrentFormSpellID () | Get the spell ID of the current shapeshift form (the spell that shifts back into it), or nil when no form is active. |
| unit.groupCount () | Get number of members in the current group (including player; 0 if solo) |
| 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.healthAfterHeals (thisUnit) | Get unit's health once your heals on their way to it land (sent, not landed yet), at most its maximum. |
| unit.hpAfterHeals (thisUnit) | Get unit's health percentage once your heals on their way to it land |
| 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.inAggroRange (thisUnit, offset, hostileOnly) | Check if a unit would aggro on the player |
| unit.inCombat (thisUnit) | Check if a unit is in combat |
| unit.inGroup () | Check if player is in a group (party or raid) |
| unit.groupHealer () | The group member who heals you, or nil (solo, no healer, or yours is dead or beyond 40 yd): the Healer role, else a member seen healing others twice this session |
| unit.inRaid () | True while the player is in a raid group |
| 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.inVehicle () | True while the player rides a vehicle |
| unit.isBehind (thisUnit, otherUnit, degrees) | Check if a unit is behind another unit |
| 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.isFleeingFrom (thisUnit, fromUnit) | Check if a unit is moving away from another unit that is facing it (being chased) |
| 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.livesFor (thisUnit, seconds) | True when BR has measured thisUnit's time to die and it lives at least seconds more; false while it's unknown (unit.ttd's 999). |
| unit.losing (thisUnit) | True when you'd die before thisUnit does: both times to die are measured and yours is shorter (false while its time is unknown). |
| 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.ooCombatTime () | Get time out of combat |
| unit.outdoors () | Check if player is outdoors |
| unit.player (thisUnit) | Check if a unit is a player |
| unit.position (thisUnit) | Where the unit stands |
| unit.pressure (thisUnit) | Why the fight against thisUnit is going badly, for a debug line: "2 enemies on you" (within 8 yd), "health 45%" (under half) or "losing: you 8.0s, it 12.5s" (unit.losing); nil when it isn't. |
| unit.pullable (thisUnit) | True when a profile may open a fight on thisUnit: valid, attackable, and never a player (attacking one flags you for PvP) |
| unit.pullTimer () | Returns the time remaining on the pull timer (DBM/BigWigs) |
| unit.race (thisUnit) | Get unit's race |
| unit.rangedAttackSpeed () | Get the player's current ranged attack speed in seconds. |
| unit.reaction (thisUnit, playerUnit) | Get unit's reaction level towards another unit |
| unit.readyToFight () | Check if it's a good moment to start a fight |
| unit.resting () | Check if player is resting |
| unit.role (thisUnit) | Get unit's assigned role in group |
| unit.sinceSwing ([hand="mh"]) | Seconds since the player's last swing landed (or since auto attack started its timer); nil before either. |
| unit.solo () | Check if player is solo (no group) |
| unit.spec () | The name of the player's spec as BR loads it ("Initial" before a spec is chosen) |
| unit.spellHaste () | Get player's spell haste percentage |
| unit.standingTime () | Get time a unit has been standing still |
| unit.startAttack ([thisUnit="target"]) | Start auto-attack. |
| unit.stopAttack () | Stop auto-attack |
| unit.swimming () | Check if player is swimming |
| unit.breathBar () | Check if the player's breath bar is up (under water without water breathing) |
| unit.swing ([hand="mh"]) | The player's swing timer: seconds until the next swing (nil before the first swing), the weapon speed and when the last swing landed (util.time()) |
| unit.target (thisUnit) | Get the current target of a unit |
| unit.tapDenied (thisUnit) | Whether the unit is tagged by someone else (tap denied): its kill isn't yours, and it doesn't proximity-aggro you (unit.inAggroRange leaves it out) |
| unit.taxi (thisUnit) | Check if a unit is on a taxi |
| unit.threat (thisUnit) | Check if a unit has threat |
| unit.threatStatus ([thisUnit]) | Get the player's current threat status, on one enemy or on any |
| unit.timeSinceDismount () | Seconds since the player last landed from a mount |
| unit.totem (thisUnit) | True for a totem |
| unit.ttd (thisUnit, percent) | Estimate time until unit dies: an enemy, or the player ("player", from their own health), 999 when it isn't known to be dying |
| unit.ttdGroup (range, percent) | Get combined time to death for all enemies in range |
| unit.undead (thisUnit) | Check if a unit is Undead |
| unit.unthreatened (thisUnit) | True when nothing in the fight against thisUnit threatens you: 60%+ health, one enemy at most within 8 yd, and you're winning (unit.winning). |
| unit.valid (thisUnit) | Check if a unit is valid for targeting |
| unit.weaponDamage (thisUnit) | Get player's average weapon damage |
| unit.winning (thisUnit) | True when the fight against thisUnit is going your way: nothing is taking your health down, or it dies in half the time you would or less (both times to die; unit.fightLength for it). |
| unit.weaponImbue.charges (imbueId, offHand) | Get weapon imbue charges |
| unit.weaponImbue.exists (imbueId, offHand) | Check if a weapon imbue exists |
| unit.weaponImbue.needed (imbueId, offHand[, refreshUnder]) | Check if a weapon imbue is missing (needs to be applied). |
| unit.weaponImbue.remain (imbueId, offHand) | Get weapon imbue remaining time |
| unit.weaponImbue.spellName (spellKey) | Get the display name of a weapon imbue spell |
Tables
| unit.fightStyle | The kind of fight, as SimC names them: fightStyle.dungeonRoute() in a Mythic+ key run, fightStyle.dungeonSlice() in another 5-man dungeon, fightStyle.patchwerk() anywhere else |
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.aggroRange (thisUnit)
-
Get a unit's aggro radius against the player
Parameters:
- thisUnit The unit to check, defaults to "target"
Returns:
-
number Aggro radius in yards, centre to centre (18 +/- level difference, growth capped at 25 levels, minimum 5)
- unit.anyInAggroRange (offset, radius, hostileOnly, accept)
-
Check if any nearby enemy would aggro on the player
Parameters:
- offset Optional extra yards added to each aggro radius
- radius Optional search radius in yards, defaults to 40
- hostileOnly Optional: leave out a neutral target (it doesn't notice you coming), as for stealthing
- accept Optional function(unit): only enemies it returns true for count
Returns:
-
boolean True if any enemy (in combat or not) is within its aggro radius
- unit.attackingOthers (thisUnit)
-
Check if an enemy is attacking someone other than you
Parameters:
- thisUnit The enemy to check
Returns:
-
boolean True when it's in combat, not attacking you, and its target is friendly
Usage:
local thisUnit = enemies.first(enemies.yards5, unit.attackingOthers) -- a mob to taunt
- 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.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.cancelForm ()
-
Cancel current shapeshift form. Does nothing if the player isn't in a form, or if a cancel was
just sent and the server hasn't replied yet (the form still shows for a round trip).
Returns:
-
boolean
True when a cancel was sent now.
- unit.cancelFormFor (outOfFormSpell, treatOutSpellAsFree, emergency)
-
Leave the current shapeshift form to cast a spell, when a player would: not while stealthed,
not while tanking in a bear form, and only with the mana to cast it and shift back. In an
emergency it leaves regardless. Shows "Cancel Form [
]" in profile debug once, when the cancel is sent. In combat, until a form is up again, casts other than that spell leave the mana to shift back into the form left. Parameters:
- outOfFormSpell Spell to cast once out of form (id/name/spell table).
- treatOutSpellAsFree If true, that spell costs nothing this time (e.g. Clearcasting).
- emergency If true, leave form regardless (e.g. an emergency heal).
Returns:
-
boolean
True while the form is being left: cancelled now, or a cancel still on its way
(keep waiting rather than acting as if still in form).
- unit.canLeaveFormFor (outOfFormSpell, treatOutSpellAsFree, emergency)
-
Whether unit.cancelFormFor would leave the current form for this spell now (same rules), without leaving it:
for steps that come before the spell, such as a stun ahead of a heal. True when not in a form.
Parameters:
- outOfFormSpell Spell to cast once out of form (id/name/spell table).
- treatOutSpellAsFree If true, that spell costs nothing this time (e.g. Clearcasting).
- emergency If true, the mana to shift back isn't needed.
Returns:
- boolean
- string why not, when false
- unit.canFly ()
-
Check if player can fly
Returns:
-
boolean True if the player can fly in the current area
- 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.castingTankBuster (thisUnit)
-
True while the unit casts a spell from the tank buster list (System/Lists/TankBusters.lua)
Parameters:
- thisUnit The unit to check, defaults to "target"
Returns:
-
boolean
- unit.charmed (thisUnit)
-
Check if a unit is charmed
Parameters:
- thisUnit The unit to check
Returns:
-
boolean True if the unit is charmed
- unit.chased ([range=10])
-
Check if you're running away from an enemy that is chasing you
Parameters:
- range number How close the chasing enemy is (default 10)
Returns:
-
boolean True while an enemy within range chases you as you move away from it
Usage:
if unit.chased(10) and cast.able.dash() then
- unit.clearTarget ()
-
Clear current target
Returns:
-
nil
- unit.combatTime ()
-
Get combat time
Returns:
-
number Time in combat in seconds
- unit.critChance ()
-
Get the player's melee critical strike chance
Returns:
-
number Critical strike chance percentage
- unit.deadGroupMember (range, ...)
-
Get a dead player in your group, to resurrect
Parameters:
- range number Yards to look within
- ... Optional roles to pick from ("TANK", "HEALER", "DAMAGER"); anyone when none are given
Returns:
-
string|nil The unit, or nil when there's none
Usage:
local thisUnit = unit.deadGroupMember(30, "TANK", "HEALER")
- 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.dragonkin (thisUnit)
-
Check if a unit is Dragonkin
Parameters:
- thisUnit The unit to check, defaults to "target" if nil
Returns:
-
boolean True if the unit is Dragonkin
- unit.dualWielding ()
-
Check if player is dual wielding weapons
Returns:
-
boolean True if player is dual wielding
- 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.enemyNear (range)
-
Check if an enemy is close enough to start a fight
Parameters:
- range number Yards to look within
Returns:
-
boolean True when an enemy is already fighting within range, or an idle one's aggro range reaches you
Usage:
if not unit.inCombat() and unit.enemyNear(20) and cast.able.prowl() then
- unit.bleedImmune (thisUnit)
-
Whether the unit's kind of mob (NPC ID) has shown immune to your bleeds: five of them in a row went
out and the bleed never showed on it (unit:isBleedImmune; learned, and kept across sessions).
Parameters:
- thisUnit The unit to check, defaults to "target" if nil
Returns:
-
boolean True when it is counted bleed-immune
- unit.evading (thisUnit)
-
Whether the unit evades your attacks (an evade bug, or leashing home): an attack of yours came back
"EVADE" and none has landed since (10 s at most, or until you move 2 yd). BR doesn't pick it and holds
its damage spells.
Parameters:
- thisUnit The unit to check, defaults to "target" if nil
Returns:
-
boolean True while it evades
- 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.facingAngle (thisUnit)
-
The direction the unit faces, in radians
Parameters:
- thisUnit The unit to check, defaults to "player"
Returns:
-
number
- unit.facingDistance ()
-
How far to the side of the player's facing line the target stands (negative behind the player,
1000 when either can't be seen)
Returns:
-
number Yards
- unit.fallDist ()
-
How far the player has fallen
Returns:
-
number Distance in yards the player has fallen
- 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.fightStyle.dungeonRoute ()
-
Returns true when inside an active Mythic+ key run.
Returns:
-
boolean
- unit.fightStyle.dungeonSlice ()
-
Returns true when inside a regular (non-Mythic+) 5-man dungeon.
Returns:
-
boolean
- unit.fightStyle.patchwerk ()
-
Returns true when not in a 5-man party instance (raid, outdoor, etc.).
Returns:
-
boolean
- unit.fightLength (thisUnit)
-
Seconds the fight against thisUnit should last: its time to die once BR has measured it, else a
guess (a mob 4+ levels below you: 0, any other: 999). For commitments a guess is good enough for (a
totem); when the time matters (damage over time), unit.livesFor.
Parameters:
- thisUnit The unit, defaults to "target"
Returns:
-
number
Usage:
if unit.fightLength(enemy) >= 10 then -- drop a totem
- 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.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.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:
-
number, boolean, boolean, number icon, isActive, isCastable, spellID
- 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.getCurrentFormSpellID ()
-
Get the spell ID of the current shapeshift form (the spell that shifts back into it), or nil
when no form is active.
Returns:
-
number|nil Spell ID of the current form, or nil if no form is active.
- unit.groupCount ()
-
Get number of members in the current group (including player; 0 if solo)
Returns:
-
number Total group member count
- 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.healthAfterHeals (thisUnit)
-
Get unit's health once your heals on their way to it land (sent, not landed yet), at most its maximum.
Decide another heal or a potion on this: unit.health() still misses a heal about to land.
Parameters:
- thisUnit The unit to check, defaults to "player" if nil
Returns:
-
number Health of the unit after your heals on their way
- unit.hpAfterHeals (thisUnit)
-
Get unit's health percentage once your heals on their way to it land
Parameters:
- thisUnit The unit to check, defaults to "player" if nil
Returns:
-
number Health percentage of the unit after your heals on their way (0-100)
- 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.inAggroRange (thisUnit, offset, hostileOnly)
-
Check if a unit would aggro on the player
Parameters:
- thisUnit The unit to check, defaults to "target"
- offset Optional extra yards added to the aggro radius
- hostileOnly Optional: leave out a neutral target
Returns:
-
boolean True if hostile (or neutral and targeted) and within its aggro radius (centre to centre,
within 8 yards of your height), not tagged by someone else, and able to see you
- 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.inGroup ()
-
Check if player is in a group (party or raid)
Returns:
-
boolean True if player is in a group
- unit.groupHealer ()
-
The group member who heals you, or nil (solo, no healer, or yours is dead or beyond 40 yd): the Healer
role, else a member seen healing others twice this session
Returns:
-
string|nil The healer's unit token ("party2")
Usage:
local selfHeal = unit.solo() or not unit.groupHealer()
- unit.inRaid ()
-
True while the player is in a raid group
Returns:
-
boolean
- 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.inVehicle ()
-
True while the player rides a vehicle
Returns:
-
boolean
- 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; false while the
game has just refused a cast on thisUnit with "You must be behind your target"
- 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 or channelling
- 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.isFleeingFrom (thisUnit, fromUnit)
-
Check if a unit is moving away from another unit that is facing it (being chased)
Parameters:
- thisUnit The unit that may be fleeing, defaults to "player"
- fromUnit The unit it may be fleeing from, defaults to "target"
Returns:
-
boolean True if thisUnit is running from fromUnit
- 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
- string The tank
- 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.livesFor (thisUnit, seconds)
-
True when BR has measured thisUnit's time to die and it lives at least seconds more; false while
it's unknown (unit.ttd's 999). Use it rather than "unit.ttd(x) > N", which reads unknown as long.
Parameters:
- thisUnit The unit, defaults to "target"
- seconds number
Returns:
-
boolean
Usage:
if unit.livesFor(enemy, 12) then -- Flame Shock's 12 s of damage over time can tick
- unit.losing (thisUnit)
-
True when you'd die before thisUnit does: both times to die are measured and yours is shorter
(false while its time is unknown).
Parameters:
- thisUnit The unit, defaults to "target"
Returns:
-
boolean
Usage:
if unit.losing(enemy) then -- spend the cooldowns, heal
- 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.ooCombatTime ()
-
Get time out of combat
Returns:
-
number Time out of combat in seconds
- unit.outdoors ()
-
Check if player is outdoors
Returns:
-
boolean True if player is outdoors
- 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.position (thisUnit)
-
Where the unit stands
Parameters:
- thisUnit The unit to check, defaults to "player"
Returns:
-
number, number, number x, y, z
- unit.pressure (thisUnit)
-
Why the fight against thisUnit is going badly, for a debug line: "2 enemies on you" (within 8 yd),
"health 45%" (under half) or "losing: you 8.0s, it 12.5s" (unit.losing); nil when it isn't.
Parameters:
- thisUnit The unit fought, defaults to "target"
Returns:
-
string|nil
Usage:
local why = unit.pressure(enemy); if why then ui.debug("Casting Earth Shock [" .. why .. "]") end
- unit.pullable (thisUnit)
-
True when a profile may open a fight on thisUnit: valid, attackable, and never a player (attacking
one flags you for PvP)
Parameters:
- thisUnit The unit, defaults to "target"
Returns:
-
boolean
Usage:
if unit.pullable("target") and cast.lightningBolt("target") then -- the pull
- unit.pullTimer ()
-
Returns the time remaining on the pull timer (DBM/BigWigs)
Returns:
-
number - Returns seconds remaining on pull timer
- 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.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.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.readyToFight ()
-
Check if it's a good moment to start a fight
Returns:
-
boolean True when you aren't low on health or mana or eating or drinking, and in a group the tanks aren't low (Ready To Fight options, Targeting page)
Usage:
if not unit.inCombat() and unit.readyToFight() and cast.able.faerieFire("target") then
- 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.sinceSwing ([hand="mh"])
-
Seconds since the player's last swing landed (or since auto attack started its timer); nil
before either. A cast right after a swing costs the least swing time where a cast resets it.
Parameters:
- hand string "mh" for melee (the main hand), "oh" for the off hand, "ranged" for Auto Shot (default "mh")
Returns:
-
number|nil
Usage:
if (unit.sinceSwing() or 0) <= 0.4 then
- unit.solo ()
-
Check if player is solo (no group)
Returns:
-
boolean True if player is solo
- unit.spec ()
-
The name of the player's spec as BR loads it ("Initial" before a spec is chosen)
Returns:
-
string
- 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 ([thisUnit="target"])
-
Start auto-attack. Not sent again while auto attack on that unit is already on or on its way
(the game confirms a round trip later), nor at your target while auto attack is on (you or BR started
it); a different unit always goes out. So a profile calls it plainly, with no cast.auto.autoAttack() check.
Parameters:
- thisUnit The unit to attack (default "target")
Returns:
-
boolean True when it was sent
- unit.stopAttack ()
-
Stop auto-attack
Returns:
-
nil
- unit.swimming ()
-
Check if player is swimming
Returns:
-
boolean True if player is swimming
- unit.breathBar ()
-
Check if the player's breath bar is up (under water without water breathing)
Returns:
-
boolean True while the game's breath timer runs
- unit.swing ([hand="mh"])
-
The player's swing timer: seconds until the next swing (nil before the first swing), the
weapon speed and when the last swing landed (util.time())
Parameters:
- hand string "mh" for melee (the main hand), "oh" for the off hand, "ranged" for Auto Shot (default "mh")
Returns:
-
number, number, number
Usage:
local untilNext, speed, last = unit.swing("ranged")
- 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.tapDenied (thisUnit)
-
Whether the unit is tagged by someone else (tap denied): its kill isn't yours, and it doesn't
proximity-aggro you (unit.inAggroRange leaves it out)
Parameters:
- thisUnit The unit to check, defaults to "target" if nil
Returns:
-
boolean True when it's tagged by someone else
- 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.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 ([thisUnit])
-
Get the player's current threat status, on one enemy or on any
Parameters:
- thisUnit The enemy; any enemy when nil (optional)
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.timeSinceDismount ()
-
Seconds since the player last landed from a mount
Returns:
-
number|nil Seconds since dismounting, nil while mounted or if not mounted since login
- unit.totem (thisUnit)
-
True for a totem
Parameters:
- thisUnit The unit to check
Returns:
-
boolean
- unit.ttd (thisUnit, percent)
-
Estimate time until unit dies: an enemy, or the player ("player", from their own health), 999 when
it isn't known to be dying
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.unthreatened (thisUnit)
-
True when nothing in the fight against thisUnit threatens you: 60%+ health, one enemy at most within 8 yd,
and you're winning (unit.winning). For spending past a reserve while it's safe.
Parameters:
- thisUnit The unit fought, defaults to "target"
Returns:
-
boolean
Usage:
if unit.unthreatened(enemy) then -- spend the mana kept back for a heal
- 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.weaponDamage (thisUnit)
-
Get player's average weapon damage
Parameters:
- thisUnit The unit to check, defaults to "player" if nil
Returns:
-
number Average weapon damage
- unit.winning (thisUnit)
-
True when the fight against thisUnit is going your way: nothing is taking your health down, or it
dies in half the time you would or less (both times to die; unit.fightLength for it).
Parameters:
- thisUnit The unit, defaults to "target"
Returns:
-
boolean
Usage:
if unit.winning(enemy) then -- no need to hold mana back for a heal
- 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.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[, refreshUnder])
-
Check if a weapon imbue is missing (needs to be applied). Not while a cast of it is still being
watched (the enchant shows a moment after the cast), nor on a weapon a cast of it showed nothing on
(it doesn't hold it, e.g. a profession tool).
Parameters:
- imbueId
The imbue list (imbues.
) or enchant ID to check for - offHand Boolean whether to check offhand (true) or main hand (false, default)
- refreshUnder Seconds: also true when the imbue is on with less than this left (a top-up) (optional)
Returns:
-
boolean True if the imbue is NOT currently applied to the specified weapon (or is about to run
out), and applying it would take
- imbueId
The imbue list (imbues.
- 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.spellName (spellKey)
-
Get the display name of a weapon imbue spell
Parameters:
- spellKey The spell key string (e.g. "rockbiterWeapon") used in br.runner.spells
Returns:
-
string The localised spell name, or the key as a fallback