> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hauch.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# hChat Configuration

> Complete reference for hChat's config.yml.

On first start, hChat generates `plugins/hChat/config.yml`. This page covers the most important sections. For a full annotated config, inspect the generated file directly.

## Key sections

* `general` — language, debug, update checks.
* `chat` — default format, permission-based formats, format mode.
* `channels` — per-channel format, range, cooldown, aliases, permissions.
* `private-messages` — DM format, spy format, sound, hover, click actions.
* `mentions` — sound, color, cooldown.
* `broadcast` — manual and scheduled broadcasts.
* `filters` — word filter, anti-caps, anti-unicode, anti-ad, anti-spam.
* `offline-messages` — mail storage limits and notifications.
* `afk` — timeout, auto-detection, messages.
* `placeholders` — ping, item, coords, world, AFK tokens.
* `logger` — rotating daily logs and retention.
* `metrics` — FastStats settings.

## Format modes

The renderer resolves formats in two passes: first placeholders are substituted, then the formatter parses the result.

| Mode | Behavior |
| - | - |
| `legacy` | Classic `&` codes + `&#RRGGBB` hex (default, backwards compatible). |
| `minimessage` | MiniMessage tags (`<red>`, `<gradient:red:blue>`, `<#RRGGBB>`, hover/click). Classic `&` codes and `&#RRGGBB` hex are still translated. |
| `auto` | Legacy when the format contains `&` codes, MiniMessage otherwise. |

Every channel can override the global mode with its own `format-mode` key, so a `global` channel in legacy and a `staff` channel in MiniMessage can coexist.

## Dynamic chat tokens

hChat renders the following tokens inside every chat format:

| Token | Replaced with |
| - | - |
| `[ping]` | Colored latency indicator. |
| `[item]` | Main-hand item with hover tooltip. |
| `[coords]` | Player position as `x, y, z`. |
| `[world]` | Current world name. |
| `[afk]` | `[AFK]` prefix when the player is away. |

Example format:

```yaml theme={null}
chat:
  default-format: "[ping] [afk]&7{player}&8: &f{message}"
```

Each token can be enabled/disabled and tuned under the `placeholders:` section.

## Sample config

```yaml theme={null}
general:
  lang: en
  debug: false
  check-updates: true

chat:
  format-mode: legacy
  default-format: "[ping] [afk]&7{player}&8: &f{message}"
  formats:
    vip:
      permission: hchat.format.vip
      format: "&a[VIP] &7{player}&8: &f{message}"

channels:
  enabled: true
  default: global
  local:
    format: "&8[Local] &7{player} &8» &f{message}"
    range: 80
    alias: "#l"
  staff:
    format: "&c[Staff] {player} &8» &f{message}"
    speak-permission: hchat.channel.staff
    see-permission: hchat.channel.staff.see
    alias: "#staff"

filters:
  word-filter:
    enabled: true
    words:
      - "badword1"
    action: block
  anti-caps:
    enabled: true
    action: lowercase
  anti-unicode:
    enabled: true
    action: block
  anti-ad:
    enabled: true
    action: warn
  anti-spam:
    enabled: true
    global-cooldown-ms: 1500
    action: block

logger:
  enabled: true
  retention-days: 7
```

## Reloading config

After editing `config.yml`, run:

```bash theme={null}
/hchat reload
```

You need the permission `hchat.reload`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.