Configuration

config.yml is in plugins/nexusshout/ (plugins/NexusShout/ on BungeeCord). Run nshoutreload after editing. The default config.yml has a comment on every setting.

Discord settings are in their own file, see Discord. The multi-proxy section is covered in multi-proxy.

Reloading

nshoutreload reloads config.yml, discord.yml, and the language files. It also:

• registers the commands again, so alias changes and turning private messages on or off apply right away,
• clears all running cooldowns,
• restarts the Discord connection and reconnects to Redis.

Two settings are read only at startup and need a proxy restart: chat-listener-priority and hooks.

If config.yml cannot be read (for example, after a YAML mistake), an error is logged and NexusShout uses built-in defaults until you fix the file and reload. Those built-in defaults are not the same as the default file. For example, they require the nshout.use permission for global chat.

General settings

Commands

commands:
  aliases:
    - "gchat"
    - "shout"
  register-all-as-commands: true
  enable-chat-toggle: true
  start-with-global-chat: false

Message format

format: "&bGlobal &8| &a{server} &8|{custom_rank} {custom_name}&f: {message}"
formatter: "smart"

format sets how a global message looks. Built-in placeholders:

Any custom placeholder, such as {custom_rank}, also works here.

formatter decides how colors are read in format, in player messages, and in the language files:

• legacy: & codes such as &a and &l, and hex colors written as &#ff8800.
• minimessage: MiniMessage tags such as <green> and <gradient:#f12711:#f5af19>.
• smart: & codes are turned into MiniMessage tags first, so both work together.

Players without formatting-permission have colors and styles removed from what they type.

Custom placeholders

placeholders:
  custom_name:
    'nshout.name.admin': "&b&l{name}"
    'nshout.name.vip': "&6{name}"
    '_default_': "&f{name}"
  custom_rank:
    'nshout.rank.admin': " <gradient:#f12711:#f5af19>Admin</gradient>"
    'nshout.rank.mvp': " &6&lMVP&r"
    'nshout.rank.vip': " &eVIP&r"
    '_default_': ""

Each name under placeholders becomes a placeholder: custom_name is used as {custom_name}. Inside it, each line is a permission and the text shown for players who have it. _default_ is used when a player has none of them.

• Permissions are checked in alphabetical order, and the first one the player has wins. In the example, a player with both nshout.rank.admin and nshout.rank.vip shows as Admin.
• Any permission name works. It does not have to start with nshout..
• Values can use other placeholders, such as {name}, {server}, or {message}.
• You can add as many placeholders as you like, and use them in format and in the private message formats.

The default rank values start with a space, so players without a rank do not get a double space in the default format.

Cooldowns

cooldown:
  'nshout.cooldown.admin': 0
  'nshout.cooldown.vip': 7.5
  '_default_': 30

The time in seconds a player must wait between global messages. Permissions are checked from top to bottom, and the first one the player has wins. _default_ applies to everyone else. 0 means no cooldown.

Global chat and private messages have separate timers. Private messages use private-messages.cooldown, and anti-spam compares each message only with the player's previous message of the same kind. Cooldowns are cleared on reload.

Where global chat works

enabled-servers: []

List server names exactly as they are in the proxy config (velocity.toml, or config.yml on BungeeCord), for example ["Lobby-1", "SkyBlock"]. Empty means every server.

When the list is set, players on other servers cannot send global messages (they get the server-disabled message) and do not see them. Messages from Discord and from other proxies follow the same list.

Server display names

server-aliases:
  - "Lobby-1:Hub"
  - "Lobby-2:Hub"
  - "Skyblock-prototype:&cSecret"

Each line is ServerName:Display name. The display name is what {server} shows, and it can have color codes. Several servers can share one display name. Server names must match the proxy config exactly, including capital letters. Servers without an entry show their real name.

Chat prefix and toggle mode

• A chat message that starts with chat-prefix (default !) goes to global chat, without the prefix.
• /gchat with no message turns global chat mode on or off. While it is on, every chat message the player sends goes to global chat.
• commands.start-with-global-chat: true turns the mode on for every player when they join.
• The mode resets when the player leaves the network, unless the multi-proxy toggle-state feature is on.

A message meant for global chat never reaches the backend server, even when it is blocked (missing permission, cooldown, filter, or mute). For players on Minecraft 1.19.1 and newer, the chat prefix and toggle mode need a helper plugin. See signed chat.

Chat listener priority

chat-listener-priority: "NORMAL"

Decides when NexusShout handles chat compared to other proxy plugins: FIRST, EARLY, NORMAL, LATE, or LAST. Changes need a proxy restart.

EARLY and FIRST can run before other chat filters. LATE and LAST can bring back the double first message on unsigned chat setups. Chat that another plugin has already cancelled is left alone.

Filters

anti-flood:
  max-consecutive-chars: 5
anti-spam:
  similarity-threshold: 0.85
anti-caps:
  enabled: true
  action: "block"
  min-length: 8
  max-uppercase-percent: 70

Messages are checked in this order: mute, anti-caps, anti-flood, anti-spam, cooldown. The first check that fails stops the message and tells the player why.

Anti-spam compares against the last message the player sent, either in global chat or as a private message.

Private messages

private-messages:
  enabled: false
  sender-format: "&8[&bYou &3-> &f{receiver}&8] &f{message}"
  receiver-format: "&8[&f{sender} &3-> &bYou&8] &f{message}"
  permission: ""
  cooldown:
    'nshout.pm.cooldown.admin': 0
    '_default_': 3
  anti-flood: true
  anti-spam: true
  anti-caps: true
  aliases:
    - "nmsg"
    - "nms"
  reply-aliases:
    - "nr"
    - "nreply"

Private messages are off by default. They work across all servers on the network.

• Other placeholders, such as {custom_name}, are filled in for the player who sees the line: the sender in sender-format, the receiver in receiver-format.
• The reply command answers the last player you messaged, or who messaged you.
• formatting-permission also applies to private messages.
• Muted players cannot send private messages. Vanished players show as not found to /nmsg, except for players with nshout.vanish.see. See hooks.
• To take over /msg or /r, add them to the alias lists. A command registered on the proxy runs instead of a backend server command with the same name.

Hooks

hooks:
  litebans: true
  libertybans: true
  premiumvanish: true
  sayanvanish: true

Each hook only turns on when that plugin is installed on the proxy. Changes need a proxy restart.

• LiteBans and LibertyBans: muted players cannot use global chat or private messages.
• PremiumVanish and SayanVanish (1.4.0 to 1.7.3): vanished players show as not found to /nmsg and are left out of its tab completion, except for players with nshout.vanish.see. /nr still reaches a vanished player while you are the last player they messaged or got a message from. Their joins, leaves, and server switches are not posted to Discord.
• SayanVanish on BungeeCord (tested with 1.7.3): its own tab completion filter hides vanished players from everyone, staff included, so players with nshout.vanish.see only see them in /nmsg tab completion if that SayanVanish filter is turned off. Its default SQLite storage also fails to start on BungeeCord, so use MySQL or MariaDB for it there.

Debug

debug: false
debug-settings:
  log-placeholders: true
  log-cooldowns: true
  log-commands: true
  log-chat: true
  log-reloads: true

debug: true prints extra [DEBUG] lines to the console. debug-settings picks which kinds: placeholder values, cooldown checks, commands, chat messages, and reloads. Turn it off when you are done, since it can print every global message.