NexaStaff Documentation

Installation#

Stop the server before replacing an existing NexaStaff jar.
Place the jar in the server's plugins folder.
Start the server once so the default files are generated.
Edit plugins/NexaStaff/config.yml, messages.yml, and the files under menus/.
Restart the server after first setup. Use /nexastaff reload only for later config changes.

For production servers, configure permissions before giving staff access to action commands such as freeze, vanish, inspect, and report management.

First Setup#

Recommended order#

Set license-key if your build requires license validation.
Set settings.server-id to a unique value on every server.
Choose storage.type and fill connection settings when using SQL.
Choose a sync.mode if more than one server needs shared staff state.
Adjust staff mode tools, vanish behavior, freeze rules, and reports.
Edit menu files and assign permission nodes to your staff ranks.

Main files#

config.yml - feature behavior, storage, sync, hooks, webhooks.
messages.yml - player and staff-facing messages.
menus/staff-panel.yml - main control panel.
menus/reports.yml - report list, template picker, report detail.
menus/logs.yml - audit log browser.
menus/hook-status.yml - integration health screen.
menus/staff-list.yml and menus/teleport.yml - staff list and teleport workflows.

Commands#

Command	Purpose	Primary permission
`/nexastaff reload`	Reload configuration, messages, menus, and plugin systems where supported.	`nexastaff.reload`
`/staff` / `/staffmode`	Open staff panel or toggle staff mode.	`nexastaff.staffmode`
`/vanish`	Toggle vanish for hidden moderation.	`nexastaff.vanish`
`/freeze <player>`	Freeze a player and notify staff.	`nexastaff.freeze`
`/unfreeze <player>`	Remove a player's frozen state.	`nexastaff.freeze`
`/freezeall`	Freeze all applicable online players.	`nexastaff.freeze`
`/inspect <player>`	Open inspection tools for a player.	`nexastaff.inspect`
`/invsee <player>`	Open a player's inventory view.	`nexastaff.inspect.inventory`
`/endersee <player>`	Open a player's ender chest view.	`nexastaff.inspect.enderchest`
`/randomtp`	Teleport to a random valid player target.	`nexastaff.randomtp`
`/reports`	Open the staff report management GUI.	`nexastaff.reports.manage`
`/report <player> [reason\|template]`	Open report templates or submit a reason directly.	`nexastaff.reports.use`
`/helpop <message>`	Send a staff help request.	Configured staff alert access
`/support <message>`	Send a support request to staff.	Configured staff alert access
`/stafflogs`	Open audit log viewer.	`nexastaff.logs.view`
`/stafflist`	Open online staff list.	`nexastaff.stafflist`
`/stafftp`	Open staff teleport menu.	`nexastaff.stafftp`
`/staffsettings`	Open staff settings where available.	`nexastaff.admin`
`/cpscheck <player>`	Run a CPS check for investigation.	`nexastaff.cps`

Permissions#

Admin#

nexastaff.admin
nexastaff.reload
nexastaff.staffsettings if added to your permission setup.

Visibility#

nexastaff.vanish
nexastaff.vanish.others
nexastaff.vanish.see
nexastaff.vanish.bypass
nexastaff.vanish.pickup

Freeze#

nexastaff.freeze
nexastaff.freeze.bypass
nexastaff.freeze.alert
nexastaff.freeze.disconnectalert

Inspect#

nexastaff.inspect
nexastaff.inspect.inventory
nexastaff.inspect.enderchest
nexastaff.inspect.edit
nexastaff.inspect.ip
nexastaff.inspect.alts

Reports and logs#

nexastaff.reports.use
nexastaff.reports.receive
nexastaff.reports.manage
nexastaff.reports.assign
nexastaff.reports.delete
nexastaff.logs.view
nexastaff.logs.view.others

Tools and hooks#

nexastaff.tool.freeze
nexastaff.tool.inspect
nexastaff.randomtp
nexastaff.stafftp
nexastaff.stafflist
nexastaff.cps
nexastaff.hooks.chat
nexastaff.hooks.punishment
nexastaff.hooks.killfarm
nexastaff.hooks.anticheat

