Complete FAQ

FAQ

All current questions and answers for setup, platforms, formatting, channels, bridges, storage, and common problems.

CoreChatX FAQ

This FAQ answers the questions a server owner is most likely to ask before or during setup. For exact config keys and defaults, use Configuration Reference. For a shorter feature overview, use Product Overview.

General

What is CoreChatX?

CoreChatX is a communication suite for Minecraft servers. It combines public chat, private messages, channels, mentions, pings, chat item previews, chat bubbles, moderation tools, player settings, locales, Discord, Telegram, and Velocity network support into one system.

What is the current plugin identity?

Current public identity:

  • Paper plugin name: CoreChatX
  • Velocity plugin id: corechatx
  • Paper jar: corechatx-paper-<version>.jar
  • Velocity jar: corechatx-velocity-<version>.jar
  • main command: /corechatx
  • main command alias: /ccx
  • permission namespace: corechatx.*
  • default network channel: corechatx:main

Was this project previously named differently?

The current project name is CoreChatX. Current docs, jars, package names, permissions, commands, plugin ids, and default network channels use CoreChatX/corechatx naming.

For old installs, treat differently named folders and configs as previous install data. For a clean CoreChatX setup, let the plugin generate fresh defaults and manually reapply only the settings you still want.

Is CoreChatX only a chat formatting plugin?

No. Formatting is only one part of it. CoreChatX is designed to replace the usual stack of separate chat, PM, mention, channel, bridge, bubble, and item-preview plugins with one consistent communication layer.

Which platforms does it support?

The current project targets:

  • Paper 1.21.11 for backend servers
  • Velocity for proxy/network support

It ships separate Paper and Velocity jars. Install each jar only on the platform it was built for.

The corechatx-common jar is an internal shared build module. Do not install it directly on Paper or Velocity.

Do I need Velocity?

No. CoreChatX works on a standalone Paper server. Velocity is needed only if you want cross-backend network features such as network channels, cross-server private messages, synced communication settings, global completions, and remote ChatItem preview retrieval.

Do I install the plugin on every server?

For standalone Paper, install only the Paper jar on that server.

For a Velocity network:

  • install the Paper jar on every Paper backend that should use CoreChatX
  • install the Velocity jar on the Velocity proxy

Do not install the Paper jar on Velocity. Do not install the Velocity jar on Paper.

Setup

What is the difference between STANDALONE and PROXY?

STANDALONE is for one Paper server. Network transport is inactive, and NETWORK channels behave like local chat.

PROXY is for Paper backends connected through Velocity. It enables the backend to participate in cross-server CoreChatX features when network-features-allowed is also true.

What must match on every network backend?

Every participating backend chooses one CoreChatX group with deployment.network-channel. Velocity must list that channel in velocity-config.properties.

For a single shared network, use one value everywhere, such as corechatx:main. For isolated groups, set Velocity to a comma-separated list, such as corechatx:survival,corechatx:minigames, and give each Paper backend the matching single channel.

Every backend must also have a unique deployment.server-id. Duplicated server ids make routing ambiguous and should be fixed before testing with players.

Why do some config changes require restart?

Identity and transport settings are initialized at boot. Changing them with reload would leave parts of the runtime using old values.

Restart after changing:

  • deployment.mode
  • deployment.server-id
  • deployment.network-channel
  • Velocity network-channel list

Most wording, formatting, feature toggles, channel rules, filters, pings, keywords, bubbles, and bridge templates can be changed with /corechatx reload.

Can I delete configs to reset them?

Yes, for generated admin config files. Stop the server, delete the config file you want to reset, then start again. CoreChatX recreates the bundled default.

Be careful with runtime data files such as playerdata.yml, channeldata.yml, ignoredata.yml, and mutedata.yml. Those are live player/plugin state, not simple defaults.

What happens if my config is missing a new key?

Since CoreChatX 2026.1.3, missing bundled default keys are added back to existing Paper config files and the default locale file when they load. Existing values are not overwritten, invalid YAML is not rewritten, and runtime data files are not treated as normal admin config.

