> For the complete documentation index, see [llms.txt](https://stellarskills.gitbook.io/stellarskills-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://stellarskills.gitbook.io/stellarskills-docs/configuration/heroes.md).

# heroes

A Hero class is an optional rare opportunity, not a forced selection. Enable it inside a class's `hero:` block.

```yaml
hero:
  enabled: true
  chance-percent: 0.25
  maximum-holders: 1
  inactivity-timeout: 1w
  badge: HERO CLASS
  reveal-title: THE FLAME HAS CHOSEN
  reveal-subtitle: A rare career is now available to you.
  reveal-style: inferno
  primary-color: '#FFC35C'
  secondary-color: '#F45132'
  duration-milliseconds: 6500
  animation-intensity: 1.0
  sound: true
  show-chance: false
  global-roll-sound: arc
  global-sound-volume: 1.0
  global-sound-pitch: 1.0
```

## Every field

| Field                                       | Meaning                                                                                  |
| ------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `enabled`                                   | Treat this class as Hero-only                                                            |
| `chance-percent`                            | Percentage from 0 to 100; `0.25` means 0.25%, not 25%                                    |
| `maximum-holders`                           | Maximum currently selected holders; 0 means unlimited                                    |
| `inactivity-timeout`                        | Time since last activity before selected holders lose this class; `disabled` disables it |
| `badge`                                     | Menu badge                                                                               |
| `reveal-title`, `reveal-subtitle`           | Reveal ceremony text                                                                     |
| `reveal-style`                              | `celestial`, `divine`, `inferno`, `storm`, `verdant`, `void`                             |
| `primary-color`, `secondary-color`          | Reveal colors                                                                            |
| `duration-milliseconds`                     | Reveal duration; valid range 1500–15000 ms                                               |
| `animation-intensity`                       | Valid range 0.25–3.0; reduced motion still respected                                     |
| `sound`                                     | Local reveal sounds                                                                      |
| `show-chance`                               | Display odds to the player                                                               |
| `global-roll-sound`                         | Global sound selection; see the current trigger limitation below                         |
| `global-sound-volume`, `global-sound-pitch` | Broadcast volume 0–4 and pitch 0.5–2                                                     |

Timeout values accept integer units `ms`, `s`, `m`, `h`, `d`, `w`, or ISO-8601 duration strings such as `P7D`. Prefer `1w`/`7d` for a week. It is real elapsed time, not seven sessions or seven Minecraft days.

## One chance, not one roll per UI opening

The database stores one player/class fate decision. Reopening, refreshing, reconnecting, normal class resets, and changing the odds do not reroll a stored decision. Unsuccessful Hero classes are omitted for that player. Successful players may choose the class later, subject to capacity and normal class requirements.

Capacity counts **selected holders**, not everybody with a successful unclaimed roll. A successful reveal does not reserve the last slot forever; selection rechecks capacity atomically. When capacity is full, players without a stored fate are not rolled for that class until space becomes available. Do not advertise a guaranteed reservation merely because a reveal played.

The client acknowledges a completed reveal. Reconnecting during it can replay the presentation but does not create a new fate decision.

## Inactivity release

Online players are touched and inactive selected Hero holders are swept roughly once per minute; login also checks expiry before refreshing last-seen. An expired player loses the class and receives a permanent forfeit for that class. The freed holder slot is available to eligible other players, but their prior failed rolls are not automatically rerolled.

Inactivity removal does not destroy all purchased tree ranks. Normal class access rules decide whether those stored ranks can contribute afterward.

## Grant/revoke for testing

```
/skills admin class hero status PlayerName
/skills admin class hero grant PlayerName hero_class_id
/skills admin class hero revoke PlayerName hero_class_id
```

Status is read-only and does not generate missing rolls. Grant explicitly overrides fate eligibility; it is not the same as selecting the class. Revoke is a deliberate test/reset operation: it clears the stored fate, forfeit, and active selection for that player/class, so capacity is released and the player can roll again on a later class-menu request. It is different from ordinary class remove/reset.

## Global audio: current source behavior

{% hint style="warning" %}
**In the current 1.0 source, the global sound is called after successful class selection, not at successful chance roll.** The parser accepts `global-roll-sound` with legacy `global-selection-sound` fallback, but the name does not change that trigger. Local Hero reveal sounds still play during the reveal. This is a documented implementation discrepancy, not a configuration mistake; the handbook does not modify the mod to fix it.
{% endhint %}

Global packets go to online clients that negotiated the compatible skills protocol, including across dimensions. Clients without the engine cannot play these bundled custom clips. Supported configured names are shown by the class schema; the bundled clips include `arc` and `gira`, and `none` disables the broadcast. Do not point this field at a server-local MP3 path.

The six reveal styles and class theme are separate selections: a class menu can use Covenant Atrium while one Hero uses a Void reveal.