Update Herochat to version 7.0.0, enhancing cross-server messaging capabilities and updating dependencies. Modify .gitlab-ci.yml for Maven image version, add deployment stage, and adjust pom.xml for groupId and version changes. Refactor ConfigManager and CrossServerListener for improved server list handling and asynchronous messaging.

Update README for version differences and installation instructions.


h1. Herochat 6 and 7

h2. Overview

Herochat is a channel-based chat plugin for Minecraft servers. Players join one or more channels, focus a single active channel for normal chat, and can use private messages, moderation tools, and (on networks) cross-server chat between backends.

* **Herochat 6.x** — Java 8–21, Spigot/Paper 1.20.x, package @com.dthielke.herochat@. Cross-server channel chat; 6.1.0 adds cross-server @/msg@ and @/r@.
* **Herochat 7.0** — Java 21+, Paper/Pufferfish **1.20.4+** ( @API-version: 1.20@), Maven @com.herocraftonline.herochat@. Same gameplay as 6.1.0 with Paper @AsyncChatEvent@, hardened cross-server, and new @com.herocraftonline.herochat.api@ / @HerochatAPI@ for integrations.

bc. **Requires Vault.** PlaceholderAPI is optional (soft dependency).

h2. Requirements

| Requirement | 6.x | 7.0 |
| Server | Spigot/Paper 1.20.x recommended | Paper or Pufferfish **1.20.4+** (also runs on 1.21.x) |
| Java | 8+ (6.1.0 builds use 21) | **21+** |
| Vault | Required | Required |
| PlaceholderAPI | Optional | Optional |
| Network proxy | Velocity/Bungee — **no Herochat on proxy**; plugin messages forwarded to backends |

h2. Version differences (6 → 7)

| Topic | 6.0.1 / Herochat Pro | 6.1.0 | 7.0.0 |
| Cross-server channels | Yes | Yes | Yes |
| Cross-server @/msg@ and @/r@ | No | Yes | Yes |
| Chat event | @AsyncPlayerChatEvent@ | Same | Paper @AsyncChatEvent@ |
| @plugin.yml api-version@ | Often none / 1.20 | 1.20 | **1.20** (not 1.21-only) |
| Public API package | @com.dthielke.herochat@ | Same | + @com.herocraftonline.herochat.api@ |

bc. **Network rule:** Use the **same JAR version** on every backend (Exodus, Release, etc.). Do not mix Herochat Pro (6.0.1) with 6.1.0 or 7.0.0.

h2. Installation

# Drop @Herochat-7.0.0-<build>.jar@ (or your CI artifact) into each backend’s @plugins/@ folder.
# Install **Vault** on each backend.
# Start the server once. Herochat creates its data folder and writes defaults (see below).
# Edit @plugins/Herochat/config.yml@ before enabling cross-server on a network.
# Restart (recommended over @/reload@ after changing cross-server settings).

h2. First run — what gets created automatically

On first enable, Herochat creates @plugins/Herochat/@ and writes missing options into @config.yml@. If no channels exist, it creates a **Global** channel.

| Path | Purpose |
| @plugins/Herochat/config.yml@ | Main settings (formats, spam, cross-server, locale) |
| @plugins/Herochat/channels/<name>.yml@ | One file per channel |
| @plugins/Herochat/chatters/<uuid>.yml@ | Per-player joins, ignores, PM reply target |
| @plugins/Herochat/logs/@ | Chat logs (if enabled) |

You do **not** need to hand-author these files for a basic server; defaults are applied on load and saved back to disk.

h2. config.yml reference

All keys below are **written automatically** if missing (@/ch reload@ merges defaults and saves).

h3. Moderation