Velocity velocity-config.properties also appends missing bundled properties instead of rewriting the whole file.

What does bridges-allowed do?

It is the global master gate for Discord and Telegram runtime. When false, bridge outbound and inbound services do not run even if the individual bridge config says enabled.

What does network-features-allowed do?

It is the backend-side gate for proxy/network behavior. In PROXY mode, setting it to false keeps the backend bootable but disables cross-server CoreChatX features.

Formatting And Placeholders

Does CoreChatX use Kyori Adventure?

Yes. CoreChatX is built around Kyori Adventure components for modern chat rendering.

Does CoreChatX support MiniMessage?

Yes. Server-controlled templates can use MiniMessage for colors, gradients, hover text, click actions, suggested commands, copied text, and rich component formatting.

Does CoreChatX support PlaceholderAPI?

Yes, where PlaceholderAPI is installed, enabled, and the string is a supported server-controlled template. This allows formats, hovers, keywords, and other configured text to react to ranks, stats, economy, worlds, progression, and installed expansions.

Can PlaceholderAPI return legacy color codes?

Yes. Since CoreChatX 2026.1.1, legacy ampersand codes, section-sign codes, and legacy hex colors returned by PlaceholderAPI or nickname plugins are converted before MiniMessage rendering. This covers EssentialsX-style hex nicknames that previously could break public chat formats.

Do player-written messages parse PlaceholderAPI?

No. Raw player chat bodies do not pass through PlaceholderAPI. That prevents players from typing arbitrary %placeholder% tokens and forcing the server to resolve them.

Which player is used for mention placeholder context?

Mention token rendering uses the mentioned player as PlaceholderAPI context. This is important for hover text and dynamic mention formatting.

For cross-backend mentions, CoreChatX uses the mentioned player's OfflinePlayer context where possible. That allows many offline-capable PlaceholderAPI expansions to resolve useful data even when the player is online on another backend.

Why does a placeholder render in one format but not another?

Common causes:

  • PlaceholderAPI is not installed on that backend
  • hooks.placeholderapi is false
  • the required expansion is missing
  • the placeholder does not support OfflinePlayer
  • the string is raw player input instead of a trusted server template

Channels, PMs, Mentions, And Settings

What can channels control?

Channels can control send permissions, receive permissions, message format, scope, source-specific mention support, ChatItem support, chat bubble support, and bridge export eligibility.

Can only some channels go to Discord or Telegram?

Yes. Use channel routing and export-to-bridges so only intentional channels are exported. This avoids bridges acting like separate chat systems with their own rules.

Can bridge formats be different per channel?

Yes. Since CoreChatX 2026.1.4, channels.yml can override Discord and Telegram inbound and outbound bridge formats per channel. Blank per-channel formats fall back to the matching global bridge format.

Can mentions be controlled by message source?

Yes. Since CoreChatX 2026.1.5, each channel uses allow-mentions.from-minecraft, allow-mentions.from-discord, and allow-mentions.from-telegram. Network chat from other Minecraft servers is treated as Minecraft-originated.

Do private messages work cross-server?

In a correctly configured Velocity network, cross-server PM routing can use the proxy route inside the sender's CoreChatX proxy group. In standalone mode, PMs are local to the backend.

PM lookup is intentionally group-local. A target connected to another Velocity network-channel group behaves like player-not-found.

Do mentions work cross-server?

CoreChatX can preserve mention metadata across network chat, and the proxy-side player directory helps find players on other backends. Suggestions can include both real Minecraft names and custom nicknames inside the same proxy group. The final behavior still depends on channel settings, player notification settings, ignore/privacy settings, and permissions.

Can players disable parts of the chat experience?

Yes. Player settings include communication preferences such as PM toggle, mention notifications, ping behavior, locale, and chat bubble visibility. In proxy mode, these settings can follow backend switches.

Does CoreChatX have nicknames?

