> For the complete documentation index, see [llms.txt](https://opuszek.gitbook.io/itemblocker/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://opuszek.gitbook.io/itemblocker/developers/api.md).

# API

Other plugins can check ItemBlocker's rules, add temporary rules and let blocked actions through. This is useful for plugins with their own ranks, quests and game modes.

## Dependency

ItemBlocker is published through [JitPack](https://jitpack.io/#kuqk/ItemBlocker). Use the tag of a release, such as `v2.6.3`.

{% tabs %}
{% tab title="Gradle (Kotlin)" %}

```kotlin
repositories {
    maven("https://jitpack.io")
}

dependencies {
    compileOnly("com.github.kuqk:ItemBlocker:v2.6.3")
}
```

{% endtab %}

{% tab title="Maven" %}

```xml
<repositories>
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
</repositories>

<dependency>
    <groupId>com.github.kuqk</groupId>
    <artifactId>ItemBlocker</artifactId>
    <version>v2.6.3</version>
    <scope>provided</scope>
</dependency>
```

{% endtab %}
{% endtabs %}

In your `plugin.yml`:

```yaml
depend: [ItemBlocker]      # or softdepend, if your plugin also works without it
```

## Getting the API

```java
ItemBlockerApi api = ItemBlockerApi.get();
```

`get()` throws `IllegalStateException` when ItemBlocker is not enabled. The API is also registered with the services manager:

```java
ItemBlockerApi api = Bukkit.getServicesManager().load(ItemBlockerApi.class);
```

## Checking rules

```java
Optional<Restriction> restriction = api.check(player, item, Action.USE);
boolean blocked = api.isBlocked(player, item, Action.PLACE);
Optional<Restriction> forHopper = api.check(item, Action.HOPPER, location);
```

`check` uses the same rules, bypass permissions, exceptions and enchantment limits as the plugin. The version with a location has no player, so bypass permissions do not apply.

`Restriction` tells why something is blocked:

| Method      | Returns                                                                    |
| ----------- | -------------------------------------------------------------------------- |
| `action()`  | What is blocked, such as `place`, `enchanted-item` or `enchanting`         |
| `subject()` | The item, or the enchantment or effect with its level, as shown to players |
| `preset()`  | The name of the preset whose rule blocks it                                |
| `reason()`  | The preset's reason, possibly empty                                        |

`Action` is `pl.variant.itemblocker.rule.Action`, with one constant per [action](/itemblocker/rules/actions.md), such as `Action.USE` or `Action.ENTITY_DROP`.

## Temporary rules

Temporary rules live in memory only: they are never written to `rules.yml` and end when the server stops.

```java
// Everyone
TemporaryRule event = api.blockTemporarily(Material.ELYTRA, Set.of(Action.ARMOR), "Elytras are off during the race");

// One player, until the rule is removed or the player leaves
TemporaryRule quest = api.blockTemporarily(player, Material.ENDER_PEARL, Set.of(Action.USE), "Not during the quest");

quest.remove();
quest.isActive();   // false
```

The reason is shown to players like a preset's reason and may be empty.

## Letting actions through

`ItemBlockedEvent` is called before anything is blocked for a player. Cancel it to let the action through:

```java
@EventHandler
public void onBlocked(ItemBlockedEvent event) {
    if (minigame.isPlaying(event.getPlayer())) {
        event.setCancelled(true);
    }
}
```

| Method             | Returns                                                         |
| ------------------ | --------------------------------------------------------------- |
| `getPlayer()`      | The player                                                      |
| `getItem()`        | A copy of the item, or `null` for enchanting and potion effects |
| `getRestriction()` | The `Restriction`, as above                                     |

The event is called for every check involving a player: items, enchanted items, enchanting, potion effects and scans of a player's items. It is not called for actions without a player, such as hoppers or mob drops. On Folia it is called on the player's region thread.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://opuszek.gitbook.io/itemblocker/developers/api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.