NexaChat Documentation

license-key: "YOUR-KEY-HERE"

Main runtime settings for engine mode, license, mentions, performance cache, integrations, anti-spam, moderation, share previews and security.

engine:
  mode: "performance"
  lightweight:
    enabled-modules:
      - "filter"
      - "spam"
      - "render"
      - "mentions"
      - "emoji"
      - "local-chat"

license-key: "LICENSE"

mentions:
  enabled: true
  require-at-symbol: true
  highlight:
    format: "<yellow><bold>{mention}</bold></yellow>"
  sound:
    name: "BLOCK_NOTE_BLOCK_PLING"

performance:
  cache:
    placeholder-ttl-ms: 1500
    prefix-ttl-ms: 5000
  async-log-batch-size: 50
  async-log-flush-ticks: 40

Defines global, local, staff, trade, private and provider-backed channels.

resolver-order:
  - towny
  - lands
  - factions
  - superior-skyblock

channels:
  global:
    permission: ""
    format: "default"
    range: -1
    cooldown-seconds: 1.0
    spy-visible: true
    logging: true
    cross-server: false
  local:
    permission: ""
    format: "default"
    range: 100
    cooldown-seconds: 0.75
  staff:
    permission: "nexachat.channel.staff"
    format: "staff"
    spy-visible: false

Controls MiniMessage chat formats, rank format selection, hover text and click actions.

formats:
  default: "<dark_gray>[<aqua>{channel}</aqua>]</dark_gray> {rank_icon}{prefix}<white>{display_name}</white>{suffix} <dark_gray>&raquo;</dark_gray> <gray>{message}</gray>"
  staff: "<dark_gray>[<gold>Staff</gold>]</dark_gray> {rank_icon}{prefix}<yellow>{display_name}</yellow> <dark_gray>&raquo;</dark_gray> <white>{message}</white>"
  trade: "<dark_gray>[<green>Trade</green>]</dark_gray> {rank_icon}{prefix}<green>{display_name}</green> <dark_gray>&raquo;</dark_gray> <white>{message}</white>"

rank-formats:
  admin:
    permission: "nexachat.format.admin"
    weight: 100
    format: "staff"

json:
  hover: "<gray>Click to message <aqua>{player}</aqua>"
  suggest-command: "/msg {player} "

Controls optional plugin hooks. Missing plugins are treated as unavailable hooks, not fatal dependencies.

metadata-priority:
  - luckperms
  - vault
  - tab

luckperms:
  enabled: true
  use-prefix-suffix: true
  use-primary-group: true

placeholderapi:
  enabled: true

vault:
  enabled: true
  use-chat-fallback: true
  use-economy-placeholders: true

essentials:
  enabled: true
  use-nickname: true
  respect-vanish: true
  respect-mute: true
  command-compat-mode: "nexachat-first"

deluxemenus:
  enabled: true
  menu-command: "dm open nexachat_settings {player}"

Controls proxy, Redis and event-bus routing for cross-server chat events.

network:
  enabled: false
  # proxy: auto-detects the bridge from bungee.enabled / velocity.enabled below
  # bungee: native BungeeCord forwarding (Forward/ALL), no proxy jar needed
  # velocity: raw plugin messaging (requires the NexaChatVelocity proxy jar)
  # redis: Redis pub/sub between backends, no proxy jar needed
  # hybrid: proxy messaging + Redis combined (diagnostics only)
  transport: "proxy"
  # MUST be unique per backend. A server still on the default "server-1" refuses to start network sync and logs a SEVERE error.
  server-id: "server-1"
  shared-secret: ""
  dedupe-ttl-seconds: 30
  # When true, each event type is published on its own channel from network.channels below.
  multi-channel: false
  receive-format: "<dark_gray>[{server}/{channel}]</dark_gray> <aqua>{player}</aqua><gray>: </gray><white>{message}</white>"
  # Optional per-type overrides. Keys: chat, staff, mute, pm, mention, punish, spam.
  receive-formats:
    staff: "<dark_gray>[{server}/staff]</dark_gray> <red>{player}</red><gray>: </gray><white>{message}</white>"
  channels:
    chat: "nexachat:chat"
    staff: "nexachat:staff"
    mute: "nexachat:mute"
    pm: "nexachat:pm"
    mention: "nexachat:mention"
    punish: "nexachat:punish"
    spam: "nexachat:spam"