Configuration#

The main config controls global settings, staff mode, vanish, freeze, reports, audit logging, storage, sync, hooks, and webhooks. Keep server-specific values such as server-id unique when running a network.

config.yml structure

license-key: "YOUR-LICENSE-KEY"

settings:
  debug: false
  server-id: "survival-1"

sync:
  mode: NONE

staff-mode:
  enabled: true
  restore-inventory: true
  disable-pickup: true
  disable-damage: true

vanish:
  hide-tab: true
  silent-join-quit: true
  allow-pickup: false

freeze:
  lock-movement: true
  lock-chat: true
  bossbar:
    enabled: true

reports:
  cooldown-seconds: 60
  daily-limit: 15
  allow-offline-target: false
  duplicate-policy: BLOCK

Report Templates#

The report system supports direct reasons, predefined templates, and custom chat input. Running /report <player> opens the template menu. Running /report <player> hacking-cheating submits the matching configured template when it exists.

config.yml report templates

reports:
  templates:
    custom:
      enabled: true
      display-name: "&eCustom"
      material: WRITABLE_BOOK
      custom-input: true
      slot: 10
    hacking-cheating:
      enabled: true
      display-name: "&cHacking/Cheating"
      material: DIAMOND_SWORD
      reason: "Hacking/Cheating"
      slot: 14
    inappropriate-language:
      enabled: true
      display-name: "&eInappropriate Language"
      material: PAPER
      reason: "Inappropriate Language"
      slot: 16

Default template names#

custom exploiting-bugs griefing-vandalism hacking-cheating harassment-bullying inappropriate-language inappropriate-skin-name other spam-advertisement

Menus and GUI#

Menu files are YAML-driven. Paginated list menus support previous and next controls. Frame fillers can draw only the outer border, which keeps list slots usable while preserving the TrainingBot-style framed layout.

menus/staff-panel.yml
menus/inspect.yml
menus/reports.yml
menus/logs.yml
menus/hook-status.yml
menus/staff-list.yml
menus/teleport.yml

Supported item options#

material, name, lore, slot
sound using Bukkit names or registry keys
permission where the menu item is permission-gated
back-item, close-item, previous-page, next-page

Frame and navigation example

fill-item:
  enabled: true
  frame: true
  material: BLACK_STAINED_GLASS_PANE
  name: " "

back-item:
  slot: 49
  material: ARROW
  name: "&cBack"
  sound: UI_BUTTON_CLICK

previous-page:
  slot: 45
  material: ARROW
  name: "&ePrevious Page"

next-page:
  slot: 53
  material: ARROW
  name: "&eNext Page"

Staff Tools#

Staff Mode#

Uses configurable staff tools and restore rules so moderators can enter and leave staff workflows cleanly.

Vanish#

Controls visibility, tab behavior, join and quit messages, pickups, damage, and bypass checks.

Freeze#

Locks movement or chat, shows boss bar warnings, and alerts staff when a frozen player disconnects.

Inspect#

Supports inventory, ender chest, IP, alternative-account context, and edit permissions.

Teleport#

Includes random teleport and staff teleport menus for fast player checks and staff coordination.

CPS Check#

Gives staff a direct command path for click investigation workflows.

Storage#

Use YAML for small standalone servers, SQLite for single-server persistence without external services, and MySQL when multiple servers or external analysis tools need shared data.

Storage example

storage:
  type: SQLITE
  mysql:
    host: "127.0.0.1"
    port: 3306
    database: "nexastaff"
    username: "root"
    password: "password"
    use-ssl: false

Sync#

Mode	Use when	Notes
`NONE`	One server only.	No cross-server state is published.
`DATABASE`	You already use MySQL and want simple shared persistence.	Good default for networks without Redis.
`REDIS`	You need fast pub/sub updates across multiple servers.	Requires Redis connection settings.
`PLUGIN_MESSAGE`	You use a proxy-connected network and want lightweight channel messages.	Depends on proxy and server channel behavior.

