🔮 MysticPlaceholders

A standalone Minecraft plugin for creating custom placeholders with PlaceholderAPI integration, Skript support, and MySQL/MariaDB storage.

---

Features

• Numeric Placeholders — Store integer values like coins, tokens, kills, deaths, levels, mana, etc.
• Text Placeholders — Store string values like ranks, titles, factions, status, etc.
• Max Value Caps — Configure optional maximum limits per numeric placeholder.
• PlaceholderAPI Integration — Access placeholders via %mysticplaceholders_<name>%.
• Skript Integration — Full Skript addon with expressions, structures, and relational placeholder support.
• MySQL/MariaDB Storage — Persistent data via [MysticLib]'s shared database connection (HikariCP pooling).
• In-Memory Caching — Fast O(1) lookups for online players with automatic cache lifecycle.
• Async Database Operations — All database writes are non-blocking, keeping your server lag-free.
• MiniMessage Support — Full support for modern MiniMessage color/gradient formatting.
• Customizable Display — Configure zero-display and normal-display formats per placeholder.
• Thread Safe — ConcurrentHashMap caching with atomic database upserts.

Requirements

Requirement	Version
Paper / Purpur	1.21.x+
Java	21+
[MysticLib]	1.0.0+ (required — provides database & logging)
[Skript]	2.8+ (required — for Skript integration)
[PlaceholderAPI]	2.11+ (required)
MySQL / MariaDB	5.7+ / 10.2+

Installation

1. Download the latest MysticPlaceholders-x.x.x.jar from [Releases].
2. Ensure MysticLib and PlaceholderAPI are already installed on your server.
3. Place the JAR in your server's plugins/ folder.
4. Start/restart the server.
5. Configure your placeholders in plugins/MysticPlaceholders/config.yml.
6. Reload with /mplaceholder reload or restart the server.

Note: Database connection is configured in MysticLib's config.yml, not in this plugin. MysticPlaceholders uses MysticLib's shared database connection.

Configuration Notes

• Numeric placeholders: %value% is replaced with the number. Optional max caps the value.
• Text placeholders: %value% is replaced with the stored string. Use null to clear.
• Colors: Use MiniMessage format (<red>, <green>, <gradient:#hex1:#hex2>, etc.). Legacy & codes are auto-converted.
• Text values: Underscores (_) in text values are converted to spaces.

Commands

Command	Description	Permission
/mplaceholder set <player> <placeholder> <value>	Set a placeholder value	mysticplaceholders.admin
/mplaceholder add <player> <placeholder> <value>	Add to a numeric value	mysticplaceholders.admin
/mplaceholder remove <player> <placeholder> <value>	Remove from a numeric value	mysticplaceholders.admin
/mplaceholder list	List all configured placeholders	mysticplaceholders.admin
/mplaceholder reload	Reload configuration	mysticplaceholders.admin

Aliases: /mph, /mysticph, /mplh

Example Placeholders

After installing PlaceholderAPI, use placeholders anywhere that supports PAPI:

%mysticplaceholders_coins%
%mysticplaceholders_tokens%
%mysticplaceholders_kills%
%mysticplaceholders_deaths%
%mysticplaceholders_level%
%mysticplaceholders_mana%
%mysticplaceholders_rank%
%mysticplaceholders_title%
%mysticplaceholders_faction%
%mysticplaceholders_status%

Skript Integration

MysticPlaceholders registers as a full Skript addon. Enable/disable via skript-integration: true in config.

Get / Set Values

# Get a placeholder value
set {_mana} to mystic placeholder "mana" of player

# Set a value
set mystic placeholder "mana" of player to 100

# Add to a value
add 25 to mystic placeholder "mana" of player

# Remove from a value
remove 10 from mystic placeholder "coins" of player

Define Custom Placeholders in Skript

mystic placeholder with the prefix "custom":
    if the identifier is "health_display":
        set the result to "&c%health of player%❤"

    if the identifier is "mana_bar":
        set {_mana} to mystic placeholder "mana" of player
        set the result to "&b%{_mana}%/100 ✦"

These are then usable as %custom_health_display% and %custom_mana_bar% via PlaceholderAPI.

Relational Placeholders

mystic relational placeholder with the prefix "rel":
    if the identifier is "compare_level":
        set {_l1} to mystic placeholder "level" of first player
        set {_l2} to mystic placeholder "level" of second player
        if {_l1} > {_l2}:
            set the result to name of the first player
        else:
            set the result to name of the second player

Database

MysticPlaceholders uses MysticLib's shared database connection — you do not configure a database in this plugin.

How it works

1. Configure your MySQL/MariaDB connection in plugins/MysticLib/config.yml.
2. MysticPlaceholders automatically creates two tables:
   • mystic_placeholders_numeric — Stores numeric placeholder values
   • mystic_placeholders_text — Stores text placeholder values
3. If the database is disabled in MysticLib, the plugin runs in memory-only mode (data is lost on restart).

Performance

• HikariCP Connection Pool — Industry-standard, high-performance JDBC pooling (via MysticLib).
• Async Operations — All database writes are asynchronous via CompletableFuture.
• Atomic Upserts — Uses INSERT ... ON DUPLICATE KEY UPDATE for safe concurrent writes.
• Smart Caching — Online player data is cached in ConcurrentHashMap for O(1) lookups.
• Max Value Caps — Enforced at both cache and database level using SQL LEAST().