bungee:
  # Set true ONLY for the proxy type you actually run. Used to auto-select the bridge.
  enabled: true
  channel: "BungeeCord"
  sub-channel: "NexaChat"

velocity:
  # Set true ONLY for the proxy type you actually run. Used to auto-select the bridge.
  enabled: true
  channel: "nexachat:main"

redis:
  enabled: false
  host: "localhost"
  port: 6379
  channel: "nexachat:sync"

These files drive moderation thresholds, spam checks, advertising filters and rule engine actions.

spam:
  checks:
    cooldown:
      seconds: 1.0
    duplicate:
      enabled: true
    caps:
      min-length: 8
      max-ratio: 0.75
    adaptive:
      mute-points: 5
      kick-points: 8
  bypass-permission: "nexachat.bypass.spam"

filters:
  block-advertising: true
  whitelist:
    permissions:
      - "nexachat.bypass.filter"
  blocked-words:
    - "badword"

rules:
  ip-advertise:
    triggers:
      - "chat"
      - "sign"
      - "book"
    actions:
      - "warn"
      - "actionbar:<red>Advertising is not allowed."

Storage settings for SQLite, MySQL, MariaDB and YAML fallback behavior.

type: sqlite
fallback-provider: yaml

pool:
  maximum-size: 10
  minimum-idle: 2
  connection-timeout-ms: 10000

yaml:
  log-chat: false

mysql:
  host: localhost
  port: 3306
  database: nexachat
  username: root
  password: ""

mariadb:
  host: localhost
  port: 3306
  database: nexachat

Auxiliary runtime files for output channels, glyphs, Unicode cleanup and broadcast templates.

outputs:
  chat:
    enabled: true
  actionbar:
    enabled: true
  title:
    enabled: true
  bossbar:
    enabled: true

emoji:
  replacements:
    ":heart:": "<red>heart</red>"
  rank-icons:
    admin: "<red>A</red> "

normalization:
  enabled: true
  strip-accents: true
  lowercase: true

announcements:
  enabled: true

prefix: "<aqua>NexaChat</aqua> <dark_gray>|</dark_gray> "
no-permission: "<red>You do not have permission."
player-only: "<red>This command can only be used by players."

admin:
  status: "<aqua>NexaChat</aqua> <gray>version {version} is running."
  reloaded: "<green>NexaChat config reloaded."
  lightweight-preset: "<green>Lightweight preset saved. Run /nexachat reload or restart to switch pipeline."
  gui-unavailable: "<yellow>Opening built-in chat settings menu."

channel:
  current: "<gray>Current channel: <aqua>{channel}"
  switched: "<green>Switched to <aqua>{channel}</aqua> channel."
  invalid: "<red>Unknown or unavailable channel: {channel}"

pm:
  outgoing: "<gray>To <aqua>{target}</aqua>: <white>{message}"
  incoming: "<gray>From <aqua>{sender}</aqua>: <white>{message}"
  spy: "<dark_gray>[Spy]</dark_gray> <aqua>{sender}</aqua> -> <aqua>{target}</aqua>: <gray>{message}"

Put complex layout in DeluxeMenus and let NexaChat handle the command bridge. Keep the fallback menu for emergency access when the external menu plugin is unavailable.

integrations:
  deluxemenus:
    enabled: true
    menu-command: "dm open nexachat_settings {player}"

share:
  inventory-title: "Shared Inventory"
  shulker-title: "Shared Shulker"
  expire-seconds: 120

Purpose: Provides prefix, suffix and primary group metadata for chat formats.

Troubleshooting: If rank text is missing, confirm LuckPerms is installed before NexaChat, metadata is assigned on the correct context and luckperms.enabled is true.

1. Install LuckPerms.
2. Set group prefixes, suffixes and weights.
3. Confirm metadata priority includes luckperms.
4. Test with /nexachat status and a non-op player.

Purpose: Expands external placeholders inside NexaChat format and message output.

