?
Host a server
Modrinth App
Sign in
ModsPluginsData PacksShadersResource PacksModpacks
Settings
Fssentials

Fssentials

Fssentials is a powerful and user-friendly plugin designed for Paper & Folia servers.

2
0

Compatibility

Minecraft: Java Edition

1.21.x
1.20.x

Platforms

Links

Report issues View source Join Discord server
Donate on Ko-fi

Creators

NightBeam Studio
NightBeam Studio Organization
NAIZO
NAIZOOwner

Details

Licensed ARR
Published 2 days ago
Updated 2 days ago

logo

Fess

Fess

logo

Discord Server Nightbeam Studio YouTube Nightbeam Studio GitHub Nightbeam Studio CurseForge Nightbeam Studio Modrinth

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.