Install CoreChatX cleanly on Paper or Velocity.

Requirements

Start here before editing any files. CoreChatX has two install shapes, but both use the same Paper config folder and the same basic dependencies.

• Java 21 runtime
• Paper 1.21.11 for backend servers
• Velocity only when you want one CoreChatX network across multiple Paper backends
• LuckPerms is optional for rank prefixes and permission assignment
• PlaceholderAPI is optional for placeholders inside trusted server-controlled templates
• Discord and Telegram bot tokens are optional and needed only when those bridges are enabled

Reference:configuration overviewclean setup notes

Choose A Mode First

Standalone Paper

Use STANDALONE when CoreChatX runs on one Paper server. Runtime player data, nicknames, settings, mutes, ignores and Discord links are stored by that Paper backend.

Choose this mode when you do not need cross-backend chat, cross-server PMs, proxy join/leave handling or Velocity-owned data.

Velocity Network

Use PROXY when multiple Paper backends should share CoreChatX behavior through Velocity. In this mode, Velocity owns runtime data per network-channel group and Paper backends act as runtime clients.

Choose this mode for group-local network chat, cross-server PMs, synced settings, proxy join/leave, network player directory, cross-backend ChatItem previews, Discord ChatItem image transfer, and proxy-side Discord account linking.

Reference:standalone vs proxyruntime data ownership

Artifacts And Folders

CoreChatX ships two runtime jars. Install each jar only on the platform it was built for, and keep Paper and Velocity jars on the same CoreChatX version.

Current release: 2026.2.4. For this release, the installable jars are corechatx-paper-2026.2.4.jar and corechatx-velocity-2026.2.4.jar.

• 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 config folder: plugins/CoreChatX/
• Velocity config folder: plugins/corechatx/

Do not mix old jars, old plugin ids, old permission namespaces, or old network channels. For the 2026.2.x line, a clean setup is recommended: regenerate defaults and manually reapply only the settings you still need.

Standalone Paper

This is the clean path for one Paper server.

1. Stop the Paper server.
2. Place corechatx-paper-<version>.jar in the server's plugins/ folder.
3. Start the server once so CoreChatX can generate plugins/CoreChatX/.
4. Stop the server again before doing the first real configuration pass.
5. Keep config.yml -> deployment.mode as STANDALONE.
6. Keep deployment.network-features-allowed false because there is no proxy runtime.
7. Configure channels, formats, messages and optional features in the Paper files.
8. If you use Discord, configure Paper discord.yml. If you use Telegram, configure Paper telegram.yml.
9. Start the server and validate chat, commands and optional bridges.

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

In standalone mode, NETWORK channel scope behaves like normal local backend chat. Cross-server PM routing, proxy player directory and proxy runtime storage are not active.

Configure next:config.ymlchannels.ymldiscord.ymltelegram.yml

Velocity Network

This is the clean path for a Velocity proxy with one or more Paper backend groups.

1. Stop the proxy and participating backends.
2. Install corechatx-paper-<version>.jar on every participating Paper backend.
3. Install corechatx-velocity-<version>.jar on the Velocity proxy.
4. Start everything once to generate defaults, then stop everything again.
5. On each backend, set config.yml -> deployment.mode to PROXY.
6. Give every backend a unique deployment.server-id, such as alpha, beta, survival-1, or hub.
7. Choose the backend's group with deployment.network-channel.
8. Set deployment.network-features-allowed true on each participating backend.
9. In Velocity velocity-config.properties, list every allowed network-channel group.
10. If Velocity must know a backend's group before the player reaches Paper, add backend-groups.<velocity-backend-name> pins.
11. Keep channel ids and important Paper formats consistent across backends that are in the same group.
12. Configure Discord bridge, account linking and role gates in Velocity velocity-discord.yml, not in Paper discord.yml.
13. Restart Velocity and the affected Paper backends after deployment identity or group changes.

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

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

Each Velocity network-channel value is an isolated CoreChatX group. Network chat, PM lookup, player directory data, TAB/completions, state sync, ChatItem snapshot routing, Discord image transfer, Discord links, pending link codes, broadcasts and join/leave routing stay inside the source group.

Velocity owns shared runtime data in proxy mode, but it does not replace every backend's Paper config. Each backend still reads its own local channels.yml, chat.yml, messages.yml and feature files.

join-quit:
  mode: "NETWORK"
  join-enabled: true
  quit-enabled: true

Use join-quit.mode: "NETWORK" only on proxy-connected backends where join/quit should be announced once at the CoreChatX group level. In this mode, Velocity renders the message from velocity-messages.yml; Paper messages.yml remains for standalone and local-only announcements.

Configure next:velocity-config.propertiesvelocity-messages.ymlvelocity-discord.ymlchannels.yml

Config Walkthrough

Use this pass after the first boot. The goal here is to decide what each file is responsible for; the complete defaults and every key live in the configuration reference.

1. Core identity and global switches

Edit config.yml first. Decide the deployment mode, backend id, network channel, bridge master switch, network feature switch, PlaceholderAPI/LuckPerms hooks, nickname behavior, first-join behavior, and join/quit mode.

Reference:config.yml

2. Chat channels and visible formats

Edit channels.yml to choose channel ids, default channel, channel scope, send/receive permissions, mention permissions, ChatItem allowance, bubble allowance and bridge export. Edit chat.yml for default chat formats, group formats, mentions, broadcasts, spy and private message formats. Edit messages.yml for command feedback and player-facing text.

