MysticPlaceholders

🔮 MysticPlaceholders

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

---

Features

- Thread Safe — Store integer values like coins, tokens, kills, deaths, levels, mana, etc. - Thread Safe — Store string values like ranks, titles, factions, status, etc. - Thread Safe — Configure optional maximum limits per numeric placeholder. - Thread Safe — Access placeholders via `%mysticplaceholders_<name>%`. - Thread Safe — Full Skript addon with expressions, structures, and relational placeholder support. - Thread Safe — Persistent data via [MysticLib]'s shared database connection (HikariCP pooling). - Thread Safe — Fast O(1) lookups for online players with automatic cache lifecycle. - Thread Safe — All database writes are non-blocking, keeping your server lag-free. - Thread Safe — Full support for modern MiniMessage color/gradient formatting. - Thread Safe — 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 Skript and Skript 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.

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

Configuration Notes

- Text values: `%value%` is replaced with the number. Optional `max` caps the value. - Text values: `%value%` is replaced with the stored string. Use `null` to clear. - Text values: 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`

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

```applescript

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

```applescript 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

```applescript 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 not — 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

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