Basic configuration - Hexaoxide/Carbon GitHub Wiki

Before you can begin to effectively configure Carbon, it is necessary to understand the basis of the plugin, and a little bit about how it works. Carbon is built on channels, or, different chats which people can see and send messages in, based on a variety of different factors.

This includes permissions, especially the ability to send messages and the ability to receive messages in a particular channel, each of which is controlled by a separate permission.

Just about every single setting and format in Carbon is configurable, which allows for massive potential! Want a broadcast channel with a special format? Simply create it in the config, and only give your players permission to see the channel, not send messages. Make the channel unignorable, and bam! a broadcast channel, exactly how you wanted.

The style for message formatting is MiniMessage. The only place legacy formatting is supported in any capacity by Carbon is as the result of a PAPI placeholder. Anywhere else it works is a bug. The Kyorify PAPI expansion can be used to convert placeholders which return legacy formatting to MiniMessage.

Carbon has various global settings that can be configured as follows in the config.conf file. Note that individual channels can be configured too as seen here.

Used internally to track changes to the config. Do not edit manually.

This setting determines the default locale used for plugin messages. By default it is en_US which corresponds to the messages-en_US.properties file in the CarbonChat/locale folder. MiniMessage is used here too for formatting, see here for more info. For translations, there are various tags/placeholders used throughout the files such as <display_name> and , note that these may or may not parse if used in other translation keys! For example may not work in whisper.from translation key. Following are some tags you can use that are not used in the default translation file:

• <render_for>

<render_for> dynamically renders placeholders for a specific player, useful in places such as whisper.to format and other keys. It can be used to render placeholders with respect to the recipient for example instead of the sender's.

Basic syntax: <render_for:'<target_uuid>':'<placeholders>'>

• <target_uuid>: The literal UUID of the player. Alternatively it can be replaced with <recipient_uuid> for dynamic formatting.

• <placeholders>: Any combination of PAPI placeholders like <luckperms_prefix> etc or in-built placeholders.

whisper.to: "<gold>[<green>You</green>] -> [<render_for:\'<recipient_uuid>':\'<luckperms_prefix><recipient_display_name>'></green>] <message>"

Above example ensures the whisper message sender sees the prefix of the recipient in the formatted message.

This setting determines the channel that players will be in when they join. By default it is carbon:global, which corresponds to the global.conf file in the CarbonChat/channels folder.

If enabled, using a channel’s command while already in that channel will return the player to the default channel.

Determines how player data is stored. Options are:

• JSON - JavaScript Object Notation. Stored locally. Best for small servers.
• H2 - H2 Database. Uses an embedded SQL database stored locally. Suitable for small to medium-sized servers that need structured data storage without external servers.
• MYSQL - MySQL Database. Uses a MySQL server to store data. Recommended for large servers or networks needing fast and scalable data access. Requires a database to be configured in database-settings.
• PSQL- PostgreSQL Database. Uses a PostgreSQL server to store data. Recommended for large servers or networks needing fast and scalable data access. Requires a database to be configured in database-settings.

Configures database connection settings when using MYSQL or PSQL. This section is ignored when JSON or H2 is selected as storage-type. Options are:

• url – JDBC URL for connecting to the database. Suggested defaults for different databases are:
  • MySQL: jdbc:mysql://host:3306/DB
  • MariaDB: jdbc:mariadb://host:3306/DB
  • PostgreSQL: jdbc:postgresql://host:5432/database
• username – The database login username.
• password – The database login password.
• connection-pool – Advanced settings for database connection pooling. Do not change if you are not sure what this setting does! Options are:
  • maximum-pool-size – The maximum number of connections allowed.
  • minimum-idle – The minimum number of idle connections maintained.
  • maximum-lifetime – Maximum lifespan of a database connection before being replaced in milliseconds.
  • keepalive-time – Frequency at which idle connections are pinged to prevent disconnection in milliseconds. Set to 0 to disable.
  • connection-timeout – Maximum time the server waits for a database connection before timing out in milliseconds.

Configures cross-server messaging between multiple servers. carbon.crossserver permission should be given to allow players to recieve cross server messages.

• enabled – Toggles cross-server messaging.
• broker-type – The messaging system to use. Options are:
  • RABBITMQ - Message broker using Advanced Message Queuing Protocol (AMQP). Requires url, port, vhost, username and password to be filled in.
  • NATS - Low-latency messaging system. Requires url, port and credentials-file to be filled in.
  • REDIS - In-memory data store with pub/sub support. Requires url, port and password to be filled in.
• url – The hostname or IP address of the messaging broker.
• port – The port used for the messaging broker connection.
• vhost – The virtual host for RabbitMQ.
• credentials-file – File path for NATS authentication credentials.
• username – Username for RabbitMQ authentication.
• password – Password for RabbitMQ or Redis authentication.

Manages player nickname settings.

• use-carbon-nicknames – Determines whether Carbon should handle nickname management. Disable to let other plugins to take over management.
• update-tab-list – If enabled, updates a player’s tab list display name to match their nickname (Paper only).
• min-length – The minimum number of characters allowed in a nickname, excluding formatting.
• max-length – The maximum number of characters allowed in a nickname, excluding formatting.
• black-list – A list of disallowed nicknames.

    black-list = [
        notch,
        admin
    ]

