# meters

Meters are dynamic, graphical progress bars on a dashboard used to visually track changing numerical valuesâ€”such as Hit Points (HP), Mana, Movement, or target health. They support real-time color transitions (Color Thresholds) and script execution boundaries (Trigger Thresholds).

---
## 1. Color Thresholds (Visual Transitions)

Color Thresholds define when and how the meter's background fill color changes as the value moves. 
### Syntax Format:
Thresholds are defined as a comma-separated list:
`[Name:]Color:Value[:ColorAnsiIndex]`

- **Name** (Optional): A custom name for the threshold (e.g., `Danger`). If omitted, it is auto-named `T1`, `T2`, etc.
- **Color**: A hexadecimal color code or a standard color name (e.g., `Red`, `Green`, `#FF5500`).
- **Value**: The percentage value (0 to 100) at which this threshold becomes active.
- **ColorAnsiIndex** (Optional): An index (0 to 15) referencing the current session's ANSI color palette.
### Evaluation Logic:
When a meter updates, the engine evaluates the thresholds in **descending order** of their percentage value:
1. It compares the current filled percentage (`currentPct`) to each threshold value.
2. The **first** threshold where `currentPct >= thresholdValue` is selected.
3. If no threshold matches, the meter retains its default background color.
### Example:
`/dashadd {MyStats} meter 1 0 1 10 {HP} {0} {100} {Char.HP} {Red:25,Yellow:75,Green:100} 1 percent`
- **100% HP**: Matches `Green:100` (`100 >= 100` is true). Bar turns **Green**.
- **80% HP**: Matches `Yellow:75` (`80 >= 75` is true). Bar turns **Yellow**.
- **50% HP**: Matches `Red:25` (`50 >= 25` is true). Bar turns **Red**.
- **10% HP**: Matches nothing (`10 >= 25` is false). Bar reverts to default.

---
## 2. Trigger Thresholds (Automations & Scripts)

Meters can execute commands or scripts when a threshold boundary is crossed. This is incredibly useful for automations, such as auto-healing or warning alerts.
### How Boundary Crossing Works:
Every time the meter's value changes, the engine evaluates two crossing states for each threshold:
- **crossedDown**: The percentage was greater than or equal to the threshold, and is now less than it.
- **crossedUp**: The percentage was less than the threshold, and is now greater than or equal to it.
### Trigger Formatting:
When a boundary is crossed, the engine triggers an event targeting `{MeterName}.{ThresholdName}`:
- **Target Name**: `{MeterName}.{ThresholdName}` (e.g., `HP.Danger` or `Mana.T1`).
- **Direction**: `down`, `up`, or `both`.

If a script trigger matches this target and direction, its command is executed instantly.
### Practical Example:
1. Define a meter named `HP` with a named threshold at 25%:
   `/dashadd {MyStats} meter 1 0 1 10 {HP} {0} {100} {Char.HP} {Danger:Red:25} 1 percent`
2. Create a threshold trigger that executes when `HP.Danger` is crossed **down**:
   - If your HP drops from 30% to 20%, `crossedDown` triggers and runs your mapped auto-heal action (e.g., `cast 'cure critical'`).

---
## Command Syntax Reference

- **/dashadd {dash} meter {row} {col} {rowspan} {colspan} {name} {min} {max} {valVar} {thresholds} {showName} {showMode} {fontSize} {fontColor} {direction} [cornerRadius] [clickCmd;rightClickCmd]**
- **/dashset {dash} {name} {property} {value}**
  - Use `/dashset {dash} {name} {colorThresholds} {newThresholdsString}` to dynamically modify color thresholds.
## See Also:
dashadd, dashset, dashboard