Troubleshooting: If placeholders stay blank, test them with /papi parse, install required expansions and check placeholderapi.enabled.

1. Install PlaceholderAPI.
2. Install expansions needed by your chat format.
3. Place the exact PAPI placeholder in formats.yml.
4. Reload PAPI, then reload NexaChat.

Purpose: Provides chat metadata fallback and economy balance placeholders.

Troubleshooting: If {vault_balance} is empty, confirm Vault has a valid economy provider and vault.use-economy-placeholders is true.

1. Install Vault and an economy provider.
2. Restart and confirm Vault reports a provider.
3. Enable Vault in integrations.yml.
4. Test {vault_balance} in a format with a normal player.

Purpose: EssentialsX supplies nickname, vanish and mute compatibility. SkinsRestorer helps offline-mode display-name fallback behavior.

Troubleshooting: If PM targets or names look wrong, verify vanish/mute settings and command compatibility mode.

1. Install the target plugin before NexaChat.
2. Enable the matching hook in integrations.yml.
3. Test nickname, vanish and mute behavior with non-op accounts.
4. Switch command-compat-mode only when command ownership conflicts with another plugin.

Purpose: Publishes chat, staff chat, mentions and moderation logs through reflection when DiscordSRV is installed.

Troubleshooting: If Discord output is missing, confirm the channel map and that DiscordSRV is fully connected before NexaChat publishes events.

1. Install and configure DiscordSRV.
2. Enable publish toggles in integrations.yml.
3. Map NexaChat channels to DiscordSRV channels.
4. Test public chat, staff chat and moderation actions separately.

Purpose: Enables packet-level rule checks for configured packet triggers.

Troubleshooting: If packet rules do not react, confirm ProtocolLib supports your server version and the trigger/action is enabled in rules.yml.

1. Install a compatible ProtocolLib build.
2. Restart the server.
3. Enable packet rules only after normal chat and command rules work.
4. Review console warnings from the packet adapter.

Purpose: Replaces the small fallback settings inventory with a fully configurable external menu command.

Troubleshooting: If /nexachat gui opens the fallback menu, check that DeluxeMenus is enabled and the configured command is valid.

1. Create a DeluxeMenus menu named for your NexaChat settings flow.
2. Set deluxemenus.menu-command to open it.
3. Use {player} in the command where DeluxeMenus expects a player.
4. Run /nexachat gui as a player.

Purpose: Loads configured glyphs, rank icons and permission icons only when the provider is installed.

Troubleshooting: If icons render as plain text, confirm the resource pack, provider glyph keys and MiniMessage output format.

1. Install the glyph provider and resource pack.
2. Configure glyph values in emoji.yml.
3. Use {rank_icon} or {permission_icons} in formats.
4. Test with one group before expanding to every rank.

Purpose: Sends chat, staff chat, PM, mention, mute and punishment events across a network.

Troubleshooting: If messages duplicate or vanish, confirm transport choice, server IDs, shared secret and channel names are identical where needed.

1. Start with one backend server and confirm local chat first.
2. Choose proxy or Redis transport.
3. Set unique server IDs.
4. Enable only the event types you actually need.
5. Test chat and staff chat before enabling moderation sync.

Purpose: Region, claim and group providers can influence channel membership, rule matching or future provider-specific chat workflows.

Troubleshooting: If provider channels do not behave as expected, confirm the provider is installed and the channel resolver is enabled. Some provider-specific member lookup remains a soft/no-op-safe surface in this build.

1. Install the provider plugin before NexaChat.
2. Enable the matching hook in integrations.yml.
3. Configure provider channels in channels.yml.
4. Test with real town, land, faction or island members.

Prerequisites: working single-server NexaChat on each backend, a BungeeCord proxy that knows all backend servers.

1. Stop every backend and the proxy.
2. Upload the nexachat-bungee jar to the proxy's /plugins folder.
3. Start the proxy once - it creates plugins/NexaChat/config.properties with channel and shared-secret.
4. On every backend edit network.yml:

network:
  enabled: true
  transport: "proxy"
  server-id: "lobby-1"
  shared-secret: "LONG-RANDOM-STRING"
  dedupe-ttl-seconds: 30

proxy:
  channel: "nexachat:main"