On a network, keep the same important channel ids across backends in the same group. Velocity routes by group, but Paper still owns local channel definitions and rendering.

Reference:channels.ymlchat.ymlmessages.yml

3. Mentions, privacy and moderation

Edit pings.yml for mention sounds, action bars and custom ping targets. Edit privacy.yml for player toggles such as PM and ping behavior. Edit moderation.yml and filter.yml for mute/chat control and word replacement rules.

Reference:pings.ymlprivacy.ymlmoderation.ymlfilter.yml

4. Optional chat interaction features

Edit chatitems.yml for item, inventory, armor, hotbar and ender chest preview tokens, in-game preview lifetime, Discord image rendering, single-item tooltip panels, dropdown item inspection menus and optional resource-pack asset paths. Edit keywords.yml for clickable or hoverable keyword shortcuts. Edit chatbubbles.yml if you want overhead chat bubbles.

On a network, ChatItem previews and Discord ChatItem image packets are routed inside the same CoreChatX group. Keep token expectations and resource-pack paths consistent across participating backends.

Reference:chatitems.ymlkeywords.ymlchatbubbles.yml

5. Storage and language files

Edit storage.yml only if you need to change the standalone storage backend. In PROXY, runtime state is owned by Velocity, so this file remains local backend configuration. Edit locales/en_us.yml for localized command text.

Reference:storage.ymllocales/en_us.yml

6. PlaceholderAPI and LuckPerms

Install PlaceholderAPI on every backend that must render PlaceholderAPI placeholders in CoreChatX templates. Install the required expansions separately. Install LuckPerms where rank prefixes and permission metadata should be resolved. On Velocity, install optional PAPIProxyBridge if Velocity-side formats such as player-list rows, channel descriptions, join/quit messages or fallback Discord formats must resolve PlaceholderAPI values from backend players.

CoreChatX also registers PlaceholderAPI values for other plugins: %corechatx_player_nickname%, %corechatx_first_join_date% and %corechatx_messages_count%.

Reference:PlaceholderAPI valuesplugin.yml

Discord And Telegram

Bridge setup depends on the deployment mode.

Standalone bridge ownership

In STANDALONE, Paper discord.yml owns the Discord bot, Discord inbound/outbound routes, account linking, link-to-play and optional Discord role checks. Paper telegram.yml owns Telegram Bot API long polling and outbound messages.

Proxy bridge ownership

In PROXY, Velocity velocity-discord.yml owns the Discord bridge, account linking, link-to-play, required role checks, Discord console command channel and Discord inbound route-to-group mapping.

Paper discord.yml can still start an optional console-only bot per backend through discord.enabled and discord.console.*. Use a separate Discord bot token per backend console bot to avoid duplicate gateway sessions.

What to decide

• Which CoreChatX channels may export messages to Discord or Telegram.
• Which Discord or Telegram channels route inbound messages back into Minecraft.
• Whether Discord users must link to Minecraft accounts before writing into bridged channels.
• Whether Minecraft players must be linked, or linked plus role-verified, before playing.
• Whether bridge output should prevent Discord mentions from Minecraft text.
• Whether join/quit/first-join messages should be mirrored to Discord as plain text or embeds.
• Whether Discord should expose !playerlist or /playerlist in bridge channels.
• Whether Discord text channel descriptions should be updated from placeholders such as {online}, {online_in_group}, or PlaceholderAPI values.
• Whether Minecraft ChatItem tokens should send rendered Discord images and item inspection menus.

Reference:Paper discord.ymltelegram.ymlVelocity discord

Runtime Data

Runtime data is player/plugin state, not normal admin configuration.

• In STANDALONE, Paper stores runtime data in local YAML files under plugins/CoreChatX/.
• In PROXY, Velocity stores shared runtime data under group-specific data files. Paper keeps local config and runtime caches, but Velocity is the authority.
• Runtime data includes player settings, nicknames, ignore lists, active channels, mutes, global state, first-join state, Discord links and pending link codes.
• Files such as playerdata.yml, state.yml, channeldata.yml, ignoredata.yml, mutedata.yml and discordlinks.yml are runtime data files, not normal setup files.
• Back up runtime files before deleting or manually editing them.

Reference:runtime ownershipplayerdata.ymlstate.ymlVelocity storage notes

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 the Velocity network-channel list, which also requires affected Paper backends to use one of the configured channels

Use reload for normal wording and format edits. Use full restarts for identity, routing and proxy group changes because those values are initialized at startup.

Regenerating A Clean Config Set

For the 2026.2.x line, clean config regeneration is recommended when upgrading from older installs.

1. Stop Paper backends and Velocity.
2. Back up plugins/CoreChatX/ and plugins/corechatx/.
3. Delete or move old admin config files you want regenerated.
4. Keep runtime data only if you intentionally want to preserve standalone state.
5. Start once to regenerate defaults.
6. Stop again and reapply only current deployment identity, channel formats, bridge tokens, Discord routes and role ids.

CoreChatX can add missing bundled keys to existing config files without overwriting current values, but a clean setup is easier to reason about after the proxy runtime ownership changes.

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 group-local cross-backend PM.
• In proxy mode, test one cross-backend ChatItem preview click.
• Test Discord outbound and inbound if enabled.
• Test Discord account linking, unlinking, blocked unlinked messages, slash command registration, and link-to-play kicks 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.

For exact defaults, every bundled Paper file, every Velocity file and troubleshooting notes, use the Configuration Reference.