Spell Reagents are resources you use to cast a spell - the most standard being something like "mana". MythicRPG comes with a couple hardcoded reagents, but also allows you to create custom reagents that you can manipulate however you want, including by scaling using the stat system.
Reagents are the resources a player spends to cast a spell — *mana* is the canonical example. MythicRPG ships with one hardcoded reagent and lets you define any number of custom reagents, each of which can scale dynamically with the [stat] system.
| `health` | `hp` | Costs the player health when the spell is cast (deals damage equal to the consumed amount). |
Hardcoded reagents accept an `amount` (alias `a`) argument:
```yaml
Cost:
-health 5# shorthand
-health{amount=5}# full form
```
Each reagent file can have as many reagents in it as you'd like, but they must all have unique names.
## Custom Reagents
### Custom Stat Options
Custom reagents are defined in a `reagents.yml` file inside any [pack] folder. Each top-level key becomes a reagent id (case-insensitive); you can define as many as you'd like.
| Display | How the reagent is displayed in messages and GUIs. |
| MinValue | The minimum value of the reagent. Usually zero. |
| MaxValue | The max value of the reagent. Can be a stat using `stat.[stat_name]` |
| Global: true | If true, players always have this reagent. |
```yaml
```yaml
Mana:
Mana:
...
@@ -27,12 +27,29 @@ Mana:
...
@@ -27,12 +27,29 @@ Mana:
MinValue:0
MinValue:0
MaxValue:stat.MAX_MANA
MaxValue:stat.MAX_MANA
Global:true
Global:true
Stamina:
Display:'&aStamina'
MinValue:0
MaxValue:100
Global:true
```
```
#### Optional Supporting Stat
### Options
As you see above in the `MaxValue` option, instead of setting a static value it's possible to use a [stat] as the `MaxValue`, making it dynamically change depending on the player's stats.
| `Display` | How the reagent is displayed in messages and GUIs. Accepts legacy color codes / language keys. | |
| `MinValue` | Lower bound. Either a fixed number or `stat.<STAT_KEY>` to bind the floor to a player stat. | `0` |
| `MaxValue` | Upper bound. Either a fixed number or `stat.<STAT_KEY>` to bind the cap to a player stat. | `100` |
| `Global` | If `true`, every player has this reagent and starts with it tracked. If `false`, only players whose archetype/talent setup grants it will. | `false` |
| `ResourceBarStates` | List of [bar states](#resource-bar-states) used to render the reagent on the action bar. Optional. | |
### Stat-backed Min/Max
To implement one such [stat], you can write something like the following in the `stats.yml` file in any [pack] folder
Either `MinValue` or `MaxValue` can be tied to a [stat] using the `stat.<STAT_KEY>` form. This lets the reagent's range scale with whatever modifies that stat — gear, talents, archetype level, etc.
Define the supporting stat in a `stats.yml` file inside any [pack]:
```yaml
```yaml
MAX_MANA:
MAX_MANA:
...
@@ -45,25 +62,86 @@ MAX_MANA:
...
@@ -45,25 +62,86 @@ MAX_MANA:
Compound:'x<value>MaxMana'
Compound:'x<value>MaxMana'
```
```
## Consuming Reagents
Then `MaxValue: stat.MAX_MANA` makes the reagent's cap follow the stat's resolved value.
Reagents can be consumed when performing certain actions. You can consume them by:
- Using the [modifyresource](/Skills/Mechanics/ModifyResource) mechanic
## Resource Bar States
A reagent can declare one or more bar states under `ResourceBarStates:`. Each state has display tokens, optional conditions for when it's shown, and optional bar styling.
```yaml
```yaml
-modifyReagent{reagent=mana;amount=10} @self
Mana:
Display:'Mana'
MinValue:0
MaxValue:stat.MAX_MANA
Global:true
ResourceBarStates:
Default:
Display:'&b<name>&f<amount>/<max><bar>'
BarLength:20
BarFiller:'|'
BarSpacer:'.'
LowMana:
Display:'&c<name>&f<amount>/<max><bar>'
BarLength:20
Conditions:
-score{objective=combat;value=>0} true
```
```
- Selecting them as a Cost when casting a [Spell](/Spells)
| `Display` | The rendered string. Supports the placeholders below. | `<bar>` |
| `BarLength` | Total number of cells in the rendered `<bar>` / `<rechargebar>`. | `20` |
| `BarFiller` | Character used for filled cells. | `=` |
| `BarSpacer` | Character used for empty cells. | `-` |
| `Conditions` | List of Mythic [conditions](/Skills/Conditions) — the first state in declaration order whose conditions all pass is the one rendered. | |
### Display tokens
These tokens can appear inside `Display:` and are substituted at render time:
| `<percent>` | Current value as an integer percentage of max |
| `<bar>` | A filled bar of length `BarLength`, filled proportionally to `<percent>` |
| `<rechargebar>` | A bar reflecting the player's main-hand item recharge state |
## Consuming Reagents
There are two ways to spend a reagent:
### As a spell cost
Listed under a spell's `Cost:` block. The player must have at least the configured amount available; if they don't, the cast fails. On a successful cast, the amount is deducted automatically.
```yaml
```yaml
Fireball:
Spell:true
Trigger:~onUse
Cost:
Cost:
-Mana 50
-mana 50
-health 5
```
### Programmatically via mechanics
Use the [`modifyResource`](/Skills/Mechanics/ModifyResource) mechanic (alias `modifyReagent`) to add or subtract a reagent at any time. Negative amounts deduct, positive amounts grant.
```yaml
Skills:
-modifyResource{resource=mana;amount=10} @self ~onTimer:20# passive mana regen
Custom Reagent values can be displayed using PlaceholderAPI placeholders - we recommend using our HappyHUD plugin for this to create nice-looking reagent bars.
-`%mythic_reagent_[name]%` - The reagent's current value
Reagent values are exposed as `%mythic_reagent_<name>%` and `%mythic_reagent_max_<name>%`. See the [Placeholders](/Placeholders#reagents) page for the full list.
-`%mythic_reagent_max_[name]%` - The reagent's maximum value
