? SpyWebSocket
SpyWebSocket 是一个轻量级的 Paper 插件,它提供了一个安全的 WebSocket API,用于远程与 Minecraft 服务器进行交互。
它允许外部程序(如 Python 脚本、机器人或自动化工具)通过结构化的 JSON 消息进行身份验证、执行控制台命令并实时获取玩家数据。
该插件专为本地或受信任的网络环境设计,注重简洁性、灵活性和线程安全。
✨ 功能特性
? 身份验证系统
客户端在访问任何功能前必须进行身份验证。
? 内置 WebSocket 服务器
无需代理或外部服务。
? 线程安全的命令执行
所有命令均在 Minecraft 主线程上分发执行。
? 实时玩家坐标 API
获取所有在线玩家的所在世界和位置数据。
⚙️ 完全可配置
主机、端口、用户名和密码均可通过 config.yml 进行配置。
? 基于 JSON 的协议
简单且易于人类阅读的消息格式,便于集成。
⚙️ 配置文件 (config.yml)
websocket:
host: 127.0.0.1
port: 8765
username: admin
password: strongpassword
⚠️ 安全警告:
请将服务器绑定到 127.0.0.1 或使用防火墙进行保护。
此插件允许远程执行控制台命令。
? 身份验证
在使用任何其他操作之前,客户端必须先进行身份验证。
➤ 请求
{
"type": "auth",
"username": "admin",
"password": "strongpassword"
}
➤ 成功响应
{
"type": "auth_ok"
}
➤ 失败响应
{
"type": "auth_fail"
}
? 执行控制台命令
以服务器控制台的身份执行命令。
➤ 请求
{
"type": "command",
"command": "say Hello from WebSocket"
}
命令将在服务器主线程上安全地执行。
? 获取在线玩家坐标
返回所有在线玩家的位置和世界数据。
➤ 请求
{
"type": "get_players"
}
➤ 响应
{
"type": "players",
"players": {
"Notch": {
"x": 123.45,
"y": 64.0,
"z": -98.32,
"world": "world"
},
"Steve": {
"x": -20.0,
"y": 70.0,
"z": 45.1,
"world": "world_nether"
}
}
}
❌ 错误响应
如果请求无效或未授权,服务器将响应:
{
"type": "error",
"reason": "not_authenticated"
}
常见错误原因:
invalid_json
missing_type
unknown_type
not_authenticated
? 使用场景
Python 控制的 Minecraft 自动化
管理面板或监控工具
Twitch / 聊天集成
实时覆盖层或外部 UI
自定义审核工具
?️ 安全须知
只有经过身份验证的客户端才能发出命令或访问数据
仅适用于受信任的环境
不建议在没有额外保护的情况下用于面向公众的服务器
? 兼容性
平台:Paper
Minecraft 版本:1.21+
Java 版本:21
依赖处理:Shaded(Shadow JAR)
⚠️ 免责声明
此插件允许远程执行服务器控制台命令。
请负责任地使用,并且仅在你信任的服务器上部署。
? SpyWebSocket
SpyWebSocket is a lightweight Paper plugin that exposes a secure WebSocket API for remotely interacting with a Minecraft server.
It allows external programs (such as Python scripts, bots, or automation tools) to authenticate, execute console commands, and retrieve live player data in real time using structured JSON messages.
This plugin is designed for local or trusted network usage and focuses on simplicity, flexibility, and thread safety.
✨ Features
? Authentication system
Clients must authenticate before accessing any functionality.
? Built-in WebSocket server
No proxies or external services required.
? Thread-safe command execution
All commands are dispatched on the Minecraft main thread.
? Live player coordinates API
Retrieve world and position data for all online players.
⚙️ Fully configurable
Host, port, username, and password are configurable via config.yml.
? JSON-based protocol
Simple, human-readable messages for easy integration.
⚙️ Configuration (config.yml)
websocket:
host: 127.0.0.1
port: 8765
username: admin
password: strongpassword
⚠️ Security warning:
Keep the server bound to 127.0.0.1 or protect it with a firewall.
This plugin allows remote console command execution.
? Authentication
Clients must authenticate first before using any other action.
➤ Request
{
"type": "auth",
"username": "admin",
"password": "strongpassword"
}
➤ Success Response
{
"type": "auth_ok"
}
➤ Failure Response
{
"type": "auth_fail"
}
? Execute Console Commands
Executes a command as the server console.
➤ Request
{
"type": "command",
"command": "say Hello from WebSocket"
}
Commands are executed safely on the main server thread.
? Get Online Player Coordinates
Returns position and world data for all online players.
➤ Request
{
"type": "get_players"
}
➤ Response
{
"type": "players",
"players": {
"Notch": {
"x": 123.45,
"y": 64.0,
"z": -98.32,
"world": "world"
},
"Steve": {
"x": -20.0,
"y": 70.0,
"z": 45.1,
"world": "world_nether"
}
}
}
❌ Error Responses
If a request is invalid or unauthorized, the server responds with:
{
"type": "error",
"reason": "not_authenticated"
}
Common error reasons:
invalid_json
missing_type
unknown_type
not_authenticated
? Use Cases
Python-controlled Minecraft automation
Admin dashboards or monitoring tools
Twitch / chat integrations
Live overlays or external UIs
Custom moderation tools
?️ Security Notes
Only authenticated clients can issue commands or access data
Intended for trusted environments
Not recommended for public-facing servers without additional protection
? Compatibility
Platform: Paper
Minecraft version: 1.21+
Java version: 21
Dependency handling: Shaded (Shadow JAR)
⚠️ Disclaimer
This plugin enables remote execution of server console commands.
Use responsibly and only on servers you trust.
评论 0
登录后参与评分
还没有评论,来抢沙发吧