Messages Configuration (messages.conf)

Relevant source files

The following files were used as context for generating this wiki page:

• Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/HoconMessages.java
• Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/MessageKeys.java
• API/src/main/java/xyz/xreatlabs/nexauth/api/configuration/Messages.java
• Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/ConfigurateConfiguration.java
• Plugin/src/main/java/xyz/xreatlabs/nexauth/common/command/CommandProvider.java
• Plugin/src/main/java/xyz/xreatlabs/nexauth/common/util/GeneralUtil.java
• Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/migrate/messages/FirstMessagesMigrator.java
• Plugin/src/main/java/xyz/xreatlabs/nexauth/common/mail/AuthenticEMailHandler.java

The messages configuration system in NexAuth is responsible for managing all user-facing text displayed by the plugin. It is designed to be highly customizable, allowing server administrators to translate or modify any message. The system is centered around the messages.conf file, which uses the HOCON (Human-Optimized Config Object Notation) format. This format supports both legacy Minecraft color codes (e.g., &a) and the modern MiniMessage format for advanced text styling.

The core of this system is the HoconMessages class, which loads, parses, and provides access to all messages. It uses a comprehensive set of predefined keys from the MessageKeys class to generate a default configuration file with comments, ensuring that administrators have a clear understanding of each message's purpose. The system also includes a migration mechanism to automatically update the messages.conf file when changes are made between plugin versions.

Core Components

The message system is built upon several key classes that work together to load, manage, and serve messages throughout the plugin.

Class/Interface	File Path	Description
Messages (Interface)	API/src/main/java/xyz/xreatlabs/nexauth/api/configuration/Messages.java	Defines the public API for the message system, including methods for retrieving and reloading messages.
HoconMessages	Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/HoconMessages.java	The primary implementation of the Messages interface. It handles loading messages.conf, parsing HOCON, processing text formats, and caching messages.
MessageKeys	Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/MessageKeys.java	A static container class holding ConfigurationKey objects for every message in the plugin. It provides default values and descriptive comments used to generate the initial messages.conf file.
ConfigurateConfiguration	Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/ConfigurateConfiguration.java	A wrapper around the SpongePowered Configurate library that manages the loading, saving, and migration of HOCON configuration files like messages.conf.
ConfigurationMigrator	Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/migrate/ConfigurationMigrator.java	An interface for migrating configuration files between versions. Implementations like FirstMessagesMigrator handle specific updates to messages.conf.

This diagram illustrates the relationships between the main components of the message configuration system.

Message Loading and Processing

The loading process is initiated by the HoconMessages.reload() method. This method orchestrates the reading of messages.conf, applying defaults, running migrations, and parsing the messages into memory.

This flowchart shows the sequence of operations during the message loading process.

Key Steps

1. Initialization: HoconMessages.reload() creates a ConfigurateConfiguration instance for messages.conf. It passes the MessageKeys class to define all default values and comments.
   Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/HoconMessages.java:74-96
2. Migration: The ConfigurateConfiguration constructor checks the revision number in the file. If the stored revision is lower than the current version, it sequentially executes migrators (e.g., FirstMessagesMigrator, SecondMessagesMigrator) to update the configuration structure.
   Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/ConfigurateConfiguration.java:62-66
3. Parsing: After loading, HoconMessages.extractKeys() is called. This method recursively walks through the HOCON nodes. For each terminal node (a key with a string value), it constructs a TextComponent.
   Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/HoconMessages.java:100-112
4. Format Handling: To support both legacy and modern formats, the string value is first processed by LegacyMessage.fromLegacy(string, "&") to convert & codes to MiniMessage tags, and then deserialized by a MiniMessage instance. The resulting TextComponent is stored in an in-memory map.
   Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/HoconMessages.java:107

Message Retrieval and Formatting

Messages are retrieved using HoconMessages.getMessage(String key, String... replacements). This method fetches the pre-parsed TextComponent from the cache and applies any dynamic placeholders.

This sequence diagram shows how a command handler retrieves and formats a message.

