[MD]
# 适用于Endstone加载器的占位符前置
一个为Endstone设计的占位符API插件，灵感来源于Spigot平台上著名的PAPI插件。本项目提供原生C++支持，并通过`endstone_papi`包提供Python绑定，实现无缝集成。
> 本插件仍在开发中，尚未发布至PyPI。如果您希望使用此插件，请从GitHub Actions页面下载最新构建版本：[构建产物](https://github.com/endstone-essentials/papi/actions/workflows/build.yml)。
## 安装
- 从[发布页面](https://github.com/endstone-essentials/papi/releases)或[GitHub Actions](https://github.com/endstone-essentials/papi/actions/workflows/build.yml)下载.whl文件
- 将其放入`plugins`文件夹
- 重启服务器，即可使用！
## 项目结构
```
endstone-essentials/papi/
├── endstone_papi/ # Python包（用于Python插件）
├── examples/
│ ├── cpp/ # C++示例插件
│ └── python/ # Python示例插件
├── include/ # 头文件（用于C++插件）
├── CMakeLists.txt # CMake构建配置
├── pyproject.toml # Python包配置
├── LICENSE # 许可证信息
└── README.md # 本文件
```
## 使用示例
### C++
> 您可以从`.whl`文件中获取打包的`papi.h`头文件。
```c++
#include <endstone/endstone.hpp>
#include <endstone_papi/papi.h>
class JoinExample : public endstone::Plugin {
public:
void onEnable() override
{
if (getServer().getPluginManager().getPlugin("papi")) {
registerEvent(&JoinExample::onPlayerJoin, *this, endstone::EventPriority::Highest);
papi_ = getServer().getServiceManager().load<papi::PlaceholderAPI>("PlaceholderAPI");
}
else {
getLogger().warning("Could not find PlaceholderAPI! This plugin is required.");
getServer().getPluginManager().disablePlugin(*this);
}
}
void onPlayerJoin(endstone::PlayerJoinEvent &event)
{
std::string join_text = "{player_name}加入了服务器！当前游戏模式为{player_gamemode}";
join_text = papi_->setPlaceholder(event.getPlayer(), join_text);
event.setJoinMessage(join_text);
}
private:
std::shared_ptr<papi::PlaceholderAPI> papi_;
};
```
完整代码请参考[C++示例插件](https://github.com/endstone-essentials/papi/blob/main/examples/cpp)。
### Python
```python
from endstone_papi import PlaceholderAPI
from endstone.plugin import Plugin
from endstone.event import event_handler, EventPriority, PlayerJoinEvent
class JoinExample(Plugin):
api_version = "0.6"
soft_depend = ["papi"]
def on_enable(self):
if self.server.plugin_manager.get_plugin("papi"):
self.register_events(self)
self.papi = self.server.service_manager.load("PlaceholderAPI")
else:
self.logger.warning("未找到PlaceholderAPI！该插件为必需依赖。")
self.server.plugin_manager.disable_plugin(self)
@event_handler(priority=EventPriority.HIGHEST)
def on_player_join(self, event: PlayerJoinEvent):
join_text = "{player_name}加入了服务器！当前游戏模式为{player_gamemode}"
join_text = self.papi.set_placeholder(event.player, join_text)
event.join_message = join_text
```
完整代码请参考[Python示例插件](https://github.com/endstone-essentials/papi/blob/main/examples/python)。
## 截图
## 占位符结构
占位符的格式为`{<标识符>|<参数>}`。其中`参数`为可选字段，可为占位符提供额外信息。`参数`的具体格式由`标识符`对应的处理器决定。若不需要参数，可直接简写为`{标识符}`。
## 内置占位符
安装PAPI后可直接使用以下内置占位符：
- [x] `{x}` x坐标
- [x] `{y}` y坐标
- [x] `{z}` z坐标
- [x] `{player_name}` 玩家名称
- [x] `{dimension}` 维度名称
- [x] `{dimension_id}` 维度ID
- [x] `{ping}` 玩家延迟
- [x] `{date}` 日期
- [x] `{time}` 时间
- [x] `{datetime}` 日期和时间
- [x] `{year}` 年份
- [x] `{month}` 月份
- [x] `{day}` 日
- [x] `{hour}` 小时
- [x] `{minute}` 分钟
- [x] `{second}` 秒
- [x] `{mc_version}` Minecraft版本
- [x] `{online}` 在线玩家数
- [x] `{max_online}` 最大在线玩家数
- [x] `{address}` 玩家IP地址
- [x] `{runtime_id}` 玩家运行时ID
- [x] `{exp_level}` 玩家经验等级
- [x] `{total_exp}` 玩家总经验值
- [x] `{exp_progress}` 玩家经验进度
- [x] `{game_mode}` 玩家游戏模式
- [x] `{xuid}` 玩家XUID
- [x] `{uuid}` 玩家UUID
- [x] `{device_os}` 玩家设备操作系统
- [x] `{locale}` 玩家语言环境
## 要求
Python: 3.10+
Endstone: 0.6+
## 贡献指南
欢迎贡献代码！您可以fork本仓库，改进代码后提交Pull Request。
## 许可证
本项目采用MIT许可证。详见[LICENSE](LICENSE)文件。
[/MD]
