> For the complete documentation index, see [llms.txt](https://territory.athelion.eu/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://territory.athelion.eu/api/custom-flags.md).

# Custom Flags

Custom flags allow developers to define unique behaviors and rules for claimed lands. Flags can trigger events, control land mechanics, and integrate with other plugin features. This section explains how to create, register, and configure a custom flag.

### 1. Creating a Custom Flag

Custom flags extend the `Flag` class and override its methods. Here's an example:

```java
public class CustomFlag extends Flag {
    @EventHandler
    public void onBlockBreak(BlockBreakEvent event) {
        // Check if the block's location belongs to a claimed land
        getLand(event.getBlock().getLocation()).ifPresent(land -> {
            // If the flag is enabled, notify the player
            if (hasEnabled(land)) {
                event.getPlayer().sendMessage("Breaking " + event.getBlock().getType().name());
            }
        });
    }

    @Override
    public String getFlagName() {
        // Define a unique name for your custom flag
        return "EXAMPLE_CUSTOM_FLAG";
    }
}
```

**Explanation**:

* **`onBlockBreak`**: A sample event handler that interacts with the flag's state (`hasEnabled`).
* **`getFlagName`**: A unique identifier for the flag, required for registration.

### 2. Registering a Custom Flag

After defining the custom flag, it must be registered to integrate with the plugin. Here's how to do it:

```java
Territory.registerFlag(
    "EXAMPLE_CUSTOM_FLAG",                        // Unique key for the flag
    CustomFlag.class,                     // Class of the custom flag
    new HashMap<>() {{
        put("item", "PAPER");             // Item representing the flag in the GUI
        put("position", 40);              // Slot position in the flag menu
        put("name", "&aCustom Example Flag");  // Display name in the GUI
        // Description/lore
        // %status% will be automaticaly replaced with status values from lang.yml
        put("lore", Arrays.asList("&7Logs mined blocks", "", "%status%"));
    }}
);
```

**Metadata Breakdown**:

* **`item`**: The item used to represent the flag in the flag menu (e.g., `"PAPER"`).
* **`position`**: The slot index in the flag menu where the flag appears.
* **`name`**: The display name of the flag, supports color codes.
* **`lore`**: A list of strings for the flag's description, also supports color codes.