📖 Table of Contents

• ✨ Features
• 📦 Dependencies
• ⚙️ Requirements
• 🚀 Installation
• 🔧 Configuration
• 💬 Commands & Permissions
• 📊 PlaceholderAPI
• 🌐 Discord Integration
• 💾 Database Setup
• 🔄 Redis (Network)
• 🖥️ GUI Overview
• 🔒 Security Features
• 🆘 Support

✨ Features

🎯 Core Moderation

• GUI-Driven Moderation – Intuitive click-based interfaces for all actions
• Override Vanilla Commands – Seamless integration with /ban, /kick, /mute, etc.
• Punishment Ladder – Automated escalating punishments (Hacking, Griefing, Scamming)
• Silent Integration – Works alongside LiteBans & AdvancedBan
• Historical Tracking – Complete audit logs for every action
• Cross-Network Sync – Redis-powered real-time data across all servers

🎨 Staff Utilities

• Staff Mode – Toggle with inventory/gamemode/position save
  • Spectator / Adventure / Creative modes
  • Auto-vanish option
  • Customizable tools: Compass, Punishment Book, Player Selector, Freeze Ice, Breadcrumb, Menu Chest
• Vanish System – Complete invisibility with visible levels
• Freeze System – Immobilize suspicious players with private chat
• Target Selection – Click, look, or GUI select with particle glow
• Internal Notes – Categories: WARNING, INFO, FOLLOWUP, PRAISE

📊 Advanced Analytics

💰 Transaction History

• Track all economy events (deposits, withdrawals, purchases, sales, transfers)
• Source tracking (Vault, ShopGUI+, commands)
• Balance snapshots and net flow calculations
• 24-hour volume summaries

📝 Command History

• Complete log of every command executed
• Configurable exclusions (staff commands filterable)
• Result tracking: SUCCESS, DENIED, ERROR, CANCELLED
• Top commands analytics

⛏️ Mining Statistics

• Block break tracking with tool type and damage
• Enchantment capture (Fortune, Silk Touch, Efficiency)
• World/environment classification
• Daily aggregates and material breakdowns
• Real-time diamond/emerald/ancient debris counts
• Top miners leaderboard

📈 Activity Metrics

• Block breaks & entity kills
• Chat messages & command executions
• Deaths & teleports
• Item pickup & drop events
• Crafting & fishing
• Level changes & respawns
• PvP kills & deaths
• Heatmap-style timeline view

🔒 Security Addon

• X-Ray Detection – Configurable ore thresholds, click-to-teleport alerts
• CPS Detection – Auto-clicker detection (18 CPS limit)
• AFK Watchdog – 5-minute idle detection
• Economy Monitoring – Suspicious balance spikes (250k threshold, 4x multiplier)
• ShopGUI+ Hook – Transaction validation for shops
• Dispatch Scan – One-click sweep for illegal items
• Quickcraft Safeguard – Prevents shift‑click crafting duplication exploits on Java & Bedrock. Fully toggleable.

📋 Reporting System

• Player Reports – /report <player> <reason> creates ticket
• Staff GUI – Claim/resolve with chat session
• Real-time Notifications – In-game + Discord webhook
• Status Tracking – OPEN, CLAIMED, RESOLVED

🌍 Network Features

• Staff Chat Bridge – /staffchat across all servers (BungeeCord/Velocity)
• Cross-Server Find – /staff connect <player> locates and teleports
• Network Staff List – See all online staff globally
• MySQL/Redis Sync – Shared data via proxy bridge

🗣️ Discord Integration

Multiple webhook routes (individually toggleable):

• default – Main log
• staff-chat – Staff messages
• punishments – Ban/mute/kick events
• teleports – Staff teleports
• alerts – Security notifications
• security – XRay/CPS/AFK alerts
• reports – New tickets
• analytics – Session data
• staff-mode – Enter/exit events

Avatar URL templating: https://mc-heads.net/avatar/{uuid}

🔧 Configuration

All features granularly configurable:

• Database type (SQLite/MySQL)
• Redis connection settings
• Vanish mode (internal/Essentials)
• Staff mode items & slots
• Freeze timeout & chat prefix
• Punishment thresholds & auto-punishment
• Security detector parameters
• Webhook routing
• Session analytics caps
• GUI titles & lore
• Language system (lang.yml)
• Geyser/Floodgate compatibility
• ItemsAdder support
• Quickcraft Safeguard options (enabled, bypass permission)

📦 Dependencies

Required (Shaded)

