Solver

# ███████╗ ██████╗ ██╗     ██╗   ██╗███████╗██████╗
# ██╔════╝██╔═══██╗██║     ██║   ██║██╔════╝██╔══██╗
# ███████╗██║   ██║██║     ██║   ██║█████╗  ██████╔╝
# ╚════██║██║   ██║██║     ██║   ██║██╔══╝  ██╔══██╗
# ███████║╚██████╔╝███████╗╚██████╔╝███████╗██║  ██║
# ╚══════╝ ╚═════╝ ╚══════╝ ╚═════╝ ╚══════╝╚═╝  ╚═╝

# Solver Configuration

# Language (en_US, es_ES, pt_BR, ru_RU, de_DE, fr_FR, ja_JP, ko_KR, eo_EO)
localization: en_US

# Automatically analyze whether there was a crash when the server starts up
check-crash-on-startup: true

# Monitor the entire console for errors (red text)
monitor-console: true
# Avoid analyzing the same error multiple times (minutes to wait)
error-cooldown-minutes: 10

# Solver Main Configuration

# Show the giant ASCII art banner in the console on startup?
show-banner: true

# AI Provider Configuration
ai-provider:
  # Provider: 'anthropic', 'google' or 'other'
  provider: "anthropic"

  # Model to use
  # Anthropic: Sonnet, Haiku, Opus
  # Google: Pro, Flash
  # Other: Model name (e.g: gpt-4o, mistral-large)
  model: "Sonnet"

  # API Keys
  anthropic-key: ""
  google-key: ""

  # Configuration for the 'other' provider (OpenAI-compatible)
  other-key: ""
  other-url: "https://api.openai.com/v1/chat/completions"

# Analysis configuration
analysis:
  # Automatically analyze exceptions
  auto-analyze: true

  # Timeout for analysis (seconds)
  timeout: 60

  # Save analysis to file
  save-to-file: true

  # Reports directory
  reports-directory: "crash-reports"

  # How many days to keep analyses saved in analysis-logs/ before deleting them.
  # 0 = keep forever.
  reports-retention-days: 0

# Notifications
notifications:
  # Notify admins in-game when there's an error
  notify-admins: true

  # Send analysis to chat (in addition to console)
  send-to-chat: false

