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 145 additions and 98 deletions
VuhDo-Custom-Flag-Bouquet-Validators.md
View page @ a611f782
......@@ -7,10 +7,13 @@ Custom flags are bouquet validators which accept a user defined anonymous functi
* Table of Contents
* Accessing Unit Information
* Example 1
* Checking for an Aura (Midnight)
* Example 2
* Example 3
* Deprecated: Debuff Icon and HoT Icon APIs
* Checking for an Aura (Midnight)
* Example 4
* Example 5
* Example 6
* Classic: Debuff Icon and HoT Icon APIs
* Secret Values (Midnight)
* More Examples
* Unit Information Table Schema
......@@ -19,7 +22,17 @@ Custom flags are bouquet validators which accept a user defined anonymous functi
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':
### Example 1
Returns true if the unit is named 'Ivaria'. **Classic** and **Midnight** differ only in secret handling; the condition is the same.
**Midnight** (secret-safe):
```
return not issecretvalue(VUHDO_unitInfo["name"]) and ("Ivaria" == VUHDO_unitInfo["name"])
```
**Classic** (no secret values on player names in this context):
```
return ("Ivaria" == VUHDO_unitInfo["name"])
......@@ -27,12 +40,26 @@ return ("Ivaria" == VUHDO_unitInfo["name"])
Full details on the unit information available in the `VUHDO_unitInfo` table can be found below.
### Example 1
### Example 2
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:
A common pattern is to require two helpful auras at once. This returns true if the unit has both **Rejuvenation** and **Rejuvenation (Germination)** (Druid), using the Midnight aura cache:
```
return ((VUHDO_getSpellCooldown("Prayer of Mending") == 0) and ((VUHDO_unitInfo["health"] / VUHDO_unitInfo["healthmax"]) < 0.9)) and true or false;
return VUHDO_hasUnitAura(VUHDO_unitInfo["unit"], "Rejuvenation", "HELPFUL")
and VUHDO_hasUnitAura(VUHDO_unitInfo["unit"], "Rejuvenation (Germination)", "HELPFUL")
or false;
```
Spell names must match what the game uses; add both auras to VuhDo's tracking (bouquets / aura groups) so they appear in the cache.
### Example 3
On Classic flavors, use the simpler spell cooldown and health math below (no secret values). On **Midnight**, prefer [Example 2](#example-2) for aura checks, or guard health and cooldown returns with `issecretvalue()` (see [Secret Values (Midnight)](#secret-values-midnight)).
Returns true only if the player's spell 'Prayer of Mending' is off cooldown and the unit is below 90% health:
```
return ((VUHDO_getSpellCooldown("Prayer of Mending") == 0) and ((VUHDO_unitInfo["health"] / VUHDO_unitInfo["healthmax"]) < 0.9)) and true or false;
```
## Checking for an Aura (Midnight)
......@@ -59,7 +86,7 @@ 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).
Returns the **cached aura entry table** for the first matching aura. 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):
......@@ -77,22 +104,25 @@ Typical keys (values may be Midnight *secret values*; see below):
| `isHelpful` | Buff |
| `dispelName` | Dispel type / school info where applicable |
### Example 2
### Example 4
Returns true only if the unit is marked with raid icon 'Green Triangle' (index 4) and has a cached harmful aura named 'Penetrating Cold':
```
return VUHDO_unitInfo["raidIcon"] == 4 and VUHDO_hasUnitAura(VUHDO_unitInfo["unit"], "Penetrating Cold", "HARMFUL") or false;
local tIcon = VUHDO_unitInfo["raidIcon"];
return not issecretvalue(tIcon) and tIcon == 4 and VUHDO_hasUnitAura(VUHDO_unitInfo["unit"], "Penetrating Cold", "HARMFUL") or false;
```
### Example 3
### Example 5
Returns true only if the unit has a cached helpful aura for 'Atonement' on the player:
Returns true only if the unit has a cached helpful aura for 'Atonement':
```
return VUHDO_hasUnitAura(VUHDO_unitInfo["unit"], "Atonement", "HELPFUL") or false;
```
### Example 6
Use `VUHDO_getUnitAura` when you need stacks or timing. Use `issecretvalue()` before comparing or doing arithmetic on numeric fields:
```
......@@ -101,23 +131,29 @@ local tStacks = tAura and tAura["applications"];
return tStacks and not issecretvalue(tStacks) and tStacks >= 3 or false;
```
## Deprecated: Debuff Icon and HoT Icon APIs
## Classic: Debuff Icon and HoT Icon APIs
Older documentation referred to:
On **Classic** game flavors (Classic Era, Wrath, Cataclysm, etc.), custom flags should use the Debuff Icon and HoT Icon APIs — these are backed by the active **Debuff Icon** and **HoT Icon** systems:
* `VUHDO_hasUnitDebuff(unit, spell)` — tied to the legacy **Debuff Icon** system
* `VUHDO_hasUnitHot(unit, spellName[, sourceType])` — tied to the legacy **HoT Icon** system
* `VUHDO_hasUnitDebuff(unit, spell)` — presence of a tracked custom debuff (Debuff Icon list)
* `VUHDO_hasUnitHot(unit, spellName[, sourceType])` — presence of a tracked HoT (HoT Icon list; `VUHDO_UNIT_HOT_TYPE_*` applies)
These functions **still exist** for backward compatibility but are implemented as thin wrappers around the Midnight aura cache:
On **Midnight (Retail)**, those same function names still exist for backward compatibility but are implemented as thin wrappers around the 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)
* `VUHDO_hasUnitDebuff` behaves like `VUHDO_hasUnitAura(unit, spell, "HARMFUL")`
* `VUHDO_hasUnitHot` behaves like `VUHDO_hasUnitAura(unit, spellName, "HELPFUL")` (the old `sourceType` argument is ignored)
New custom flags should prefer **`VUHDO_hasUnitAura`** / **`VUHDO_getUnitAura`** directly.
New **Midnight** custom flags should use **`VUHDO_hasUnitAura`** / **`VUHDO_getUnitAura`** directly (see [Checking for an Aura (Midnight)](#checking-for-an-aura-midnight)).
## 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`.
In Midnight, some game-provided values are *secret values*: you must not use native Lua comparisons (`==`, `<`, etc.) or arithmetic (`+`, `/`, etc.) on them until you know they are not secret. Use `issecretvalue(x)` to test a value, or read the matching `hasSecretFoo` flag on `VUHDO_unitInfo` when VuhDo provides one.
**`VUHDO_unitInfo`:** Fields such as `health`, `healthmax`, `name`, `range`, `power`, `powermax`, and `raidIcon` may be secret. Prefer checking `VUHDO_unitInfo["hasSecretHealth"]`, `hasSecretHealthMax`, `hasSecretName`, `hasSecretRange`, `hasSecretPower`, or `hasSecretRaidIcon` where applicable, or call `issecretvalue()` on the field before comparing or doing math.
**`VUHDO_getSpellCooldown`:** The returned start time (and related values, when secrets are enabled) may be secret; guard with `issecretvalue()` before comparing to `0` or other numbers.
**`VUHDO_getUnitAura`:** Fields on the cached aura table may be secret; use `issecretvalue()` before comparisons or arithmetic on numeric or string fields (e.g. `applications`, `expirationTime`).
## More Examples
......@@ -125,81 +161,92 @@ More example bouquets using custom flags of various kinds can be found via Ivari
## Unit Information Table Schema
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 | |
| 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 | |
| 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 |
| health | number | the unit's current health |
| healthmax | number | the unit's maximum health |
| isAltPower | boolean | true if unit has an alt power active |
| isPet | boolean | true if unit is a pet |
| isVehicle | boolean | true if unit is in a vehicle |
| name | string | the name of the unit |
| ownerUnit | string | unit's owner if pet or vehicle |
| 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 | |
| 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 | |
| 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 | |
| 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 | |
| threatPerc | number | the unit's threat percentage |
| unit | string | the unit ID |
| visible | boolean | true if the unit is visible |
Unit information (`VUHDO_unitInfo` table). The **midnight only** column marks fields that exist only on Midnight (Retail); other keys are available on Classic flavors as well.
| key | type / value | Midnight only | value description |
|-----|--------------|---------------|-------------------|
| afk | boolean | no | true if unit is AFK |
| aggro | boolean | no | true if unit has aggro |
| charmed | boolean | no | true if unit is charmed |
| canAttack | boolean | yes | true if the player can attack the unit |
| class | string | no | the unit's class name |
| classId | number | no | the unit's class ID |
| 20 | warrior | no | |
| 21 | rogue | no | |
| 22 | hunter | no | |
| 23 | paladin | no | |
| 24 | mage | no | |
| 25 | warlock | no | |
| 26 | shaman | no | |
| 27 | druid | no | |
| 28 | priest | no | |
| 29 | death knight | no | |
| 30 | monk | no | |
| 31 | demon hunter | no | |
| 32 | evoker | no | |
| className | string | no | the unit's class name prettified |
| connected | boolean | no | true if unit is connected |
| dead | boolean | no | true if unit is dead |
| debuff | number | no | the unit's last active debuff type |
| 0 | no active debuff | no | |
| 1 | poison | no | |
| 2 | disease | no | |
| 3 | magic | no | |
| 4 | curse | no | |
| 6 | custom debuff | no | |
| 7 | missing Buff Watch aura | no | |
| 8 | bleed | no | |
| debuffName | string | no | the most recent debuff on the unit |
| fullName | string | no | the full name of the unit |
| group | number | no | the group the unit is in |
| health | number | no | the unit's current health |
| healthmax | number | no | the unit's maximum health |
| hasSecretHealth | boolean | yes | true if `health` is a secret value |
| hasSecretHealthMax | boolean | yes | true if `healthmax` is a secret value |
| isAltPower | boolean | no | true if unit has an alt power active |
| isPet | boolean | no | true if unit is a pet |
| isVehicle | boolean | no | true if unit is in a vehicle |
| name | string | no | the name of the unit |
| hasSecretName | boolean | yes | true if `name` is a secret value |
| number | number | no | the unit number from the unit ID (e.g. raid index) |
| ownerUnit | string | no | unit's owner if pet or vehicle |
| petUnit | string | no | the unit's pet unit ID |
| power | number | no | the unit's current power |
| powermax | number | no | the unit's maximum power |
| hasSecretPower | boolean | yes | true if `power` or `powermax` is a secret value |
| powertype | number | no | the type of power (see: <https://warcraft.wiki.gg/wiki/Enum.PowerType>) |
| 0 | mana | no | |
| 1 | rage | no | |
| 2 | focus | no | |
| 3 | energy | no | |
| 4 | happiness | no | |
| 5 | runes | no | |
| raidIcon | number | no | the raid icon if unit is marked |
| hasSecretRaidIcon | boolean | yes | true if `raidIcon` is a secret value |
| 1 | yellow 4-point Star | no | |
| 2 | orange circle | no | |
| 3 | purple diamond | no | |
| 4 | green triangle | no | |
| 5 | white crescent moon | no | |
| 6 | blue square | no | |
| 7 | red "X" cross | no | |
| 8 | white skull | no | |
| range | boolean | no | true if unit is in range |
| hasSecretRange | boolean | yes | true if `range` is a secret value |
| baseRange | boolean | yes | true if the unit passes `UnitInRange` (when not the player) |
| role | number | no | the unit's combat role |
| 60 | melee tank | no | |
| 61 | melee damage | no | |
| 62 | ranged damage | no | |
| 63 | ranged heal | no | |
| targetUnit | string | no | the unit's target |
| threat | number | no | the unit's threat status |
| 0 | not tanking, lower threat than tank | no | |
| 1 | not tanking, higher threat than tank | no | |
| 2 | insecurely tanking, another unit has higher threat | no | |
| 3 | securely tanking, highest threat | no | |
| threatPerc | number | no | the unit's threat percentage |
| unit | string | no | the unit ID |
| visible | boolean | no | true if the unit is visible |
| zone | string | yes | the unit's zone name |
| map | string | yes | the unit's map name |
\ No newline at end of file