Staff+

Appearance

Frequently Asked Questions (FAQ) ​

This FAQ answers common operational and architectural questions about Staff+'s capabilities, including the interactive GUI, Folia region safety, database synchronization, and LuckPerms-independent hierarchy protection.

🛡️ Hierarchy Protection ​

Q: How does the Hierarchy Protection work? Does it require hooking into LuckPerms? ​

No. Staff+ does not require any direct API hooks to LuckPerms.

Instead, it reads permission nodes natively via Spigot/Paper's standard getEffectivePermissions() API.

  • How to assign weight: Assign staff members the permission node staff.hierarchy.weight.<number> (e.g. staff.hierarchy.weight.50 for moderators or staff.hierarchy.weight.100 for administrators).
  • Authority checks: When a punishment is placed, the weight of the punisher is recorded. If another staff member attempts to lift, override, or clear that punishment, Staff+ checks if their weight is equal to or greater than the original punisher.
  • Decoupled design: Because it relies on standard Bukkit permission checks, this system works out-of-the-box with any permissions plugin (LuckPerms, UltraPermissions, GroupManager, etc.).

📊 Staff Info GUI ​

Q: What is /staff info <player>? ​

It is a dynamic, interactive chest GUI that presents comprehensive profile, connection, and moderation statistics for a specific player. This allows staff members to inspect details in busy lobbies without chat flood.

Q: Does /staff info work for offline players? ​

Yes. When a player is offline, Staff+ queries their last known database record to display:

  • Last known IP address
  • Hierarchy weight
  • Total active warnings
  • Alt accounts registered under their IP
  • Whitelist IP-ban exemption status

Actions that require the player to be online (such as Teleport, Kick, and Inspect Inventory) are visually marked as disabled (using red stained glass panes) and clicking them is blocked. Moderation commands (ban, mute, warn, allow, history logs) remain fully active.

🧵 Folia & Regional Safety ​

Q: What makes Staff+ fully Folia-compatible? ​

Traditional plugins fail under Folia due to region-threading constraints. Staff+ enforces complete region-safety:

  1. Asynchronous Database & Webhooks: All database and Discord webhook transactions are run asynchronously via ForkJoinPool.commonPool(), preventing any tick lag.
  2. Asynchronous Teleports: All teleports (such as spectator camera follows) use modern non-blocking Entity#teleportAsync() futures rather than standard synchronous teleports.
  3. Recipient-Threaded Packets: Player visibility toggles (hide/show packet loops in Vanish) are run on each recipient's specific entity scheduler to prevent cross-region threading exceptions.
  4. Isolating block-state reads: Traditional /invsee plugins query .getHolder() on block inventories in other regions, which triggers Folia crashes. Staff+ uses a thread-safe InvseeSession registry to bypass this entirely.

🌐 Network Sync & Database ​

Q: How do we sync mutes and bans across our server network? ​

To enable network-wide moderation, configure both the Velocity proxy plugin and the Paper backend plugins to point to the same database (MySQL/MariaDB).

  • Mutes: Actively muted players are blocked from typing in chat network-wide at the Velocity proxy level.
  • Bans: Banned players are rejected at the Velocity proxy pre-login event, saving backend resources.
  • IP-Ban Exemptions: Whitelisted players bypass active IP bans at the gateway without removing the IP ban itself.

Q: Why did the database fail to connect or say it "can't find it"? ​

Starting in v1.2.2:

  1. Bundled Drivers: Staff+ includes relocated MySQL (com.mysql.cj.jdbc.Driver) and MariaDB (org.mariadb.jdbc.Driver) JDBC drivers directly inside both the Paper and Velocity JARs. You do not need to install external driver JARs.
  2. Auto-creation: Connection pools configure createDatabaseIfNotExist=true and allowPublicKeyRetrieval=true automatically. If the target database schema does not exist on your MySQL server, it will be automatically provisioned.
  3. Graceful SQLite Fallback: If remote database credentials are invalid or your SQL server is offline, Staff+ falls back to a local SQLite database (database.db) instead of crashing or disabling the plugin, ensuring your server remains protected.
  4. Dynamic Reconnect: Running /staff reload automatically re-establishes the database connection pool without requiring a full server reboot.

🔑 Permissions & Velocity Proxy ​

Q: Why do I get "no permission" on Velocity even if I have OP on Paper? ​

  • On Paper/Folia backend servers: All Staff+ commands default to Server Operators (default: op). Additionally, assigning staff.admin grants immediate full access to all commands and bypasses all restrictions.
  • On Velocity proxy servers: The Velocity proxy has no native /op command. If you manage permissions via LuckPerms Velocity, you can assign staff.admin:
    bash
    /lpv user <your-username> permission set staff.admin true
  • Seamless Backend Forwarding (velocity-forward-to-backend: true): If you only manage LuckPerms and OPs on your backend Paper servers, Staff+ automatically forwards commands executed on Velocity down to your active Paper server (player.spoofChatInput), allowing Paper to evaluate LuckPerms and OP status seamlessly!

🚪 Proxy Disconnects & Limbo Prevention ​

Q: Why did kicks and bans send players to Limbo instead of disconnecting them? ​

By default in Velocity networks with fallback configurations, when a backend server kicks a player, Velocity's failover mechanism redirects the player to fallback or limbo servers rather than dropping their connection.

In Staff+:

  • Staff+ listens directly to Velocity's KickedFromServerEvent.
  • When a player is explicitly kicked (/kick) or banned by staff, Velocity intercepts the event and executes DisconnectPlayer.create(reason).
  • This completely disconnects the player from the proxy network with their kick/ban reason, preventing them from bouncing into Limbo.
  • Routine server reboots and shutdowns ("Server closed") continue to smoothly route players back to your lobby.

📱 Bedrock & Geyser Compatibility ​

Q: Do I need GeyserMC on both the proxy and the backend servers? ​

Staff+ features multi-classloader Geyser detection. If Geyser is present on the server where the command is executed (whether Velocity or Paper), Bedrock players receive an interactive GUI form. If Geyser is only on the proxy and you run backend commands (or vice versa), Staff+ safely falls back to standard text/chat pagination with zero console errors.

❄️ Freeze & Screenshare ​

Q: How do I change the TeamSpeak or Discord message in /freeze? ​

In config.yml, set your voice communication addresses:

yaml
teamspeak-server: "ts.yourserver.com"
discord-invite: "discord.gg/yourserver"

The {teamspeak} and {discord} placeholders are dynamically mapped into all freeze chat reminders, on-screen titles, subtitles, and the action bar indicator configured in messages.yml.

Q: What happens if a player disconnects while frozen? ​

Staff+ immediately broadcasts an alert to all online staff. If freeze-logout-action-enabled: true, Staff+ executes the configured console command (by default, ban {player} 30d Disconnecting while frozen [Auto-Ban]).

Q: Can I choose between Chat, Title, and Action Bar instead of showing everything at once? ​

Yes! Set freeze-message-mode in config.yml:

yaml
freeze-message-mode: "chat" # CHAT, TITLE, ACTION_BAR, or ALL

You can also override this per-command by specifying a flag:

  • /freeze <player> [reason] --chat
  • /freeze <player> [reason] --title
  • /freeze <player> [reason] --actionbar
  • /freeze <player> [reason] --all

Released under the MIT License.

Copyright © 2026-present synkfr & Antigravity