Remote velocity whitelist

Velocity Whitelist Worker

A simple remote whitelist plugin for Velocity proxy servers.

What it does

This plugin fetches a whitelist from a remote URL and controls which players can join your Velocity proxy. The whitelist is stored in a JSON file that you host somewhere (like a CDN or web server), so you can update it without restarting the server.

Features

- Fetches whitelist from a remote URL - Username-based whitelisting - Multiple list support (admin, vip, members, etc.) - Special modes: allow everyone or deny everyone - Auto-reload from URL every few seconds - Kicks players when removed from whitelist - Customizable messages

Installation

1. Download the JAR file 2. Place it in your Velocity `plugins/` folder 3. Start the server (it will create example config files) 4. Stop the server 5. Edit `plugins/velocity-whitelist-worker/config.json` and set your URL 6. Create your whitelist JSON file at that URL 7. Start the server again

Configuration

Local config file: `config.json`

```json { "url": "https://your-domain.com/whitelist.json", "reloadIntervalSeconds": 10 } ```

- `url` - Where to fetch the whitelist from (required) - `reloadIntervalSeconds` - How often to check for updates (default: 10)

Remote whitelist file

This is the JSON file at your configured URL:

```json { "customLists": ["admin", "vip"], "admin": [ "Player1", "Player2" ], "vip": [ "Player3", "Player4" ] } ```

- `customLists` - Which lists to use (if empty or missing, everyone is allowed) - Add your own list names with player usernames

Special modes

Set `customLists` to special values:

- `["all"]` - Allow everyone - `["none"]` - Deny everyone (maintenance mode) - `[]` or missing - Allow everyone (default)

Messages file: `messages.json`

Customize the messages players see:

```json { "deniedMessage": "Sorry, You don't fit the Vibe(SMP)...", "kickedMessage": "You no longer fit the Vibe(SMP)...", "maintenanceMessage": "Don't worry, we'll be right back, just some maintenance" } ```

How it works

1. Plugin loads and reads your local config 2. Fetches the whitelist from your URL 3. Checks which mode/lists are active 4. Allows or denies players based on the whitelist 5. Automatically reloads every X seconds 6. Kicks players if they're removed from the whitelist

Examples

Allow only admins: ```json { "customLists": ["admin"], "admin": ["Admin1", "Admin2"] } ```

Allow multiple groups: ```json { "customLists": ["admin", "member"], "admin": ["Admin1"], "member": ["Player1", "Player2", "Player3"] } ```

Maintenance mode: ```json { "customLists": ["none"] } ```

Allow everyone: ```json { "customLists": ["all"] } ```

Or just leave it empty: ```json {} ```

Requirements

- Velocity 3.4.0 or higher - Java 21 or higher - A web server to host your whitelist JSON file