Optional (Provided)

⚙️ Requirements

🚀 Installation

1. Download the latest StaffSuite-3.6.0.jar
2. Place it in your server's plugins/ folder
3. Start your server
4. Configure plugins/StaffSuite/config.yml as needed
5. Reload with /staffsuite reload or restart
6. Assign permissions to your staff groups

That's it. No additional setup required.

🔧 Configuration

Main Config (config.yml)

# ============================================
# DATABASE
# ============================================
database:
  type: "sqlite"  # "sqlite" or "mysql"
  mysql:
    host: "localhost"
    port: 3306
    database: "staffsuite"
    username: "root"
    password: ""

# ============================================
# REDIS (Cross-server sync)
# ============================================
redis:
  enabled: false
  host: "localhost"
  port: 6379
  password: ""

# ============================================
# VANISH SETTINGS
# ============================================
vanish:
  mode: "internal"  # "internal" or "essentials"
  levels:
    enabled: false
    default_level: 1

# ============================================
# STAFF MODE
# ============================================
staffmode:
  save_inventory: true
  save_flight: true
  auto_vanish_on_staffmode: true
  mode_style: "creative"  # "spectator", "adventure", "creative"
  items:
    random_teleport_compass:
      enabled: true
      slot: 0
    punishment_book:
      enabled: true
      slot: 1
    player_selector:
      enabled: true
      slot: 2
    staff_menu:
      enabled: true
      slot: 4
    freeze_ice:
      enabled: true
      slot: 5
    breadcrumb_tool:
      enabled: true
      slot: 7
    exit_barrier:
      enabled: true
      slot: 8

# ============================================
# FREEZE SYSTEM
# ============================================
freeze:
  prevent_commands: true
  prevent_movement: true
  freeze_chat_prefix: "<dark_red><bold>FROZEN</bold> <gray>»</gray>"
  auto_unfreeze_seconds: 300

# ============================================
# PUNISHMENTS
# ============================================
punishments:
  warn_threshold: 3
  warn_auto_punishment: "mute 1h"
  broadcast_punishments: true
  ladders:
    enabled: true
    "Hacking/Cheating":
      - "30d"
      - "90d"
      - "perm"
    "Griefing/Theft":
      - "7d"
      - "30d"
      - "perm"
    "Scamming/Phishing":
      - "14d"
      - "90d"
      - "perm"
  integration:
    litebans:
      enabled: false
      silent: true
    advancedban:
      enabled: false
      silent: true

# ============================================
# REPORTS
# ============================================
reports:
  discord_webhook_url: ""
  notify_staff_ingame: true

# ============================================
# SNAPSHOTS
# ============================================
snapshots:
  auto_snapshot_interval_minutes: 30
  max_entries: 12
  shulker_export: false
  shulker_blacklisted_materials:
    - "BARRIER"
    - "COMMAND_BLOCK"

death_logs:
  enabled: true
  max_entries: 10

# ============================================
# SECURITY DETECTION
# ============================================
security:
  xray:
    enabled: true
    ore_threshold: 15
    time_window_seconds: 60
    tracked_ores:
      - DIAMOND_ORE
      - DEEPSLATE_DIAMOND_ORE
      - EMERALD_ORE
      - DEEPSLATE_EMERALD_ORE
      - ANCIENT_DEBRIS
  cps:
    enabled: true
    window_seconds: 5
    max_cps: 18
    min_clicks: 25
  afk:
    enabled: true
    idle_threshold_seconds: 300
  economy:
    enabled: true
    absolute_threshold: 250000
    multiplier: 4.0
    check_interval_seconds: 45
    shopgui_plus:
      enabled: false
      threshold: 150000

# ============================================
# WEBHOOKS
# ============================================
webhooks:
  default: ""
  staff-chat: ""
  punishments: ""
  teleports: ""
  alerts: ""
  security: ""
  reports: ""
  analytics: ""
  staff-mode: ""
  avatar_url: "https://mc-heads.net/avatar/{uuid}"

# ============================================
# SESSION ANALYTICS
# ============================================
session_analytics:
  enabled: true
  history_cap: 40
  risk_profile: true

# ============================================
# GUI CUSTOMIZATION
# ============================================
gui:
  enabled: true
  titles:
    staff_control: "<gradient:#5e9eff:#1e3a8a>Staff Control</gradient> <dark_gray>»</dark_gray> <white>Panel"
    player_selector: "<green>Online Players"
    reports: "<yellow>Reports"
    history: "<aqua>History"
    notes: "<aqua>Notes"
  items:
    lore_enabled: true

