UltraWhitelist

UltraWhitelist is a Paper/Folia whitelist plugin with multiple named lists, JSON imports, and folia-safe enforcement.

Features

• Multi Whitelist support: Designed for multiple Lists at the same time
• Hotswapping Lists: Lists can be swapped using a single command
• Easy Import: /wl import whitelist.json xxx imports your already existing Server whitelist.json
• Enforcement: Kicks all players not on the list
• Extensive list management: Lots of commands to Create/Delete/Merge/Manage lists
• Developer friendly API: Easy plugin integration

Commands

| Command | Purpose |
|---|---|
| /wl on | Enable whitelist. |
| /wl off | Disable whitelist. |
| /wl info | Show current status. |
| /wl list | Show every whitelist. |
| /wl listplayers <list> [page] | Show player names in a list. |
| /wl find <player> | Show every list containing a player. |
| /wl create <name> | Create a list. |
| /wl delete <list> | Delete a list |
| /wl add <list\|all> <player> | Add a player to a list / all lists. |
| /wl remove <list\|all> <player> | Remove a player from a list / all lists. |
| /wl use <list> | Change the active in-use list. |
| /wl enforce [list] | Kick online players not allowed by a list. |
| /wl merge <a> <b> <new> | Merge two lists into a new list. |
| /wl addfromlist <source> <destination> | Copy new entries between lists. |
| /wl import <file.json> <list> | Import a whitelist-style JSON file. |
| /wl reload | Reload the plugin. |
| /wl help | Show command help. |

Permissions

| Permission | Purpose | Default |
|---|---|---|
| ultrawhitelist.admin | Use whitelist-management commands. | Operators |
| ultrawhitelist.bypass | Avoid /wl enforce kicks. | Operators |

Developer API

1. Add the Dependency:

Maven

<repositories>
    <repository>
        <id>lolyay-releases</id>
        <url>https://maven.lolyay.dev/releases</url>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>io.lolyay.mc</groupId>
        <artifactId>WhitelistPlugin</artifactId>
        <version>1.0.0</version>
        <scope>provided</scope>
    </dependency>
</dependencies>

Gradle (Kotlin DSL)

repositories {
    maven("https://maven.lolyay.dev/releases")
}
dependencies {
    compileOnly("io.lolyay.mc:WhitelistPlugin:1.0.0")
}

2. Depend on it:

depend: [UltraWhitelist]

3. Get the service

Everything goes through WhitelistService, reachable from the plugin instance:

import io.lolyay.mc.whitelistPlugin.WhitelistPlugin;
import io.lolyay.mc.whitelistPlugin.core.WhitelistService;

WhitelistPlugin wl = (WhitelistPlugin) Bukkit.getPluginManager().getPlugin("UltraWhitelist");
if (wl == null || wl.service() == null) return;   // not installed / not enabled yet
WhitelistService service = wl.service();

3. WhitelistService API

Global state

| Method | Description |
|---|---|
| boolean isEnabled() | Is whitelisting globally on? |
| boolean setEnabled(boolean) | Turn whitelisting on/off; returns false when unchanged. |
| String activeListName() | Name of the active (login-enforced) list, or null. |
| WhitelistList activeList() | The active list object, or null. |
| boolean setActiveList(String name) | Set the active list (null clears it); false when unchanged. |

Membership

| Method | Description |
|---|---|
| boolean isWhitelisted(UUID id, String name) | The exact check used on login. true if whitelisting is off, no active list, or the identity is on the active list (by UUID or name). |

boolean allowed = service.isWhitelisted(event.getUniqueId(), event.getName());

Lists

| Method | Description |
|---|---|
| WhitelistList getList(String name) | Case-insensitive lookup, or null. |
| Collection<WhitelistList> lists() | All lists. |
| List<String> findLists(UUID id, String name) | Sorted names of every matching list. |
| boolean createList(String name) | false if it already exists. |
| boolean deleteList(String name) | false if no such list. |

Entries

| Method | Description |
|---|---|
| boolean addUuid(String list, UUID id) | Add an entry; false when unchanged or missing. |
| boolean addName(String list, String name) | Add a name entry; false when unchanged or missing. |
| boolean removeUuid(String list, UUID id) | Remove an entry; false when unchanged or missing. |
| boolean removeName(String list, String name) | Remove an entry; false when unchanged or missing. |
| List<String> addUuidToAll(UUID) / addNameToAll(String) | Add to every list and return changed list names. |
| List<String> removeUuidFromAll(UUID) / removeNameFromAll(String) | Remove from every list and return changed list names. |
| MergeResult merge(String a, String b, String newName) | Merge two lists into a new one. |
| int addFromList(String src, String dest) | Copy entries and return the number added (-1 if missing). |

Name cache (UUID <-> name)

Entries are stored UUID-first; a persistent cache maps UUIDs to last-known names
(fed by logins, imports, and playerdb.co lookups).

| Method | Description |
|---|---|
| void cacheName(UUID id, String name) | Record/persist a UUID -> name mapping. |
| String nameFor(UUID id) | Last-known name for a UUID, or null. |
| UUID uuidForName(String name) | Cached UUID for a name (case-insensitive), or null. |

WhitelistList

| Method | Description |
|---|---|
| String name() | Display name. |
| boolean contains(UUID id, String name) | Matches by UUID or name. |
| Set<UUID> uuids() | Live UUID entries. |
| Map<String,String> names() | lower-cased name -> display name. |
| int size() | Total entry count. |

MergeResult: { OK, MISSING_A, MISSING_B, TARGET_EXISTS }.