hChat

hChat — A modern and complete chat system for Paper 1.20+ servers.
Chat channels, direct messages, mentions, moderation (slowmode, chatlock, filters), AFK, staff chat, mail, replay, and more.

Features • Quick Start • Commands • Permissions • Configuration • Localization • Placeholders • Dependencies • Building • Contributing

✨ Features

⚡ Quick Start

📥 Installation

# 1. Download the latest JAR from Releases
wget https://github.com/hauchdev/hChat/releases/latest/download/hChat.jar

# 2. Drop it into your server's plugins folder
mv hChat.jar /your-server/plugins/

# 3. Make sure PlaceholderAPI is installed (required). LuckPerms is
#    recommended but no longer required

# 4. Restart or reload your server

hChat generates plugins/hChat/config.yml and plugins/hChat/lang/lang_en.yml on first start. Edit them, then run /hchat reload.

🎮 Commands

⌨️ Tab completion — every command supports it where it makes sense: /hchat completes its subcommands (reload, help, lang, update, filtered by permission) and /hchat lang completes the language codes from lang/; /message and /ignore complete online player names (/message also suggests offline players, since it can deliver offline messages); /channel completes the configured channel ids.

🔒 Permissions

⚙️ Configuration

config.yml is generated automatically on first start. The same file also controls every audio / visual cue the plugin emits.

# config-version is bumped automatically when new options are added;
# your settings are always kept (old file backed up as
# config-backup-v{n}.yml).
config-version: 10

lang: en
debug: false

update-checker:
  enabled: true
  notify-admins: true
  project: "hchat"

chat:
  default-format: "&7%luckperms_prefix% {player} %luckperms_suffix%&8: &f{message}"
  hex-colors: true
  formats:
    vip:
      permission: hchat.chat.format.vip
      format: "&6&lVIP &8» &e{prefix}{player}{suffix} &8: &f{message}"
    mvp:
      permission: hchat.chat.format.mvp
      format: "&b&lMVP &8» &b{prefix}{player}{suffix} &8: &7{message}"
    admin:
      permission: hchat.chat.format.admin
      format: "&c&lADMIN &8» &c{prefix}{player}{suffix} &8: &7{message}"

# Dynamic chat tokens: [ping] [item] [coords] [world] [afk]
placeholders:
  ping:
    enabled: true
    symbol: "▪"
    show-value: true
    value-suffix: "ms"
    good-max: 80
    medium-max: 150
    good-color: "&a"
    medium-color: "&e"
    bad-color: "&c"
    value-color: "&7"
  item:
    enabled: true
  coords:
    enabled: true
    format: "&7({x}, {y}, {z})"
  world:
    enabled: true
    format: "&7{world}"
  afk:
    enabled: true
    placeholder: "%essentials_afk%"
    afk-values: ["yes", "true"]
    format: "&c[AFK]&r "

welcome:
  enabled: true
  message: "&a&lWelcome &e{player} &a&lto the server!"
  hide-vanilla: true
  motd-on-join: false
  sound:
    enabled: true
    sound: "entity.player.levelup"
    volume: 0.6
    pitch: 1.0
  first-join:
    enabled: true
    message: "&6&l★ &e{player} &6just joined for the first time!"
    hide-vanilla: true

quit:
  enabled: true
  message: "&c{player} &7left the server."
  hide-vanilla: true

mentions:
  sound:
    enabled: true
    sound: "entity.experience_orb.pickup"
    volume: 1.0
    pitch: 1.0
  colors:
    enabled: true
    color: "&#54A3FF"
  # Bold highlight (a real background color is not possible in chat).
  highlight: true
  everyone-permission: hchat.mention.everyone
  here-permission: hchat.mention.here
  everyone-cooldown-seconds: 60
  everyone-sound:
    enabled: true
    sound: "entity.wither.spawn"
    volume: 1.0
    pitch: 1.0

direct-messages:
  sender:
    format: "&7[&eYou &7-> &e{receiver}&7] &7{message}"
    hover-text:
      enabled: false
  receiver:
    format: "&7[&e{sender} &7-> &eYou&7] &7{message}"
    hover-text:
      enabled: true
  clickable-actions:
    enabled: true
    reply-command: "/msg {sender}"
  silenced-action-bar:
    enabled: true
    text: "&e{receiver} is muted - the message was not delivered."

