nonebot-plugin-palworld-sync 0.2.0

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

nonebot-plugin-palworld-sync

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

介绍

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

安装

推荐使用 nb-cli 安装：

nb plugin install nonebot-plugin-palworld-sync --upgrade

或使用包管理器

pip install nonebot-plugin-palworld-sync --upgrade

并在 pyproject.toml 或 bot.py 中加载插件：

plugins = ["nonebot_plugin_palworld_sync"]

1. 插件配置

服务端 PalDefender 扩展安装 (可选)

若需使用查包、发放道具/帕鲁、强拆据点等高级扩展功能，请先按照 PalDefender 官方指南 在您的幻兽帕鲁服务器上配置并运行该扩展。

幻兽帕鲁服务端配置 (PalWorldSettings.ini)

RESTAPIEnabled=True,RESTAPIPort=8212,AdminPassword="您的管理员密码"

Nonebot 环境变量配置 (.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 (UserId) 说明：

• 智能模糊匹配：输入昵称/ID时，精确匹配优先，模糊匹配次之。多名重名时机器人会拒绝执行并列出列表提示细化。
• 统一使用 ID：无论输入昵称、32位 UUID 还是 @群友/QQ，机器人底层均会统一转换为唯一的 玩家ID (UserId) 发送执行。若玩家离线且未绑定，则必须直接提供其玩家ID。
• 平台前缀：玩家ID格式依平台而定，通常带有前缀。如 Steam 为 steam_xxx，Xbox 为 gdk_xxx，PS5 为 ps5_xxx（亦可为纯数字）。

帕鲁服务器命令

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

PalDefender 扩展命令

指令	参数要求	功能描述	权限要求
/pw bind <玩家>	<玩家> 必填 (游戏昵称/玩家ID)	绑定 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/@群友 <物品名/ID> 物品中文名或 ID [数量] 数量 (默认1)	后台发放道具/武器/材料 (支持中文，需启用 PDAPI)	管理员
/pw givepal <玩家> <帕鲁名/ID>	<玩家> 玩家名/QQ/@群友 <帕鲁名/ID> 帕鲁中文名或 ID	后台发放特定帕鲁实体 (支持中文，需启用 PDAPI)	管理员
/pw deletebase <据点UUID>	<据点UUID> 据点UUID	一键强拆销毁指定的玩家据点 (需启用 PDAPI)	管理员
/pw tp <玩家> [玩家2]	<玩家> 玩家名/QQ/@群友 [玩家2] 选填	直接传送玩家 (只填一个目标时传送自己，需绑定；填两个目标时将源玩家传送到目的地)	管理员

---

致谢

本项目在实现物品及帕鲁中文化映射功能时，翻译数据来源于以下开源项目，特此致谢：

• zaigie/palworld-server-tool：提供了最新、最完整的帕鲁和物品的 ID 与中英文翻译配置数据。