Yes. /nick sets a persistent CoreChatX display name. It can sync through same-group proxy state sync and appears in chat, PMs, spy output, broadcasts, join/quit, first-join, ChatItem titles, and network chat formatting.

It does not change the real Minecraft username or UUID identity used for routing and privacy. {player_name} always means the real Minecraft username, while {player_nickname} means the custom nickname when set, with the configured nickname prefix included.

Nicknames support legacy & colors, legacy hex such as &#ff0000, and safe MiniMessage color, format, hex, and gradient tags. Unsupported MiniMessage tags are stripped. Admins can grant narrow child permissions for named colors, formats, hex, and gradients, and can set nicknames.change-only-colors: true if players should only recolor/restyle their exact username.

/realname <nickname> resolves a custom nickname back to the real Minecraft username. CoreChatX also rejects custom plain nicknames that duplicate another custom nickname or another player's real username.

ChatItems And Chat Bubbles

What are ChatItems?

ChatItems let players type configured tokens such as [item], [armor], [hotbar], [inventory], or [enderchest] and expose interactive previews in chat.

When Discord image rendering is enabled, Minecraft-to-Discord messages can also attach rendered PNG previews. Multi-item previews can include Discord dropdown menus, and selecting one item sends an ephemeral single-item tooltip panel to that Discord user.

Do ChatItems work across servers?

Yes, in network mode they use lightweight references in the rendered chat message and retrieve the needed snapshot on demand through Velocity. Discord image packets and item preview requests are routed through the same CoreChatX group. This avoids stuffing large item or inventory payloads into every network chat packet.

Do ChatItems render on Discord?

Yes, when chatitems.yml -> discord-images.enabled is true and the message is exported to Discord. CoreChatX can render inventory-like snapshots, single-item tooltip panels, potion data, lore, enchantments, attributes, armor trims, durability and selected hotbar slot state. Vanilla assets can be downloaded automatically, and resource-pack paths can be configured in discord-images.assets.resource-packs.

Are huge custom inventories guaranteed to work cross-server?

They are protected by size and safety limits. The goal is to support real usage without letting oversized metadata destabilize proxy messaging. If a snapshot is too large, expired, rejected, or unavailable, the click fails closed with the configured expired-preview feedback.

What is max-snapshots-per-message?

It is a defensive protocol bound for how many unique network snapshot bundle references one chat message may carry. Normal parsing usually produces one shared bundle for the message, even if several ChatItem tokens appear.

Why can old ChatItem previews expire?

Snapshots are temporary. They exist so players can click a recent chat preview, not so the server stores every old item preview forever. Expiry limits memory usage and avoids stale data.

Do chat bubbles appear across the whole network?

No. In proxy mode, bubbles stay local to the backend where the sender is physically playing. An overhead bubble is a local visual effect, not something that can sensibly float above a player on another server.

Discord And Telegram

Does CoreChatX support Discord?

Yes. It supports outbound Minecraft-to-Discord messages and inbound Discord-to-Minecraft relay when configured.

Discord inbound uses the Discord Gateway through JDA. It does not use REST polling for inbound chat.

What does Discord inbound need?

At minimum:

  • a valid bot token
  • inbound enabled in Paper discord.yml for STANDALONE, or Velocity velocity-discord.yml for PROXY
  • a route to an existing CoreChatX channel
  • the required Discord intents, including Message Content where message content is needed

In proxy mode, run the bridge/linking Discord bot on Velocity. Paper backends may run separate console-only bots through discord.console.*, but those backend bots do not handle bridge routes, account linking or role gates.

Can Discord inbound messages be formatted?

Yes. Discord-to-Minecraft messages are controlled by discord.inbound.format. It can use {source}, {source_type}, {channel_id}, {channel_prefix}, {sender_name}, {player_name}, {player_nickname}, {discord_name}, {discord_id}, {rank_prefix}, {role_color}, and {plain_text} or {message}.

There is no forced hardcoded [Discord] prefix; include the source text only where you want it in the format.

