nonebot-plugin-palworld-sync 0.1.0__py3-none-any.whl

nonebot_plugin_palworld_sync/__init__.py

@@ -0,0 +1,327 @@
+import shlex
+import nonebot
+from nonebot import on_command, on_message
+from nonebot.adapters.onebot.v11 import Bot, GroupMessageEvent, Message, MessageEvent
+from nonebot.params import CommandArg
+from nonebot.permission import SUPERUSER
+from nonebot.plugin import PluginMetadata
+
+from .api import PalWorldAPI, PalWorldAPIError
+from .config import Config
+
+__plugin_meta__ = PluginMetadata(
+    name="Palworld",
+    description="幻兽帕鲁服务器 REST API 插件",
+    usage=(
+        "帕鲁服务器命令：\n"
+        "/pw status - 查看服务器状态\n"
+        "/pw players [目标] - 查看在线玩家/详细信息\n"
+        "/pw save - 保存世界存盘\n"
+        "/pw say <消息> - 广播全局消息\n"
+        "/pw shutdown [秒/force] [消息] - 关闭服务器\n"
+        "/pw kick <目标> [原因] - 踢出玩家\n"
+        "/pw ban <目标> [原因] - 封禁玩家\n"
+        "/pw unban <SteamID> - 解封玩家"
+    ),
+    type="application",
+    homepage="https://github.com/yuexps/nonebot-plugin-palworld-sync",
+    supported_adapters={"~onebot.v11"},
+)
+
+# 加载配置
+try:
+    from nonebot import get_plugin_config
+    pal_config = get_plugin_config(Config)
+except ImportError:
+    pal_config = Config.parse_obj(nonebot.get_driver().config)
+
+# 初始化 API 客户端
+api = PalWorldAPI(pal_config.palworld_api_url, pal_config.palworld_api_password)
+
+pal_cmd = on_command("pw", priority=5, block=True)
+
+
+async def check_admin(bot: Bot, event: MessageEvent) -> bool:
+    """检查用户是否具有管理员或超级用户权限"""
+    if await SUPERUSER(bot, event):
+        return True
+    if isinstance(event, GroupMessageEvent):
+        return event.sender.role in ("owner", "admin")
+    return False
+
+
+def format_uptime(seconds: int) -> str:
+    """格式化运行时间为易读的中文字符串"""
+    days, remain = divmod(seconds, 86400)
+    hours, remain = divmod(remain, 3600)
+    minutes, secs = divmod(remain, 60)
+
+    parts = []
+    if days > 0:
+        parts.append(f"{days}天")
+    if hours > 0:
+        parts.append(f"{hours}小时")
+    if minutes > 0:
+        parts.append(f"{minutes}分钟")
+    if secs > 0 or not parts:
+        parts.append(f"{secs}秒")
+    return "".join(parts)
+
+
+@pal_cmd.handle()
+async def handle_pal(bot: Bot, event: MessageEvent, command_arg: Message = CommandArg()):
+    # 仅在配置的帕鲁群内响应命令
+    if not isinstance(event, GroupMessageEvent) or str(event.group_id) not in pal_config.palworld_qq_groups:
+        return
+
+    args_str = command_arg.extract_plain_text().strip()
+    if not args_str:
+        await pal_cmd.finish(__plugin_meta__.usage)
+
+    try:
+        args = shlex.split(args_str)
+    except ValueError as e:
+        await pal_cmd.finish(f"参数解析错误：{str(e)}（请检查双引号是否闭合）")
+
+    action = args[0].lower()
+    
+    valid_actions = {
+        "status",
+        "players",
+        "say",
+        "kick",
+        "ban",
+        "unban",
+        "save",
+        "shutdown",
+    }
+    if action not in valid_actions:
+        await pal_cmd.finish(f"未知子命令：{action}\n{__plugin_meta__.usage}")
+
+    # 权限校验
+    admin_actions = {
+        "say",
+        "kick",
+        "ban",
+        "unban",
+        "save",
+        "shutdown",
+    }
+    if action in admin_actions:
+        if not await check_admin(bot, event):
+            await pal_cmd.finish("权限不足：仅超级用户、群主或管理员有权执行此操作。")
+
+    try:
+        if action == "status":
+            import asyncio
+            res = await asyncio.gather(
+                api.get_info(),
+                api.get_metrics(),
+                api.get_settings(),
+                return_exceptions=True
+            )
+
+            info = res[0] if not isinstance(res[0], Exception) else {}
+            metrics = res[1] if not isinstance(res[1], Exception) else {}
+            settings = res[2] if not isinstance(res[2], Exception) else {}
+
+            if isinstance(res[0], Exception) and isinstance(res[1], Exception):
+                raise PalWorldAPIError("获取服务器状态失败，请确认 API 服务在线。")
+
+            version = info.get("version", "Unknown")
+            s_name = info.get("servername", "Unknown")
+            guid = info.get("worldguid", "N/A")
+
+            fps = metrics.get("serverfps", "N/A")
+            frame_time = metrics.get("serverframetime", 0.0)
+            players_num = metrics.get("currentplayernum", 0)
+            max_players = metrics.get("maxplayernum", 0)
+            uptime = metrics.get("uptime", 0)
+            days = metrics.get("days", 0)
+
+            uptime_str = format_uptime(uptime) if isinstance(uptime, int) else "N/A"
+
+            difficulty = settings.get("Difficulty", "N/A")
+            penalty = settings.get("PlayerDeathPenalty", "N/A")
+            pvp = "启用" if settings.get("bIsPvP") is True else "禁用" if settings.get("bIsPvP") is False else "N/A"
+
+            reply = (
+                f"【服务器状态 - {s_name}】\n"
+                f"版本：{version}\n"
+                f"存档GUID：{guid}\n"
+                f"帧率 (FPS)：{fps} ({frame_time:.2f} ms)\n"
+                f"运行时间：{uptime_str} (第 {days} 天)\n"
+                f"在线人数：{players_num} / {max_players}\n"
+                f"核心配置：难度 {difficulty} | PvP {pvp} | 死亡惩罚 {penalty}"
+            )
+            await pal_cmd.finish(reply)
+
+        elif action == "players":
+            players = await api.get_players()
+            if not players:
+                await pal_cmd.finish("当前没有玩家在线。")
+
+            # 若提供了目标参数，则进行模糊匹配并返回详细信息
+            if len(args) > 1:
+                target = args[1]
+                matched_player = None
+                for p in players:
+                    p_name = p.get("name", "")
+                    p_pid = p.get("playerId", "")
+                    p_uid = p.get("userId", "")
+                    if target.lower() in (p_name.lower(), p_pid.lower(), p_uid.lower()):
+                        matched_player = p
+                        break
+
+                if not matched_player:
+                    await pal_cmd.finish(f"在线玩家中未找到匹配「{target}」的人。")
+
+                name = matched_player.get("name", "Unknown")
+                reply = (
+                    f"【玩家详细信息 - {name}】\n"
+                    f"等级：{matched_player.get('level', 0)}\n"
+                    f"玩家ID：{matched_player.get('playerId', 'N/A')}\n"
+                    f"SteamID：{matched_player.get('userId', 'N/A')}\n"
+                    f"延迟：{matched_player.get('ping', 0.0):.1f}ms\n"
+                    f"坐标：({matched_player.get('location_x', 0.0):.1f}, {matched_player.get('location_y', 0.0):.1f})\n"
+                    f"建筑数：{matched_player.get('building_count', 0)}"
+                )
+                await pal_cmd.finish(reply)
+            else:
+                # 默认返回简要的玩家昵称、等级、延迟列表
+                lines = [f"【在线玩家 ({len(players)}人)】"]
+                for i, p in enumerate(players, 1):
+                    lines.append(
+                        f"{i}. {p.get('name', 'Unknown')} "
+                        f"(等级: {p.get('level', 0)}) "
+                        f"[延迟: {p.get('ping', 0.0):.1f}ms]"
+                    )
+                await pal_cmd.finish("\n".join(lines))
+
+        elif action == "say":
+            if len(args) < 2:
+                await pal_cmd.finish("格式错误：/pw say <消息内容>")
+            message = " ".join(args[1:])
+            await api.announce(message)
+            await pal_cmd.finish(f"已广播公告：\n「{message}」")
+
+        elif action == "kick":
+            if len(args) < 2:
+                await pal_cmd.finish("格式错误：/pw kick <玩家名/PlayerID/SteamID> [原因]")
+            target = args[1]
+            reason = args[2] if len(args) > 2 else "Kicked by Admin"
+
+            players = await api.get_players()
+            userid = None
+            target_name = target
+            for p in players:
+                p_name = p.get("name", "")
+                p_pid = p.get("playerId", "")
+                p_uid = p.get("userId", "")
+                if target.lower() in (p_name.lower(), p_pid.lower(), p_uid.lower()):
+                    userid = p_uid
+                    target_name = p_name
+                    break
+
+            if not userid:
+                if target.startswith("steam_") or target.isdigit():
+                    userid = target
+                else:
+                    await pal_cmd.finish(f"未在在线列表中找到玩家「{target}」，且其不符合 SteamID 格式。")
+
+            await api.kick(userid, reason)
+            await pal_cmd.finish(f"成功踢出玩家「{target_name}」(SteamID: {userid})，原因: {reason}")
+
+        elif action == "ban":
+            if len(args) < 2:
+                await pal_cmd.finish("格式错误：/pw ban <玩家名/PlayerID/SteamID> [原因]")
+            target = args[1]
+            reason = args[2] if len(args) > 2 else "Banned by Admin"
+
+            players = await api.get_players()
+            userid = None
+            target_name = target
+            for p in players:
+                p_name = p.get("name", "")
+                p_pid = p.get("playerId", "")
+                p_uid = p.get("userId", "")
+                if target.lower() in (p_name.lower(), p_pid.lower(), p_uid.lower()):
+                    userid = p_uid
+                    target_name = p_name
+                    break
+
+            if not userid:
+                if target.startswith("steam_") or target.isdigit():
+                    userid = target
+                else:
+                    await pal_cmd.finish(f"未在在线列表中找到玩家「{target}」，且其不符合 SteamID 格式。")
+
+            await api.ban(userid, reason)
+            await pal_cmd.finish(f"成功封禁玩家「{target_name}」(SteamID: {userid})，原因: {reason}")
+
+        elif action == "unban":
+            if len(args) < 2:
+                await pal_cmd.finish("格式错误：/pw unban <SteamID>")
+            userid = args[1]
+            if not (userid.startswith("steam_") or userid.isdigit()):
+                await pal_cmd.finish("解封错误：解封必须提供有效的 SteamID (如 steam_00000000000000000)")
+            await api.unban(userid)
+            await pal_cmd.finish(f"成功解封玩家 (SteamID: {userid})。")
+
+        elif action == "save":
+            await api.save()
+            await pal_cmd.finish("世界存档保存成功。")
+
+        elif action == "shutdown":
+            waittime = 60
+            message = "Server is shutting down for maintenance."
+            is_force = False
+
+            if len(args) > 1:
+                first_arg = args[1].lower()
+                if first_arg in ("force", "0"):
+                    is_force = True
+                else:
+                    try:
+                        waittime = int(first_arg)
+                    except ValueError:
+                        message = " ".join(args[1:])
+                    else:
+                        if len(args) > 2:
+                            message = " ".join(args[2:])
+
+            if is_force:
+                await api.stop()
+                await pal_cmd.finish("已发送强制关闭指令。")
+            else:
+                await api.shutdown(waittime, message)
+                await pal_cmd.finish(f"已发送优雅关机指令：将在 {waittime} 秒后关闭，公告: 「{message}」")
+
+    except PalWorldAPIError as e:
+        await pal_cmd.finish(f"操作失败：{e}")
+
+
+# 转发 QQ 群消息至帕鲁服务器
+group_forward = on_message(priority=100, block=False)
+
+
+@group_forward.handle()
+async def handle_forward(bot: Bot, event: GroupMessageEvent):
+    if not pal_config.palworld_forward_group_msg:
+        return
+
+    # 仅在配置的帕鲁群内转发消息
+    if not isinstance(event, GroupMessageEvent) or str(event.group_id) not in pal_config.palworld_qq_groups:
+        return
+
+    text = event.get_plaintext().strip()
+    if not text or text.startswith(("/", "pw")):
+        return
+
+    sender_name = event.sender.card or event.sender.nickname or str(event.user_id)
+    forward_text = f"[QQ] {sender_name}: {text}"
+
+    try:
+        await api.announce(forward_text)
+    except Exception:
+        pass