Hooks and Integrations#

Hooks can enrich staff workflows with permission data, punishment context, chat signals, anti-cheat alerts, and Discord notifications. The hook status menu gives staff a quick health overview.

Permission and staff context#

Use permission hooks to resolve staff groups, visibility, and access checks consistently with your rank plugin.

Punishment and anti-cheat context#

Use punishment and anti-cheat hooks to show relevant investigation context without forcing staff to leave the workflow.

Webhooks#

Webhooks can forward report, freeze, audit, or staff workflow events to external systems such as Discord channels.

Webhook shape

webhooks:
  enabled: false
  report-url: ""
  audit-url: ""
  freeze-url: ""

API and Placeholders#

NexaStaff is structured around managers and services, so external additions can query staff state, reports, logs, or hook status when exposed by the build. Prefer permission checks and service methods over duplicating plugin state in another plugin.

Developer usage#

Check whether a player is vanished before showing staff-only data.
Read report state before creating duplicate moderation entries.
Use hook status when presenting integration diagnostics.

Placeholder strategy#

Use placeholders in menu names and lore for player, target, report, server, and status values.
Keep placeholder-heavy menus paginated when they list dynamic entries.

Common Setups#

Junior Moderator#

Give report receive/manage access, staff list, inspect read-only access, and freeze alerts. Avoid edit inventory and admin reload permissions.

Senior Staff#

Add vanish, freeze, unfreeze, staff teleport, random teleport, report assign/delete, audit log access, and hook views.

Network Admin#

Use MySQL storage, unique server IDs, a sync mode, and external webhook destinations for audit and report escalation.

Single Server#

Use SQLite or YAML, keep sync disabled, and focus on report templates, staff mode tools, freeze rules, and clean menu permissions.

Staff Quick Start#

Set up a complete report-to-resolution path before giving staff investigative tools.

Test with reporter, junior staff, senior staff and reported-player accounts.

First incident#

Submit /report <player> as a normal player.
Open /reports as staff and accept/assign it.
Enter /staff or /staffmode and verify snapshot protection.
Close the report with a reason and confirm the audit entry.

Permission layers#

Give receive/manage permissions only to the correct staff group.
Separate vanish/freeze/inspect from report submission.
Test every tool with the lowest intended staff level.

Report & Incident Workflow#

Turn player reports into a consistent, documented investigation.

A report that is created but never delivered is an operational failure; test both sides.

Reporter flow#

Open report templates and choose a short reason.
Submit once and verify cooldown/duplicate policy.
Check confirmation and privacy message.
Reopen only when staff requests more information.

Investigation flow#

Open reports and assign the case.
Use /vanish, then /freeze <player>.
Inspect with /inspect, /invsee, /endersee or /cpscheck.
Record decision, unfreeze and restore staff mode.

Evidence & Staff Mode Setup#

Configure snapshots, evidence, punishments and report templates as separate responsibilities.

Never rely on a single permission or GUI visibility as proof that an action is authorized.

Staff mode baseline safe inventory

staff-mode: enabled: true restore-inventory: true disable-pickup: true disable-damage: true vanish: hide-tab: true silent-join-quit: true freeze: lock-movement: true lock-chat: true

Report templates public forms

Define cheating, chat, griefing, scam, exploit and other reasons.
Set cooldown, daily limit, duplicate and offline-target policy.
Test creation, delivery, assignment, close and deletion permissions.

Production Rollout#

Deploy moderation tools with recoverable state, restricted evidence and consistent network behavior.

Back up reports/logs and protect webhook/database credentials.

Go-live#

Use separate junior/senior/network-admin groups.
Test restart while vanished/frozen and verify restoration.
Use unique server ids for cross-server sync.
Review webhook and audit output with staff only.

Operational rule#

Every investigation should end with one of: closed, escalated, punished or dismissed. Keep the reason and evidence reference in the report history.

