AnimalHunger Plugin - API
Vlsq# AnimalHunger Developer API
## Overview
AnimalHunger now exposes two API layers:
1. `AnimalHungerProvider`
Recommended for new integrations.
2. `AnimalHungerAPI`
Legacy static facade kept for compatibility.
Main entry points:
- `animalhunger.animalhunger.api.AnimalHungerProvider`
- `animalhunger.animalhunger.api.service.AnimalHungerService`
- `animalhunger.animalhunger.api.model.AnimalSnapshot`
- `animalhunger.animalhunger.api.model.AnimalMutationResult`
## Softdepend
Add this to your `plugin.yml` if your plugin can integrate with AnimalHunger:
```yml
softdepend:
- AnimalHunger
```
## Getting The Service
```java
import animalhunger.animalhunger.api.AnimalHungerProvider;
import animalhunger.animalhunger.api.service.AnimalHungerService;
AnimalHungerProvider.getService().ifPresent(service -> {
service.getTrackedAnimals().forEach(snapshot -> {
getLogger().info(snapshot.getUniqueId() + " -> level " + snapshot.getLevel());
});
});
```
## Main Concepts
### `AnimalSnapshot`
Immutable developer-safe state object.
Fields available:
- UUID
- entity type
- hunger and max hunger
- level
- feed count
- bond
- resource count
- custom name
- name color
- tracked flag
- entity validity
- location snapshot
### `AnimalMutationResult`
Returned by mutation methods.
Contains:
- `isSuccess()`
- `getMessage()`
- `getSnapshot()`
Use it instead of guessing whether a write worked.
## Query Methods
Available on `AnimalHungerService`:
- `isTracked(UUID animalId)`
- `getAnimal(UUID animalId)`
- `getAnimal(Entity entity)`
- `getTrackedAnimals()`
- `getAnimalsOwnedBy(UUID playerId)`
- `findNearbyTrackedAnimals(Location center, double radius)`
- `getPluginVersion()`
- `getApiVersion()`
Example:
```java
service.findNearbyTrackedAnimals(player.getLocation(), 20.0).forEach(snapshot -> {
if (snapshot.getBondLevel() >= 75) {
player.sendMessage("Trusted animal nearby: " + snapshot.getEntityType());
}
});
```
## Mutation Methods
Safe write methods:
- `setHunger(UUID, int)`
- `setLevel(UUID, int)`
- `setBond(UUID, int)`
- `setResources(UUID, int)`
- `setCustomName(UUID, String)`
- `clearCustomName(UUID)`
- `setNameColor(UUID, ChatColor)`
- `save(UUID)`
- `delete(UUID)`
Example:
```java
service.setBond(animalId, 100).getSnapshot().ifPresent(snapshot -> {
player.sendMessage("Bond is now " + snapshot.getBondLevel() + "%");
});
```
## Legacy Static API
`AnimalHungerAPI` still works and now delegates to the new provider.
Useful compatibility methods:
- `AnimalHungerAPI.isAvailable()`
- `AnimalHungerAPI.getService()`
- `AnimalHungerAPI.getAnimalSnapshot(UUID)`
- `AnimalHungerAPI.getTrackedAnimals()`
- `AnimalHungerAPI.setHunger(UUID, int)`
- `AnimalHungerAPI.setBond(UUID, int)`
- `AnimalHungerAPI.setLevel(UUID, int)`
- `AnimalHungerAPI.setResources(UUID, int)`
## Bukkit Events
Current public events:
- `AnimalFedEvent`
- `AnimalHungerUpdateEvent`
- `AnimalLevelUpEvent`
Base class:
- `AnimalHungerEvent`
### Listening Example
```java
import animalhunger.animalhunger.api.event.AnimalLevelUpEvent;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;
public final class AnimalListener implements Listener {
@EventHandler
public void onLevelUp(AnimalLevelUpEvent event) {
getLogger().info(event.getAnimal().getType() + " -> " + event.getNewLevel());
}
}
```
### Cancelling Example
```java
import animalhunger.animalhunger.api.event.AnimalFedEvent;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;
public final class FeedLimiter implements Listener {
@EventHandler
public void onFeed(AnimalFedEvent event) {
if (event.getAnimal().getLocation().getWorld().getName().equalsIgnoreCase("spawn")) {
event.setCancelled(true);
}
}
}
```
## Quest API
Quest helpers remain available through `QuestManager` and `AnimalHungerAPI`:
- `isQuestCompleted`
- `completeQuest`
- `getCompletedQuestsCount`
- `getCompletedQuests`
- `getPlayerQuestData`
- `resetPlayerQuests`
## PlaceholderAPI
Identifier:
```text
%animalhunger_<placeholder>%
```
Examples from config:
- `%animalhunger_hunger%`
- `%animalhunger_max_hunger%`
- `%animalhunger_level%`
- `%animalhunger_bond%`
- `%animalhunger_resources%`
- `%animalhunger_hunger_bar%`
The expansion reads the last animal a player interacted with.
## Threading Notes
- Treat Bukkit entities and world operations as main-thread work.
- `AnimalSnapshot` is safe to store and read later.
- Do not keep references to internal `AnimalData` for long-lived external state.
- Prefer the new provider service instead of mutating plugin internals directly.
## Compatibility Notes
- Plugin code targets Java 17.
- Actual server runtime requirements depend on the Paper/Spigot version you deploy on.
- The new API is designed to stay stable even if internal storage and managers are refactored later.