# ============================================
# TRACKING (New Features)
# ============================================
tracking:
  transactions:
    enabled: true
    track_vault: true
    track_shopgui_plus: true
    track_commands: true
    retention_days: 90
  command_history:
    enabled: true
    track_all_commands: true
    track_staff_commands: true
    retention_days: 30
    excluded_commands:
      - "/staff"
      - "/staffmode"
      - "/vanish"
      - "/mute"
      - "/ban"
      - "/kick"
      - "/warn"
      - "/freeze"
      - "/unfreeze"
  mining_stats:
    enabled: true
    track_block_breaks: true
    track_tool_info: true
    track_enchantments: false
    retention_days: 90
    auto_save_interval_minutes: 10
    ores_only: false
  activity_metrics:
    enabled: true
    track_block_breaks: true
    track_entity_kills: true
    track_chat: true
    track_command_executions: true
    track_deaths: true
    track_teleports: true
    track_item_pickup_drop: true
    retention_days: 7

# ============================================
# COMPATIBILITY
# ============================================
compatibility:
  geyser:
    enabled: false
    bedrock_prefix_stripping: true
  itemsadder:
    enabled: false
    custom_items: false

💬 Commands & Permissions

Command Reference

Permission Nodes

staffsuite.*:
  description: "All StaffSuite permissions"
  children:
    staffsuite.mod: true
    staffsuite.ban: true
    staffsuite.mute: true
    staffsuite.kick: true
    staffsuite.warn: true
    staffsuite.freeze: true
    staffsuite.reports: true
    staffsuite.reports.notify: true
    staffsuite.history: true
    staffsuite.transactions: true
    staffsuite.cmdhistory: true
    staffsuite.miningstats: true
    staffsuite.activity: true
    staffsuite.staffmode: true
    staffsuite.staffmode.builder: false
    staffsuite.vanish: true
    staffsuite.audit: true
    staffsuite.logs: true
    staffsuite.reload: true
    staffsuite.notify: true
    staffsuite.alerts: true
    staffsuite.admin: false
    staffsuite.bypass.xray: false
    staffsuite.bypass.cps: false
    staffsuite.bypass.afk: false
    staffsuite.bypass.economy: false

📊 PlaceholderAPI

StaffSuite provides 20+ placeholders for scoreboards, tab lists, and plugins.

Dynamic Player-Specific Placeholders:

%staffsuite_warns_Steve%
%staffsuite_transactions_last24h_Steve%
%staffsuite_mining_diamonds_last24h_Steve%

🌐 Discord Integration

Webhook Setup

1. Create webhooks in your Discord server settings
2. Paste URLs into config.yml under webhooks: section
3. Enable log-<feature> toggles as needed

webhooks:
  punishments: "https://discord.com/api/webhooks/..."
  reports: "https://discord.com/api/webhooks/..."
  security: "https://discord.com/api/webhooks/..."
  staff-chat: "https://discord.com/api/webhooks/..."

DiscordSRV Bridge

If DiscordSRV is installed, staff chat messages sent via /staffchat are automatically forwarded to a configured Discord channel.

💾 Database Setup

SQLite (Default)

No configuration needed. Database file: plugins/StaffSuite/database.db

Pros: Simple, zero configuration, good for single-server setups.
Cons: Not recommended for multi-server networks.

MySQL / MariaDB

database:
  type: "mysql"
  mysql:
    host: "localhost"
    port: 3306
    database: "staffsuite"
    username: "staffsuite_user"
    password: "secure_password"

Create Database:

CREATE DATABASE staffsuite CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
GRANT ALL PRIVILEGES ON staffsuite.* TO 'staffsuite_user'@'localhost' IDENTIFIED BY 'secure_password';
FLUSH PRIVILEGES;

Connection Pool (HikariCP):

• Max Pool Size: 10
• Min Idle: 2
• Connection Timeout: 5s
• Idle Timeout: 5 min
• Max Lifetime: 10 min

🔄 Redis (Network)

Required for multi-server setups (BungeeCord / Velocity proxy).

Configuration

redis:
  enabled: true
  host: "localhost"
  port: 6379
  password: ""  # if set

Channels

• staffsuite:bridge – Primary channel for staff chat, bans, vanishes
• Additional pub/sub used for real-time sync

Proxy Setup

1. Install StaffSuite on all servers (lobby, survival, kitpvp, etc.)
2. Enable Redis on each server with same host/port
3. Set server-name in config.yml to differentiate each server
4. Restart all servers