bungee:
  enabled: true
velocity:
  enabled: false

5. Set the same channel and shared-secret in the proxy's config.properties.
6. Make every backend server-id unique (e.g. lobby-1, survival-1, pvp-1).
7. Optional alternative without the proxy jar: transport: "bungee" uses native BungeeCord forwarding on the bungee.channel/bungee.sub-channel pair.
8. Set cross-server: true on each channel that should travel across servers (see channels.yml below).
9. Restart proxy and all backends, then send a chat message with a player on each server.

Prerequisites: working single-server NexaChat on each backend, Velocity proxy with backend forwarding configured.

1. Stop backends and proxy.
2. Upload the nexachat-velocity jar to the Velocity /plugins folder.
3. Start the proxy once - it creates plugins/nexachat/config.properties (channel=nexachat:main, shared-secret=).
4. On every backend edit network.yml:

network:
  enabled: true
  transport: "proxy"
  server-id: "skyblock-1"
  shared-secret: "LONG-RANDOM-STRING"

bungee:
  enabled: false
velocity:
  enabled: true
  channel: "nexachat:main"

5. Copy the same shared-secret into the Velocity config.properties and restart the proxy. With transport: "proxy" the backend auto-selects the Velocity bridge because only velocity.enabled is true. (transport: "velocity" also works as an explicit override.)
6. Enable cross-server: true on the channels that should sync.
7. Restart all backends and test chat between two servers with two accounts.

Prerequisites: a Redis instance reachable from every backend. No proxy module is needed.

1. Stop all backends.
2. On every backend edit network.yml:

network:
  enabled: true
  transport: "redis"
  server-id: "survival-2"
  shared-secret: "LONG-RANDOM-STRING"

redis:
  enabled: true
  host: "127.0.0.1"
  port: 6379
  password: "YOUR-REDIS-PASSWORD"
  database: 0
  channel: "nexachat:sync"

3. Use identical Redis host, credentials and redis.channel on every server.
4. Keep server-id unique per server.
5. Restart all backends and verify chat arrives on both servers.

Only channels marked cross-server: true are published to the network; incoming remote chat is also filtered by the receiving channel's cross-server flag, permission and visibility (so staff chat stays staff-only on every backend). Local chat with a bounded range should normally stay local.

channels:
  global:
    cross-server: true
  staff:
    cross-server: true
  local:
    cross-server: false

Received remote chat is rendered with network.receive-format; available placeholders: {server}, {channel}, {player}, {message}. Add receive-formats.chat and receive-formats.staff keys to override the format per event type (staff chat uses the staff key, everything else falls back to chat then to receive-format).

By default every event rides one channel (proxy.channel or the Redis channel). With network.multi-channel: true each event type is published on its own channel from network.channels - e.g. nexachat:chat, nexachat:staff, nexachat:pm. The proxy bridge modules (nexachat-bungee/nexachat-velocity) register every listed channel automatically.

network:
  transport: "hybrid"      # or proxy / redis
  multi-channel: true
  channels:
    chat: "nexachat:chat"
    staff: "nexachat:staff"
    mute: "nexachat:mute"
    pm: "nexachat:pm"
    mention: "nexachat:mention"
    punish: "nexachat:punish"
    spam: "nexachat:spam"

Keep the same channel names on every backend. With transport: "hybrid" multi-channel requires redis.enabled: true for the dedicated Redis channels; otherwise the plugin logs a warning and falls back to a single wire channel.

1. Unique server IDs: two backends with the same server-id will swallow each other's events. If a backend is still on the default server-1, network sync refuses to start and the startup log shows a SEVERE network.yml still uses the default server-id message - set unique IDs and restart.
2. One transport at a time: do not enable Redis while using proxy transport unless intentionally running hybrid.
3. Bridge flags: with transport: "proxy", set bungee.enabled/velocity.enabled to match your real proxy only. Both true makes Bungee win (console warning); both false leaves no bridge for plugin-message routing.
4. Shared secret: backend network.shared-secret and proxy config.properties shared-secret must match exactly. A mismatch shows as "Could not decode ... network event" in the proxy console.
5. Channel mismatch: proxy.channel/Velocity channel on backends must equal the channel registered by the proxy module.
6. No players online: proxy plugin-message transport cannot publish when a backend has zero players connected.
7. Channel flag: confirm the sending channel has cross-server: true.
8. Dedupe TTL: raise dedupe-ttl-seconds if events replay after long proxy hiccups; keep it sane for large networks.