# AI Chat Moderation (Fyrx reads chat and evaluates the CONTEXT of the conversation,
# not a word blacklist. Enabling this sends chat content to the AI provider configured
# above in 'ai-provider'. Disabled by default for privacy.
chat-moderation:
  enabled: false

  # If true (default), OPs are automatically exempt from chat moderation.
  # Set to false so OPs are also examined like any other player. The
  # solver.moderation.bypass permission still works independently to exempt a specific
  # player (OP or not), regardless of this value.
  exempt-ops: true

  # Maximum recent messages to remember per player / globally
  buffer-size: 50

  # Time window of context sent to the AI (minutes)
  context-window-minutes: 5

  # How often (seconds) to check whether there's new chat to analyze (unconditional
  # sweep, never depends on the pre-filter: nothing can be hidden from the AI this way)
  analysis-interval-seconds: 45

  # How to scan chat each cycle:
  # bulk: 1 single AI call with the whole mixed conversation. Cheap, but with many
  #       players talking at once the AI can confuse who said what.
  # individual: 1 AI call PER player with new activity. The offender is already known
  #       beforehand (the AI doesn't have to guess), so this eliminates that confusion
  #       risk, but the cost scales with how many players are active per cycle - on a
  #       busy server this can burn through the provider's rate limit fast.
  scan-mode: "bulk"

  # How often the AI actually gets called to check chat (0-3). scan-mode above decides HOW
  # the AI is called; this decides WHEN.
  # 0 = never call the AI - the pre-filter above decides entirely on its own (cheaper/faster,
  #     less accurate; works with no AI provider configured at all).
  # 1 = only call the AI once the pre-filter already flagged something suspicious (balanced).
  # 2 = default/classic behavior: the AI reviews all new chat every cycle, regardless of
  #     whether the pre-filter flagged anything.
  # 3 = real-time: every message is sent to the AI immediately as it arrives, instead of
  #     waiting for analysis-interval-seconds (much faster reaction, at the cost of many more calls).
  llm-analysis-level: 2

  # Lightweight pre-filter: computes an urgency score (0.0-1.0) combining several signals.
  # NEVER decides whether something is harassment nor blocks the analysis - the sweep
  # above still reads all the chat regardless. It only decides whether it's worth WAKING
  # Fyrx up early instead of waiting for the full interval, to react faster in obvious cases.
  pre-filter:
    # Raises the urgency score if the same player receives several messages in a row from
    # others (possible insistent harassment toward a fixed target).
    trigger-on-repeated-target: true
    # Fraction (0.0-1.0) of a message in UPPERCASE from which it's considered "shouted"
    # and adds urgency score (0.6 = 60% or more of the message in caps).
    trigger-on-caps-ratio: 0.6
    # How many messages from a player need to build up before the pre-filter starts
    # evaluating the "repeated target" pattern described above.
    min-messages-before-trigger: 3
    # Minimum score (0.0-1.0) to trigger an immediate analysis instead of waiting
    urgent-score-threshold: 0.65

  # What to do when the AI reports a toxic/harassment verdict
  action:
    # alert-only: only notifies players with the solver.notify permission
    # warn-player: alert-only + a private notice to the flagged player
    # auto-action: warn-player + automatic mute/kick based on severity (1-5)
    mode: "alert-only"
    # Severity (1-5, set by the AI on each verdict) at which "auto-action" automatically
    # mutes the player instead of just warning them.
    severity-threshold-mute: 4
    # Severity at which "auto-action" automatically kicks the player instead of muting them.
    # Should be >= severity-threshold-mute for the escalation to make sense.
    severity-threshold-kick: 5
    # Duration in minutes of the automatic mute applied by "auto-action" when crossing
    # severity-threshold-mute (does not affect the manual /solver mute|tempmute).
    mute-duration-minutes: 10

    # Optional: force a specific sanction type for specific "situations" (AI tags), regardless of
    # severity-threshold-mute/kick above - only used when mode is "auto-action". Valid tags:
    # TOXIC, HARASSMENT, THREAT, HATE_SPEECH, SCAM, SPAM. Valid types: warn, mute, tempmute, kick,
    # ban, tempban ('duration' required for tempmute/tempban, same s/m/h/d/w format as elsewhere).
    # If a verdict matches more than one configured tag, the harshest configured type wins. This
    # is also the only way to reach an automatic ban/tempban from chat moderation - the severity
    # thresholds above never go past kick on their own.
    tag-overrides: {}
    #  THREAT:
    #    type: tempban
    #    duration: 7d
    #  HATE_SPEECH:
    #    type: tempban
    #    duration: 3d
    #  SCAM:
    #    type: ban

    # Multi-signal corroboration: the AI verdict alone can only trigger a real warn/mute/kick
    # when it's at least this confident AND this severe. Below that, it also needs at least one
    # corroborating pre-filter signal (caps/insult/repeated-target/burst - see pre-filter above);
    # without one it stays as a staff-only alert for manual review via /solver check, never an
    # automatic sanction. Confidence 0-100, severity 1-5.
    min-confidence-to-act-alone: 85
    min-severity-to-act-alone: 4

  # Save every detected incident to moderation-reports/
  log-incidents-to-file: true

  # Also show in console the result of /solver moderation test <message> when a player
  # runs it (the console always sees it already if it's the one running the command).
  log-test-results-to-console: true

  # How many days to keep incidents saved in moderation-reports/ before deleting them.
  # 0 = keep forever.
  reports-retention-days: 0

# Whether these command groups can also be run directly without the /solver prefix (e.g. /vanish
# instead of /solver vanish). /solver <command> always keeps working either way regardless of
# these settings. Turn a category off if another plugin you have installed already claims one of
# its command names (e.g. EssentialsX also has /mute, /kick, /ban, /warn, /tempban, /tempmute,
# /unmute, /unban) - Bukkit will otherwise let whichever plugin registers first keep the bare name.
# /enderchest is the one exception handled automatically: if EssentialsX is detected, its
# standalone form is skipped on its own (no need to toggle this whole category off for it) -
# EssentialsX's /enderchest means "show MY OWN enderchest", a different meaning from ours.
standalone-commands:
  staff-mode: true  # /vanish, /freeze, /staffchat, /commandspy, /enderchest (unless EssentialsX is installed)
  sanctions: true   # /warn, /mute, /tempmute, /kick, /ban, /tempban, /unban, /unmute, /unwarn, /history, /check, /note, /checkuser, /appeal, /sanctions
  moderation: true  # /moderation
  reports: true     # /report

# Live relay of executed commands to whoever has toggled it on with /solver commandspy - not just
# retrospective logging.
commandspy:
  enabled: true
  # "*" watches every command. Otherwise list specific command names (without the leading /) to
  # watch only those, e.g. ["op", "gamemode", "give"].
  watch-patterns: ["*"]
  # Player names (case-insensitive) never relayed, regardless of who's watching.
  exempt-players: []
  # Anyone holding one of these permissions is never relayed either.
  exempt-permissions: []

