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:

  1. boolean
  2. 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:

  1. boolean True if a tank is in range
  2. 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
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

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
generated by LDoc 1.5.0 Last updated 2026-11-16 01:18:17