# Developer Overview
Bookshelf is a shared utility library for the Lodestone plugin ecosystem. It provides common systems that other plugins build on top of, including a menu framework, custom item registry, scoreboard abstraction, cooldown manager, configuration wrappers, and MiniMessage helpers. Instead of reimplementing these utilities in every plugin, you depend on Bookshelf and use its API.
---
## Maven / Gradle
The Bookshelf-API artifact is available through JitPack. Add it as a `compileOnly` / `provided` dependency so that Bookshelf is not shaded into your plugin jar.
> [!tip] Shading
> If you prefer not to require Bookshelf as a server plugin, you may shade the API directly into your jar instead of using `compileOnly` / `provided`.
**Repository:**
*Gradle (Kotlin DSL):*
```kotlin
repositories {
maven("https://jitpack.io")
}
```
*Maven:*
```xml
<repository>
<id>jitpack.io</id>
<url>https://jitpack.io</url>
</repository>
```
**Dependency:**
*Gradle (Kotlin DSL):*
```kotlin
compileOnly("com.github.Lodestones:Bookshelf-API:1.2.0")
```
*Maven:*
```xml
<dependency>
<groupId>com.github.Lodestones</groupId>
<artifactId>Bookshelf-API</artifactId>
<version>1.2.0</version>
<scope>provided</scope>
</dependency>
```
Add `Bookshelf` as a `depend` or `softdepend` in your `plugin.yml`:
```yaml
depend:
- Bookshelf
```
Or, if Bookshelf is optional for your plugin:
```yaml
softdepend:
- Bookshelf
```
---
## Accessing the API
The API is accessed through the static `BookshelfAPI` class. The API instance is available after Bookshelf has been enabled.
```java
import gg.lode.bookshelfapi.BookshelfAPI;
import gg.lode.bookshelfapi.IBookshelfAPI;
IBookshelfAPI api = BookshelfAPI.getApi();
if (api == null) {
// Bookshelf is not loaded
return;
}
```
If you are shading Bookshelf rather than depending on the server plugin, initialise the API manually during your plugin's `onEnable`:
```java
BookshelfAPI.init(this); // pass your JavaPlugin instance
```
---
## Common Operations
### Menu Creation
Extend `Menu` to build interactive inventory menus. `Menu` implements `InventoryHolder`. Use `TopMenuBuilder` to define the layout.
```java
public class MyMenu extends Menu {
@Override
protected @NotNull TopMenuBuilder getTopMenuBuilder(TopMenuBuilder builder) {
return builder
.setTitle(title)
.setRows(3)
.fill(background)
.set(row, col, itemStack, event -> {
// handle click
});
}
}
```
### Cooldowns
```java
ICooldownManager cooldowns = api.getCooldownManager();
// Apply a 5-second cooldown
cooldowns.setCooldown(player, "ability_fireball", 5000);
// Check remaining time
if (cooldowns.hasCooldown(player, "ability_fireball")) {
long remaining = cooldowns.getCooldown(player, "ability_fireball");
}
```
### Custom Items
Register and retrieve custom items through the item manager.
```java
ICustomItemManager items = api.getCustomItemManager();
CustomItem sword = items.getItem("my_custom_sword");
```
### Scoreboard
Create per-player scoreboards using the board API.
```java
IBoard board = api.createBoard(player);
board.setTitle("My Scoreboard");
board.setLine(0, "Line one");
board.setLine(1, "Line two");
```
### Configuration
Wrap a plugin config for convenient typed access.
```java
plugin.config().getInt("path.to.value", defaultValue);
plugin.config().getString("path.to.value", "default");
plugin.config().getDouble("path.to.value", defaultValue);
```
---
## Related Pages
- [[Bookshelf/Developers/API Reference]] — Full interface documentation