spy-format: "&e{sender} &7-> &e{target}&7: &7{message}"

hover-text:
  enabled: true
  format:
    - "&#54FF7F %player_name%"
    - "&7"
    - "&eClick to send a private message"

channels:
  default-by-permission:
    - permission: hchat.channel.default.vip
      channel: vip
  hint-on-switch: true
  hint-on-join: true
  global:
    range: -1
  local:
    format: "&8[Local] &7{player} &8» &f{message}"
    range: 80
    action-bar-hint: "&eThere are people talking near you"
    alias: "#l"
  staff:
    format: "&c[Staff] {player} &8» &f{message}"
    speak-permission: hchat.channel.staff
    see-permission: hchat.channel.staff.see
    alias: "#staff"
  vip:
    format: "&e[VIP] {player} &8» &f{message}"
    speak-permission: hchat.chat.format.vip
    alias: "#vip"
  trade:
    format: "&6[Trade] {player} &8» &f{message}"
    cooldown-ms: 5000
    alias: "#trade"
  world:
    format: "&7[{world}] {player} &8» &f{message}"
    range: -1
    per-world: true
    alias: "#world"

broadcast:
  enabled: true
  cooldown-ms: 0
  format:
    - ""
    - "&#2791F5Broadcast:"
    - "{message}"
  example1:
    enabled: true
    message: "&#F52727This broadcast sent every 10 minutes. Edit in /hChat/config.yml"
    interval: 600
    display-in-console: true

offline-messages:
  max-pending: 10
  sound:
    enabled: true
    sound: "entity.experience_orb.pickup"
    volume: 1.0
    pitch: 1.0

logging:
  private-messages:
    enabled: true
    path: logs
    retention-days: 30

word-filter:
  enabled: true
  words: ["blacklist1", "blacklist2"]
  action: "block"   # block | mask | warn

# Advanced filters (config v6): anti-caps, anti-unicode, anti-ad,
# anti-spam - see the "Filters" section below.
filters:
  anti-caps:
    enabled: true
    max-uppercase-percent: 70
    min-length: 8
    action: "mask"
  anti-unicode:
    enabled: true
    block-invisible: true
    action: "block"
  anti-ad:
    enabled: true
    patterns:
      - "(?<![a-zA-Z0-9])([a-z0-9-]+\\.)+(com|net|org|gg|io)"
      - "(discord\\.gg/|discordapp\\.com/invite/)"
    sensitivity: medium
    whitelist:
      - "tu-servidor.com"
      - "discord.gg/tuinvite"
    action: "warn"
  anti-spam:
    enabled: true
    global-cooldown-ms: 1500
    flood:
      max-messages: 5
      window-seconds: 3
      similarity-threshold: 0.8
    action: "block"

replay:
  capacity: 50

afk:
  enabled: true
  auto-timeout-seconds: 300
  check-interval-seconds: 30
  unset-on-activity: true
  notify-unset: true

slowmode:
  enabled: true
  seconds: 3
  bypass-permission: hchat.slowmode.bypass

chat-lock:
  enabled: true
  bypass-permission: hchat.chatlock.bypass

staff-chat:
  format: "&c[Staff] {player} &8» &f{message}"
  log-to-console: true

death-message:
  enabled: true
  format: "&c☠ &7{player} &fdied by {cause}"
  custom:
    FALL: "&c{player} learned to fly."
    LAVA: "&c{player} made friends with the magma."

🔁 Available placeholders

The renderer resolves every entry in two passes: first placeholders are substituted, then MessageFormatter parses the format. How formats are parsed is controlled by chat.format-mode:

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. Player-typed text is always escaped under MiniMessage modes: players can use & colors but cannot inject tags, click or hover events.

🎯 Dynamic chat tokens

hChat renders the following NoNChat-style tokens itself, inside every chat format (default format, chat.formats.* and channel formats):

Example format: "[ping] [afk]&7{player}&8: &f{message}". Each token can be enabled/disabled and tuned under the placeholders: section of config.yml (ping colors/thresholds, coords/world formats, the AFK placeholder and its afk-values). Tokens are resolved at the Component level after PAPI, so a literal [ping] typed by a player is never turned into an indicator.

