> For the complete documentation index, see [llms.txt](https://simplymines.gitbook.io/simplymines-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://simplymines.gitbook.io/simplymines-docs/introduction/api-developer-guide/requirements-api.md).

# Requirements API

## Requirements API

Requirements come in two flavors. See [Mine and Reset Requirements](/simplymines-docs/introduction/configuration/mine-and-reset-requirements.md) for the conceptual overview. Both are managed through `SimplyMinesAPI`.

### Mine requirements

Gate whether a player can break blocks in a mine.

```java
// Generic access
List<IMineRequirement> requirements = api.getMineRequirements("diamond");
IMineRequirement req = api.getMineRequirement("diamond", PermissionMineRequirement.class);

api.addMineRequirement("diamond", myCustomRequirement);
api.removeMineRequirement("diamond", myCustomRequirement);

// Convenience helpers — attach-or-update, enabled by default
api.setPermissionRequirement("diamond", "myserver.mines.diamond");
api.setEfficiencyRequirement("diamond", 3);   // requires Efficiency III+
```

***

### Reset requirements

Decide when a mine resets.

```java
List<IResetRequirement> requirements = api.getResetRequirements("diamond");
IResetRequirement req = api.getResetRequirement("diamond", TimeResetRequirement.class);

api.addResetRequirement("diamond", myCustomRequirement);
api.removeResetRequirement("diamond", myCustomRequirement);

// Convenience helpers — attach-or-update
api.setTimeResetRequirement("diamond", 600);        // reset every 10 minutes
api.setPercentResetRequirement("diamond", 20.0);    // reset once 20% is left (enabled by default)
```

***

### Custom requirements

You can register your own `IMineRequirement` / `IResetRequirement` implementations so SimplyMines can save and load them to/from a mine's JSON file, just like the built-in ones.

```java
public void onEnable() {
    SimplyMinesAPI api = SimplyMinesAPI.getInstance();

    api.registerMineRequirement(MyRequirement.NAME, MyRequirement::deserialize);
    api.registerResetRequirement(MyResetRequirement.NAME, MyResetRequirement::deserialize);
}
```

Requirements:

* Your class must implement `IMineRequirement` or `IResetRequirement`.
* It must expose a `public static final String NAME` field — this is the id used both when registering the factory and when persisting to JSON.
* Register your factory during `onEnable`, before mines are loaded from disk — declare SimplyMines as a hard `depend` (not `softdepend`) in your `plugin.yml` so load order is guaranteed, and register early in your `onEnable`.

{% hint style="danger" %}
If a mine's JSON file references a requirement id that no plugin has registered a factory for (e.g. your integration plugin isn't installed), that requirement is skipped when the mine loads.
{% endhint %}


---

# 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 dynamically by asking a question.

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

```
GET https://simplymines.gitbook.io/simplymines-docs/introduction/api-developer-guide/requirements-api.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.