| Key | Default | Description |
| @Moderator-permissions.can-kick@ | @True@ | Channel mods can kick |
| @Moderator-permissions.can-ban@ | @True@ | Channel mods can ban |
| @Moderator-permissions.can-mute@ | @True@ | Channel mods can mute |
| @Moderator-permissions.can-remove-channel@ | @True@ | Channel mods can remove channel |
| @Moderator-permissions.can-modify-nick@ | @True@ | Mods can change nick |
| @Moderator-permissions.can-modify-color@ | @True@ | Mods can change color |
| @Moderator-permissions.can-modify-distance@ | @True@ | Mods can change distance |
| @Moderator-permissions.can-modify-password@ | @True@ | Mods can change password |
| @Moderator-permissions.can-modify-format@ | @False@ | Mods can change format |
| @Moderator-permissions.can-modify-shortcut@ | @False@ | Mods can change shortcut |
| @Moderator-permissions.can-modify-verbose@ | @True@ | Mods can change verbose join/leave |
| @Moderator-permissions.can-modify-focusable@ | @False@ | Mods can change focusable |
| @Moderator-permissions.can-modify-crossworld@ | @False@ | Mods can change crossworld |
| @Moderator-permissions.can-color-messages@ | @True@ | Mods can use color in chat |
| @Moderator-permissions.can-view-info@ | @True@ | Mods can use @/ch info@ |
| @Moderator-permissions.can-focus@ | @True@ | Mods can focus channel |

h3. Channels and formats

| Key | Default | Description |
| @Default-channel@ | @Global@ | Channel players speak in when focused by default |
| @format.default@ | @[{nick}] {prefix}{sender}{suffix}: {msg}@ | Standard channel message format |
| @format.announce@ | @[{nick}] {msg}@ | Announcement format |
| @format.emote@ | @* {sender} {msg}@ | Emote format |
| @format.private-message@ | @From/To partner format@ | PM format (@{convoaddress}@, @{convopartner}@, etc.) |
| @use-channel-emotes@ | @True@ | Allow @/ch me@ style emotes in channels |

h3. Spam and filters

| Key | Default | Description |
| @spam.message-limit@ | @3@ | Messages allowed before spam filter trips |
| @spam.message-limit-buildoff@ | @20@ | Ticks between “cooldown” reductions |
| @censors@ | @[]@ | Regex list; matching messages are blocked |

h3. Logging and locale

| Key | Default | Description |
| @locale@ | @en_US@ | Messages bundle (@en_US@, @de@, @pt_BR@, etc.) |
| @Log-chat@ | @True@ | Write chat to @plugins/Herochat/logs/@ |
| @Log-to-bukkit@ | @False@ | Also log via Bukkit logger |
| @Log-colors@ | @False@ | Color codes in file logs |
| @Log-colors-to-bukkit@ | @False@ | Color codes in Bukkit logs |

h3. Private messages and Twitter-style

| Key | Default | Description |
| @twitter-style-private-messages@ | @True@ | @\@player message@ routes to @/ch msg@ |

h3. Cross-server (Velocity / Bungee backends)

| Key | Default | Description |
| @use-cross-server@ | @False@ | Enable plugin messaging to other backends |
| @Servername@ | @My Minecraft Server@ | Shown in PM format (@{servername}@) |
| @serveralias@ | @[M]@ | Short tag (@{serveralias}@) |
| @Servers@ | @[]@ | **Required when cross-server is on.** Velocity @Servers@ keys, e.g. @exodus@, @Release@ |

Example for a two-backend network (edit names to match **velocity.toml**):

<pre><code class="yaml">
use-cross-server: true
servername: Exodus
serveralias: '[E]'
servers:
- exodus
- release
</code></pre>

bc. Herochat is **not** installed on Velocity. The proxy only forwards @BungeeCord@ / @Herochat@ plugin messages. At least one player must be online on a backend for outbound messages to send (platform limitation).

h3. World aliases

| Key | Default | Description |
| @World-alias.<worldname>@ | (none) | Replace @{world}@ with alias when @{worldalias}@ is used in formats |

h2. Channel files ( @plugins/Herochat/channels/<name>.yml@)

Created by @/ch create <name> [nick]@ or on first-run Global channel. Missing keys are filled when the channel is loaded/saved.

| Key | Default | Description |
| @name@ | (filename) | Channel name |
| @Nick@ | @name@ | Shortcut / display nick |
| @format@ | @{{default}}@ | Channel format |
| @password@ | @(empty)@ | Join password; empty = none |
| @Color@ | @White@ | Channel color |
| @distance@ | @0@ | Block range (@0@ = global on this server) |
| @shortcutAllowed@ | @False@ | Allow @/<nick> message@ without switching focus |
| @verbose@ | @True@ | Join/leave announcements |
| @crossworld@ | @True@ | Hear members in other worlds |
| @Cross-server@ | @False@ | **Network:** broadcast to same channel on other backends |
| @muted@ | @False@ | Channel-wide mute |
| @spam.message-limit@ | @3@ | Per-channel spam override |
| @spam.message-limit-buildoff@ | @20@ | Per-channel spam buildoff |
| @worlds@ | @[]@ | Empty = all worlds; else restrict list |
| @Bans@ / @mutes@ / @moderators@ | @[]@ | UUID lists |

