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

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（亦可为纯数字）。

帕鲁服务器命令

PalDefender 扩展命令

致谢

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

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