# service access

PracticeBot registers its public API through Bukkit `ServicesManager`.

## Recommended access

```java
import com.sheldera.practicebot.api.PracticeBotApi;
import com.sheldera.practicebot.api.PracticeBotApiProvider;

PracticeBotApi api = PracticeBotApiProvider.get();
```

`PracticeBotApiProvider.get()` throws `IllegalStateException` if the service is not available.

## Optional integration access

For soft dependencies:

```java
import com.sheldera.practicebot.api.PracticeBotApi;
import org.bukkit.Bukkit;
import org.bukkit.plugin.RegisteredServiceProvider;

public PracticeBotApi resolvePracticeBotApiOrNull() {
    RegisteredServiceProvider<PracticeBotApi> provider =
            Bukkit.getServicesManager().getRegistration(PracticeBotApi.class);

    return provider == null ? null : provider.getProvider();
}
```

## Startup guidance

Use this pattern:

```java
@Override
public void onEnable() {
    PracticeBotApi api = PracticeBotApiProvider.get();
    getLogger().info("Connected to PracticeBot API " + api.getApiVersion());
}
```

For optional integration:

```java
@Override
public void onEnable() {
    PracticeBotApi api = resolvePracticeBotApiOrNull();
    if (api == null) {
        getLogger().info("PracticeBot not found; integration disabled.");
        return;
    }

    getLogger().info("Connected to PracticeBot API " + api.getApiVersion());
}
```

## Error handling

The API may throw:

| Exception                  | Common cause                                                                                    |
| -------------------------- | ----------------------------------------------------------------------------------------------- |
| `IllegalStateException`    | PracticeBot not loaded, license not active, Citizens not ready, wrong bot type, async API call. |
| `IllegalArgumentException` | Invalid template key, invalid target, unknown NPC UUID, invalid metadata value.                 |
| `NullPointerException`     | Passing `null` to a method requiring non-null input.                                            |

Handle these failures in admin-facing commands and avoid exposing raw exceptions to players.


---

# 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://edelweiss-network.gitbook.io/practicebot/service-access.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.