Fssentials is a production-ready moderation and administration utilities plugin for Paper with Folia-aware scheduling. It combines a persistent punishment system, IP locking, maintenance tools, announcements, vanish, inventory management, configurable messages, and Folia-safe task handling into a single server administration toolkit.
Features
| Feature |
Description |
| Complete Punishment System |
Kick, ban, mute, warn, note, IP-ban, temporary punishments, history, pagination, silent actions, and reason editing |
| Persistent Punishments |
Stores punishment records in punishments.yml when persistence is enabled |
| IP Locking |
Lock accounts to allowed IP addresses with login blocking, management commands, logging, and bypass support |
| Maintenance Mode |
Whitelist, MOTD sets, scheduled start/end timers, join notifications, and configurable permissions |
| Broadcast System |
Send MiniMessage full-screen titles and subtitles with optional configurable sounds |
| Vanish |
Hide staff members and protect vanished administrators from interactions and damage |
| InvSee |
View and edit player inventories through a 54-slot Folia-safe GUI |
| Configurable Messages |
Central MessageService with prefixes, placeholders, and configurable enforcement messages |
| Folia Scheduler |
Centralized async, global, and entity scheduler dispatch |
| Async Operations |
File I/O and long-running work are dispatched asynchronously |
| YAML Configuration |
Uses dedicated files for punishments, IP locks, and messages |
| Admin Utilities |
Includes system preferences, offline teleport, player lists, reload tools, and punishment management |
Punishment System
Fssentials includes a complete punishment system designed for day-to-day server moderation.
Supported punishment types:
KICKBANMUTEWARNNOTEIP_BAN
Permanent and temporary punishments are supported.
Temporary durations are parsed through TimeParser, including configurable time-layout tokens such as #default.
Each punishment stores:
- ID
- Type
- Target UUID, name, or IP
- Actor
- Reason
- Creation time
- Expiration time
- Active state
- Silent state
Punishment Management
Moderators can:
- Create punishments
- Deactivate punishments
- Change punishment reasons
- Delete records
- List punishment history
- View active punishments
- Browse paginated punishment records
When storage.persistence-enabled is enabled, punishment data is stored in:
punishments.yml
Temporary punishment expiration runs through the Folia async scheduler and can notify staff when a punishment expires.
Punishment Commands
| Command |
Description |
kick <player> <reason...> |
Immediately kick a player with the configured enforcement message |
ban <player> <reason...> |
Permanently ban a player and kick them if online |
mute <player> <reason...> |
Mute a player and block their chat |
warn <player> <reason...> |
Add a warning record and notify the target when online |
note <player> <note...> |
Add an internal moderation note |
banip <player|ip> <reason...> |
Ban an IP and kick matching online players |
tempban <player> <duration> <reason...> |
Temporarily ban a player |
tempmute <player> <duration> <reason...> |
Temporarily mute a player |
tempwarn <player> <duration> <reason...> |
Create a temporary warning |
tempipban <player|ip> <duration> <reason...> |
Temporarily ban an IP |
unban <id|player> |
Remove a ban |
unmute <id|player> |
Remove a mute |
unwarn <id|player> |
Remove a warning |
unnote <id|player> |
Remove a note |
unpunish <id|player> |
Remove a punishment |
change-reason <id> <new reason> |
Edit an existing punishment reason |
warns <player> |
List a player's warnings |
notes <player> |
List a player's notes |
check <player> |
Display UUID, IP, ban/mute status, and punishment counts |
banlist [page] |
Display active bans with pagination |
history <player> [page] |
Display a player's punishment history |
Commands support a -s prefix for silent actions.
Silent punishments are announced only to staff members with the configured silent-notification permission.
Reason layouts can be referenced using:
@layoutKey
Time-layout tokens such as:
#default
can map to configured values under time-layouts.
IP Locking
Fssentials includes per-account IP locking stored in:
ip-locks.yml
Administrators can:
- Set an allowed IP
- Remove an allowed IP
- Change an allowed IP
- Check an account's configured IP
IP addresses are normalized using Java networking APIs and invalid inputs are rejected.
During login, the attempted IP is collected and checked against the account's allowed IP.
If the address does not match, login is blocked unless the player has the configured bypass permission.
Configurable options include:
ip-lock.enabledip-lock.log-blocked-attemptsip-lock.kick-message
Default bypass permission used by the IP lock manager:
plugin.iplock.bypass
Maintenance Mode
Fssentials provides a complete maintenance subsystem for safely restricting server access.
Features include:
- Enable and disable maintenance
- Maintenance whitelist
- Multiple MOTD sets
- Scheduled maintenance
- Start timers
- End timers
- Automatic maintenance duration
- Timer cancellation
- Join-attempt notifications for staff
- Configurable bypass permissions
- Configurable notification permissions
Maintenance Commands
| Command |
Description |
maintenance on |
Enable maintenance mode |
maintenance off |
Disable maintenance mode |
maintenance reload |
Reload maintenance configuration |
maintenance add <player> |
Add a player to the maintenance whitelist |
maintenance remove <player> |
Remove a player from the whitelist |
maintenance whitelist |
View the maintenance whitelist |
maintenance starttimer <minutes> |
Schedule maintenance to start |
maintenance endtimer <minutes> |
Schedule maintenance to end |
maintenance schedule <startMinutes> <durationMinutes> |
Schedule a complete maintenance window |
maintenance aborttimer |
Cancel the active maintenance timer |
maintenance motd |
Manage maintenance MOTD sets |
maintenance setmotd <index> <line> <message> |
Edit a maintenance MOTD line |
Broadcast & Announcements
Use:
/broadcast <title> [subtitle]
to send a full-screen announcement to all players.
Broadcasts support:
- MiniMessage formatting
- Titles
- Subtitles
| title/subtitle splitting- Configurable announcement sounds
Sound settings are configured under:
announcements.sound.*
Vanish & Admin Protection
Staff members can toggle vanish using:
/vanish
VanishService manages player visibility.
While vanished, AdminToolsListener protects staff from being interacted with or damaged.
Vanish state is reapplied when session-owned vanished players rejoin.
InvSee
Use:
/invsee <player>
to open a 54-slot inventory GUI containing a snapshot of the target player's inventory.
The system is Folia-safe:
- Inventory cloning runs on the target player's entity scheduler
- GUI opening runs on the viewer's entity scheduler
- Viewer changes are written back when the interface closes
The GUI supports editing:
- Player storage
- Armor
- Off-hand slot
Message Service
MessageService loads configurable messages from:
messages.yml
Messages support:
- Configurable prefix
- Placeholder replacement
- Error messages
- Usage messages
- Enforcement messages
The file is copied from the plugin jar into the plugin data folder on first run.
Folia Scheduler
FoliaScheduler centralizes Folia-friendly task dispatch.
Supported scheduler utilities include:
runAsyncrunAsyncTimerrunGlobalrunAtEntity
File I/O and long-running operations are dispatched asynchronously, while player-specific operations run through the appropriate player's entity scheduler.
Storage
Fssentials creates or uses the following files:
| File |
Purpose |
punishments.yml |
Persistent punishment records through YamlPunishmentStorage |
ip-locks.yml |
Per-account IP lock entries |
messages.yml |
Configurable plugin messages loaded by MessageService |
Complete Command List
Commands registered by the current implementation include:
kickbanmutewarnnotebaniptempbantempmutetempwarntempipbanunbanunmuteunwarnunnoteunpunishchange-reasonwarnsnotescheckbanlisthistoryfssentialssystemprefsvanishofflinetpplayerlistpunishmentinvseemaintenancebroadcastiplock
Refer to plugin.yml for exact command help and usage lines.
The fssentials command prints configurable help lines from config.yml.
Permissions
| Permission |
Purpose |
fssentials.punish.kick |
Kick players |
fssentials.punish.ban |
Permanently ban players |
fssentials.punish.tempban |
Temporarily ban players |
fssentials.punish.mute |
Mute players |
fssentials.punish.tempmute |
Temporarily mute players |
fssentials.punish.warn |
Warn players |
fssentials.punish.tempwarn |
Temporarily warn players |
fssentials.punish.banip |
IP-ban players |
fssentials.punish.tempipban |
Temporarily IP-ban players |
fssentials.punish.unpunish |
Remove punishments |
fssentials.punish.change-reason |
Edit punishment reasons |
fssentials.view.banlist |
View active bans |
fssentials.view.history |
View punishment history |
fssentials.view.check |
View player moderation information |
fssentials.view.playerlist |
View player lists |
fssentials.invsee |
View and edit player inventories |
fssentials.vanish |
Toggle vanish |
fssentials.admin.reload |
Reload the plugin |
fssentials.admin.systemprefs |
View system preferences |
fssentials.maintenance.admin |
Full maintenance administration |
plugin.iplock.bypass |
Bypass account IP locking |
Maintenance bypass and notification permissions are configurable through MaintenanceConfig.
Why Choose Fssentials?
- Complete Moderation Suite — Manage kicks, bans, mutes, warnings, notes, IP bans, and temporary punishments from one plugin.
- Folia-Aware Architecture — Uses dedicated async, global, and entity scheduler utilities.
- Persistent Records — Keep punishment history available through YAML-backed storage.
- Account Protection — IP locking can restrict accounts to approved addresses.
- Maintenance Management — Schedule maintenance windows, manage whitelists, and customize MOTDs.
- Staff Utilities — Vanish, InvSee, offline teleport, player lists, and system tools are available in one package.
- Configurable Communication — Messages, prefixes, placeholders, layouts, announcements, and sounds can be customized.
- Admin-Friendly Design — Extensive commands and permissions provide granular control over moderation workflows.
- Paper & Folia Focused — Designed for modern server environments with Folia-aware task handling.
Compatibility
- Paper
- Folia-aware server environments
Requirements
Fssentials requires a supported Paper server environment.
Folia-aware scheduling is built into the plugin's task handling.
Community & Support
If you encounter a bug or have a feature request, please join the Discord community or report it through the appropriate project page.