Yes. Enable top-level account-linking.enabled, then use account-linking.require-linked globally or override it per Discord route and per CoreChatX channel. Unlinked Discord messages can be blocked, deleted when the bot has Manage Messages, and answered with a DM.

Linked Discord inbound uses Minecraft identity for player-facing placeholders such as {sender_name}, {player_name}, {player_nickname}, and {rank_prefix}. {discord_name} and {discord_id} remain available when you still want to expose Discord identity.

Yes. When top-level account-linking.require-linked-to-play is true, CoreChatX generates or reuses a temporary link code and denies the unlinked player with the Discord /link code:<code> instruction. In PROXY, Velocity owns that decision and can check the linked Discord role before the player reaches the backend when backend group pins are configured.

Can Minecraft-to-Discord output use PlaceholderAPI?

Yes. CoreChatX processes PlaceholderAPI placeholders and {rank_prefix} in discord.format, so trusted outbound templates can include server-side rank, world, economy, or other expansion data. In PROXY, Velocity-side PlaceholderAPI resolving needs optional PAPIProxyBridge when the placeholder is resolved from Velocity-owned formats such as player-list rows, channel descriptions, join/quit messages, or fallback Discord formats.

Can Discord roles appear in Minecraft chat?

For normal unlinked Discord-to-Minecraft messages, Discord role data can be used in the inbound bridge format. When a Discord user is linked, Minecraft identity placeholders use the linked Minecraft account instead, so the visible sender can follow the player's real name, CoreChatX nickname, and Minecraft rank.

Can Discord users trigger custom pings like @staff?

Only when the matching custom ping in pings.yml has at least one matching Discord role id in discord-roles. Empty or missing discord-roles keeps the token as plain text and does not notify Minecraft players.

Minecraft-origin custom pings still use use-permission, and recipient checks still use receive-permission.

How does Discord playerlist work?

In STANDALONE, Paper discord.yml -> discord.player-list.* controls the text command, optional slash command, visibility and embed format, and the list contains players online on that Paper server.

In PROXY, Velocity velocity-discord.yml -> discord.player-list.* controls the command. The Discord channel must resolve to a CoreChatX route or channel override so Velocity knows which network-channel group to list.

Can Discord text channel descriptions update automatically?

Yes. Enable discord.channel-description. Paper standalone updates configured Discord text channel topics from the standalone server. Velocity proxy mode updates text channel topics per configured network-channel, with internal placeholders such as {online} and {online_in_group} plus optional PlaceholderAPI values through PAPIProxyBridge.

What if a bridge format is invalid?

Bridge formats are validated on config load. Unknown placeholders and invalid inbound MiniMessage syntax produce warnings instead of failing startup.

For Minecraft-to-Discord and Minecraft-to-Telegram output, CoreChatX strips Minecraft formatting codes from templates and rank prefixes while preserving literal ampersands in the actual chat message.

Does CoreChatX support Telegram?

Yes. It supports outbound Minecraft-to-Telegram messages, inbound Telegram-to-Minecraft relay, and Telegram forum topic routing.

Does Telegram use MTProto or Telegram4J?

No. Telegram uses the Telegram Bot API with long polling through getUpdates. There is no MTProto bridge, no Telegram4J runtime, no webhook mode, and no embedded HTTP server.

Can Telegram messages route by forum topic?

Yes. Outbound targets can include message-thread-id, and inbound routing can map chat ids and topic thread ids to CoreChatX channels.

Permissions And Commands

Are all permissions fixed in plugin.yml?

No. Some permissions are intentionally configurable in YAML files. Examples include channel send/receive permissions, ping permissions, keyword permissions, privacy bypass permissions, and ChatItem token permissions.

What happens if a configured permission is malformed?

Where validation exists, CoreChatX warns and disables only the affected binding or keyword. The whole plugin should not be treated as broken because one dynamic permission node is invalid.

Are player commands available by default?

Player-facing commands such as /corechatx, /corechatx settings, /corechatx locale, private messages, replies, nicknames, pings, channel access, ignore, PM toggle, and chat settings default to normal player access where appropriate. Administrative, staff-targeted nickname editing, and moderation commands remain operator-only by default.