📡 Chat Channels

Channels give every conversation its own format, visibility range, permissions and cooldown. Ship config includes global, local (distance-based), staff, vip, trade and world (per-world).

channels:
  local:
    format: "&8[Local] &7{player} &8» &f{message}"
    range: 80
    action-bar-hint: "&eThere are people talking near you"
    alias: "#l"
  staff:
    format: "&c[Staff] {player} &8» &f{message}"
    speak-permission: hchat.channel.staff
    see-permission: hchat.channel.staff.see
    alias: "#staff"

In game: /channel lists channels (click to switch), /channel <name> switches your active channel (remembered between sessions) and #staff hello sends to a channel from anywhere. The default channel (global) uses chat.default-format / the permission-based chat.formats (vip/mvp/admin).

🌐 Localization

Language files live in plugins/hChat/lang/. The plugin ships lang_en.yml and supports any number of additional files.

# lang_es.yml
no-permission: "&cYou do not have permission!"
player-only: "&cOnly players can use this command!"
player-offline: "&cPlayer is offline!"
mentioned: "&#ffffffYou were mentioned in chat by &#84FFB8{player}!"

Switch the server-wide language from config.yml:

lang: es

Each player can also override their own language with /hchat lang <lang> (stored in plugins/hChat/storage/player-lang.yml). At runtime, messages are looked up in the per-player file first and fall back to the server-wide lang setting from config.yml when the key is missing or the player has not chosen a language.

🔌 Placeholders

When PlaceholderAPI is installed, hChat registers the placeholders listed below.

Any placeholder that resolves against a player who is currently offline returns the safe (no-player) phrasing defined in lang_en.yml.

🛡️ Filters

Every chat message runs through a filter chain in this order: word-filter → anti-unicode → anti-caps → anti-ad → anti-spam. Each filter supports the same actions:

Word filter

word-filter:
  enabled: true
  words:
    - "blacklist1"
    - "blacklist2"
  action: "block"   # block | mask | warn

Anti-caps

Blocks / masks / lowercases messages that are mostly uppercase (max-uppercase-percent, min-length).

Anti-unicode

Blocks invisible characters used to bypass filters: zero-width spaces, direction overrides, BOM, tag characters (U+E0000+) and soft hyphens.

Anti-advertisement

Matches URLs and Discord invites with configurable regex patterns plus a whitelist (substring match) that always passes.

filters:
  anti-ad:
    enabled: true
    patterns:
      - "(?<![a-zA-Z0-9])([a-z0-9-]+\\.)+(com|net|org|gg|io)"
      - "(discord\\.gg/|discordapp\\.com/invite/)"
    whitelist:
      - "tu-servidor.com"
    action: "warn"

ℹ️ The default TLD list omits me on purpose — help.me would false-positive on normal prose.

Anti-spam

A global per-player cooldown (global-cooldown-ms) plus flood detection: more than max-messages within window-seconds, or a near-identical repeat (similarity-threshold), are blocked.

filters:
  anti-spam:
    enabled: true
    global-cooldown-ms: 1500
    flood:
      max-messages: 5
      window-seconds: 3
      similarity-threshold: 0.8
    action: "block"

📦 Broadcasts

/broadcast <message> (alias /bc) shows a configurable multi-line broadcast to every player on the server. The format is set under broadcast.format in config.yml and supports placeholders plus hex colors. Players with hchat.broadcast.color can use color codes inside the broadcast body.

For scheduled announcements, drop additional entries under broadcast.<id> with enabled, message, interval (in seconds) and display-in-console:

broadcast:
  example1:
    enabled: true
    message: "&#F52727This is a recurring broadcast every 10 minutes"
    interval: 600
    display-in-console: true

The scheduler is implemented in AutoBroadcastManager.

ℹ️ Discord bridge: when DiscordSRV is installed at startup, hChat logs a confirmation and reserves the integration for the upcoming chat bridge (see ROADMAP.md). No broadcast or /msg is currently relayed to Discord.

📨 Mail (Offline Messages)