# ⚠ BETA: Sanctions System (warn/mute/kick/ban via /solver, persistent history in
# sanctions.db). Double-check /solver history after any sanction until you're fully
# comfortable with how it behaves on your server.
punishments:
  # Where sanction history is stored: sqlite (default, zero config, local file) or mysql
  # (for multi-server setups sharing one sanctions database).
  storage: sqlite

  # Only read when storage is mysql.
  mysql:
    host: localhost
    port: 3306
    database: solver
    user: solver
    password: ""

  # Shortcut reason templates: "/solver ban Player #griefing" expands to the configured text
  # (and duration, if the sanction type needs one and none was given explicitly). Unmatched
  # #names are left as a literal reason, so this never breaks a reason that legitimately starts
  # with "#".
  reason-templates: {}
  #  griefing:
  #    text: "Griefing / destroying other players' builds"
  #    duration: "1d"

  # Auto-escalation on warn count: after a WARN is recorded, if the player's total warn count
  # matches a key here, the configured action fires automatically. "action: sanction" applies
  # another sanction (type/reason/duration, same as a manual one); "action: command" runs a
  # console command instead ({player} is replaced with the player's name).
  warn-escalation: {}
  #  "3":
  #    action: sanction
  #    type: kick
  #    reason: "Auto: 3 warnings"
  #  "5":
  #    action: sanction
  #    type: tempban
  #    duration: "1d"
  #    reason: "Auto: 5 warnings"

  appeals:
    # Show a line pointing to /solver appeal <id> <reason> in warn/mute/kick/ban messages.
    show-in-sanction-message: true

# ⚠ BETA: Staff Mode Toolkit (vanish/freeze/staff chat via /solver).
staff-mode:
  vanish:
    # Also subtract vanished players from the online-player count shown in the server list (MOTD)
    hide-from-server-list: true
    # Also make a vanished player immune to damage while vanished.
    invulnerable-while-vanished: false
  freeze:
    # Commands allowed while a player is frozen (without the leading /)
    allowed-commands: ["msg", "tell", "r", "helpop"]

  # Named combined profiles for /solver staffmode <profile> - each toggles a bundle of the
  # individual staff tools at once instead of turning them on one by one. Every field is optional
  # and defaults to off. clear-inventory always saves your items first and restores them when you
  # leave the profile.
  profiles: {}
  #  moderator:
  #    vanish: true
  #    freeze-immunity: true
  #    flight: true
  #    god-mode: true
  #    clear-inventory: true
  #  builder:
  #    flight: true

# /solver inspect <player> - view a player's inventory without physically opening it.
inspect:
  # Keep refreshing the opened inventory every few ticks instead of a one-time snapshot. This is
  # polling, not a real push update (Bukkit has no "inventory changed" event to react to).
  live-refresh: false
  live-refresh-interval-ticks: 10

Base command: /solver (alias: /as). Most subcommands also work without the /solver prefix — see standalone-commands in config.yml.

Commands