Remove modules you do not need. Every removed module means fewer checks per chat message.

engine:
  mode: "lightweight"
  lightweight:
    enabled-modules:
      - "filter"
      - "spam"
      - "render"
      - "mentions"
      - "emoji"
      - "local-chat"

1. Add a new block under channels in channels.yml.
2. Point format at an existing or new format key in formats.yml.
3. Gate it with a permission and grant that permission to the target group.
4. /nexachat reload, then test with /channel <name>.

channels:
  vip:
    permission: "nexachat.channel.vip"
    format: "vip"
    range: -1
    cooldown-seconds: 1.0
    spy-visible: true
    logging: true
    cross-server: false

1. Set the prefix on the LuckPerms group: /lp group admin meta setprefix "&4Admin ".
2. Confirm metadata-priority in integrations.yml starts with luckperms.
3. Add a weighted rank format in formats.yml:

formats:
  vip: "<dark_gray>[<light_purple>VIP</light_purple>]</dark_gray> {prefix}<white>{display_name}</white> <dark_gray>&raquo;</dark_gray> <gray>{message}</gray>"

rank-formats:
  vip:
    permission: "nexachat.format.vip"
    weight: 50
    format: "vip"

4. /nexachat reload and test as a non-op player with the nexachat.format.vip permission.

Highest matching weight wins. Missing prefixes usually mean metadata priority or a missing LuckPerms context.

Rules react to triggers and run actions. Triggers: chat, command, sign, book and packet. Actions: cancel, replace, warn, mute, kick, command, reply, broadcast, actionbar, title, bossbar, discord, proxy, log.

rules:
  no-invite-trading:
    enabled: true
    priority: 40
    triggers:
      - "chat"
    pattern: "(?i)buy.*invite|sell.*invite"
    match-normalized: true
    whitelist:
      permissions:
        - "nexachat.bypass.filter"
    actions:
      - "cancel"
      - "reply:<red>Invites are not for sale here."
      - "broadcast:<gray>{player} attempted invite trading."

1. Add the rule, keep priority sensible (lower fires first).
2. /nexachat reload and test the pattern with a normal account.
3. Check the first console error if the YAML does not parse.

filters:
  block-advertising: true
  whitelist:
    permissions:
      - "nexachat.bypass.filter"

Combine with the bundled ip-advertise rule in rules.yml to also cover signs and books. Give only trusted staff nexachat.bypass.filter. Verify feedback via the configured actionbar/reply outputs.

1. Install and fully connect DiscordSRV first - NexaChat publishes through reflection and needs DiscordSRV online.
2. Enable the toggles in integrations.yml:

discordsrv:
  enabled: true
  publish-chat: true
  publish-staff-chat: true
  publish-mentions: true
  publish-moderation-logs: true
  inbound-channel-map:
    global: global
    staff: staff

3. Map NexaChat channels to DiscordSRV channels and test public chat, staff chat and moderation output separately.
4. /nexachat reload, then restart if DiscordSRV load order is the problem.

emoji:
  replacements:
    ":heart:": "<red>heart</red>"
    ":star:": "<yellow>star</yellow>"
  rank-icons:
    admin: "<red>A</red> "

• Plain MiniMessage replacements work without any extra plugin.
• ItemsAdder, Oraxen or Nexo glyphs: install the provider and resource pack, enable it under custom-font in integrations.yml, then use provider glyph values in emoji.yml.
• Use {rank_icon} and {permission_icons} inside chat formats.

1. Copy the bundled messages.yml values into the generated file in the plugin folder.
2. Translate the text values; keep every key name and every placeholder ({player}, {target}, {message}, {reason}, {channel}, {sender}) intact.
3. Use MiniMessage tags such as <green>; legacy & colors still work.
4. /nexachat reload and trigger each message in-game to verify.