How does /broadcast work in proxy mode?

Paper /broadcast remains local in STANDALONE. In PROXY, it routes through Velocity and is delivered to the sender's CoreChatX group.

Velocity also registers /broadcast. If only one CoreChatX group exists, use /broadcast <message>. If multiple groups exist, use /broadcast <group|all> <message>. The command uses corechatx.command.broadcast.

Storage And Data

Is SQL the active storage backend?

No. SQL settings currently exist as groundwork for future storage work. The active public runtime behavior uses the current generated data files documented in the configuration instructions.

Which files should I back up?

Back up the whole CoreChatX folder before major changes. At minimum, preserve:

  • config files you customized
  • playerdata.yml
  • channeldata.yml
  • ignoredata.yml
  • mutedata.yml
  • bridge configs containing routing ids

Keep private tokens out of public backups and logs.

Build And Testing

What does "smoke tested" mean?

It means a small practical test was run to prove the main path starts and behaves at a basic level. It is not the same as exhaustive QA. For example, starting the server, sending one message, checking one command, or verifying one bridge path can be a smoke test.

Why do I see Maven Shade warnings while building?

Shaded dependency jars can contain overlapping metadata or service resources. Some warnings are normal, but dependency changes should still be reviewed. The important checks are that tests pass, the package builds, and the produced jars start on the intended platform.

What should I test before inviting real players?

Test:

  • startup on every backend and proxy
  • public chat
  • channels
  • private messages and replies
  • mentions and custom pings
  • PlaceholderAPI templates
  • keywords
  • ChatItems
  • chat bubbles
  • moderation commands
  • network chat if using Velocity
  • group-local cross-server PMs if using Velocity
  • Discord and Telegram paths if enabled

Do this before a public rollout, not after players find the broken route for you.

Common Problems

"My network channel does not work."

Check that the Paper backend's deployment.network-channel is listed in Velocity network-channel. For one shared group, every backend and Velocity can use the same value, for example corechatx:main. For multiple groups, Velocity lists all groups and each backend uses one matching value.

Also verify that every participating backend has deployment.mode: "PROXY" and deployment.network-features-allowed: true.

"My private message target is online but not found."

Check the CoreChatX proxy group. PM lookup is limited to the sender's group. A player on another configured Velocity channel group is intentionally hidden from that PM route.

"/nick only changes colors."

Check config.yml -> nicknames.change-only-colors. When true, the visible text after stripping color and style codes must exactly match the real Minecraft username.

"Discord or Telegram is duplicating messages."

In proxy mode, outbound export should happen from the source backend only. Check that you did not also configure another plugin or another backend path to export the same channel independently.

"Discord users are blocked from writing into Minecraft."

Check top-level account-linking.enabled, account-linking.require-linked, route overrides, and channel overrides. For linked users, also check Minecraft mute state and channel send permissions if those enforcement options are enabled.

account-linking.require-linked-to-play is enabled. The player must complete the Discord slash command shown in the kick reason before joining normally. In STANDALONE, verify Paper discord.yml, the bot token, and that the bot can register slash commands. In PROXY, verify Velocity velocity-discord.yml, matching network-channel values, and backend group pins when the check must happen before Paper receives the player.

"A PlaceholderAPI hover shows the wrong player."

For mentions, CoreChatX uses the mentioned player as context. If a hover still shows unexpected data, check the placeholder expansion itself and whether it supports offline player resolution.

"ChatItems say the preview expired."

The snapshot may have expired, been rejected by size limits, or failed to arrive before the network timeout. This is expected fail-closed behavior. Increase limits only after checking the size and complexity of the custom items involved.

"Can I use CoreChatX together with another chat plugin?"

Technically, maybe. Operationally, be careful. Two chat plugins trying to format, cancel, bridge, moderate, or route the same message will eventually disagree. CoreChatX is designed to own the communication flow so the result feels like one system.