hChat Configuration

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:

chat:
  default-format: "[ping] [afk]&7{player}&8: &f{message}"

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

Sample config

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:

/hchat reload

You need the permission hchat.reload.

Home

hLobby

hChat

Community

Key sections

Format modes

Dynamic chat tokens

Sample config

Reloading config

​Key sections

​Format modes

​Dynamic chat tokens

​Sample config

​Reloading config

Key sections

Format modes

Dynamic chat tokens

Sample config

Reloading config