Skip to content

GitLab

VuhDo Custom Flag Bouquet Validators · Changes

Page history
Update VuhDo Custom Flag Bouquet Validators authored by Ivaria's avatar Ivaria
Hide whitespace changes
Inline Side-by-side
Showing with 131 additions and 76 deletions
VuhDo-Custom-Flag-Bouquet-Validators.md
View page @ 35c9aa67
Custom flags are bouquet validators which accept a user defined anonymous function that returns a boolean value. This allows for any custom condition to be used as part of the evaluation of a bouquet's chain of validators. These custom flag validators can be any valid Lua snippet which returns `true` or `false`.
# VuhDo Custom Flag Bouquet Validators
Custom flags are bouquet validators which accept a user defined anonymous function that returns a boolean value. This allows for any custom condition to be used as part of the evaluation of a bouquet's chain of validators. These custom flag validators can be any valid Lua snippet which returns `true` or `false`.
## Table of Contents
[[_TOC_]]
* Table of Contents
* Accessing Unit Information
* Example 1
* Checking for an Aura (Midnight)
* Example 2
* Example 3
* Deprecated: Debuff Icon and HoT Icon APIs
* Secret Values (Midnight)
* More Examples
* Unit Information Table Schema
## Accessing Unit Information
The `VUHDO_unitInfo` table provides the relevant cached information on the subject unit to the anonymous function.
The simple example below returns true if the unit is named 'Ivaria':
```lua
```
return ("Ivaria" == VUHDO_unitInfo["name"])
```
Full details on the unit information available in the `VUHDO_unitInfo` table can be found [below](https://gitlab.vuhdo.io/vuhdo/vuhdo/-/wikis/VuhDo-Custom-Flag-Bouquet-Validators/#unit-information-table-schema).
Full details on the unit information available in the `VUHDO_unitInfo` table can be found below.
### Example 1
The follow is a more complicated example which returns true only if the player's spell 'Prayer of Mending' is off cooldown and the unit is below 90% health:
The following is a more complicated example which returns true only if the player's spell 'Prayer of Mending' is off cooldown and the unit is below 90% health:
```lua
```
return ((VUHDO_getSpellCooldown("Prayer of Mending") == 0) and ((VUHDO_unitInfo["health"] / VUHDO_unitInfo["healthmax"]) < 0.9)) and true or false;
```
## Checking for a Debuff Icon
## Checking for an Aura (Midnight)
As of VuhDo for Midnight, aura presence for custom flags is resolved through **VuhDo's aura cache** (`VUHDO_UNIT_AURA_CACHE`). Only auras that VuhDo is already configured to track (for example via bouquets, aura groups, or panel aura displays) are present in this cache. If a spell is not tracked, these APIs will not find it even if the unit has the aura in game.
### `VUHDO_hasUnitAura(unit, spell, filter)`
Returns `true` if the unit has a **cached** aura matching `spell` (spell name string or spell ID number). Optional third argument `filter`:
As of VuhDo v3.168, there is a new API that must be used to determine whether a unit has an active Debuff Icon:
* `"HARMFUL"` — only harmful (debuff) auras
* `"HELPFUL"` — only helpful (buff) auras
* omitted or `nil` — any cached aura matching the spell
Spell IDs may be passed as numbers or as numeric strings (e.g. `"12345"`).
```
return VUHDO_hasUnitAura(VUHDO_unitInfo["unit"], "Penetrating Cold", "HARMFUL") or false;
```
```lua
VUHDO_hasUnitDebuff(<unit ID>, <spell name|spell ID>)
```
return VUHDO_hasUnitAura(VUHDO_unitInfo["unit"], 123456, "HELPFUL") or false;
```
### `VUHDO_getUnitAura(unit, spell, filter)`
Returns the **cached aura entry table** for the first matching aura, or `nil` if none. The same `spell` and `filter` rules as `VUHDO_hasUnitAura` apply. This is the same table VuhDo uses internally; treat it as read-only (do not assign into it from custom flags).
Typical keys (values may be Midnight *secret values*; see below):
| Key | Description |
|-----|-------------|
| `auraInstanceID` | Aura instance ID |
| `icon` | Texture file id or path |
| `name` | Aura name |
| `spellId` | Spell ID |
| `applications` | Stack count |
| `duration` | Total duration |
| `expirationTime` | Expiration time (compare with `GetTime()` for remaining time, only if present) |
| `sourceUnit` | Source unit token |
| `isHarmful` | Debuff |
| `isHelpful` | Buff |
| `dispelName` | Dispel type / school info where applicable |
### Example 2
Another example which returns true only if the unit is currently marked with a raid icon of 'Green Triangle' and also has a custom debuff active called 'Penetrating Cold':
Returns true only if the unit is marked with raid icon 'Green Triangle' (index 4) and has a cached harmful aura named 'Penetrating Cold':
```lua
return VUHDO_unitInfo["raidIcon"] == 4 and VUHDO_hasUnitDebuff(VUHDO_unitInfo["unit"], "Penetrating Cold") or false;
```
return VUHDO_unitInfo["raidIcon"] == 4 and VUHDO_hasUnitAura(VUHDO_unitInfo["unit"], "Penetrating Cold", "HARMFUL") or false;
```
## Checking for a HoT Icon
### Example 3
As of VuhDo v3.173, there is a new API that must be used to determine whether a unit has an active HoT Icon:
Returns true only if the unit has a cached helpful aura for 'Atonement' on the player:
```lua
VUHDO_hasUnitHot(<unit ID>, <spell name|spell ID>[, VUHDO_UNIT_HOT_TYPE_<MINE|OTHERS|BOTH|OTHERSHOTS>])
```
return VUHDO_hasUnitAura(VUHDO_unitInfo["unit"], "Atonement", "HELPFUL") or false;
```
The third optional argument to `VUHDO_hasUnitHot` specifies the unit type who must be the source of the HoT aura:
Use `VUHDO_getUnitAura` when you need stacks or timing. Use `issecretvalue()` before comparing or doing arithmetic on numeric fields:
* `VUHDO_UNIT_HOT_TYPE_MINE` - HoTs cast by the player.
* `VUHDO_UNIT_HOT_TYPE_OTHERS` - HoTs cast by other players.
* `VUHDO_UNIT_HOT_TYPE_BOTH` - HoTs cast by either the player or other players.
* `VUHDO_UNIT_HOT_TYPE_OTHERSHOT` - HoTs tracked via the special built-in `Other player's HoTs` bouquet.
```
local tAura = VUHDO_getUnitAura(VUHDO_unitInfo["unit"], "Renew", "HELPFUL");
local tStacks = tAura and tAura["applications"];
return tStacks and not issecretvalue(tStacks) and tStacks >= 3 or false;
```
When omitted, the third argument defaults to `VUHDO_UNIT_HOT_TYPE_MINE`.
## Deprecated: Debuff Icon and HoT Icon APIs
### Example 3
Older documentation referred to:
One more example which returns true only if the unit has an active HoT Icon tracking 'Atonement' cast by the player:
* `VUHDO_hasUnitDebuff(unit, spell)` — tied to the legacy **Debuff Icon** system
* `VUHDO_hasUnitHot(unit, spellName[, sourceType])` — tied to the legacy **HoT Icon** system
```lua
return VUHDO_hasUnitHot(VUHDO_unitInfo["unit"], "Atonement");
```
These functions **still exist** for backward compatibility but are implemented as thin wrappers around the Midnight aura cache:
* `VUHDO_hasUnitDebuff` is equivalent to `VUHDO_hasUnitAura(unit, spell, "HARMFUL")`
* `VUHDO_hasUnitHot` is equivalent to `VUHDO_hasUnitAura(unit, spellName, "HELPFUL")` (the old `sourceType` argument is ignored)
New custom flags should prefer **`VUHDO_hasUnitAura`** / **`VUHDO_getUnitAura`** directly.
## Secret Values (Midnight)
Some aura-related values may be secret in Midnight. Custom flag code must use `issecretvalue()` (and avoid native comparisons or arithmetic on secret values) when reading fields from the table returned by `VUHDO_getUnitAura`.
## More Examples
More example bouquets using custom flags of various kinds can be found via [Ivaria's profile on wago.io](https://wago.io/search/imports/wow/vuhdo?q=User%3A%22Ivaria%22). Note that not all of these have been updated to use the new Debuff and HoT Icon APIs.
More example bouquets using custom flags of various kinds can be found via Ivaria's profile on wago.io. Note that older examples may need updating to use the Midnight aura APIs above.
## Unit Information Table Schema
Unit information (`VUHDO_unitInfo` table):
Unit information (`VUHDO_unitInfo` table):
| key | type / value | value description |
| --- | ------ |----------|
|-----|--------------|---------------------|
| afk | boolean | true if unit is AFK |
| aggro | boolean | true if unit has aggro |
| charmed | boolean | true if unit is charmed |
| class | string | the unit's class name |
| classId | number | the unit's class ID |
| | 20 | warrior |
| | 21 | rogue |
| | 22 | hunter |
| | 23 | paladin |
| | 24 | mage |
| | 25 | warlock |
| | 26 | shaman |
| | 27 | druid |
| | 28 | priest |
| | 29 | death knight |
| | 30 | monk |
| | 31 | demon hunter |
| | 32 | evoker |
| 20 | warrior | |
| 21 | rogue | |
| 22 | hunter | |
| 23 | paladin | |
| 24 | mage | |
| 25 | warlock | |
| 26 | shaman | |
| 27 | druid | |
| 28 | priest | |
| 29 | death knight | |
| 30 | monk | |
| 31 | demon hunter | |
| 32 | evoker | |
| className | string | the unit's class name prettified |
| connected | boolean | true if unit is connected |
| dead | boolean | true if unit is dead |
| debuff | number | the unit's last active debuff type |
| | 0 | no active debuff |
| | 1 | poison |
| | 2 | disease |
| | 3 | magic |
| | 4 | curse |
| | 6 | custom debuff |
| | 7 | missing Buff Watch aura |
| | 8 | bleed |
| 0 | no active debuff | |
| 1 | poison | |
| 2 | disease | |
| 3 | magic | |
| 4 | curse | |
| 6 | custom debuff | |
| 7 | missing Buff Watch aura | |
| 8 | bleed | |
| debuffName | string | the most recent debuff on the unit |
| fullName | string | the full name of the unit |
| group | number | the group the unit is in |
......@@ -117,34 +172,34 @@ Unit information (`VUHDO_unitInfo` table):
| petUnit | string | the unit's pet unit ID |
| power | number | the unit's current power |
| powermax | number | the unit's maximum power |
| powertype | number | the type of power (see: https://warcraft.wiki.gg/wiki/Enum.PowerType) |
| | 0 | mana |
| | 1 | rage |
| | 2 | focus |
| | 3 | energy |
| | 4 | happiness |
| | 5 | runes |
| powertype | number | the type of power (see: <https://warcraft.wiki.gg/wiki/Enum.PowerType>) |
| 0 | mana | |
| 1 | rage | |
| 2 | focus | |
| 3 | energy | |
| 4 | happiness | |
| 5 | runes | |
| raidIcon | number | the raid icon if unit is marked |
| | 1 | yellow 4-point Star |
| | 2 | orange circle |
| | 3 | purple diamond |
| | 4 | green triangle |
| | 5 | white crescent moon |
| | 6 | blue square |
| | 7 | red "X" cross |
| | 8 | white skull |
| 1 | yellow 4-point Star | |
| 2 | orange circle | |
| 3 | purple diamond | |
| 4 | green triangle | |
| 5 | white crescent moon | |
| 6 | blue square | |
| 7 | red "X" cross | |
| 8 | white skull | |
| range | boolean | true if unit is in range |
| role | number | the unit's combat role |
| | 60 | melee tank |
| | 61 | melee damage |
| | 62 | ranged damage |
| | 63 | ranged heal |
| 60 | melee tank | |
| 61 | melee damage | |
| 62 | ranged damage | |
| 63 | ranged heal | |
| targetUnit | string | the unit's target |
| threat | number | the unit's threat status |
| | 0 | not tanking, lower threat than tank |
| | 1 | not tanking, higher threat than tank |
| | 2 | insecurely tanking, another unit has higher threat |
| | 3 | securely tanking, highest threat |
| 0 | not tanking, lower threat than tank | |
| 1 | not tanking, higher threat than tank | |
| 2 | insecurely tanking, another unit has higher threat | |
| 3 | securely tanking, highest threat | |
| threatPerc | number | the unit's threat percentage |
| unit | string | the unit ID |
| visible | boolean | true if the unit is visible |
\ No newline at end of file
| visible | boolean | true if the unit is visible |