monban is a whitelist, access-control, and permissions plugin with explicit ONLINE and OFFLINE player identities. It supports standalone Bukkit/Spigot and Paper/Folia servers, and can act as the central access authority for a Velocity network with player groups, scoped backend access, and synchronized backend permissions.

Supported platforms

Platform	Deployment	Global whitelist	Player permissions	Scoped backend access	Hybrid auth
Bukkit / Spigot	Standalone or backend	✓	✓	—	—
Paper / Folia	Standalone or backend	✓	✓	—	—
Velocity	Network authority	✓	✓	✓	✓

The Paper/Folia artifact is a Paper plugin and is separate from the Bukkit/Spigot compatibility artifact. Hybrid authentication-flow selection belongs to Velocity; the Paper/Folia plugin does not implement deployment.mode: VELOCITY.

Features

• Explicit ONLINE and OFFLINE identities instead of inferring trust from the presence of a UUID.
• Player groups separate from Velocity SERVER_GROUP definitions.
• Group and direct player permissions for proxy and backend plugins.
• NETWORK, SERVER_GROUP, and SERVER scopes for access rules and permissions.
• Group access grants for individual backend servers and server groups.
• One /monban whitelist administration model across supported platforms.
• Runtime /monban whitelist enable and /monban whitelist disable.
• Automatic ONLINE profile lookup by player name, with explicit UUID input still available.
• Interactive whitelist and scoped-access lists with pagination and filter-preserving navigation.
• Network-wide whitelist enforcement on Velocity.
• Per-backend OPEN and GRANT_REQUIRED access policies.
• /monban lookup <player> on Velocity for identity and whitelist status details.
• /monban status on Velocity for a runtime access summary.
• Effective access inspection with group and direct-grant origins.
• Optional Velocity hybrid ONLINE / OFFLINE authentication-flow selection.
• Centralized Velocity state synchronization to Bukkit and Paper backends.
• Local backend permissions without requiring LuckPerms.
• Permission-aware command help and backend command-tree refresh after permission updates.
• Native Folia-compatible scheduling at the Paper platform boundary.
• Strict, versioned YAML configuration and persistent access state.
• Fail-closed startup and access verification for security-sensitive initialization failures.

Requirements

monban plugin bytecode targets Java 21. Server runtime requirements are platform/version-specific; in particular, Paper 26.1+ requires Java 25 to run.

Install

1. Download the build for your platform from Modrinth or GitHub Releases.
2. Put the JAR in the platform's plugins/ directory.
3. For standalone Bukkit/Spigot or Paper/Folia, set the native Minecraft whitelist to white-list=false.
4. Start the server once, configure plugins/monban/config.yml, then restart.
5. Manage access with /monban whitelist .... Velocity additionally provides /monban access ..., /monban lookup ..., /monban group ..., /monban user ..., and /monban status.

Do not install multiple monban platform builds on the same server.

Standalone servers

For standalone servers, monban is the whitelist authority. Disable the native whitelist in server.properties:

white-list=false

The whitelist can be changed at runtime:

/monban whitelist enable
/monban whitelist disable

For automatic ONLINE profile resolution, use:

/monban whitelist add online <name>

Explicit UUID input remains available with /monban whitelist add online <name> <uuid> and bypasses profile lookup.

Velocity networks

Velocity is the central authority for the network whitelist, backend access, groups, and permissions. Install monban-velocity on Velocity and the matching Bukkit/Spigot or Paper/Folia build on every backend that should apply synchronized permissions.

Enable backend permissions on Velocity:

backend-permissions:
  enabled: true

Velocity creates plugins/monban/sync.yml automatically. Copy the generated file with the same contents to every enabled backend. Do not copy state-revision to backends.

Enable backend permissions in the backend's config.yml and set server-name to the exact registered server name from Velocity:

backend-permissions:
  enabled: true
  server-name: lobby

The backend creates server-groups.yml automatically. Matching server-group mappings are only needed when SERVER_GROUP permissions or access grants are used.

In centralized mode, whitelist, group, and permission administration is performed on Velocity. Backend servers do not manage a separate local monban state, preventing different whitelists or permissions on different servers.

Example backend permission setup using Chunky:

monban group create moderator
monban group moderator access grant server lobby
monban group moderator permission add server lobby chunky.command.start
monban group moderator permission add server lobby chunky.command.cancel
monban user hanamuramiyu offline group add moderator

Reconnect the player and check /chunky tab completion, then run /chunky start or /chunky cancel as appropriate.

Documentation

Full setup, configuration, commands, storage, permissions, backend synchronization, and hybrid authentication documentation is available at monban.miyu.pw.

License

monban is licensed under the Mozilla Public License 2.0.