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

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

The same setup works on Folia servers.

Default Join Permission

By default, the plugin checks for:

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:

/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:

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:

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

Supported placeholders:

<player>
<permission>

Commands

Reload the Config

/holywhitelistperm reload

Aliases:

/holywhitelist reload
/hwp reload

Required permission:

holywhitelist.reload

This reloads config.yml without restarting the server.

Permissions

Join Permission

holywhitelist.join

Grants access to the server.

Reload Permission

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