> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sentrystudios.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration Guide

> A deep dive into configuring SentryWipe, covering databases, presets, GUIs, and common questions.

SentryWipe is an incredibly powerful tool. With that power comes a lot of configuration options. This guide will walk you through every aspect of SentryWipe's configuration to ensure your server is set up safely and efficiently, answering common questions and preventing support tickets before they happen.

<Info>
  Looking for the full default code templates? Check out the complete, downloadable versions at [here](https://docs.sentrystudios.org/sentry-wipe).
</Info>

***

## 1. Main Configuration (`config.yml`)

The `config.yml` is the brain of the plugin. It dictates where data is stored, how automated systems run, and integrates with external services like Discord.

### 1.1 Database Selection

SentryWipe needs a place to store logs, backup data, and statistics. You have three choices: SQLite, H2, or MySQL.

```yaml theme={null}
database:
  type: H2
  sqlite: # Legacy local storage
    enabled: false
  h2: # Recommended for small/single servers
    enabled: true

  mysql: # Required for multi-server networks
    enabled: false
    host: localhost
    port: 3306
    database: sentrywipe
    username: root
    password: ""
    useSSL: false
```

**Frequently Asked Questions:**

* **Which database should I use?** If you run a single survival/factions server, use **H2**. It's fast, embedded, and requires zero setup. If you run a network (e.g., multiple servers connected via BungeeCord/Velocity) and want wipes to sync across them, you **must** use **MySQL**.
* **I'm getting an SSL error with MySQL!** Set `useSSL: false`. If your MySQL server requires SSL, ensure your certificates are configured correctly on the machine.

### 1.2 Backups & Data Recovery

SentryWipe includes an automated backup system that snapshots player data before a wipe. This is what powers the `/wipe undo` command.

```yaml theme={null}
backups:
  enabled: true
  storage: FILE # Or DATABASE
  keep-days: 7
  max-size-mb: 500
```

**Common Pitfalls:**

* **"Why isn't /wipe undo working?"** Ensure `backups.enabled` is `true`. If backups are disabled, wipes are permanent immediately.
* **Storage Mode:** `FILE` storage saves zipped backups locally in the plugin folder. `DATABASE` stores the binary data in your SQL database. We highly recommend `FILE` for most servers to prevent your MySQL database from bloating massively over time.
* **Data Caps:** The `max-size-mb` ensures your disk doesn't fill up. Once the backup folder hits 500MB, older backups are deleted.

### 1.3 Auto-Purge System

The auto-purge system cleans up data from players who haven't logged in for a long time, keeping your server optimized.

```yaml theme={null}
auto-purge:
  enabled: false
  threshold-days: 30
  mode: "soft"
  bypass-permission: "sentrywipe.bypass.purge"
  purge-banned-players: false
```

**Important Notes:**

* **Protecting Staff & VIPs:** You absolutely must give your staff members and VIPs the `sentrywipe.bypass.purge` permission! Otherwise, if an admin goes on vacation for 31 days, their data will be wiped!
* **Mode:** This references a preset from your `presets.yml`. We strongly recommend using a `soft` wipe for auto-purges, which deletes inventory and location but preserves balances and ranks, just in case an old player returns.
* **Banned Players:** If `purge-banned-players` is true, banned players are immediately purged to save disk space.

### 1.4 System Settings & Kick Messages

When a player is wiped while online, they are kicked for safety. You can customize this entire screen.

```yaml theme={null}
system:
  async: true
  confirm-required: true
  log-actions: true
  
  kick-reason:
    - "&#c93434✘ ᴇʀʀᴏʀ &7• ᴘʀᴏғɪʟᴇ ᴡɪᴘᴇᴅ"
    - "&#c93434&lʏᴏᴜʀ ᴀᴄᴄᴏᴜɴᴛ ʜᴀs ʙᴇᴇɴ ᴡɪᴘᴇᴅ"
    - "&#ffd439⌚ &fᴡɪᴘᴇᴅ ʙʏ &7• &f%admin%"
    - "&#ff5348✉ &fʀᴇᴀsᴏɴ &7• &f%reason%"
```

* **Async Execution:** Keep `async: true` enabled. This ensures that massive wipes (like `/wipeall`) do not freeze or lag your main server thread.

### 1.5 Discord Integrations

Keep your staff team accountable and informed.

```yaml theme={null}
discord:
  enabled: true
  webhook-url: "https://discord.com/api/webhooks/..."
  username: "SentryWipe"
  avatar-url: "https://yourdomain.com/logo.png"
  embed-color: "#5eb7b7"
```

**How to get a Webhook URL:**

1. Go to your Discord server settings.
2. Navigate to Integrations -> Webhooks -> Create Webhook.
3. Copy the URL and paste it here.

### 1.6 Custom Sounds

You can fully customize the audio feedback for admins using the plugin.

```yaml theme={null}
sounds:
  enabled: true
  on-wipe: "ENTITY_PLAYER_LEVELUP"
  on-error: "ENTITY_VILLAGER_NO"
  on-gui-click: "UI_BUTTON_CLICK"
```

Ensure you use valid Sound enum names for your specific Minecraft version (e.g., 1.20+ sound names).

### 1.7 Worlds Configuration

This is a critical, often-overlooked section. SentryWipe needs to know which worlds to look inside when deleting `playerdata`.

```yaml theme={null}
worlds:
  world:
    enabled: true
    include-playerdata: true
  world_nether:
    enabled: true
    include-playerdata: true
  world_the_end:
    enabled: true
    include-playerdata: true
```

**Custom Worlds:** If you have a world called `resource_world` or `dungeons`, you **must** add them to this list. If you don't, SentryWipe won't delete the player's position or local data inside those custom worlds.

```yaml theme={null}
  resource_world: # Just append your world name to the bottom!
    enabled: true
    include-playerdata: true
```

### 1.8 Dev Mode (Testing Safely)

Are you customizing the GUI and want to test it without accidentally wiping someone?

```yaml theme={null}
dev-mode:
  enabled: true
  fake-players: 10
  tag: "&#b6d9d8[DEV]"
  bypass-permissions: true
  debug-mode: true
```

When `dev-mode` is on, the GUI will populate with fake players (e.g., `Fake_Player01`). You can click them, wipe them, and test all your preset menus—zero actual data will be harmed.

***

## 2. Wipe Presets (`presets.yml`)

The `presets.yml` file is the most powerful part of the plugin. It lets you define *exactly* what data is removed.

A preset is defined by its name, a display name, and a list of `actions` (data points).

### 2.1 Understanding Actions (Data Points)

Here is exactly what each true/false toggle does:

* `inventory`: Clears the player's main inventory, armor, and offhand.
* `ender_chest`: Clears their Ender Chest contents.
* `xp`: Resets levels and experience points to 0.
* `health`: Resets health to 20 (full hearts) and clears active damage/fire ticks.
* `food`: Resets hunger and saturation.
* `potions`: Removes all active potion effects (useful for clearing infinite buff glitches).
* `balance`: Wipes their vanilla economy balance.
* `homes`: Wipes their saved homes (requires integration hooks like Essentials).
* `stats`: Clears vanilla Minecraft statistics (blocks broken, playtime, mobs killed).
* `advancements`: Resets all Minecraft achievements.
* `playerdata`: Deletes their `.dat` file from the world folders. *Warning: This is the nuclear option and resets everything.*
* `bedspawn`: Removes their respawn point.
* `fire`: Extinguishes the player if they are burning.
* `flight`: Disables fly mode.
* `glow`: Removes the glowing effect.

### 2.2 Understanding Hooks

SentryWipe seamlessly integrates with other plugins. If you have `essentials: true`, SentryWipe hooks into the Essentials API and clears their Essentials user data (balance, homes, jails, mails).

**Supported Hooks include:** `essentials`, `luckperms`, `cmi`.

* **LuckPerms Note:** Setting `luckperms: true` will strip the player of all ranks and permissions, returning them to the default group. Only use this for full blacklists/bans!

### 2.3 Creating a Custom Preset

Let's say your server has a bug where players duplicated money, and you need to wipe everyone's balances but leave their builds and items intact.

```yaml theme={null}
presets:
  economy_reset:
    display: "&eEconomy Reset"
    actions:
      inventory: false
      ender_chest: false
      xp: false
      balance: true # Wipe money
      homes: false
      stats: false
      advancements: false
      playerdata: false
      
      # Hook Actions
      essentials: true # We hook essentials to ensure their economy files are cleared
      luckperms: false
```

You could then run `/wipeall economy_reset`!

***

## 3. GUI Customization (`gui.yml`)

The in-game GUI is completely modular. You can change slots, sizes, items, and lore.

### 3.1 GUI Structure

```yaml theme={null}
    action:
      title: "&#333333Manage&#6d6d6d: &#a9c8ff%player%"
      size: 27 # Must be a multiple of 9! (9, 18, 27, 36, 45, 54)
      fill: "BLACK_STAINED_GLASS_PANE"
```

**Important:** Inventory sizes in Minecraft *must* be multiples of 9. If you set `size: 30`, the plugin will throw an error and fall back to default settings.

### 3.2 Modifying Filter Buttons

Filters are a unique feature of SentryWipe that allows admins to sort players.

```yaml theme={null}
      filters:
        wealth:
          material: "GOLD_INGOT"
          name: "&#a9c8ffHigh Wealth"
          slot: 46 # The inventory slot (0-53 for a size 54 inventory)
          lore:
            - ""
            - " &fFilter"
            - " &#6d6d6d• &7Sort by total balance"
            - ""
            - " &#6d6d6d→ &#ffd439Click to apply"
```

* **Slots**: Slots start at `0` (top left corner) and end at `size - 1`. For a 54-slot inventory, the bottom right corner is `53`.
* **Materials**: Must be a valid Bukkit `Material` enum (e.g., `DIAMOND_SWORD`, `GOLD_INGOT`).

***

## 4. Localization & Messages (`messages.yml`)

Every single message SentryWipe outputs can be modified.

### 4.1 Hex Colors and Formatting

We highly recommend using modern Hex formatting for beautiful chat messages.

* Format: `&#HEXCODE` (e.g., `&#c93434`).
* Standard Minecraft color codes (e.g., `&c`, `&l`) are also supported.

```yaml theme={null}
    success:
      wipe: " &l&#6eff4aSuccess &#6d6d6d• &fWipe completed for &#a9c8ff%player% &#6d6d6d(&f%preset%&#6d6d6d)"
```

### 4.2 Interactive Hover Text

When an admin runs a command, SentryWipe can return a message that, when hovered over with the mouse, reveals a multi-line tooltip with extra data.

```yaml theme={null}
    hover:
      success:
        wipe:
          - "&#00b4d8Sentry Wipe"
          - " &#6d6d6d• &fPlayer&#6d6d6d: &#a9c8ff%player%"
          - " &#6d6d6d• &fPreset&#6d6d6d: &#ffd439%preset%"
          - " &#6d6d6d• &fReason&#6d6d6d: &7%reason%"
```

**Available Placeholders:**

* `%player%` - The target player.
* `%admin%` - The admin executing the command.
* `%preset%` - The name of the preset used.
* `%reason%` - The reason provided for the wipe.
* `%time%` - Timestamp or duration data.
* `%session%` - The unique UUID of the wipe session (used for undo/redo).

### 4.3 Disabling Broadcasts

If you run a stealthy wipe on a hacker, you might not want the whole server to know or the admins. While you can use silent console commands, you can also globally disable broadcasts:

```yaml theme={null}
    broadcast:
      enabled: false # Set to false to silence global announcements
      message: " &l&#a9c8ffSentry Wipe &#6d6d6d• &#a9c8ff%player% &fhas been purged by &#ffd439%admin%"
```

***

## 5. Troubleshooting & Common Tickets

Here are a few quick tips to resolve the most common issues players run into:

1. **"The plugin didn't load after an update!"**
   * Did you use Plugman or `/reload`? SentryWipe hooks deep into player data streams and requires a full server restart or /wipe reload to load safely.
2. **"My GUI is broken and showing a generic chest name."**
   * Check your `gui.yml` for YAML syntax errors. If you miss a quotation mark or indent a space incorrectly, the server will reject the file and load defaults. Put your `gui.yml` code into an online YAML validator.
3. **"Wipes aren't deleting player inventories in my custom dungeon world."**
   * Ensure your custom world name is added to the `worlds` section in `config.yml`. SentryWipe only scans the worlds you tell it to!
4. **"The Discord webhook isn't sending messages."**
   * Double check that `enabled: true` is set, and verify that your URL hasn't been deleted or regenerated in your Discord server settings. Ensure your server firewall allows outbound connections to `discord.com`.