LightStaff

A modern staff utility plugin for Paper and Folia servers. LightStaff gives moderators a clean staff mode toolset for investigations: hotbar tools, vanish, freeze, inspection, teleporting, recovery, audit logging, and flexible storage.

Built against Paper 1.19.4 with Java 17, while keeping the runtime path ready for newer Paper builds.

Showcase

Staff Mode Hotbar

The default setup gives staff a compact investigation hotbar with clear names, lore, and actionbar state.

Staff Mode Tools

Staff entering Staff Mode receives a configurable hotbar:

Slot	Tool	Purpose
`0`	Vanish	Hide from regular players while staying visible to staff with permission.
`1`	Push	Move players away for quick spacing or control.
`2`	Inspector	Open a read-only inventory view with armor and offhand.
`4`	Freeze	Stop movement, chat, commands, damage bypasses, and inventory actions.
`6`	Flight	Toggle flight while investigating.
`8`	Exit	Leave Staff Mode and restore the saved player state.

Every tool is configured in tools.yml: enabled state, slot, permission, material fallback list, cooldown, display name, lore, sound, volume, and pitch.

Storage Choices

Pick the backend that fits the server:

sqlite for simple local production use
json for readable local files
mysql for networked setups
mariadb for MariaDB deployments

Combat-Aware Staff Mode

LightStaff can block players from entering Staff Mode while combat tagged. The check is configurable and supports:

metadata keys used by combat plugins
PlaceholderAPI placeholders
a bypass permission for trusted staff

Features

Staff Mode enter/exit with inventory, armor, offhand, exp, gamemode, and flight restoration
Persistent vanish and freeze state
Read-only inventory inspection
Freeze command and freeze tool with disconnect handling
Staff teleport command
Staff whitelist bypass mode
Session recovery command
Audit logging for moderation actions
Configurable actionbar
Configurable command, plugin, and tool messages
Configurable storage: SQLite, JSON, MySQL, MariaDB
Paper and Folia scheduler support
Material fallback lists for cross-version compatibility

Requirements

Java 17 or newer
Paper 1.19.4+
Optional: PlaceholderAPI
Optional: CombatLogX, PvPManager, DeluxeCombat, CombatPlus, or another combat plugin exposed through metadata or PlaceholderAPI

Installation

Download the latest jar from GitHub Releases.
Put it in your server plugins folder.
Start the server once.
Edit the generated files in plugins/LightStaff/.
Run /lightstaff reload or restart the server.

Configuration

LightStaff separates configuration into three files:

File	Purpose
`config.yml`	Plugin behavior, storage, combat checks, freeze behavior, whitelist mode, audit logging
`tools.yml`	Staff tool setup, slots, permissions, materials, names, lore, sounds
`messages.yml`	Prefix, command messages, plugin messages, actionbar labels

Storage

Default:

storage:
  type: "sqlite"

Available values:

storage:
  type: "sqlite" # sqlite, json, mysql, mariadb

JSON storage writes to:

plugins/LightStaff/data/sessions.json
plugins/LightStaff/data/moderation_states.json

Combat Blocking

combat:
  block_lightstaff_entry: true
  bypass_permission: "lightstaff.combat.bypass"
  metadata_keys:
    - "combatlogx_in_combat"
    - "in_combat"
    - "combatTagged"
  placeholderapi:
    enabled: true
    placeholders:
      - "%combatlogx_in_combat%"
      - "%pvpmanager_in_combat%"
    combat_values:
      - "yes"
      - "true"
      - "1"
      - "tagged"

Players with the configured bypass permission can enter Staff Mode even while tagged.

Freeze Disconnect Message

Single line:

freeze_ban_message: "You disconnected while frozen."

Multiple lines:

freeze_ban_message:
  - "You disconnected while frozen."
  - "Open a ticket if this was a mistake."

Commands

Command	Description
`/lightstaff`, `/ls`, `/staffmode`, `/sm`	Toggle Staff Mode
`/lightstaff reload`	Reload config, tools, and messages
`/lightstaff status [player]`	Show staff/vanish/freeze/session status
`/lightstaff recover <player>`	Recover a saved Staff Mode session
`/vanish [player]`	Toggle vanish for yourself or another player
`/freeze <player> [reason]`	Toggle freeze
`/freeze on <player> [reason]`	Freeze a player
`/freeze off <player>`	Unfreeze a player
`/unfreeze <player>`	Unfreeze a player
`/stafftp <player>`	Teleport to an online player
`/staffwhitelist`	Toggle staff whitelist bypass mode

Permissions

Permission	Description
`lightstaff.use`	Use Staff Mode
`lightstaff.reload`	Reload configuration
`lightstaff.recover`	Recover stuck sessions
`lightstaff.status`	View status
`lightstaff.vanish`	Use vanish
`lightstaff.vanish.others`	Vanish other players
`lightstaff.freeze`	Freeze players
`lightstaff.freeze.staff`	Freeze staff users
`lightstaff.inspect`	Inspect inventories
`lightstaff.inspect.staff`	Inspect staff users
`lightstaff.fly`	Use flight tool
`lightstaff.push`	Use push tool
`lightstaff.stafftp`	Use staff teleport
`lightstaff.whitelist.toggle`	Toggle staff whitelist mode
`lightstaff.whitelist.bypass`	Bypass staff whitelist mode
`lightstaff.combat.bypass`	Enter Staff Mode while combat tagged
`lightstaff.creative`	Use creative-mode behavior in Staff Mode
`lightstaff.see`	See vanished staff
`lightstaff.alerts`	Receive staff join/leave alerts
`lightstaff.admin`	Admin wildcard handled by LightStaff
`lightstaff.*`	Full LightStaff access