• filter – A regex pattern that nicknames must match, unless bypassed with carbon.nickname.filter permission.

    filter="^[a-zA-Z0-9_]*$"

Example only allows alphanumeric characters and underscores.

• format – The display format for nicknames.
• skip-format-when-name-matches – If enabled, skips applying formatting when a nickname matches a player’s username except for decorations.

This section of the config sets custom placeholders that can be used in chat (formats, messages, and anything else rendered by Carbon). These formats also accept PAPI placeholders if you have PAPI installed. Make sure to close your tags so they do not bleed into other formats. Only a single pass is done so custom placeholders will not work within each other.

custom-placeholders = {
  test = "This is an example!"
  papitest = "%server_tps%!"
}

Based on the example, <test> would display as This is an example! and <papitest>, on a 20TPS server with the PAPI 'Server' expansion installed, would display as 20.0!.

Defines a list of predefined custom suggestions that appear when players press the TAB key in chat.

custom-chat-suggestions = [  
  "Need help? Type /help for commands!",
  "Join our Discord: discord.gg/example",
  "Remember to claim your land with /claim"
  ]

Defines placeholders that will be dynamically replaced in chat messages. This is compatible with chat previews. Make sure to close your tags so they do not bleed into other formats. Only a single pass is done so chat placeholders will not work within each other.

chat-placeholders = {
    server = "Carbon"
    version = "1.21"
}

Based on the example Welcome to <server>, a <version> Survival server! would be Welcome to Carbon, a 1.21 Survival server!

Basic regex-based chat filtering system. Used to automatically censor unwanted words or patterns.

chat-filter = {
    "\\b(hell)\\b" = "h***"
    "\\b(damn)\\b" = "d***"
}

Based on the example hell (but not hello due to \\b) will be replaced with h***. Similarly with damn.

Configures the behavior of player mentions in chat.

• highlight-text-color – The color used to highlight a player’s name when mentioned.
• prefix – The character used to trigger a mention.
• play-sound – If enabled, plays a sound when a player is mentioned.
• name – The name of the sound effect played on mention. Reference for names can be found here. Sound names need to be prefixed with minecraft: and should be separated with dots (.) instead of underscores (_) like in the Paper Javadocs. For example, AMBIENT_CRIMSON_FOREST_LOOP would become minecraft:ambient.crimson.forest.loop where source would be ambient.
• source – Specifies the music category and options the sound falls under. Must be one of master, music, record, weather, block, hostile, neutral, player, ambient, or voice. If omitted, master is used.
• volume – The volume of the mention sound.
• pitch – The pitch of the mention sound.

Configures the party chat system.

• enabled – Enables or disables party chat.
• expire-invites-after-seconds – Time in seconds before a party invite expires.
• play-sound – If enabled, plays a sound when receiving a party message.
• message-sound – Sound settings for party messages. Configuration is similar to the sound options in ping-settings.
  • name – The sound effect played when receiving a party message.
  • source – The sound category the sound belongs to.
  • volume – The volume of the message sound.
  • pitch – The pitch of the message sound.

Defines the sound effect for receiving direct messages. Configuration is similar to the sound options in ping-settings.

• name – The name of the sound effect.
• source – The sound category.
• volume – The volume of the sound effect.
• pitch – The pitch of the sound effect.

Defines what happens when chat is cleared by someone with permission.

• message - The 'clearing' message that will be sent to each player.
• iterations - The number of times the 'clearing' message will be sent to each player. Effectively, this is the 'depth' of the chat clear.
• broadcast - The message sent to players after chat is cleared on their screen

Settings for compatibility with other plugins and mods. Settings only apply when the relevant plugin/mod is present.

• discordsrv – Enables integration with DiscordSRV.
• essentialsx_discord – Enables integration with EssentialsX Discord.
• factionsuuid – Enables support for FactionsUUID. In case of issues with double messages set tagHandledByAnotherPlugin to true in the main config file of FUUID.
  • faction-channel – Whether to enable a dedicated faction chat channel.
  • alliance-channel – Whether to enable an alliance chat channel.
  • truce-channel – Whether to enable a truce chat channel.
  • faction-mod-channel – Whether to enable a faction moderator-only channel.
• mcmmo – Enables integration with mcMMO.
  • party-channel – Enables mcMMO’s party chat system replacing Carbon's. Make sure to disable Carbon's party-chat feature first! Some of mcMMO's party-chat commands are still accessible, which do not utilise Carbon for it's formatting so they will need to be overriden/disabled within mcMMO.
• towny – Enables integration with Towny.
  • town-channel – Whether to enable a town chat channel.
  • nation-channel – Whether to enable a nation chat channel.
  • alliance-channel – Whether to enable an alliance chat channel.

Determines whether Carbon should check for plugin updates via the GitHub API on startup.

A toggleable chat filter that players can enable or disable individually with the /filter command. Useful for mild profanity filtering.

optional-chat-filter = {
    "\\b(hell)\\b" = "h***"
    "\\b(damn)\\b" = "d***"
}