Velocity Web API

Minecraft 版本： 1.8 1.8.1 1.8.2 1.8.3 1.8.4 1.8.5 1.8.6 1.8.7 1.8.8 1.8.9 1.9 1.9.1 1.9.2 1.9.3 1.9.4 1.10 1.10.1 1.10.2 1.11 1.11.1 1.11.2 1.12 1.12.1 1.12.2 1.13 1.13.1 1.13.2 1.14 1.14.1 1.14.2 1.14.3 1.14.4 1.15 1.15.1 1.15.2 1.16 1.16.1 1.16.2 1.16.3 1.16.4 1.16.5 1.17 1.17.1 1.18 1.18.1 1.18.2 1.19 1.19.1 1.19.2 1.19.3 1.19.4 1.20 1.20.1 1.20.2 1.20.3 1.20.4 1.20.5 1.20.6 1.21 1.21.1 1.21.2 1.21.3 1.21.4 1.21.5 1.21.6 1.21.7 1.21.8 1.21.9 1.21.10

平台： velocity

标签： utility

Velocity Web API

Lightweight HTTP API for Velocity proxies. Expose player lists, per-server counts, per-player details, etc. Ideal for websites, bots or other monitoring applications. I built it for my own uses, but it might help someone else out too.

Quick Install

• Drop the compiled plugin JAR into your Velocity plugins/ folder.
• Start (or restart) your proxy; the plugin will create its data folder and a config.cfg (if missing) in the plugin data directory.

Configuration

• The plugin creates a config.cfg in its data folder on first run. Available keys:
  • port : port the HTTP server listens on (default 25576).
  • bindAddress : interface/address to bind the HTTP server (default 0.0.0.0 to listen on all IPv4 interfaces; set to 127.0.0.1 for local-only access).
  • checkUpdates : enable automatic Hangar update checks (default true).
  • snapshotUpdates : include snapshot/unstable updates in checks (default false).
  • debugEnabled : show debug messages (logger.debug) in the proxy console when true (default false).
  • allowedOrigins : CORS allowed origins for HTTP API access (comma-separated, or for all) (default ``).

Tested With

• Velocity 3.x (expects velocity-api on the runtime classpath)

Endpoints

All JSON endpoints return Content-Type: application/json; charset=utf-8 unless otherwise noted.

• /

  • Serves the embedded index.html (browser-friendly).
  • Example URL: http://localhost:25576/

• /playerlist

  • Purpose: list connected players with basic metadata and a total count.
  • Example URL: http://localhost:25576/playerlist
  • Sample response:

    {
        "count": 2,
        "players": 
        [
            {"username":"Alice","uuid":"...","currentServer":"lobby"},
            {"username":"Bob","uuid":"...","currentServer":"minigames"}
        ]
    }

• /count

  • Purpose: return the total number of connected players.
  • Example URL: http://localhost:25576/count
  • Sample response:

    { 
      "count": 42 
    }

• /player/<username> or /player?username=<name>

  • Purpose: fetch detailed info for a connected player (exact-case lookup).
  • Example URLs:
    • http://localhost:25576/player/Notch
    • http://localhost:25576/player?username=Notch
  • Notes: returns 400 if username is missing; 404 if the player is not connected.
  • Sample response:

    {
        "username":"Notch",
        "uuid":"...",
        "currentServer":"lobby",
        "ping":42,
        "sessionDurationSeconds":360
    }

• /servers

  • Purpose: returns a mapping of server names to player counts.
  • Example URL: http://localhost:25576/servers
  • Sample response:

    { 
      "lobby": 5, 
      "minigames": 12 
    }

• /health

  • Purpose: lightweight health check for monitoring.
  • Example URL: http://localhost:25576/health
  • Sample response:

    { 
      "status": "ok" 
    }

Commands

• /vwapi reload : reloads the config.cfg from the plugin data directory and restarts the HTTP server if the port or bindAddress have changed.
• /vwapi version : prints the plugin version (from the plugin metadata).
• /vwapi debug [on|off] : toggle or explicitly set debug logging at runtime. When enabled, the plugin prints detailed debug messages and HTTP access lines to the console.
• /vwapi status : shows the current HTTP server status (running/not running), the bound host and port, and an example URL you can visit (falls back to localhost when bound to all interfaces).
• /vwapi help : prints a short help listing the available /vwapi subcommands and usage examples.

Permissions

• vwapi.admin : required to use the /vwapi commands.

Notes & Behavior

• Player lookup is exact-case and only returns connected players.
• The HTTP server binds to bindAddress; by default this is 0.0.0.0 (all interfaces). Change to 127.0.0.1 for local-only access or a specific IP if desired.
• When you change bindAddress or port and run /vwapi reload, the plugin will restart the HTTP server automatically to apply the new bind/port (a full proxy restart is no longer required for those changes).

Troubleshooting

• If the HTTP server does not start, check the proxy logs for errors about port binding or resource issues.
• Ensure velocity-api is available at runtime and that the plugin is placed in the correct plugins/ folder.

License & Support

• Licensed under the MIT License.
• If you need any help or support, please contact me on our Discord.