Install CoreChatX cleanly on Paper or Velocity.

Requirements

• Java 21 runtime
• Paper 1.21.11 for backend servers
• Velocity for multi-backend network installs
• LuckPerms is optional for rank/group metadata and permission assignment
• PlaceholderAPI is optional for dynamic placeholders in server-controlled templates
• Discord bot token and required gateway intents are optional for the Discord bridge
• Telegram bot token is optional for the Telegram Bot API long-polling bridge

Artifacts And Identity

CoreChatX currently ships as two separate runtime jars. Install each jar only on the platform it was built for.

• Paper jar: corechatx-paper-<version>.jar
• Velocity jar: corechatx-velocity-<version>.jar
• Internal shared module: corechatx-common-<version>.jar, not a runtime jar to install
• Paper plugin name: CoreChatX
• Velocity plugin id: corechatx
• Main Paper command: /corechatx
• Main command alias: /ccx
• Settings command alias: /ccxsettings
• Permission namespace: corechatx.*
• Default plugin messaging channel: corechatx:main

Do not mix old jars, old plugin ids, old permission namespaces, or old network channels with CoreChatX. For a clean setup, let the plugin generate fresh defaults and manually reapply only the settings you still want.

Standalone Paper

Use this for one Paper server without cross-backend CoreChatX routing.

1. Stop the Paper server.
2. Install corechatx-paper-<version>.jar on that Paper server.
3. Start the server once so CoreChatX can generate plugins/CoreChatX/.
4. Keep deployment mode as STANDALONE.
5. Keep deployment.network-features-allowed false.
6. Configure formats, channels, messages, moderation, ChatItems, keywords, bubbles, and optional bridges on that backend.

deployment:
  mode: "STANDALONE"
  server-id: "paper-1"
  network-channel: "corechatx:main"
  bridges-allowed: true
  network-features-allowed: false

In standalone mode, no Velocity module is required. NETWORK channels behave as normal local backend chat, cross-server PM routing is inactive, and network player directory features are inactive.

Velocity Network

Use this for Paper backends connected through Velocity.

1. Stop the proxy and participating backends.
2. Install corechatx-paper-<version>.jar on every Paper backend that should use CoreChatX.
3. Install corechatx-velocity-<version>.jar on the Velocity proxy.
4. On each backend, set deployment.mode to PROXY.
5. Give every backend a unique deployment.server-id, such as alpha, beta, survival-1, or hub.
6. Use the exact same lowercase deployment.network-channel on every backend.
7. Use the exact same network-channel in plugins/corechatx/velocity-config.properties.
8. Set deployment.network-features-allowed true on every backend that should participate in cross-server features.
9. Restart the affected Paper backends and Velocity after changing identity or network channel values.

deployment:
  mode: "PROXY"
  server-id: "survival-1"
  network-channel: "corechatx:main"
  bridges-allowed: true
  network-features-allowed: true

# plugins/corechatx/velocity-config.properties
network-channel=corechatx:main
player-directory.chat-completions=true
player-directory.tab-entries=true

Network behavior enabled by this setup includes network channels, cross-server PM routing, synced communication settings, active channel state, ping toggles, PM toggle, social spy, mention notifications, locale, staff-chat state, ignore lists, global player name completions, TAB entries where available, rich Adventure component transport, ChatItem preview refs, mentions, and custom ping metadata across backends.

Bridge Installs

• Keep deployment.bridges-allowed true.
• Enable only the bridge services you actually use.
• Enable outbound export only on CoreChatX channels that should leave Minecraft.
• Configure inbound routes so external messages land in intentional CoreChatX channels.
• In proxy mode, run inbound bridge listeners only on backend instances that should locally display inbound messages.
• For Discord inbound, configure a valid bot token, inbound route, and required intents including Message Content where needed.
• For Telegram, use a bot token for Bot API long polling. Telegram does not use MTProto, Telegram4J, webhook mode, or an embedded HTTP server.

PlaceholderAPI-Heavy Installs

• Install PlaceholderAPI on every backend that must render placeholders.
• Install the expansions required by your formats.
• Keep raw player messages separate from admin templates.
• Remember that mention token placeholders use the mentioned player as context.
• Test offline-player placeholder behavior before relying on it for cross-backend hover text.

ChatItems On A Network

• Keep ChatItems enabled only on channels where previews are wanted.
• Prefer the bundled on-demand snapshot flow over embedding huge item data into every network chat packet.
• Accept that expired or rejected snapshots fail closed with the normal expired-preview feedback.
• Tune byte limits only after checking the size of custom item metadata.

Reload vs Restart

Safe with /corechatx reload

• messages, chat formats, pings, filters, ChatItems, keywords, chat bubbles, channels, privacy, moderation, storage, Discord, Telegram, and locale files
• non-identity runtime toggles such as debug, hooks, logging, bridge gates, join/quit, first-join, and reload summary behavior

Requires full restart

• deployment.mode
• deployment.server-id
• deployment.network-channel
• switching a backend between standalone and proxy deployment
• changing Velocity velocity-config.properties
• changing Velocity network-channel, which also requires affected Paper backends to use the same new channel

File Layout

Paper folder

plugins/CoreChatX/

Paper files created from bundled defaults

config.yml
messages.yml
chat.yml
pings.yml
filter.yml
chatitems.yml
keywords.yml
chatbubbles.yml
playerdata.yml
state.yml
channels.yml
privacy.yml
moderation.yml
storage.yml
discord.yml
telegram.yml
locales/en_us.yml

Additional Paper runtime files created on demand

channeldata.yml
ignoredata.yml
mutedata.yml

Velocity folder and file

plugins/corechatx/
velocity-config.properties

Regenerating A Clean Config Set

Stop the server before deleting generated admin config files. CoreChatX recreates bundled defaults on next boot. Be careful with runtime data files such as playerdata.yml, channeldata.yml, ignoredata.yml, and mutedata.yml; those are live player/plugin state.

Before major changes, back up the whole CoreChatX folder. Keep private bridge tokens out of public backups and logs.

Production Validation Checklist

• Boot every Paper backend and confirm the CORECHATX startup banner.
• Boot Velocity and confirm the proxy-side startup banner when using proxy mode.
• Run a normal public chat message.
• Run a channel switch and verify send/receive permissions.
• Test /msg and /reply.
• Test mentions, custom pings, and notification toggles.
• Test one PlaceholderAPI value in a server-controlled template.
• Test one keyword hover/click action.
• Test one ChatItem preview locally.
• In proxy mode, test one network channel message from each backend.
• In proxy mode, test one cross-backend PM.
• In proxy mode, test one cross-backend ChatItem preview click.
• Test Discord outbound and inbound if enabled.
• Test Telegram outbound, inbound, and topic routing if enabled.
• Test mute, mutechat, clear chat, social spy, ignore, and PM toggle behavior.
• Run /corechatx reload after a harmless wording change and confirm it applies.