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:

• KICK
• BAN
• MUTE
• WARN
• NOTE
• IP_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...>`
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...>`
`unban <id	player>`
`unmute <id	player>`
`unwarn <id	player>`
`unnote <id	player>`
`unpunish <id	player>`
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.enabled
• ip-lock.log-blocked-attempts
• ip-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:

• runAsync
• runAsyncTimer
• runGlobal
• runAtEntity

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:

• kick
• ban
• mute
• warn
• note
• banip
• tempban
• tempmute
• tempwarn
• tempipban
• unban
• unmute
• unwarn
• unnote
• unpunish
• change-reason
• warns
• notes
• check
• banlist
• history
• fssentials
• systemprefs
• vanish
• offlinetp
• playerlist
• punishment
• invsee
• maintenance
• broadcast
• iplock

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?

1. Complete Moderation Suite — Manage kicks, bans, mutes, warnings, notes, IP bans, and temporary punishments from one plugin.
2. Folia-Aware Architecture — Uses dedicated async, global, and entity scheduler utilities.
3. Persistent Records — Keep punishment history available through YAML-backed storage.
4. Account Protection — IP locking can restrict accounts to approved addresses.
5. Maintenance Management — Schedule maintenance windows, manage whitelists, and customize MOTDs.
6. Staff Utilities — Vanish, InvSee, offline teleport, player lists, and system tools are available in one package.
7. Configurable Communication — Messages, prefixes, placeholders, layouts, announcements, and sounds can be customized.
8. Admin-Friendly Design — Extensive commands and permissions provide granular control over moderation workflows.
9. 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

• Discord: https://discord.gg/TJc3CxR4jK
• GitHub: https://github.com/MeherBenSalem
• Website: https://nightbeam.dev
• Store: https://nightbeam.dev/store
• CurseForge: https://www.curseforge.com/members/nightbeamstudio/projects
• Modrinth: https://modrinth.com/organization/nightbeam

If you encounter a bug or have a feature request, please join the Discord community or report it through the appropriate project page.