F-Essentials

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.

---

High-level Overview

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

---

Features (exhaustive)

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

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

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

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

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

Maintenance commands (via `maintenance` command): - `maintenance on|off|reload` - `maintenance add <player>` / `remove <player>` / `whitelist` - `maintenance starttimer <minutes>` / `endtimer <minutes>` / `schedule <startMinutes> <durationMinutes>` / `aborttimer` - `maintenance motd` / `maintenance setmotd <index> <line> <message>`

Broadcast / Announcements - `/broadcast <title> [subtitle]` — sends a full-screen title to all players using MiniMessage formatting. - Supports splitting title/subtitle by `|` or heuristics; configurable sound (`announcements.sound.*` in config).

Vanish & Admin Tools - Toggle vanish with `/vanish` (visibility handled by `VanishService`). - `AdminToolsListener` protects vanished staff from being interacted with or damaged. - Vanish state is reapplied on join for session-owned vanished players.

InvSee (Inventory View/Edit) - `/invsee <player>` opens a 54-slot GUI snapshot of the target player's inventory (uses `InvseeInventoryHolder`). - Snapshot and restore are Folia-safe: inventory cloning happens on the target's entity scheduler and GUI open on the viewer's entity scheduler. - Viewer edits are written back on close (invsee allows editing of player storage, armor, off-hand slots as described in the GUI layout).

Message Service & Localization - `MessageService` loads `messages.yml` from the plugin folder; messages use a `prefix` and support placeholder replacement via `MessageService.get(key, placeholders)`. - Error/usage/enforcement messages are all configurable in `messages.yml` and `config.yml`.

Folia Scheduler Compatibility - `FoliaScheduler` centralizes Folia-friendly task dispatch: `runAsync`, `runAsyncTimer`, `runGlobal`, `runAtEntity`. - All file I/O and long-running work is dispatched async; player-specific operations run on the player's entity scheduler.

Storage Files Created/Used - `punishments.yml` — persisted punishment records (via `YamlPunishmentStorage`). - `ip-locks.yml` — per-account IP lock entries. - `messages.yml` — plugin messages loaded by `MessageService` (copied from plugin jar to data folder on first run).

---

Commands (complete list registered at runtime)

- `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` (separately registered with its own executor) - `broadcast`, `iplock` (separately registered)

Refer to `plugin.yml` for the exact help/usage lines; `fssentials` command prints configurable help-lines from `config.yml`.

---

Permissions (used in code)

- `fssentials.punish.kick` — kick players - `fssentials.punish.ban` / `fssentials.punish.tempban` — ban players - `fssentials.punish.mute` / `fssentials.punish.tempmute` — mute players - `fssentials.punish.warn` / `fssentials.punish.tempwarn` — warn players - `fssentials.punish.banip` / `fssentials.punish.tempipban` — IP ban - `fssentials.punish.unpunish` — remove punishments - `fssentials.punish.change-reason` — edit punishment reason - `fssentials.view.banlist` / `fssentials.view.history` / `fssentials.view.check` / `fssentials.view.playerlist` — view lists/check info - `fssentials.invsee` — view and edit player inventories - `fssentials.vanish` — toggle vanish - `fssentials.admin.reload` — reload plugin - `fssentials.admin.systemprefs` — view system prefs - `fssentials.maintenance.admin` — full maintenance administration - maintenance bypass/notify permissions are configurable (defaults shown in `MaintenanceConfig`). - IP-locking bypass permission: `plugin.iplock.bypass` (constant in `IpLockManager`).

Note: the plugin uses permission checks liberally; ensure your server's permission system maps the nodes to the desired roles.