HolyWhitelistPerm

HolyWhitelistPerm User Guide

This guide is intended for server owners, admins, and moderators who want to install and use `HolyWhitelistPerm` on a Paper or Folia server.

What the Plugin Does

`HolyWhitelistPerm` works like a permission-based whitelist.

Players can only join your server when at least one of the following is true:

- they have the configured join permission - they are OP and `allow-ops` is enabled in the config

This lets you control server access with your permission system instead of the vanilla whitelist.

The plugin also supports Folia.

Installation

1. Put the plugin JAR into your server's `plugins/` folder. 2. Start the server once. 3. Open `plugins/HolyWhitelistPerm/config.yml`. 4. Adjust the permission name or messages if needed. 5. Restart the server or use the reload command.

The same setup works on Folia servers.

Default Join Permission

By default, the plugin checks for:

```text holywhitelist.join ```

Only players with this permission can join.

Recommended Setup

If you use a permission plugin such as LuckPerms, create one group that is allowed to join and grant the permission there.

Example with LuckPerms:

```bash /lp group default permission set holywhitelist.join false /lp group member permission set holywhitelist.join true ```

You can also change the permission name in `config.yml` if you want to use a different node.

Configuration Overview

Example configuration:

```yaml settings: required-permission: "holywhitelist.join" allow-ops: true

format: prefix: "<gradient:#148217:#6F32A8><bold>HolyWhitelist</bold></gradient><dark_gray>»</dark_gray><white> "

messages: kick-no-permission: "<gray>You do not have permission to join this server!" reload-success: "<green>Configuration reloaded successfully." reload-no-permission: "<red>You do not have permission to use this command." reload-usage: "<yellow>Usage: /holywhitelistperm reload" ```

`settings.required-permission`

The permission node a player needs to join.

`settings.allow-ops`

If set to `true`, server operators can always join even without the permission.

`format.prefix`

This prefix is added in front of player-facing messages.

`messages.*`

All player-visible and console messages can be changed here.

MiniMessage Support

Player messages support MiniMessage formatting.

Example:

```yaml messages: kick-no-permission: "<red><bold>Access denied!</bold></red> <gray>You need <permission>." ```

Supported placeholders:

- `<player>` - `<permission>`

Commands

Reload the Config

```text /holywhitelistperm reload ```

Aliases:

```text /holywhitelist reload /hwp reload ```

Required permission:

```text holywhitelist.reload ```

This reloads `config.yml` without restarting the server.

Permissions

Join Permission

```text holywhitelist.join ```

Grants access to the server.

Reload Permission

```text holywhitelist.reload ```

Allows use of the reload command.

Common Use Cases

Private Server Access

Grant `holywhitelist.join` only to your internal member group.

Staff-Only Development Server

Grant the permission only to staff members and leave `allow-ops` enabled.

Temporary Closed Server

Remove the join permission from normal groups until maintenance is finished.

Troubleshooting

Players cannot join even though they should

Check the following:

- the player really has the configured permission - the permission name in `config.yml` matches your permission setup - the player is OP if you rely on `allow-ops: true` - the server was restarted or the config was reloaded after changes

The reload command does not work

Check the following:

- you used `/holywhitelistperm reload` - you have the `holywhitelist.reload` permission - there are no syntax errors in `config.yml`

Messages look wrong

If you use MiniMessage formatting, make sure all tags are valid and properly closed.

Summary

`HolyWhitelistPerm` is meant to be simple:

- one permission controls access - OP support is optional - all messages are configurable - config changes can be applied with a reload command