SpyWebSocket

📡 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.