1. Back up: copy the plugin folder including the SQLite file, and record plugin + server versions.
2. Stop the server.
3. Create the target database and grant a user with full privileges on it.
4. Change storage.yml to type: mysql (or mariadb) and fill the credentials.
5. Start the server. NexaChat creates its tables on first connect.
6. Old SQLite history is not auto-merged - restore or export historical logs separately if you need them for reporting.

type: mysql

mysql:
  host: localhost
  port: 3306
  database: nexachat
  username: nexachat_user
  password: "CHANGE-ME"

The editor exposes GUI pages for engine, moderation, channels, announcements, storage/network and formats, plus direct config edits:

/nexachat editor main
/nc editor get channels.yml channels.global.range
/nc editor set channels.yml channels.global.range -1
/nc editor toggle network.yml network.enabled
/nc editor add channels.yml channels.private-example.members Steve
/nc editor remove channels.yml channels.private-example.members Steve

• Requires nexachat.editor (default: op) - do not hand this to regular players.
• Editor writes edit YAML files directly; run /nexachat editor reload or /nexachat reload afterwards.
• Restart-level settings (license, storage driver, transport) still need a real restart.

enabled: true

announcements:
  events:
    enabled: true
    interval-seconds: 240
    initial-delay-seconds: 45
    permission: ""
    worlds: []
    random: true
    sound: "ENTITY_EXPERIENCE_ORB_PICKUP"
    outputs:
      - "chat"
      - "actionbar"
    messages:
      - "<gold>Event</gold> <gray>Vote for the server with /vote."
      - "<gold>Event</gold> <gray>Join our Discord for giveaways."

• One block per announcement group with its own interval, permission and world filters.
• random: true picks messages in random order instead of rotation.
• /nexachat reload after changes; test with /announcement broadcast.

1. Engine mode performance, storage sqlite.
2. Keep global + local channels; local range around 100 blocks.
3. Relax spam: raise anti-spam.cooldown-seconds slightly, keep duplicate/caps checks.
4. Enable mentions with sound and title output for community interaction.
5. Rank formats via LuckPerms prefixes; test with non-op accounts.

1. Enable staff channel (nexachat.channel.staff) and social spy for moderators.
2. Keep /clearchat, /mutechat and nexachat.bypass.* nodes on staff groups only.
3. Enable advertising filter + command-hiding rule for /plugins, /version.
4. Route staff chat cross-server when running multiple backends.
5. Use MySQL for durable moderation logs across restarts.

1. Follow the full Cross-Server Setup walkthrough.
2. MySQL/MariaDB storage on every backend for shared history/reporting.
3. Unique server-id per backend, one shared secret everywhere.
4. Enable only the event types you need; start with chat + staff.
5. Verify de-duplication: a message should appear once per server.

1. Get a baseline with /nexachat perf and server TPS.
2. Change one value, /nexachat reload, wait a few minutes of real traffic.
3. Compare again. Revert if timing numbers got worse.
4. If lightweight pipeline cuts too many features, prefer tuning cache/batch values first before switching engine mode.

security:
  hidden-commands:
    - plugins
    - pl
    - version
    - ver
    - about
  max-book-pages: 50
  max-book-page-length: 1024
  max-sign-length: 256
  command-spy: true

These limits bound sign/book inputs before filter layers run, keeping packet and content checks cheap.

Confirm Java 21, compatible server software, valid YAML files and a configured license key. Temporarily disable optional hooks if the console points to a third-party plugin conflict.

Check LuckPerms metadata, Vault chat fallback, TAB fallback, metadata priority and whether the player has the rank-format permission expected by formats.yml.

Verify the channel's range, world list, region list and whether the player actually switched to the local channel.

Confirm EssentialsX hook settings, command compatibility mode and whether the sender has nexachat.bypass.vanish or nexachat.bypass.mute.

Check nexachat.feature.item and nexachat.feature.inventory, token spelling, share expiry and whether the player is online when opening the preview.

Check transport type, server ID uniqueness, dedupe TTL, shared secret, proxy channel names and whether both proxy and Redis transports were accidentally enabled.

Install PlaceholderAPI, test the placeholder directly with PAPI, confirm the target expansion is installed and keep internal NexaChat placeholders spelled exactly as documented.