h2. Message format tags

| Tag | Replacement |
| @{default}@ | Default format from @config.yml@ |
| @{name}@ / @{nick}@ / @{color}@ | Channel name, nick, color |
| @{msg}@ | Message text |
| @{sender}@ / @{plainsender}@ | Display name / username |
| @{world}@ / @{worldalias}@ | World / configured alias |
| @{servername}@ / @{serveralias}@ | From @config.yml@ (cross-server networks) |
| @{prefix}@, @{suffix}@, @{group}@, @{groupprefix}@, @{groupsuffix}@ | Vault |
| @{convoaddress}@, @{convopartner}@, @{convoplainpartner}@ | Private messages |

PlaceholderAPI placeholders work in formats when PAPI is installed (7.0 applies per recipient where supported).

h2. Permissions

Channel name in permissions must be **lowercase**.

| Permission | Purpose |
| @herochat.create@ | Create channels |
| @herochat.save@ / @herochat.reload@ | Save / reload data |
| @herochat.mod@ | Moderation commands |
| @herochat.pm@ | Private messages |
| @herochat.join.<channel>@ | Join channel |
| @herochat.speak.<channel>@ | Speak in channel |
| @herochat.focus.<channel>@ | Focus channel |
| @herochat.bypass.spam@ | Bypass spam filter |
| @herochat.admin.stealth@ | Hidden from “no one hears you” |
| @herochat.admin.unignore@ | Cannot be ignored |

Grant @herochat.join.*@, @herochat.speak.*@, @herochat.leave.*@ broadly, then deny specific channels as needed.

h2. Commands

Root: @/ch@ (aliases: @Leave@, @Join@, @msg@, @Tell@, @pm@, @w@, @r@, @AFK@, @me@, etc.). Dedicated @/reply@ (alias @/r@) in 6.1.0+.

Type @/ch help@ or @/ch <command> ?@ in-game for details.

h2. Upgrading

h3. From Herochat Pro / 6.0.1 to 6.1.0 or 7.0

* Replace JAR on **all** network backends.
* Enable @use-cross-server@ and set @servers if you use cross-server PM/reply.
* Set @Cross-server: true@ on network channels in channel YAML on each backend (same channel name).

h3. From 6.1.0 to 7.0

* Use Java 21+ on the host.
* Server must be Paper/Pufferfish **1.20.4+** ( @API-version 1.21@ will **not** load on 1.20.4).
* Existing @plugins/Herochat/@ data is compatible; config keys are unchanged.
* Plugin integrations: @com.dthielke.herochat@ API unchanged; new code may use @HerochatAPI@ and @com.herocraftonline.herochat.api@.

See @MIGRATION.md@ in the repository for Maven coordinates and relocation POM.

h2. For developers

* **Existing:** @com.dthielke.herochat.ChannelChatEvent@, @Chatter@, @Herochat.getChannelManager()@, etc.
* **7.0 new:** @com.herocraftonline.herochat.HerochatAPI@, @com.herocraftonline.herochat.api.*@ (mirror types in the same JAR).

Listen for @ChannelChatEvent@ on the main thread after chat is processed. If you change the target channel on the event, call @event.setResult(event.getSender().canSpeak(newChannel))@ unless you intentionally bypass checks.

h2. FAQ

*Q: Plugin fails with “Unsupported API version 1.21”?*
*A:* You are on Minecraft 1.20.x but installed a build with @API-version: '1.21'@. Use Herochat **7.0.0** with @API-version: '1.20'@ (current builds).

*Q: Cross-server does nothing / no PM across servers?*
*A:* Check @use-cross-server: true@, non-empty @servers matching Velocity, same JAR on all backends, @Cross-server: true@ on the channel, and at least one player online to carry plugin messages.

*Q: Autojoin did not work?*
*A:* @herochat.autojoin.<channel>@ only applies when the player has **no** existing chatter file (first join with Herochat).