nonebot_plugin_palworld_sync/api.py

@@ -0,0 +1,79 @@
+import httpx
+from typing import Any, Dict, List
+
+
+class PalWorldAPIError(Exception):
+    """API 基础异常类"""
+    pass
+
+
+class PalWorldAPI:
+    def __init__(self, base_url: str, password: str):
+        self.base_url = base_url.rstrip("/")
+        self.auth = httpx.BasicAuth("admin", password)
+        self.timeout = 10.0
+
+    async def _request(self, method: str, path: str, **kwargs) -> httpx.Response:
+        """发送 API 请求并进行统一异常封装"""
+        try:
+            async with httpx.AsyncClient(auth=self.auth, timeout=self.timeout) as client:
+                url = f"{self.base_url}{path}"
+                response = await client.request(method, url, **kwargs)
+                response.raise_for_status()
+                return response
+        except httpx.HTTPStatusError as e:
+            if e.response.status_code == 401:
+                raise PalWorldAPIError("认证失败：管理员密码错误")
+            raise PalWorldAPIError(f"HTTP 请求失败：状态码 {e.response.status_code}")
+        except httpx.RequestError as e:
+            raise PalWorldAPIError(f"网络连接错误：无法连接到帕鲁服务器 ({e})")
+        except Exception as e:
+            raise PalWorldAPIError(f"请求异常：{e}")
+
+    async def get_info(self) -> Dict[str, Any]:
+        """获取服务器信息"""
+        res = await self._request("GET", "/v1/api/info")
+        return res.json()
+
+    async def get_players(self) -> List[Dict[str, Any]]:
+        """获取在线玩家列表"""
+        res = await self._request("GET", "/v1/api/players")
+        return res.json().get("players", [])
+
+    async def get_settings(self) -> Dict[str, Any]:
+        """获取服务器设置"""
+        res = await self._request("GET", "/v1/api/settings")
+        return res.json()
+
+    async def get_metrics(self) -> Dict[str, Any]:
+        """获取服务器指标"""
+        res = await self._request("GET", "/v1/api/metrics")
+        return res.json()
+
+    async def announce(self, message: str) -> None:
+        """发送公告"""
+        await self._request("POST", "/v1/api/announce", json={"message": message})
+
+    async def kick(self, userid: str, message: str = "") -> None:
+        """踢出玩家"""
+        await self._request("POST", "/v1/api/kick", json={"userid": userid, "message": message})
+
+    async def ban(self, userid: str, message: str = "") -> None:
+        """封禁玩家"""
+        await self._request("POST", "/v1/api/ban", json={"userid": userid, "message": message})
+
+    async def unban(self, userid: str) -> None:
+        """解封玩家"""
+        await self._request("POST", "/v1/api/unban", json={"userid": userid})
+
+    async def save(self) -> None:
+        """保存存档"""
+        await self._request("POST", "/v1/api/save")
+
+    async def shutdown(self, waittime: int, message: str = "") -> None:
+        """优雅关闭服务器"""
+        await self._request("POST", "/v1/api/shutdown", json={"waittime": waittime, "message": message})
+
+    async def stop(self) -> None:
+        """强行关闭服务器"""
+        await self._request("POST", "/v1/api/stop")

