> ## 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.

# SentrySettings

> How to read toggles or register your own custom settings in the GUI.

SentrySettings exposes a powerful API that allows external plugins to check if a player has a specific setting enabled, or even inject completely custom toggles directly into the `/settings` menu!

## Getting the API Instance

You can access the `SentrySettingsAPI` by grabbing the main plugin instance.

```java theme={null}
import me.sentrystudios.sentrysettings.SentrySettings;
import me.sentrystudios.sentrysettings.api.SentrySettingsAPI;

public class MyPlugin {
    public void setupAPI() {
        SentrySettings plugin = SentrySettings.getPlugin();
        SentrySettingsAPI api = plugin.getSettingsAPI();
    }
}
```

***

## Reading Player Preferences

If your custom plugin sends chat messages or plays sounds, you should check the player's SentrySettings preferences first to ensure they haven't muted them!

```java theme={null}
import me.sentrystudios.sentrysettings.SentrySettings;
import org.bukkit.entity.Player;

public void sendCustomAlert(Player player) {
    // Check if the player has Actionbar Alerts enabled. 
    // The boolean 'true' is the default value returned if they haven't set it yet.
    boolean wantsAlerts = SentrySettings.getPlugin().getSettingsAPI().getSetting(player.getUniqueId(), "actionbar-alerts", true);
    
    if (wantsAlerts) {
        player.sendActionBar("WARNING: A boss has spawned!");
    }
}
```

***

## Registering Custom GUI Toggles

You can inject your own custom toggles into the SentrySettings GUI. These toggles will automatically be saved to the database (H2/MySQL) just like native settings!

To do this, you implement the `CustomSetting` interface.

```java theme={null}
import me.sentrystudios.sentrysettings.api.SentrySettingsAPI;
import org.bukkit.entity.Player;
import org.bukkit.inventory.ItemStack;
import org.bukkit.Material;
import org.bukkit.inventory.meta.ItemMeta;

public class MyCustomToggle implements SentrySettingsAPI.CustomSetting {

    @Override
    public ItemStack getIcon(Player player) {
        // Build the icon that will be displayed in the GUI
        ItemStack icon = new ItemStack(Material.DIAMOND);
        ItemMeta meta = icon.getItemMeta();
        
        // You can use the API to dynamically change the lore based on their current state!
        boolean currentState = SentrySettings.getPlugin().getSettingsAPI().getSetting(player.getUniqueId(), "my-custom-toggle", false);
        meta.setDisplayName("My Custom Toggle: " + (currentState ? "§aON" : "§cOFF"));
        icon.setItemMeta(meta);
        
        return icon;
    }

    @Override
    public void onToggle(Player player) {
        // This is called when the player clicks your icon in the GUI!
        boolean currentState = SentrySettings.getPlugin().getSettingsAPI().getSetting(player.getUniqueId(), "my-custom-toggle", false);
        
        // Flip the state and save it to the database!
        SentrySettings.getPlugin().getSettingsAPI().setSetting(player.getUniqueId(), "my-custom-toggle", !currentState);
        
        player.sendMessage("You toggled the custom setting!");
    }
}
```

**Registering it with the API:**

```java theme={null}
// Once you've created your CustomSetting class, register it during your plugin's onEnable!
SentrySettings.getPlugin().getSettingsAPI().registerSetting("my-custom-toggle", new MyCustomToggle());
```