The placeholder replacement logic in getMessage converts the String... replacements varargs into a Map<String, String>. This map is then passed to GeneralUtil.formatComponent, which uses the Adventure API's replaceText method to substitute placeholders in the TextComponent.
Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/HoconMessages.java:52-66

The getRawMessage(String key) method is also available for cases where the raw, unparsed string is needed, such as for email templates which support HTML.
Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/HoconMessages.java:114-116, Plugin/src/main/java/xyz/xreatlabs/nexauth/common/mail/AuthenticEMailHandler.java:67-74

Configuration Structure and Keys

All available message keys are defined as static ConfigurationKey constants in the MessageKeys class. This provides a single source of truth for default messages and their documentation. The keys are organized into logical groups using HOCON's nested structure.

Example Key Definition

Here is how the key for the login prompt is defined:

// Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/MessageKeys.java:515-519
public static final ConfigurationKey<String> PROMPT_LOGIN = new ConfigurationKey<>(
    "prompt-login",
    "Please login using: &e/login &b<password> [2fa_code]",
    "This message is displayed when the player is prompted to login.",
    ConfigurateHelper::getString
);

Message Categories

The MessageKeys class defines a vast number of messages, which can be grouped into the following categories:

| Category | Description | Example Keys -
| Kicks | Messages displayed when a player is kicked from the server for various reasons. | KICK_INVALID_CASE_USERNAME, KICK_IP_LIMIT, KICK_TIME_LIMIT -
| Command Errors | Error messages for failed command executions, such as incorrect passwords, permissions, or state. | ERROR_ALREADY_REGISTERED, ERROR_PASSWORD_WRONG, TOTP_WRONG -
| Information | General feedback messages for successful operations or status updates. | INFO_LOGGED_IN, INFO_REGISTERED, INFO_RELOADED, INFO_USER -
| Prompts & Titles | Messages used in chat, titles, subtitles, and action bars to prompt the user for an action. | PROMPT_REGISTER, PROMPT_LOGIN, TITLE_REGISTER, ACTION_BAR_LOGIN -
| TOTP (2FA) | Messages related to the Two-Factor Authentication setup and confirmation process. | TOTP_SHOW_INFO, TOTP_GENERATING, TOTP_WRONG_VERSION -
| Emails | Subject lines and HTML content for emails sent for verification and password resets. | EMAIL_VERIFICATION_CONTENT, EMAIL_VERIFICATION_SUBJECT, EMAIL_PASSWORD_RESET_CONTENT -
| Command Syntax | Defines the syntax strings displayed for commands when usage is incorrect. | SYNTAX_LOGIN, SYNTAX_REGISTER, SYNTAX_USER_INFO -
| Command Autocomplete | Provides hint text for command argument autocompletion. | AUTOCOMPLETE_LOGIN, AUTOCOMPLETE_USER_INFO, AUTOCOMPLETE_USER_MIGRATE -

Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/MessageKeys.java

Configuration Migration

To ensure smooth updates, the message system includes a migrator that automatically updates the messages.conf file.

The ConfigurateConfiguration class takes an array of ConfigurationMigrator instances. It checks a revision field in the config file and applies any migrators that correspond to a newer revision number.

For example, FirstMessagesMigrator was created to consolidate a generic auto-login message into two more specific ones:

// Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/migrate/messages/FirstMessagesMigrator.java:16-24
public class FirstMessagesMigrator implements ConfigurationMigrator {
    @Override
    public void migrate(ConfigurateHelper helper, Logger logger) {
        var autoLoginText = helper.getString("info-automatically-logged-in");

        if (autoLoginText != null) {
            helper.set("info-premium-logged-in", autoLoginText);
            helper.set("info-session-logged-in", autoLoginText);
        }

        helper.set("info-automatically-logged-in", null);
    }
}

This migrator reads the old info-automatically-logged-in value, copies it to the new info-premium-logged-in and info-session-logged-in keys, and then removes the old key. This prevents administrators from losing their custom messages during an update.

Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/ConfigurateConfiguration.java:62-66, Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/migrate/messages/FirstMessagesMigrator.java, Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/migrate/messages/SecondMessagesMigrator.java