ModGUI

A Paper moderation plugin that provides staff with GUI-based tools for punishing, investigating, and reporting players. Punishment actions are dispatched as console commands, so ModGUI works alongside any punishment plugin (LiteBans, AdvancedBan, EssentialsX, etc.).

---

Features

• Punishment GUI - click-to-punish interface with configurable punishment types, icons, and commands
• Investigate GUI - view a player's anticheat flags for the current session (GrimAC integration)
• Staff Notes - add notes against a player, logged to Discord
• Player Reports - players can submit reports via /report, with optional severity levels
• Discord Webhooks - logs punishments, anticheat alerts, reports, and staff notes to Discord
• Staff Compass - recovery compass item that opens the investigate GUI on right-click
• Fully configurable - punishment types, durations, borders, messages, and webhook URLs all defined in config

---

Requirements

• Paper 1.21.11 or newer
• GrimAC (optional) - required for anticheat flag tracking in the investigate GUI

---

Installation

1. Drop modgui-x.x.jar into your server's plugins/ folder
2. Restart the server - plugins/ModGUI/config.yml and messages.yml will be generated
3. Configure your punishment types, webhook URLs, and permissions (see below)
4. Run /modgui reload to apply changes without restarting

---

Commands

Command	Description	Permission
/punish <player>	Opens the punishment GUI	Any modgui.punish.* node
/investigate <player>	Opens the investigate GUI	modgui.investigate
/report <player> [severity] <reason>	Submit a report against a player	modgui.report
/modgui spyglass	Gives you the staff compass	modgui.spyglass
/modgui reload	Reloads config and messages	modgui.admin

---

Permissions

Permission	Description	Default
modgui.admin	Full access, includes all punish, investigate, notes, and spyglass permissions	OP
modgui.punish.*	All punishment types	false
modgui.punish.warn	Can warn players	false
modgui.punish.kick	Can kick players	false
modgui.punish.mute	Can mute players	false
modgui.punish.tempban	Can temporarily ban players	false
modgui.punish.ban	Can permanently ban players	false
modgui.investigate	Can open the investigate GUI	false
modgui.notes.add	Can add staff notes	false
modgui.spyglass	Can receive and use the staff compass	false
modgui.report	Can submit reports via /report	true
modgui.exempt	Cannot be punished, investigated, or reported through ModGUI	false

---

Configuration

The full config is generated at plugins/ModGUI/config.yml on first run. Key sections:

Punishment types - defined under punishments:. Each entry specifies a label, icon, permission node, console command, and optional duration list. Use <player>, <reason>, and <duration> as placeholders in commands.

punishments:
  ban:
    label: "Ban"
    icon: "BARRIER"
    permission: "modgui.punish.ban"
    command: "ban <player> <reason>"
    requires-duration: false

Webhooks - set a Discord webhook URL under each type. Leave blank to disable that webhook.

webhooks:
  punishment-log:
    url: "https://discord.com/api/webhooks/..."
    ping: "123456789012345678"  # Discord role ID to ping, or leave blank

GrimAC - controls which flags are stored and alerted on.

anticheat:
  grim:
    enabled: true
    minimum-violation: 10   # ignore flags below this threshold
    ignored-checks: []      # check names to suppress entirely

Messages are defined in plugins/ModGUI/messages.yml and support full MiniMessage formatting.

---

LuckPerms Setup

LuckPerms lets you assign permissions to groups and players using /lp commands. Here are some common setups.

Moderator - can warn, kick, mute, investigate, add notes, and use the spyglass:

/lp creategroup moderator
/lp group moderator permission set modgui.punish.warn true
/lp group moderator permission set modgui.punish.kick true
/lp group moderator permission set modgui.punish.mute true
/lp group moderator permission set modgui.investigate true
/lp group moderator permission set modgui.notes.add true
/lp group moderator permission set modgui.spyglass true

Senior moderator - same as above plus temporary bans:

/lp group moderator permission set modgui.punish.tempban true

Admin - full access to everything including permanent bans and /modgui reload:

/lp creategroup admin
/lp group admin permission set modgui.admin true

Assigning a group to a player:

/lp user <player> parent set moderator

Exempting a player from all moderation (they cannot be punished, investigated, or reported):

/lp user <player> permission set modgui.exempt true

---

Webhook Setup

1. In Discord, go to a channel's settings, then Integrations, then Webhooks, then New Webhook
2. Copy the webhook URL and paste it into the relevant field in config.yml
3. To enable role pings, copy the role's ID (Enable Developer Mode, right-click the role, Copy ID) and paste it into the ping: field
4. Run /modgui reload

ModGUI sends four types of webhook embeds: punishment log, anticheat alert, player report, and staff note.