? MysticPlaceholders
一款独立的 Minecraft 插件,用于创建自定义占位符,支持 PlaceholderAPI 集成、Skript 支持以及 MySQL/MariaDB 存储。
功能特性
- 数值占位符 — 存储整型值,如金币、代币、击杀数、死亡数、等级、法力值等。
- 文本占位符 — 存储字符串值,如头衔、称号、阵营、状态等。
- 最大值上限 — 可为每个数值占位符配置可选的最大限制。
- PlaceholderAPI 集成 — 通过
%mysticplaceholders_<name>% 访问占位符。
- Skript 集成 — 提供完整的 Skript 插件扩展,包含表达式、结构和关系型占位符支持。
- MySQL/MariaDB 存储 — 通过 [MysticLib] 的共享数据库连接实现持久化数据存储(使用 HikariCP 连接池)。
- 内存缓存 — 对在线玩家进行快速的 O(1) 查找,并具有自动缓存生命周期管理。
- 异步数据库操作 — 所有数据库写入均为非阻塞操作,确保服务器无延迟。
- MiniMessage 支持 — 完全支持现代 MiniMessage 颜色/渐变格式化。
- 可自定义显示 — 可为每个占位符配置
zero-display(零值显示)和 normal-display(正常显示)格式。
- 线程安全 — 使用
ConcurrentHashMap 进行缓存,并通过原子数据库更新操作保证安全性。
依赖要求
| 依赖项 |
版本 |
| Paper / Purpur |
1.21.x+ |
| Java |
21+ |
| MysticLib |
1.0.0+ (必需 — 提供数据库及日志功能) |
| Skript |
2.8+ (必需 — 用于 Skript 集成) |
| PlaceholderAPI |
2.11+ (必需) |
| MySQL / MariaDB |
5.7+ / 10.2+ |
安装步骤
- 从 Releases 页面下载最新的
MysticPlaceholders-x.x.x.jar。
- 确保您的服务器上已安装 MysticLib 和 Skript。
- 将 JAR 文件放入服务器的
plugins/ 文件夹中。
- 启动或重启服务器。
- 在
plugins/MysticPlaceholders/config.yml 中配置您的占位符。
- 执行
/mplaceholder reload 命令重载配置,或重启服务器。
注意: 数据库连接在 MysticLib 的 config.yml 中进行配置,而非本插件。MysticPlaceholders 使用 MysticLib 的共享数据库连接。
配置说明
- 数值占位符:
%value% 将被替换为数字。可选的 max 参数用于限制数值上限。
- 文本占位符:
%value% 将被替换为存储的字符串。使用 null 可清空该值。
- 颜色: 使用 MiniMessage 格式(如
<red>、<green>、<gradient:#hex1:#hex2> 等)。旧的 & 代码会自动转换。
- 文本值: 文本值中的下划线 (
_) 会被转换为空格。
命令列表
| 命令 |
描述 |
权限节点 |
/mplaceholder set <player> <placeholder> <value> |
设置占位符的值 |
mysticplaceholders.admin |
/mplaceholder add <player> <placeholder> <value> |
向数值类型的占位符增加值 |
mysticplaceholders.admin |
/mplaceholder remove <player> <placeholder> <value> |
从数值类型的占位符减少值 |
mysticplaceholders.admin |
/mplaceholder list |
列出所有已配置的占位符 |
mysticplaceholders.admin |
/mplaceholder reload |
重载配置文件 |
mysticplaceholders.admin |
别名: /mph、/mysticph、/mplh
占位符用法
安装 PlaceholderAPI 后,您可以在任何支持 PAPI 的地方使用以下占位符:
%mysticplaceholders_coins%
%mysticplaceholders_tokens%
%mysticplaceholders_kills%
%mysticplaceholders_deaths%
%mysticplaceholders_level%
%mysticplaceholders_mana%
%mysticplaceholders_rank%
%mysticplaceholders_title%
%mysticplaceholders_faction%
%mysticplaceholders_status%
Skript 集成
MysticPlaceholders 注册为一个完整的 Skript 插件扩展。可在配置文件中通过 skript-integration: true 启用或禁用。
获取 / 设置值
# 获取一个占位符的值
set {_mana} to mystic placeholder "mana" of player
# 设置一个值
set mystic placeholder "mana" of player to 100
# 向一个值添加数值
add 25 to mystic placeholder "mana" of player
# 从一个值减去数值
remove 10 from mystic placeholder "coins" of player
在 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 ✦"
这些占位符随后可以通过 PlaceholderAPI 作为 %custom_health_display% 和 %custom_mana_bar% 使用。
关系型占位符
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
数据库
MysticPlaceholders 使用 MysticLib 的共享数据库连接 — 您无需在此插件中配置数据库。
工作原理
- 在
plugins/MysticLib/config.yml 中配置您的 MySQL/MariaDB 连接。
- MysticPlaceholders 会自动创建两个表:
mystic_placeholders_numeric — 存储数值型占位符的值
mystic_placeholders_text — 存储文本型占位符的值
- 如果在 MysticLib 中禁用了数据库,插件将以仅内存模式运行(重启后数据将丢失)。
性能优化
- HikariCP 连接池 — 工业标准的高性能 JDBC 连接池(由 MysticLib 提供)。
- 异步操作 — 所有数据库写入均通过
CompletableFuture 异步执行。
- 原子性更新 (Upserts) — 使用
INSERT ... ON DUPLICATE KEY UPDATE 确保并发写入的安全性。
- 智能缓存 — 在线玩家的数据缓存在
ConcurrentHashMap 中,以实现 O(1) 的快速查找。
- 最大值上限 — 在缓存层和数据库层均强制执行,使用 SQL
LEAST() 函数。
? 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
- Download the latest
MysticPlaceholders-x.x.x.jar from Releases.
- Ensure MysticLib and Skript are already installed on your server.
- Place the JAR in your server's
plugins/ folder.
- Start/restart the server.
- Configure your placeholders in
plugins/MysticPlaceholders/config.yml.
- 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
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
- Configure your MySQL/MariaDB connection in
plugins/MysticLib/config.yml.
- MysticPlaceholders automatically creates two tables:
mystic_placeholders_numeric — Stores numeric placeholder values
mystic_placeholders_text — Stores text placeholder values
- 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().
评论 0
登录后参与评分
还没有评论,来抢沙发吧