nonebot_plugin_palworld_sync/config.py

@@ -0,0 +1,9 @@
+from pydantic import BaseModel
+from typing import List
+
+
+class Config(BaseModel):
+    palworld_api_url: str = "http://127.0.0.1:8212"
+    palworld_api_password: str = ""
+    palworld_forward_group_msg: bool = False
+    palworld_qq_groups: List[str] = []

nonebot_plugin_palworld_sync-0.1.0.dist-info/METADATA

@@ -0,0 +1,92 @@
+Metadata-Version: 2.4
+Name: nonebot-plugin-palworld-sync
+Version: 0.1.0
+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. 插件配置
+
+### 幻兽帕鲁服务端配置 (PalWorldSettings.ini)
+```ini
+RESTAPIEnabled=True,RESTAPIPort=8212,AdminPassword="您的管理员密码"
+```
+
+### Nonebot 环境变量配置 (.env)
+```env
+PALWORLD_API_URL="http://<服务器IP>:8212"
+PALWORLD_API_PASSWORD="您的管理员密码"
+PALWORLD_QQ_GROUPS=["123456", "789012"]  # 必填：本插件生效的 QQ 群号列表（JSON 数组格式），非列表内的群不响应任何指令
+PALWORLD_FORWARD_GROUP_MSG=True  # 可选：设置为 True 即可开启 QQ 群消息互通转发至游戏内，默认 False
+```
+
+---
+
+## 2. 指令一览
+
+### 公共指令
+
+| 指令 | 参数要求 | 功能描述 |
+| :--- | :--- | :--- |
+| /pw status | 无 | 查看服务器状态 (版本、FPS、在线人数、核心设置等) |
+| /pw players [目标] | [目标]: 选填 (名字/PlayerID/SteamID) | 查看在线玩家简表，若指定目标则返回其详细状态 |
+
+### 管理员指令 (限超级用户、群主、群管理员)
+
+| 指令 | 参数要求 | 功能描述 |
+| :--- | :--- | :--- |
+| /pw say <msg> | <msg>: 消息内容 | 发送全局广播消息 |
+| /pw kick <target> [reason] | <target>: 名字/PlayerID/SteamID<br>[reason]: 可空 | 踢出指定玩家 (支持在线玩家名字模糊匹配) |
+| /pw ban <target> [reason] | <target>: 名字/PlayerID/SteamID<br>[reason]: 可空 | 封禁指定玩家 (支持在线玩家名字模糊匹配) |
+| /pw unban <steam_id> | <steam_id>: SteamID | 解封指定的玩家 |
+| /pw save | 无 | 保存当前游戏世界的存盘 |
+| /pw shutdown [秒/force] [msg] | [秒/force]: 秒数或 force 强制关闭<br>[msg]: 可空 | 关闭服务器 (优雅关机或强关合并) |
+

nonebot_plugin_palworld_sync-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+nonebot_plugin_palworld_sync/__init__.py,sha256=UFI6Q3gEoyFb9Qaqvtgr92kqokpv11DzpZbKLag-kQ8,12491
+nonebot_plugin_palworld_sync/api.py,sha256=nocXC78-eMnBa0esK0LALm6CUA41NBu8lHYPjsptTUE,3122
+nonebot_plugin_palworld_sync/config.py,sha256=iHf_5mTThCbklzu7YBQEf8s5LHJfoDkAkaIvY7UK-yU,254
+nonebot_plugin_palworld_sync-0.1.0.dist-info/METADATA,sha256=z5o2vPOdUDjxb5IWX4Obh85G6wPYxi5QORmIfHQtOI4,3707
+nonebot_plugin_palworld_sync-0.1.0.dist-info/WHEEL,sha256=EGEvSphFYqXKs23-kQBeyNoJP1nrT8ZJKQoi5p5DYL8,88
+nonebot_plugin_palworld_sync-0.1.0.dist-info/RECORD,,

nonebot_plugin_palworld_sync-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.4.0
+Root-Is-Purelib: true
+Tag: py3-none-any