<p align="center"> <h1 align="center">🔮 MysticPlaceholders</h1> <p align="center"> A standalone Minecraft plugin for creating custom placeholders with PlaceholderAPI integration, Skript support, and MySQL/MariaDB storage. </p> --- ## 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 ```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 **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()`.