⭐ hTitles [1.21.X-26.X] ⭐ | PAPI, Vault, LuckPerms and more

hTitles
Custom prefixes and suffixes with managed access
MiniMessage • Installation balances • Confirmation • SQLite / MySQL • Flexible actions

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

OVERVIEW
hTitles lets players create and install their own custom prefixes and suffixes. The plugin validates formatting, manages available installations, requests confirmation, and executes an action chain configured by the server owner.
There is no restricted catalog of predefined entries: players enter their own value with colors and formatting. Application is not tied to one chat plugin— actions.yml can call the command provided by your metadata, permissions, or chat system.
Access can be tracked in two ways. PLUGIN mode stores finite and unlimited installation balances in SQLite or MySQL, while LEGACY mode uses the htitle.prefix and htitle.suffix permissions. Prefixes and suffixes are always handled independently.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

CORE FEATURES

• Self-service custom prefix and suffix installation
• MiniMessage, traditional color codes, and several HEX formats
• Separate visible-length limits for prefixes and suffixes
• Configurable blocked words, characters, colors, and formatting
• Two-step confirmation before a value is applied
• Separate confirmation for self-service resets
• Finite installation counts or an unlimited -1 balance
• Configurable delay between installations for unlimited access
• Database-backed or permission-backed access modes
• Access is rechecked at confirmation; in PLUGIN mode, one finite installation is consumed transactionally
• Grants for online, offline, and not-yet-known players
• Automatic delivery of a name-based pending grant on the next matching login attempt
• SQLite by default or MySQL; both backends use HikariCP
• Asynchronous database operations
• 9 built-in action types for messages, commands, and visual effects
• PlaceholderAPI and contextual variables inside actions
• Configurable player-command aliases
• Administrator tab completion for subcommands, targets, types, amounts, and formatting examples
• Bundled Russian and English configuration templates

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

INSTALLATION FLOW

1. An administrator grants one or more installations or unlimited access. In LEGACY mode, the corresponding permission is used instead of a balance.
2. The player enters /hprefix <value> or /hsuffix <value>.
3. The plugin normalizes color codes, validates the content, and measures rendered text without counting MiniMessage tags.
4. The player receives configurable chat and BossBar prompts asking them to confirm the selection.
5. The confirm command checks access again. In PLUGIN mode, one finite installation is consumed transactionally, while unlimited access is checked against its cooldown.
6. After a successful check, prefixFinish or suffixFinish runs; the bundled template passes the value to an external server command. hTitles does not verify the result of that external command.

Confirmation is available for 300 server ticks by default—nominally 15 seconds at 20 TPS. A new value of the same type replaces the previous pending confirmation. Pending confirmations are kept in memory and are cancelled by a plugin or server reload.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

ACCESS MODES
PLUGIN — internal balances

• Prefix and suffix installation counts are stored separately in the database
• A positive grant is added to a finite balance; an existing -1 remains unlimited
• -1 provides an unlimited number of installations
• A finite balance is reduced by one only after confirmation
• Unlimited access has an independent cooldown for each type; the default is 3 minutes
• htitle.prefix and htitle.suffix are not checked in this mode
• The /htitles give administrator command is available only in this mode

LEGACY — permission-based access

• Prefix installation requires htitle.prefix
• Suffix installation requires htitle.suffix
• The internal balance database is not started
• After confirmation, prefixFinish/suffixFinish and prefixLegacyConsume/suffixLegacyConsume execute in sequence
• The bundled action template dispatches a server command intended to revoke the corresponding permission; hTitles does not verify its result, and the template can be replaced completely

Select the mode with settings.accessMode. Prefixes and suffixes have independent access and confirmations; in PLUGIN mode, unlimited-access cooldowns are also tracked separately.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

FORMATTING AND VALIDATION
hTitles accepts native MiniMessage tags and converts common legacy color formats to MiniMessage:

<gradient:#FDBE00:#FFFFFF><bold>VIP</bold></gradient>
&6&lVIP
&#FDBE00VIP
&x&F&D&B&E&0&0VIP
{#FDBE00}VIP
#FDBE00VIP

• Default prefix maximum: 8 Unicode code points in rendered text
• Default suffix maximum: 12 Unicode code points in rendered text
• MiniMessage tags and color codes are not counted as visible text
• A value that renders as empty is rejected
• Double quotes and literal LF/CR characters in the normalized input are rejected before actions run
• blockedColors rejects selected colors and formatting in the normalized value
• blockedWords checks rendered text case-insensitively

The bundled configuration blocks obfuscation and a selection of potentially unwanted characters. Both lists and both length limits can be adapted to your server rules.
When text spans several command arguments, hTitles combines them without inserting ordinary spaces: for example, Hello World is processed as HelloWorld. Account for this when preparing player instructions.
The first reset argument always opens the reset branch, while a lone confirm confirms the pending value.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

CONFIRMATION AND RESET

• /hprefix confirm — confirm the pending prefix
• /hsuffix confirm — confirm the pending suffix
• /hprefix reset → /hprefix reset confirm — reset the prefix
• /hsuffix reset → /hsuffix reset confirm — reset the suffix

Self-service reset is enabled separately for each type through settings.resetEnabled. The reset handler runs a configurable action without consuming, refunding, or changing the internal installation balance or unlimited-access cooldown.
Prompts, clickable confirmation commands, BossBars, and timeouts are configurable. Prefix and suffix confirmations are independent of each other.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

ACTION SYSTEM
Primary player-facing flows and administrator actions are configured as lists in actions.yml. Feedback for administrator commands run from the server console comes from messages.yml, while target set and reset chains still execute from actions.yml. Lines run from top to bottom in [TYPE] content format, with case-insensitive type names.
Available action types:

• [MESSAGE] — send a MiniMessage message to the sender
• [BROADCAST] — send a MiniMessage message to the whole server
• [CONSOLE] — execute a command as the server console
• [PLAYER] — execute a command as the player
• [BOSSBAR] — display a configurable BossBar
• [SOUND] — play a sound
• [TITLE] — display a title and subtitle
• [ACTIONBAR] — display a message above the hotbar
• [PARTICLE] — spawn particles at the supplied location

Example prefix application through LuckPerms:

actions:
  prefixFinish:
    - '[CONSOLE] lp user {player} meta setprefix 101 "{title}<reset> "'
    - '[MESSAGE] {prefix} <green>Prefix {title}<reset> installed!'

LuckPerms is not a hard dependency: the lp command above is an example, while the bundled action templates call an external perms command that hTitles does not provide. Install a compatible metadata system or replace those lines with its commands. Commands in CONSOLE and PLAYER actions are written without a leading /.
{player} and {prefix} are supplied automatically. Depending on the event, actions also receive {title}, {target}, {type}, {amount}, {balance}, {seconds}, {maxSize}, and {blocked}. PlaceholderAPI placeholders are additionally resolved for actions that have a player context.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

VISUAL ACTIONS

[BOSSBAR] TEXT;TICKS[;COLOR[;OVERLAY[;PROGRESS]]]
[SOUND] SOUND_ID[;VOLUME[;PITCH]]
[TITLE] TITLE_TEXT[&&SUBTITLE_TEXT]
[ACTIONBAR] TEXT
[PARTICLE] PARTICLE_ID[;SPEED[;COUNT[;COLOR]]]

• BossBars support PINK/BLUE/RED/GREEN/YELLOW/PURPLE/WHITE colors, PROGRESS and NOTCHED_6/10/12/20 overlays, tick-based duration, and progress from 0 to 1
• Sound uses a registered Minecraft ID with configurable volume and pitch
• Title fade-in, stay, and fade-out timings are configured globally in config.yml
• Particle count, speed, and spread have configurable defaults
• The Particle HEX color applies to DUST with a fixed size of 1.0; other supported particles must not require additional data

PLAYER and visual actions are intended for flows with an online player context. Without a player context, PLAYER is skipped, while BOSSBAR, SOUND, TITLE, and ACTIONBAR apply to every online player. Use server-side CONSOLE actions in administrator chains that may target offline players.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

ADMINISTRATION

• Grant a finite number of installations
• Grant an unlimited -1 balance
• Start direct prefix or suffix application through an action chain without consuming a balance
• Start a reset through its dedicated action chain
• Target online players, known offline players, and UUIDs
• Grant installations to a valid username not yet known by the server
• Tab completion for online players, types, amounts, and formatting examples
• Reload configuration, aliases, actions, and the database connection in PLUGIN mode

/htitles and all of its subcommands require htitle.admin and can be used from the console. The type argument is prefix or suffix. The set and reset subcommands pass the target to configured action chains; their handlers do not change installation balances or verify the result of external commands.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

GRANTS FOR UNKNOWN PLAYERS
In PLUGIN mode, an administrator can grant installations before a player exists in the server cache:

• An unknown UUID receives a balance directly when UUID grants are enabled
• An unknown username containing 1–16 Latin letters, digits, or underscores is stored as a pending grant when settings.unknownPlayerGrants.name is enabled
• Usernames are stored and matched case-insensitively
• On the next matching login attempt, accumulated prefix and suffix installations are merged into the player's UUID balances and the pending row is deleted in the same transaction
• Finite amounts are added together, while any -1 value preserves unlimited access

Configure the behavior independently with settings.unknownPlayerGrants.name and settings.unknownPlayerGrants.uuid. When set to false, no new record is created for an unknown target; however, if that UUID balance or pending-name row already exists, later /htitles give commands can still add to it. Disabling the option does not delete stored records.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

DATA STORAGE
The default local database is:

plugins/hTitles/titles.db

The database stores separate prefix and suffix balances, unlimited-access cooldown timestamps, and pending name-based grants. hTitles passes the value being applied to a configurable chain in actions.yml, but it neither stores that text in its database nor verifies the result of the external command.

• SQLite — local storage; schema initialization applies journal_mode=WAL, synchronous=NORMAL, and busy_timeout=5000, while the pool is forced to one connection
• MySQL — remote storage with a configurable HikariCP pool and JDBC properties
• Two dedicated threads are used for asynchronous database work by default
• Grant, consume, and pending-balance transfer operations are transactional
• MySQL uses row locking for concurrent balance changes

Database type, credentials, MySQL pool properties, and worker-thread count are configured in storage.yml. Data is not copied automatically when switching between SQLite and MySQL, changing the SQLite file, or selecting another MySQL connection, so migrate it separately.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

COMMANDS
Player commands:

/hprefix <prefix>
/hprefix confirm
/hprefix reset
/hprefix reset confirm
/hsuffix <suffix>
/hsuffix confirm
/hsuffix reset
/hsuffix reset confirm

Default configurable aliases: /prefix and /suffix.
/hprefix, /hsuffix, and their aliases are player-only. /htitles and all of its subcommands can be run from the console with htitle.admin.
Administrator commands:

/htitles
/htitles reload
/htitles give <player|UUID> <prefix|suffix> [amount|-1]
/htitles set <player|UUID> <prefix|suffix> <value>
/htitles reset <player|UUID> <prefix|suffix>

When give has no amount, one installation is granted. An explicit amount must be a 64-bit integer equal to -1 or at least 1; 0 and values below -1 are rejected. -1 means an unlimited number of installations, not the lifetime of the applied prefix or suffix.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

PERMISSIONS

htitle.admin
htitle.prefix
htitle.suffix

• htitle.admin — /htitles and all of its subcommands
• htitle.prefix — prefix installation in LEGACY mode
• htitle.suffix — suffix installation in LEGACY mode

All three permissions default to server operators. In PLUGIN mode, htitle.prefix and htitle.suffix do not determine player access; database balances do. Self-service reset does not require htitle.prefix or htitle.suffix even in LEGACY mode; it is controlled by settings.resetEnabled.prefix and settings.resetEnabled.suffix.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

CONFIGURATION FILES