If a player runs /msg Steve hola while Steve is offline, the message is stored with the sender name and timestamp in OfflineMessageStore (capped at offline-messages.max-pending per recipient). When Steve logs in he sees a clickable summary — &eYou have 3 pending messages. Click to read. — instead of automatic delivery:

Messages are only removed when read or cleared, and a sound plays on join if offline-messages.sound.enabled: true. If the target has never joined the server (hasPlayedBefore() == false), /msg falls back to the standard player-not-found message.

😴 AFK

hChat has a built-in AFK system — no Essentials needed:

• /afk toggles it; /afk <message> goes AFK with a reason.
• After afk.auto-timeout-seconds (default 300) of inactivity, players are marked AFK automatically.
• Any real activity (movement, chat, commands, interactions) removes the state (afk.unset-on-activity); returning players are announced in chat (afk.notify-unset).
• The [afk] chat token uses this state (with a PAPI fallback when the built-in feature is disabled).

🔌 Developer API

HChatProvider is the public entry point for other plugins. Get the singleton, then use its accessors:

import dev.hauch.hchat.api.HChatProvider;
import dev.hauch.hchat.model.ChatChannel;

public class MyListener implements Listener {

    public void demo() {
        HChatProvider api = HChatProvider.get();

        // who is spying right now
        for (java.util.UUID uuid : api.spyManager().getSpies()) {
            // ...
        }

        // last private message received by a player
        api.messageHistory().getLastMessage(player.getUniqueId());

        // the player's active channel
        ChatChannel channel = api.channelManager().activeChannel(player);

        // broadcast through an existing channel (staff, vip, ...),
        // honoring its see-permission
        api.publishToChannel(api.channelManager().get("staff"),
                "Server restarting in 5 minutes!");

        // DND state
        api.dndManager().isDnd(player);
    }
}

ℹ️ HChatProvider.get() throws IllegalStateException before the plugin is fully initialized (first ticks). Access it from ServerLoadEvent or later. Other plugins depending on hChat should declare it as a softdepend (or depend) in their plugin.yml.

🌐 Proxy note (Velocity / BungeeCord)

hChat runs inside the backend servers, not on the proxy:

• Player#getUniqueId and %player_name% keep working behind Velocity and BungeeCord — Paper forwards the real UUID and name to the backend.
• Private messages, offline messages, ignore and DND state are per backend server. A player connected to server A cannot /msg a player on server B; for cross-server chat use a proxy-side solution or the DiscordSRV bridge.
• {world} and [coords] placeholders resolve on the backend the player is currently on.
• The update checker, faststats.dev metrics and the auto-broadcast scheduler run once per backend instance — disable auto-broadcast on all but one server if you run a network and do not want duplicated announcements.

🧩 Dependencies

✅ Required

🟡 Optional (softdepend)

If DiscordSRV is present at startup, hChat logs a confirmation so admins know the hook is registered. Forwarding of /msg and /broadcast to Discord is not implemented yet — see ROADMAP.md for the planned bridge.

📊 Metrics (faststats.dev)

hChat bundles faststats.dev for anonymous plugin statistics — no extra download needed and nothing to configure: metrics are always on. No player or chat data is ever collected, only anonymous plugin usage counters.

🛠️ Building from Source

Requirements: JDK 21 and Maven 3.5+.

# Clone the repository
git clone https://github.com/hauchdev/hChat.git
cd hChat

# Compile & package
mvn clean package

# The shaded JAR is at: plugin-dist/target/hChat-<version>.jar

ℹ️ Releases — the plugin version lives in one place: the <revision> property at the top of the root pom.xml. Change it there (or pass -Drevision=1.3.0 to Maven) and every module, the filtered plugin.yml version and the final jar name follow automatically. You never have to touch the other 13 POM files.

CI is wired through .github/workflows/build.yml: every push to dev runs mvn clean verify. Tagged v* builds additionally publish a GitHub Release with the packaged JAR.

🤝 Contributing

Pull requests and ideas are very welcome.

Please follow Conventional Commits (Spanish or English both fine), update lang_en.yml / plugin.yml / README.md whenever you add a command, permission, or feature, and make sure mvn clean verify stays green. See ROADMAP.md for the larger picture and upcoming phases.

📄 License

Released under the MIT License.

_{Made with ❤️ by Hauchdev}