*Q: @{world}@ appears but I did not put it in the format?*
*A:* Another plugin (often Multiverse) injects world prefixes; adjust that plugin’s config.

h2. Support

Herocraft Online — internal deployments: align JAR and @config.yml@ across Exodus, Release, and other backends per @TESTING.md@.

Version Update Summary
✅ Updated Version to 6.1.0

• pom.xml: Changed from 6.0.1-SNAPSHOT to 6.1.0

• plugin.yml: Changed from 6.0.2-SNAPSHOT-blocal to 6.1.0-blocal

This version bump to 6.1.0 appropriately reflects the significant modernization changes made:

• Java 7 → Java 21

• Spigot 1.13 → Spigot 1.20.4

• Updated Maven plugins and dependencies

• Fixed deprecated API usage

• Repository modernization

Rebase and update versions, prep for some changes.

Updated things, recompiled and tested hex chat colorization (FAQs)

You can display hex colours with Herochat Pro by starting with §x, then for each of the 6 characters in the hex code, prefix them with a §. For example, to show colour #90435D you would use... §x§9§0§4§3§5§D.

No change in API!

Re-up for version updates

Various bug fixes preparing for hex

Some bug fixes, should work for 1.16+ please post issues

Not required to update, minor changes.

This is an attempt to roll back the emote command to see if we fixed stuff...

Please leave feedback unnecessary update otherwise.

More to come!

Note: this may need more testing, please post bugs.
Changes. Special thanks to @dwi
#31 (Jul 25, 2018 11:34:18 AM)

1. Add the simple file — Kainzo / gitlab
2. Update Messages_es.properties — Kainzo / gitlab
3. Upgrade PlaceholderAPI depency — omg / gitlab
4. Compile with Spigot 1.13 API — omg / gitlab
5. Fix the emote command containing hardcoded player name. The default — omg / gitlab
6. Fix the help page number is offset by -1 — omg / gitlab
7. Remove the %1$s/%2$s parts. Might cause issues with PlaceholderAPI. If — omg / gitlab
8. Backward compatibility with Factions and other plugins relating on old — omg / gitlab

Changes

1. Make sure the server from a Bungee PlayerList message isn't "ALL". (detail / gitlab)
2. Update for Spanish translation "messages_es" (detail / gitlab)
3. Fix this. (detail / gitlab)

FactionChat fixes.

Changes

1. Put the Events back to ensure backwards compatibility (detail / gitlab)

Changes

1. Do not use String.format(), will cause problems in the future with PAPI (detail / gitlab)
2. Do not send {serveralias} and {servername} to the players on the same (detail / gitlab)
3. Initial PlaceholderAPI support (detail / gitlab)

(6.0.1)
Thanks to @dwi for the hard work piecing this update together!
config.yml
Then add to each channel you want forwarded
"cross-server: true"

Changes

1. New config option log-colors-to-bukkit that enables colored logging in (detail / gitlab)
2. Added Czech localization (detail / gitlab)
3. Initial migration of BungeeCord support from Herochat 5.7. Cross server (detail / gitlab)

Thanks to @Eisenwave - we will be doing bi-weekly updates on new features of Herochat! This week is adding a spam filter to all channels. Based on feedback and comments, we'll attempt to add as many bug fixes and features as possible!

#23 (Mar 4, 2018 5:49:12 PM)

1. Update to 6.0.0 in the POM.xml — Kainzo / gitlab

#21 (Mar 3, 2018 6:33:33 PM)

1. Revert "Revert "Added UUID support."" — rramos / gitlab
2. version bump — rramos / gitlab
3. initial inspect, clean, simplify, annotate — janschultke / gitlab
4. more cleanup — janschultke / gitlab
5. even more cleanup — janschultke / gitlab
6. cleanup & docs — janschultke / gitlab
7. spam filter and stuff — janschultke / gitlab
8. final cleanup before features — janschultke / gitlab
9. per-channel spam-tracking fully implemented — janschultke / gitlab

Re-upping this while we work on the previous build based on feedback.

WARNING: this is still considered a "beta" build. It should function, it passed our basic testing.

Apologies for the delays on bug fixing! We had to reproduce the issues on 1.12 and we believe we've fixed them all. Please update to latest if you are on 1.12

There's been a lot of RL stuff getting in the way.

Thanks to @mung3r for jumping in and fixing this up.