Note: Data is stored in MySQL (or SQLite per-server if not using network DB). For true network-wide data, configure MySQL host accessible by all servers.

🖥️ GUI Overview

Main Menu (/staff)

┌─────────────────────────────────────┐
│        🛡️ Staff Control Panel       │
├─────────────────────────────────────┤
│  👥 Online Players                  │
│  ⚖️  Active Punishments             │
│  📝 Reports                         │
│  📜 History                        │
│  👁️  Staff Mode Toggle             │
│  ❄️  Freeze Manager                │
│  🔍 Security Center                │
│  📊 Analytics                     │
│  📋 Notes                         │
│  💬 Staff Chat                    │
│  ⚙️  Settings                     │
└─────────────────────────────────────┘

Player Action GUI

Click a player → Action menu with buttons:

History GUI

Combined timeline view with filter buttons:

• ALL – Show all entries
• PUNISHMENT – Bans, mutes, warns
• REPORT – Report tickets
• NOTE – Staff notes
• ACTION – Audit log

Entries sorted by timestamp, paginated (36 per page).

Reports GUI

List of open tickets with color coding:

• 🟢 Open – White paper icon
• 🟡 Claimed – Yellow paper icon
• 🔴 Resolved – Red barrier icon

Click to claim/resolve and open private chat with reporter.

🔒 Security Features

X-Ray Detection

security:
  xray:
    enabled: true
    ore_threshold: 15      # Ores in 60 seconds triggers
    time_window_seconds: 60
    tracked_ores:
      - DIAMOND_ORE
      - DEEPSLATE_DIAMOND_ORE
      - EMERALD_ORE
      - DEEPSLATE_EMERALD_ORE
      - ANCIENT_DEBRIS

Alert format:

[XRAY ALERT] Player found 15 DIAMOND_ORE in 58s [Click to TP]

Click the message in console or in-game (if using modern clients) to teleport to suspect.

CPS Detection

cps:
  enabled: true
  window_seconds: 5
  max_cps: 18
  min_clicks: 25

Triggers when a player clicks >18 CPS with at least 25 clicks in a 5-second window.

AFK Watchdog

afk:
  enabled: true
  idle_threshold_seconds: 300  # 5 minutes

Players not moving for 5 minutes are flagged. Toggle alerts with /alerts.

Economy Monitor

economy:
  enabled: true
  absolute_threshold: 250000    # $250k in short time
  multiplier: 4.0               # 4x normal gain
  check_interval_seconds: 45
  shopgui_plus:
    enabled: false
    threshold: 150000

Detects suspicious balance spikes via Vault or ShopGUI+.

🎯 Feature Deep Dive

Transaction History

What it tracks:

• Every deposit/withdrawal via Vault
• Shop purchases/sales (ShopGUI+)
• /pay command (EssentialsX)
• Balance snapshots from /economyaudit

Database Table: transactions

GUI Features:

• Paginated list (36 per page)
• Color-coded by type (green = credit, red = debit)
• Shows running balance
• Date range filtering via config retention

Command History

What it tracks:

• Every command executed by players (with configurable exclusions)
• Command name, raw args, timestamp
• Result status (captured via Bukkit's command handling)

Database Table: command_logs

GUI Features:

• List all commands with colored results
• Filter by player
• Command count analytics

Mining Statistics

What it tracks:

• Every block break (configurable)
• Tool used (diamond_pickaxe, netherite_pickaxe, etc.)
• Tool damage value (if available)
• Enchantments (Fortune, Silk Touch, Efficiency – optional JSON)
• World type (NORMAL, NETHER, END)
• Daily aggregation

Database Table: mining_stats

Example Query:

SELECT material, SUM(count) as total
FROM mining_stats
WHERE player_uuid = '...' AND last_updated > ?
GROUP BY material ORDER BY total DESC;

GUI Features:

• Shows material with icon
• Total count for each block type
• Last 24h summary
• Top miners leaderboard for specific ores

Activity Metrics

Tracked Activities:

Database Table: activity_metrics

GUI Features:

• Timeline view (most recent first)
• Color-coded by activity type
• Expandable details (JSON in lore)
• 24-hour summary with totals per type

🆘 Support

For assistance, bug reports, or feature requests, please join our Discord server.

Discord: https://discord.gg/fxgnEQNAhJ

Our support team will help you with any issues.

🙏 Credits

BitRift.de Staff team – Development & Maintenance