Usage Guide#

Incident workflow#

Open /reports or receive a /report <player> notification.
Enter /staff//staffmode and verify inventory/armor/location snapshot.
Use /vanish, then /freeze <player> before inspecting a suspicious player.
Open /inspect, /invsee, /endersee or /cpscheck according to the case.
Record notes in the report/log flow, unfreeze the player and exit staff mode so the snapshot restores.

Safe staff-mode baseline#

staff-mode:
  enabled: true
  restore-inventory: true
  disable-pickup: true
  disable-damage: true
vanish:
  hide-tab: true
  silent-join-quit: true
freeze:
  lock-movement: true
  lock-chat: true

Report templates#

Keep reasons short and actionable: cheating, chat, griefing, scam, exploit and other. Set cooldown, daily limit, duplicate policy and offline-target policy before enabling public reports.

Test both player submission and staff management permissions; a report that is created but never delivered is an operational failure.

Network moderation#

Use a unique server-id on every server, choose one sync mode and verify report/state delivery before enabling Redis or proxy sync. Keep staff level visibility and webhook credentials restricted.

Troubleshooting#

Problem	Likely cause	Fix
Menu item does not appear	Wrong slot, missing material, disabled item, or permission gate.	Check the matching `menus/*.yml` file and console warnings.
Invalid menu material warning	The material name is not valid for your server version.	Use a Bukkit material name such as `BLACK_STAINED_GLASS_PANE`.
Invalid menu sound warning	The configured sound is not available on the server version.	Use Bukkit names such as `UI_BUTTON_CLICK` or a valid registry key supported by your version.
`/report` opens no templates	Templates are disabled or the template section is empty.	Enable entries under `reports.templates` and reload.
Staff cannot see reports	Missing management or receive permissions.	Grant `nexastaff.reports.manage` and `nexastaff.reports.receive`.
Cross-server state is missing	Sync mode or storage is not configured consistently.	Use unique server IDs and matching storage/sync settings on every server.

FAQ#

Can I add more report reasons?#

Yes. Add a new entry under reports.templates, choose a material, display name, reason, slot, and optional lore.

Yes. Menu sounds can be configured with Bukkit-style names such as UI_BUTTON_CLICK when the server version supports them.

Should I use Redis?#

Use Redis when fast cross-server event delivery matters. For simpler networks, MySQL-backed database sync may be enough.

Is Folia supported?#

Do not claim Folia support unless your final server build and all used workflows have been verified for region-thread safety.

Changelog Notes#

Added YAML-driven report templates with a custom chat prompt option.
Added framed menu filler support and paginated list menus for report, log, hook, staff list, and teleport screens.
Added back items to required menus and documented menu sound handling.
Expanded Features and documentation pages for public plugin presentation.

Installation#

First Setup#

Recommended order#

Main files#

Commands#

Permissions#

Admin#

Visibility#

Freeze#

Inspect#

Reports and logs#

Tools and hooks#

Configuration#

Report Templates#

Default template names#

Menus and GUI#

Menu files#

Supported item options#

Staff Tools#

Staff Mode#

Vanish#

Freeze#

Inspect#

Teleport#

CPS Check#

Storage#

Sync#

Hooks and Integrations#

Permission and staff context#

Punishment and anti-cheat context#

Webhooks#

API and Placeholders#

Developer usage#

Placeholder strategy#

Common Setups#

Junior Moderator#

Senior Staff#

Network Admin#

Single Server#

Staff Quick Start#

First incident#

Permission layers#

Report & Incident Workflow#

Reporter flow#

Investigation flow#

Evidence & Staff Mode Setup#

Production Rollout#

Go-live#

Operational rule#

Usage Guide#

Incident workflow#

Safe staff-mode baseline#

Report templates#

Network moderation#

Troubleshooting#

FAQ#

Can I add more report reasons?#

Can menu sounds use old enum-style names?#

Should I use Redis?#

Is Folia supported?#

Changelog Notes#