/solver help: Displays the list of available commands.
/solver reload: Reloads the plugin's configuration and messages.
/solver analyze-last: Re-analyzes the last detected crash/error.
/solver crashme <exception|deadlock|oom|dry-run>: Triggers a synthetic error for testing the AI analysis pipeline.
/solver moderation status: Shows the current chat moderation diagnostics (buffer, last verdict, action mode, scan mode, AI analysis level, etc).
/solver moderation test <message>: Runs a message through the AI moderation prompt without it being a real chat message.
/solver warn <player> <reason>: Issues a warning. Reason accepts a #template from reason-templates.
/solver mute <player> <reason>: Mutes a player indefinitely.
/solver tempmute <player> <duration> <reason>: Mutes a player for a set duration.
/solver kick <player> <reason>: Kicks a player.
/solver ban <player> <reason>: Bans a player indefinitely. Also instantly kicks any known alt already online.
/solver tempban <player> <duration> <reason>: Bans a player for a set duration.
/solver unban <player>: Lifts an active ban/tempban.
/solver unmute <player>: Lifts an active mute/tempmute.
/solver unwarn <player>: Revokes the player's most recent active warning.
/solver history <player>: Shows a player's full sanction history.
/solver check <id>: Shows the details of a single sanction by its ID.
/solver note <player> <text>: Attaches a staff-only note to a player, without issuing a sanction.
/solver checkuser <player>: Cross-references IP history - shows every known alt account and any active sanction across that whole network.
/solver appeal <id> <reason>: Lets a sanctioned player appeal their own sanction in-game. Open to everyone by default.
/solver appeal list|accept|reject <id>: Staff review pending appeals.
/solver sanctions <player>: Opens a GUI browsing a player's full sanction history; click an active one for the exact revoke command.
/solver report <player> <reason>: Files a report against a player for staff attention. Open to everyone by default.
/solver reports: Lists open reports.
/solver reports claim|close|reopen <id> [reason]: Manages the reports queue. Notifies the original reporter.
/solver reports gui: Opens a GUI of open reports (left-click claims, right-click closes).
/solver vanish [strict]: Toggles your own vanish (hidden from other players, mob targeting, join/quit messages, tab-complete, and the server list count). "strict" is a second tier invisible to most staff too.
/solver freeze <player>: Toggles a freeze on a player (can't move, can't run most commands, can't break/place blocks, can't deal or take combat damage). Always toggleable even by the frozen player themselves.
/solver freeze <player> <message>: Sends a message in that player's private freeze chat channel instead of toggling.
/solver staffchat: Toggles staff-chat mode (your normal chat messages go to staff only instead of public chat).
/solver staffchat <message>: Sends a one-off message to staff chat without toggling the mode.
/solver commandspy: Toggles a live relay of other players' executed commands into your chat.
/solver staffmode <profile>: Toggles a named combined profile (vanish/freeze-immunity/flight/god-mode/inventory-clear) defined in config.yml.
/solver fly: Toggles flight, independent of any profile.
/solver god: Toggles invulnerability, including PvP damage.
/solver rtp: Teleports you to a random online non-staff player.
/solver inspect <player>: Opens a view of a player's inventory/armor/offhand without opening it; click an item to confiscate it.
/solver enderchest <player>: Same view/confiscate treatment for a player's ender chest.

solver.admin: Full access to every command below. Default: op.
solver.notify: Receive error and chat-moderation staff alerts. Default: op.
solver.moderation.bypass: Exempts this specific player from chat moderation, regardless of OP status. Default: false.

solver.diagnostics.*: All diagnostics commands (reload/analyze-last/crashme/moderation). Default: false.
solver.diagnostics.reload: Allows /solver reload.
solver.diagnostics.analyzelast: Allows /solver analyze-last.
solver.diagnostics.crashme: Allows /solver crashme.
solver.diagnostics.moderation: Allows /solver moderation status|test.

solver.sanctions.*: All sanctions commands. Default: false.
solver.sanctions.warn: Allows /solver warn.
solver.sanctions.mute: Allows /solver mute.
solver.sanctions.tempmute: Allows /solver tempmute.
solver.sanctions.kick: Allows /solver kick.
solver.sanctions.ban: Allows /solver ban.
solver.sanctions.tempban: Allows /solver tempban.
solver.sanctions.unban: Allows /solver unban.
solver.sanctions.unmute: Allows /solver unmute.
solver.sanctions.unwarn: Allows /solver unwarn.
solver.sanctions.history: Allows /solver history.
solver.sanctions.check: Allows /solver check.
solver.sanctions.note: Allows /solver note.
solver.sanctions.checkuser: Allows /solver checkuser.
solver.sanctions.appeal: Allows /solver appeal <id> <reason> (submit your own). Default: true.
solver.sanctions.appeal.manage: Allows /solver appeal list|accept|reject.
solver.sanctions.gui: Allows /solver sanctions (history GUI).

solver.reports.*: All staff reports commands. Default: false.
solver.report: Allows /solver report (submit one). Default: true.
solver.reports.manage: Allows /solver reports listing/claim/close/reopen.
solver.reports.gui: Allows the reports GUI.

solver.staffmode.*: All Staff Mode Toolkit commands. Default: false.
solver.staffmode.vanish: Allows /solver vanish.
solver.staffmode.vanish.see-strict: See through another player's strict-tier vanish.
solver.staffmode.freeze: Allows /solver freeze.
solver.staffmode.staffchat: Allows /solver staffchat.
solver.staffmode.commandspy: Allows /solver commandspy.
solver.staffmode.profiles: Allows /solver staffmode <profile>.
solver.staffmode.fly: Allows /solver fly.
solver.staffmode.god: Allows /solver god.
solver.staffmode.rtp: Allows /solver rtp.
solver.staffmode.silentjoin: Auto-vanish on join with no join message.
solver.staffmode.inspect: Allows /solver inspect.
solver.staffmode.enderchest: Allows /solver enderchest.