{"id":73803,"date":"2026-06-04T10:04:37","date_gmt":"2026-06-04T07:04:37","guid":{"rendered":"https:\/\/vpesports.com\/minecraft\/mods\/fssentials\/"},"modified":"2026-06-04T10:04:37","modified_gmt":"2026-06-04T07:04:37","slug":"fssentials","status":"publish","type":"mod","link":"https:\/\/vpesports.com\/minecraft\/mods\/fssentials\/","title":{"rendered":"F-Essentials"},"content":{"rendered":"

\n \"logo\"\n<\/p>\n

\n \"Fess\"\n<\/p>\n

\n \"Fess\"\n<\/p>\n

\n

\"logo\"<\/p>\n

\n

\"Discord<\/p>\n

\"Nightbeam<\/p>\n

\"Nightbeam<\/p>\n

\"Nightbeam<\/p>\n

\"Nightbeam<\/p>\n

Fssentials is a production-ready moderation and admin utilities plugin for Paper (Folia-aware). This document enumerates every feature implemented in the current codebase so server operators can configure, use, and extend the plugin confidently.<\/p>\n

—<\/p>\n

## High-level Overview
\n– Folia-friendly scheduler utilities for safe async\/global\/entity dispatch (`FoliaScheduler`).
\n– Full-featured punishment system with persistent YAML storage and temporary punishments.
\n– IP-locking (per-account allowed IP entries + login-blocking) with admin commands and bypass permission.
\n– Maintenance subsystem with whitelist, MOTD sets, scheduling\/timers and join notifications.
\n– Broadcast\/announcement system using MiniMessage titles with optional configurable sound.
\n– Vanish and admin protections for hidden staff members.
\n– Inventory viewing and editing (InvSee) with Folia-safe snapshot\/restore behavior.
\n– Central `MessageService` for configurable chat messages and prefix handling.<\/p>\n

—<\/p>\n

## Features (exhaustive)<\/p>\n

**Punishment System**
\n– Supported punishment types: `KICK`, `BAN`, `MUTE`, `WARN`, `NOTE`, `IP_BAN`.
\n– Supports permanent and temporary punishments. Temporary durations parse via `TimeParser` and server-configurable time-layout tokens (e.g. `#default`).
\n– Each punishment stores: id, type, target UUID\/name\/ip, actor, reason, createdAt, expiresAt, active flag and silent flag.
\n– Storage: persisted to `punishments.yml` via `YamlPunishmentStorage` when `storage.persistence-enabled` is true.
\n– Management: create, deactivate (unpunish), change reason, delete record, list history, view active punishments, page helper utilities (`PunishmentManager`).
\n– Expiration: scheduled expiration runs on Folia async scheduler and notifies staff when punishments expire.<\/p>\n

Commands (handled by `CommandRouter`):
\n– `kick ` \u2014 immediate kick with enforcement message.
\n– `ban ` \u2014 permanent ban (kicks online target).
\n– `mute ` \u2014 mute (blocks chat via `PunishmentListener`).
\n– `warn ` \u2014 adds a warn record; notifies target if online.
\n– `note ` \u2014 internal note record.
\n– `banip ` \u2014 IP ban (kicks matching IPs).
\n– `tempban\/tempmute\/tempwarn\/tempipban ` \u2014 temporary punishments.
\n– `unban\/unmute\/unwarn\/unnote\/unpunish ` \u2014 remove punishments.
\n– `change-reason ` \u2014 edit a punishment’s reason.
\n– `warns ` \/ `notes ` \u2014 list warns\/notes.
\n– `check ` \u2014 show UUID, IP, ban\/mute status, counts.
\n– `banlist [page]` \u2014 list active bans (paginated).
\n– `history [page]` \u2014 view player’s punishment history (paginated).<\/p>\n

Notes:
\n– Commands support a `-s` prefix to make an action silent (announce only to staff with the configured silent notify permission).
\n– Reason layouts can be referenced with `@layoutKey` to reuse predefined layouts from `config.yml` (`layouts.`).
\n– Time-layout tokens (e.g. `#default`) map to values in `time-layouts` config.<\/p>\n

**IP Locking**
\n– Per-account IP lock storage in `ip-locks.yml` (`IpLockManager`).
\n– Admin commands to `set`, `remove`, `change`, and `check` an account’s allowed IP.
\n– Normalizes IPs using Java networking APIs; invalid inputs are rejected.
\n– Login flow hooks: pre-login collects attempted IP and if mismatch is found the player is kicked (unless they have bypass permission).
\n– Configurable: `ip-lock.enabled`, `ip-lock.log-blocked-attempts`, `ip-lock.kick-message`.<\/p>\n

**Maintenance Mode**
\n– Enable\/disable maintenance mode programmatically or via commands.
\n– Whitelist management (add\/remove\/list) for players allowed during maintenance.
\n– MOTD sets: multiple message sets supported and editable using `\/maintenance motd` and `setmotd`.
\n– Scheduling\/timers: `starttimer`, `endtimer`, `schedule`, `aborttimer` to schedule enable\/disable automatically (`MaintenanceTimer`).
\n– Join notifications: staff with `notify` permission receive join-attempt notifications during maintenance.
\n– Configurable messages and bypass\/notify permissions via `MaintenanceConfig`.<\/p>\n

Maintenance commands (via `maintenance` command):
\n– `maintenance on|off|reload`
\n– `maintenance add ` \/ `remove ` \/ `whitelist`
\n– `maintenance starttimer ` \/ `endtimer ` \/ `schedule ` \/ `aborttimer`
\n– `maintenance motd` \/ `maintenance setmotd `<\/p>\n

**Broadcast \/ Announcements**
\n– `\/broadcast [subtitle]` \u2014 sends a full-screen title to all players using MiniMessage formatting.<br \/>\n– Supports splitting title\/subtitle by `|` or heuristics; configurable sound (`announcements.sound.*` in config).<\/p>\n<p>**Vanish & Admin Tools**<br \/>\n– Toggle vanish with `\/vanish` (visibility handled by `VanishService`).<br \/>\n– `AdminToolsListener` protects vanished staff from being interacted with or damaged.<br \/>\n– Vanish state is reapplied on join for session-owned vanished players.<\/p>\n<p>**InvSee (Inventory View\/Edit)**<br \/>\n– `\/invsee <player>` opens a 54-slot GUI snapshot of the target player’s inventory (uses `InvseeInventoryHolder`).<br \/>\n– Snapshot and restore are Folia-safe: inventory cloning happens on the target’s entity scheduler and GUI open on the viewer’s entity scheduler.<br \/>\n– Viewer edits are written back on close (invsee allows editing of player storage, armor, off-hand slots as described in the GUI layout).<\/p>\n<p>**Message Service & Localization**<br \/>\n– `MessageService` loads `messages.yml` from the plugin folder; messages use a `prefix` and support placeholder replacement via `MessageService.get(key, placeholders)`.<br \/>\n– Error\/usage\/enforcement messages are all configurable in `messages.yml` and `config.yml`.<\/p>\n<p>**Folia Scheduler Compatibility**<br \/>\n– `FoliaScheduler` centralizes Folia-friendly task dispatch: `runAsync`, `runAsyncTimer`, `runGlobal`, `runAtEntity`.<br \/>\n– All file I\/O and long-running work is dispatched async; player-specific operations run on the player’s entity scheduler.<\/p>\n<p>**Storage Files Created\/Used**<br \/>\n– `punishments.yml` \u2014 persisted punishment records (via `YamlPunishmentStorage`).<br \/>\n– `ip-locks.yml` \u2014 per-account IP lock entries.<br \/>\n– `messages.yml` \u2014 plugin messages loaded by `MessageService` (copied from plugin jar to data folder on first run).<\/p>\n<p>—<\/p>\n<p>## Commands (complete list registered at runtime)<br \/>\n– `kick`, `ban`, `mute`, `warn`, `note`, `banip`<br \/>\n– `tempban`, `tempmute`, `tempwarn`, `tempipban`<br \/>\n– `unban`, `unmute`, `unwarn`, `unnote`, `unpunish`<br \/>\n– `change-reason`, `warns`, `notes`, `check`, `banlist`, `history`<br \/>\n– `fssentials`, `systemprefs`, `vanish`, `offlinetp`, `playerlist`, `punishment`, `invsee`<br \/>\n– `maintenance` (separately registered with its own executor)<br \/>\n– `broadcast`, `iplock` (separately registered)<\/p>\n<p>Refer to `plugin.yml` for the exact help\/usage lines; `fssentials` command prints configurable help-lines from `config.yml`.<\/p>\n<p>—<\/p>\n<p>## Permissions (used in code)<br \/>\n– `fssentials.punish.kick` \u2014 kick players<br \/>\n– `fssentials.punish.ban` \/ `fssentials.punish.tempban` \u2014 ban players<br \/>\n– `fssentials.punish.mute` \/ `fssentials.punish.tempmute` \u2014 mute players<br \/>\n– `fssentials.punish.warn` \/ `fssentials.punish.tempwarn` \u2014 warn players<br \/>\n– `fssentials.punish.banip` \/ `fssentials.punish.tempipban` \u2014 IP ban<br \/>\n– `fssentials.punish.unpunish` \u2014 remove punishments<br \/>\n– `fssentials.punish.change-reason` \u2014 edit punishment reason<br \/>\n– `fssentials.view.banlist` \/ `fssentials.view.history` \/ `fssentials.view.check` \/ `fssentials.view.playerlist` \u2014 view lists\/check info<br \/>\n– `fssentials.invsee` \u2014 view and edit player inventories<br \/>\n– `fssentials.vanish` \u2014 toggle vanish<br \/>\n– `fssentials.admin.reload` \u2014 reload plugin<br \/>\n– `fssentials.admin.systemprefs` \u2014 view system prefs<br \/>\n– `fssentials.maintenance.admin` \u2014 full maintenance administration<br \/>\n– maintenance bypass\/notify permissions are configurable (defaults shown in `MaintenanceConfig`).<br \/>\n– IP-locking bypass permission: `plugin.iplock.bypass` (constant in `IpLockManager`).<\/p>\n<p>Note: the plugin uses permission checks liberally; ensure your server’s permission system maps the nodes to the desired roles.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>Punishments, IPlock, maintenance mode, and much more ..<\/p>\n","protected":false},"featured_media":73804,"template":"","meta":{"_minecraft_slug":"fssentials","_minecraft_project_id":"1YpSYvSs","_minecraft_author":"NAIZO","_minecraft_license":"LicenseRef-All-Rights-Reserved","_minecraft_downloads":33,"_minecraft_follows":0,"_minecraft_client_side":"unsupported","_minecraft_server_side":"required","_minecraft_storage_type":"zip","_minecraft_archive_name":"fssentials.zip","_minecraft_size_bytes":151264,"_minecraft_version_count":2,"_minecraft_updated_at":"2026-05-15T22:10:34.183166Z","_minecraft_date_created":"2026-03-17T00:39:11.514425Z","_minecraft_date_modified":"2026-03-17T11:18:38.220507Z","_minecraft_project_url":"https:\/\/modrinth.com\/mod\/fssentials","_minecraft_icon_attachment_id":73804,"_minecraft_imported_at":"2026-06-04T07:04:38+00:00","_minecraft_import_hash":"82881474c78268917c343fa55f2c223d","_minecraft_versions":"","_minecraft_links":"","_minecraft_gallery":"","_minecraft_api_metadata":""},"mod_category":[124,88,125,126,90,127,128,129,123,92],"mod_loader":[130,131,132,133,134],"minecraft_version":[59,36,60,93,94,101,102,62,37,40,41,73,74,38,78,79,80,81,82],"class_list":["post-73803","mod","type-mod","status-publish","has-post-thumbnail","hentry","mod_category-bukkit","mod_category-equipment","mod_category-folia","mod_category-management","mod_category-optimization","mod_category-paper","mod_category-purpur","mod_category-spigot","mod_category-technology","mod_category-utility","mod_loader-bukkit","mod_loader-folia","mod_loader-paper","mod_loader-purpur","mod_loader-spigot","minecraft_version-1-20","minecraft_version-1-20-1","minecraft_version-1-20-2","minecraft_version-1-20-3","minecraft_version-1-20-4","minecraft_version-1-20-5","minecraft_version-1-20-6","minecraft_version-1-21","minecraft_version-1-21-1","minecraft_version-1-21-10","minecraft_version-1-21-11","minecraft_version-1-21-2","minecraft_version-1-21-3","minecraft_version-1-21-4","minecraft_version-1-21-5","minecraft_version-1-21-6","minecraft_version-1-21-7","minecraft_version-1-21-8","minecraft_version-1-21-9"],"yoast_head":"<!-- This site is optimized with the Yoast SEO plugin v27.6 - https:\/\/yoast.com\/product\/yoast-seo-wordpress\/ -->\n<title>F-Essentials - Minecraft<\/title>\n<meta name=\"robots\" content=\"index, follow, max-snippet:-1, max-image-preview:large, max-video-preview:-1\" \/>\n<link rel=\"canonical\" href=\"https:\/\/vpesports.com\/minecraft\/mods\/fssentials\/\" \/>\n<meta property=\"og:locale\" content=\"en_US\" \/>\n<meta property=\"og:type\" content=\"article\" \/>\n<meta property=\"og:title\" content=\"F-Essentials - Minecraft\" \/>\n<meta property=\"og:description\" content=\"Punishments, IPlock, maintenance mode, and much more ..\" \/>\n<meta property=\"og:url\" content=\"https:\/\/vpesports.com\/minecraft\/mods\/fssentials\/\" \/>\n<meta property=\"og:site_name\" content=\"Minecraft\" \/>\n<meta property=\"og:image\" content=\"https:\/\/i.imgur.com\/F4yTBhW.png\" \/>\n<meta name=\"twitter:card\" content=\"summary_large_image\" \/>\n<meta name=\"twitter:label1\" content=\"Est. reading time\" \/>\n\t<meta name=\"twitter:data1\" content=\"5 minutes\" \/>\n<script type=\"application\/ld+json\" class=\"yoast-schema-graph\">{\"@context\":\"https:\\\/\\\/schema.org\",\"@graph\":[{\"@type\":\"WebPage\",\"@id\":\"https:\\\/\\\/vpesports.com\\\/minecraft\\\/mods\\\/fssentials\\\/\",\"url\":\"https:\\\/\\\/vpesports.com\\\/minecraft\\\/mods\\\/fssentials\\\/\",\"name\":\"F-Essentials - Minecraft\",\"isPartOf\":{\"@id\":\"https:\\\/\\\/vpesports.com\\\/minecraft\\\/#website\"},\"primaryImageOfPage\":{\"@id\":\"https:\\\/\\\/vpesports.com\\\/minecraft\\\/mods\\\/fssentials\\\/#primaryimage\"},\"image\":{\"@id\":\"https:\\\/\\\/vpesports.com\\\/minecraft\\\/mods\\\/fssentials\\\/#primaryimage\"},\"thumbnailUrl\":\"https:\\\/\\\/vpesports.com\\\/minecraft\\\/wp-content\\\/uploads\\\/2026\\\/06\\\/fssentials-icon-96c3c3fbc2ef78722b8340f8896e5f4129564544_96.webp\",\"datePublished\":\"2026-06-04T07:04:37+00:00\",\"breadcrumb\":{\"@id\":\"https:\\\/\\\/vpesports.com\\\/minecraft\\\/mods\\\/fssentials\\\/#breadcrumb\"},\"inLanguage\":\"en-US\",\"potentialAction\":[{\"@type\":\"ReadAction\",\"target\":[\"https:\\\/\\\/vpesports.com\\\/minecraft\\\/mods\\\/fssentials\\\/\"]}]},{\"@type\":\"ImageObject\",\"inLanguage\":\"en-US\",\"@id\":\"https:\\\/\\\/vpesports.com\\\/minecraft\\\/mods\\\/fssentials\\\/#primaryimage\",\"url\":\"https:\\\/\\\/vpesports.com\\\/minecraft\\\/wp-content\\\/uploads\\\/2026\\\/06\\\/fssentials-icon-96c3c3fbc2ef78722b8340f8896e5f4129564544_96.webp\",\"contentUrl\":\"https:\\\/\\\/vpesports.com\\\/minecraft\\\/wp-content\\\/uploads\\\/2026\\\/06\\\/fssentials-icon-96c3c3fbc2ef78722b8340f8896e5f4129564544_96.webp\",\"width\":96,\"height\":96},{\"@type\":\"BreadcrumbList\",\"@id\":\"https:\\\/\\\/vpesports.com\\\/minecraft\\\/mods\\\/fssentials\\\/#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Home\",\"item\":\"https:\\\/\\\/vpesports.com\\\/minecraft\\\/\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Mods\",\"item\":\"https:\\\/\\\/vpesports.com\\\/minecraft\\\/mods\\\/\"},{\"@type\":\"ListItem\",\"position\":3,\"name\":\"F-Essentials\"}]},{\"@type\":\"WebSite\",\"@id\":\"https:\\\/\\\/vpesports.com\\\/minecraft\\\/#website\",\"url\":\"https:\\\/\\\/vpesports.com\\\/minecraft\\\/\",\"name\":\"Minecraft\",\"description\":\"\",\"potentialAction\":[{\"@type\":\"SearchAction\",\"target\":{\"@type\":\"EntryPoint\",\"urlTemplate\":\"https:\\\/\\\/vpesports.com\\\/minecraft\\\/?s={search_term_string}\"},\"query-input\":{\"@type\":\"PropertyValueSpecification\",\"valueRequired\":true,\"valueName\":\"search_term_string\"}}],\"inLanguage\":\"en-US\"}]}<\/script>\n<!-- \/ Yoast SEO plugin. -->","yoast_head_json":{"title":"F-Essentials - Minecraft","robots":{"index":"index","follow":"follow","max-snippet":"max-snippet:-1","max-image-preview":"max-image-preview:large","max-video-preview":"max-video-preview:-1"},"canonical":"https:\/\/vpesports.com\/minecraft\/mods\/fssentials\/","og_locale":"en_US","og_type":"article","og_title":"F-Essentials - Minecraft","og_description":"Punishments, IPlock, maintenance mode, and much more ..","og_url":"https:\/\/vpesports.com\/minecraft\/mods\/fssentials\/","og_site_name":"Minecraft","og_image":[{"url":"https:\/\/i.imgur.com\/F4yTBhW.png","type":"","width":"","height":""}],"twitter_card":"summary_large_image","twitter_misc":{"Est. reading time":"5 minutes"},"schema":{"@context":"https:\/\/schema.org","@graph":[{"@type":"WebPage","@id":"https:\/\/vpesports.com\/minecraft\/mods\/fssentials\/","url":"https:\/\/vpesports.com\/minecraft\/mods\/fssentials\/","name":"F-Essentials - Minecraft","isPartOf":{"@id":"https:\/\/vpesports.com\/minecraft\/#website"},"primaryImageOfPage":{"@id":"https:\/\/vpesports.com\/minecraft\/mods\/fssentials\/#primaryimage"},"image":{"@id":"https:\/\/vpesports.com\/minecraft\/mods\/fssentials\/#primaryimage"},"thumbnailUrl":"https:\/\/vpesports.com\/minecraft\/wp-content\/uploads\/2026\/06\/fssentials-icon-96c3c3fbc2ef78722b8340f8896e5f4129564544_96.webp","datePublished":"2026-06-04T07:04:37+00:00","breadcrumb":{"@id":"https:\/\/vpesports.com\/minecraft\/mods\/fssentials\/#breadcrumb"},"inLanguage":"en-US","potentialAction":[{"@type":"ReadAction","target":["https:\/\/vpesports.com\/minecraft\/mods\/fssentials\/"]}]},{"@type":"ImageObject","inLanguage":"en-US","@id":"https:\/\/vpesports.com\/minecraft\/mods\/fssentials\/#primaryimage","url":"https:\/\/vpesports.com\/minecraft\/wp-content\/uploads\/2026\/06\/fssentials-icon-96c3c3fbc2ef78722b8340f8896e5f4129564544_96.webp","contentUrl":"https:\/\/vpesports.com\/minecraft\/wp-content\/uploads\/2026\/06\/fssentials-icon-96c3c3fbc2ef78722b8340f8896e5f4129564544_96.webp","width":96,"height":96},{"@type":"BreadcrumbList","@id":"https:\/\/vpesports.com\/minecraft\/mods\/fssentials\/#breadcrumb","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https:\/\/vpesports.com\/minecraft\/"},{"@type":"ListItem","position":2,"name":"Mods","item":"https:\/\/vpesports.com\/minecraft\/mods\/"},{"@type":"ListItem","position":3,"name":"F-Essentials"}]},{"@type":"WebSite","@id":"https:\/\/vpesports.com\/minecraft\/#website","url":"https:\/\/vpesports.com\/minecraft\/","name":"Minecraft","description":"","potentialAction":[{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https:\/\/vpesports.com\/minecraft\/?s={search_term_string}"},"query-input":{"@type":"PropertyValueSpecification","valueRequired":true,"valueName":"search_term_string"}}],"inLanguage":"en-US"}]}},"_links":{"self":[{"href":"https:\/\/vpesports.com\/minecraft\/wp-json\/wp\/v2\/mod\/73803","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/vpesports.com\/minecraft\/wp-json\/wp\/v2\/mod"}],"about":[{"href":"https:\/\/vpesports.com\/minecraft\/wp-json\/wp\/v2\/types\/mod"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/vpesports.com\/minecraft\/wp-json\/wp\/v2\/media\/73804"}],"wp:attachment":[{"href":"https:\/\/vpesports.com\/minecraft\/wp-json\/wp\/v2\/media?parent=73803"}],"wp:term":[{"taxonomy":"mod_category","embeddable":true,"href":"https:\/\/vpesports.com\/minecraft\/wp-json\/wp\/v2\/mod_category?post=73803"},{"taxonomy":"mod_loader","embeddable":true,"href":"https:\/\/vpesports.com\/minecraft\/wp-json\/wp\/v2\/mod_loader?post=73803"},{"taxonomy":"minecraft_version","embeddable":true,"href":"https:\/\/vpesports.com\/minecraft\/wp-json\/wp\/v2\/minecraft_version?post=73803"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}