Metadata-Version: 2.4
Name: nonebot-plugin-palworld-sync
Version: 0.1.5
Summary: 基于NoneBot2的幻兽帕鲁 (Palworld) 服务器 REST API 插件
Keywords: nonebot,nonebot2,palworld,pal
Author: yuexps@qq.com
Requires-Python: >=3.9,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: httpx (>=0.20.0,<1.0.0)
Requires-Dist: nonebot-adapter-onebot (>=2.4.0,<3.0.0)
Requires-Dist: nonebot2 (>=2.2.0,<3.0.0)
Project-URL: Homepage, https://github.com/yuexps/nonebot-plugin-palworld-sync
Project-URL: Repository, https://github.com/yuexps/nonebot-plugin-palworld-sync
Description-Content-Type: text/markdown

<p align="center">
  <a href="https://adapter-onebot.netlify.app/"><img src="https://img.shields.io/badge/nonebot2-plugin-red.svg" alt="nonebot2"></a>
  <a href="https://pypi.org/project/nonebot-plugin-palworld-sync"><img src="https://img.shields.io/pypi/v/nonebot-plugin-palworld-sync.svg" alt="pypi"></a>
  <img src="https://img.shields.io/badge/python-3.9+-blue.svg" alt="python">
</p>

# nonebot-plugin-palworld-sync

基于 Nonebot2 的幻兽帕鲁 (Palworld) 服务器 REST API 插件。

## 介绍

通过幻兽帕鲁官方 REST API 实现服务器状态监控与群内管理。支持群消息和游戏内互通、玩家踢出/封禁/解封、在线人数查询以及关机与存档等操作。

## 安装

推荐使用 `nb-cli` 安装：
```bash
nb plugin install nonebot-plugin-palworld-sync --upgrade
```

<details>
<summary>或使用包管理器</summary>

```bash
pip install nonebot-plugin-palworld-sync --upgrade
```
并在 `pyproject.toml` 或 `bot.py` 中加载插件：
```toml
plugins = ["nonebot_plugin_palworld_sync"]
```
</details>

## 1. 插件配置

### 服务端 PalDefender 扩展安装 (可选)
若需使用查包、发放道具/帕鲁、强拆据点等高级扩展功能，请先按照 [PalDefender 官方指南](https://github.com/Ultimeit/PalDefender) 在您的幻兽帕鲁服务器上配置并运行该扩展。

### 幻兽帕鲁服务端配置 (PalWorldSettings.ini)
```ini
RESTAPIEnabled=True,RESTAPIPort=8212,AdminPassword="您的管理员密码"
```

### Nonebot 环境变量配置 (.env)

```env
# 基础配置 (官方 REST API)
PALWORLD_API_URL="http://<服务器IP>:8212"
PALWORLD_API_PASSWORD="您的管理员密码"
PALWORLD_QQ_GROUPS=["123456"]  # 生效 QQ 群列表 (JSON 数组格式)
PALWORLD_FORWARD_GROUP_MSG=False  # 是否转发 QQ 群消息到游戏内
PALWORLD_PLAYER_TRACKING=True  # 是否广播玩家进出服通知
PALWORLD_PLAYER_TRACKING_INTERVAL=10  # 状态轮询间隔（秒）

# PalDefender 配置 (可选，用于查包/发物品奖励/强拆)
PALWORLD_PDAPI_ENABLED=True  # 启用 API 扩展
PALWORLD_PDAPI_URL="http://<服务器IP>:17993"
PALWORLD_PDAPI_TOKEN="您的 Token"

# RCON 配置 (需服务端已配置并安装 PalDefender 以支持扩展 RCON 命令，用于 TPA 传送)
PALWORLD_RCON_HOST="<服务器IP>"
PALWORLD_RCON_PORT=25575
PALWORLD_TPA_TIMEOUT=60  # TPA 超时时间（秒）
```

---

## 2. 指令一览

> **玩家智能模糊匹配说明**：
> 所有需要指定目标的指令（如踢出、封禁、传送、查包、发物品等），在匹配输入的目标昵称/ID时，采用**精确匹配最优先，模糊匹配次之**的逻辑。若检索到多名重名相似的玩家，为防止误伤，机器人将拒绝执行并列出备选重名列表供发起人细化。

### 帕鲁服务器命令

| 指令 | 参数要求 | 功能描述 | 权限要求 |
| :--- | :--- | :--- | :--- |
| /pw status | 无 | 查看服务器状态 (版本、FPS、在线人数、核心配置等) | 公共 |
| /pw players [目标] | [目标] 选填 (名字/SteamID) | 查看在线玩家，若指定目标则返回详细状态 | 公共 |
| /pw save | 无 | 保存当前游戏世界存盘 | 管理员 |
| /pw say <消息> | <消息> 广播消息 | 发送全局广播公告 | 管理员 |
| /pw shutdown [秒/force] [消息] | [秒/force] 选填 (关闭时间)<br>[消息] 选填 (广播公告) | 关闭服务器 (定时关闭或强制停止) | 管理员 |
| /pw kick <目标> [原因] | <目标> 昵称/SteamID<br>[原因] 选填 | 踢出指定玩家 | 管理员 |
| /pw ban <目标> [原因] | <目标> 昵称/SteamID<br>[原因] 选填 | 封禁指定玩家 | 管理员 |
| /pw unban <SteamID> | <SteamID> SteamID | 解封指定玩家 | 管理员 |

### PalDefender 扩展命令

| 指令 | 参数要求 | 功能描述 | 权限要求 |
| :--- | :--- | :--- | :--- |
| /pw bind <目标> | <目标> 必填 (游戏昵称/SteamID) | 绑定 QQ 与游戏角色 | 公共 |
| /pw unbind | 无 | 解除当前 QQ 绑定 | 公共 |
| /pw tpa <目标> | <目标> 必填 (昵称/QQ/@群友) | 申请传送到目标玩家身边 (TPA 交互，有效时间 60 秒) | 公共 |
| /pw tpaccept | 无 | 同意他人的 TPA 传送请求 | 公共 |
| /pw tpdeny | 无 | 拒绝他人的 TPA 传送请求 | 公共 |
| /pw items [目标] | [目标] 选填 (昵称/QQ/@群友) | 查看背包物品 (不填查看自己，需启用 PDAPI) | 公共 |
| /pw pals [目标] | [目标] 选填 (昵称/QQ/@群友) | 查看持有帕鲁详细属性、IV 值与被动词条 (需启用 PDAPI) | 公共 |
| /pw guilds | 无 | 查看服务器全部公会列表 (需启用 PDAPI) | 管理员 |
| /pw give <目标> <物品ID> [数量] | <目标> 玩家名/QQ/@群友<br><物品ID> 物品ID<br>[数量] 数量 (默认1) | 后台发放道具/武器/材料 (需启用 PDAPI) | 管理员 |
| /pw givepal <目标> <帕鲁ID> | <目标> 玩家名/QQ/@群友<br><帕鲁ID> 帕鲁ID | 后台发放特定帕鲁实体 (需启用 PDAPI) | 管理员 |
| /pw deletebase <据点UUID> | <据点UUID> 据点UUID | 一键强拆销毁指定的玩家据点 (需启用 PDAPI) | 管理员 |

