# Setup

[![Package](https://img.shields.io/maven-metadata/v?metadataUrl=https://repo.incredibleplugins.com/releases/com/incredibleplugins/lands-api/maven-metadata.xml)](https://repo.incredibleplugins.com/#/releases/com/incredibleplugins/lands-api)

The API is in our repository: [repo.incredibleplugins.com](https://repo.incredibleplugins.com/#/releases/com/incredibleplugins/lands-api)

## Javadoc

The Javadoc can be found here: [repo.incredibleplugins.com](https://repo.incredibleplugins.com/javadoc/releases/com/incredibleplugins/lands-api/latest)

## API Usage Explained

First, include the API in your build file. Example snippets for your build file can be found here: [Maven, Gradle, SBT](https://repo.incredibleplugins.com/#/releases/com/incredibleplugins/lands-api)

> You can also download the API file from there, if you want to add it to your libraries manually.

The API is accessible through an implementation of the `LandsIntegration` interface. It is recommended to bind this instance to a variable of a singleton class, if possible.

```java
LandsIntegration api = LandsIntegration.of(plugin);
```

**Common Use-Cases**

1. Checking Role-Flag States for Players\
   Using [LandWorld](https://javadoc.jitpack.io/com/github/angeschossen/LandsAPI/7.10.6/javadoc/me/angeschossen/lands/api/land/LandWorld.html) to check flag states has the benefit that it also checks wilderness flags. Some use cases might not intent that. In this case you can use [LandsIntegration#getArea(location)](https://javadoc.jitpack.io/com/github/angeschossen/LandsAPI/7.10.6/javadoc/me/angeschossen/lands/api/LandsIntegration.html#getArea\(org.bukkit.Location\)) and check the flag state of the area instead.

   ```java
   LandWorld world = api.getWorld(world);
   if (world != null) { // Lands is enabled in this world
       if (world.hasFlag(api.getLandPlayer(player), location, material, Flags.BLOCK_BREAK, false)) {
           // the player is allowed to break blocks with the given material at the given location
       } else {
           // the player isn't allowed to break this block in wilderness or a claimed land at this position
       }
   }
   ```
2. Checking Natural-Flag States\
   [LandWorld](https://javadoc.jitpack.io/com/github/angeschossen/LandsAPI/7.10.6/javadoc/me/angeschossen/lands/api/land/LandWorld.html) does check wilderness and claimed lands if applicable. If you want to limit the check to claimed land, use [LandsIntegration#getArea(location)](https://javadoc.jitpack.io/com/github/angeschossen/LandsAPI/7.10.6/javadoc/me/angeschossen/lands/api/LandsIntegration.html#getArea\(org.bukkit.Location\)) instead of getting the world.

   ```java
   LandWorld world = api.getWorld(world);
   if (world != null) { // Lands is enabled in this world
       if (world.hasNaturalFlag(location, Flags.MONSTER_SPAWN)) {
           // monsters are allowed to spawn at this location
       } else {
           // they aren't allowed to spawn at this location
       }
   }
   ```
3. Registering custom Flags\
   This one is simple as well. Just use the factory methods of the needed flag type's interface: [RoleFlag.of(...)](https://javadoc.jitpack.io/com/github/angeschossen/LandsAPI/7.10.6/javadoc/me/angeschossen/lands/api/flags/type/RoleFlag.html#of\(me.angeschossen.lands.api.LandsIntegration,me.angeschossen.lands.api.flags.enums.FlagTarget,me.angeschossen.lands.api.flags.enums.RoleFlagCategory,java.lang.String\)), [NaturalFlag.of(...)](https://javadoc.jitpack.io/com/github/angeschossen/LandsAPI/7.10.6/javadoc/me/angeschossen/lands/api/flags/type/NaturalFlag.html#of\(me.angeschossen.lands.api.LandsIntegration,me.angeschossen.lands.api.flags.enums.FlagTarget,java.lang.String\)) etc. Please note that flags need to registered after Lands was loaded, but before Lands enables. You can ensure that, by using this method in your `onLoad` method of your plugins main class: [LandsIntegration#onLoad](https://javadoc.jitpack.io/com/github/angeschossen/LandsAPI/7.10.6/javadoc/me/angeschossen/lands/api/LandsIntegration.html#onLoad\(java.lang.Runnable\))

   ```java
   RoleFlag flag = RoleFlag.of(api, FlagTarget.PLAYER, RoleFlagCategory.ACTION, "flag_name");
   ```

   It is recommended to set further attributes:

   ```java
   flag.setDisplayName("Name")
       .setIcon(itemstack)
       .setDescription(description);
   ```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://wiki.incredibleplugins.com/lands/developers/api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.