# API

## API

Read NPCs, react to clicks, add your own action types or draw the nameplates yourself.

## Maven Repository

```xml
<repositories>
    <repository>
        <id>phoenixplugins</id>
        <url>https://repo.phoenixplugins.com/repository/maven-public/</url>
    </repository>
</repositories>
```

## Dependency

```xml
<dependency>
    <groupId>com.phoenixplugins.phoenixnpcs</groupId>
    <artifactId>api</artifactId>
    <version>1.3.0</version>
</dependency>
```

## Getting started

Add PhoenixNPCs to your **plugin.yml** so your plugin loads after it.

```yaml
depend: [PhoenixNPCs]
```

Use `softdepend` instead if your plugin should still work without it, and check `PhoenixNPCsAPI.isAvailable()` before calling anything.

```java
if (!PhoenixNPCsAPI.isAvailable()) {
    return;
}

NpcPlugin npcs = PhoenixNPCsAPI.get();
```

| Method | Returns |
| ------ | ------- |
| `getNpc(String identifier)` | One NPC by its id, as an `Optional` |
| `getNpcs()` | Every loaded NPC |
| `getNpcsByGroup(String group)` | Every NPC in that [group](../features/groups.md) |
| `registerCondition(String prefix, String syntax, NpcConditionProvider provider)`, `unregisterCondition(String prefix)` | Adds or removes a condition prefix for show conditions, indicators and `[CONDITION]` |
| `createPersistent(String identifier, Location location)` | A saved NPC with a file, listed in the editor |
| `addAction(String identifier, NpcTrigger trigger, String action)` | Adds an action to a saved NPC, `false` if it does not exist |
| `registerAction(String type, String syntax, NpcActionHandler handler)` | Adds an action type, see below |
| `unregisterAction(String type)` | Removes an action type you added |
| `setNameplateProvider(NameplateProvider provider)` | Draws every nameplate and indicator with your own code, `null` to hide them. PhoenixNPCs sets its own PhoenixHolograms provider again when PhoenixHolograms enables or reloads |
| `create(Plugin owner, String identifier, Location location)` | A temporary NPC owned by your plugin, see below |
| `getHandle(String identifier)` | The handle of a temporary NPC, as an `Optional` |
| `remove(String identifier)`, `removeAll(Plugin owner)` | Removes one temporary NPC, or every one your plugin made |

> **Info:**
On Folia, click handlers, custom actions and `runActions` run on the player's own region thread. A `NameplateProvider`'s handles are called from several region threads, so keep them thread-safe.

## The NPC

| Method | Returns |
| ------ | ------- |
| `getIdentifier()`, `getDisplayName()`, `getGroup()`, `isEnabled()` | The NPC's settings |
| `getLocation()`, `getCurrentLocation()` | Where the NPC stands |
| `getNameplateLocation()` | Where its name is drawn |
| `getHeight()` | The height of its body, in blocks |
| `getViewerIds()` | The players who can see it now |
| `isVisibleTo(Player player)` | Whether that player can see it |
| `refreshNameplate()` | Redraws the name, for example after a placeholder changed |
| `runActions(Player player, List<String> actions)` | Runs [actions](../plugin-information/action-types.md) for a player as if this NPC ran them |

## Movement

`npc.getMovement()` walks the NPC with the same ground-following rules as [Movement](../features/movement.md). It works on saved and temporary NPCs.

| Method | Does |
| ------ | ---- |
| `startPath()`, `stopPath()` | Lets the NPC walk its mode again, or freezes it where it is |
| `isMoving()` | Whether it is walking, paused for a player or following |
| `follow(Player player)`, `stopFollowing()`, `getFollowing()` | Follows a player, stops, or the followed player's id |
| `moveTo(Location location)` | Walks to the location; the `CompletableFuture<Boolean>` completes `true` on arrival, `false` if there is no way there or another `moveTo` replaced it |

After `moveTo`, a standing NPC stays where it arrived; a path or wandering NPC goes back to its route.

```java
npc.getMovement().moveTo(target).thenAccept(arrived -> {
    if (arrived) {
        npc.runActions(player, Collections.singletonList("[MESSAGE] &aHere we are!"));
    }
});
```

## Custom Actions

A registered type shows in the editor's action builder and in `/pnpc edit <id> action`, with a single text field. The handler gets the NPC, the player and everything after the type. Return `false` to stop the actions after it.

```java
PhoenixNPCsAPI.get().registerAction("QUEST", "<quest>", (npc, player, argument) -> {
    return quests.start(player, argument);
});
```

Unregister it in your `onDisable`. An NPC that still lists a type nobody registered logs a warning when clicked and skips that action.

## Temporary NPCs

`create` shows an NPC that only lives while your plugin runs: it has no file, is not listed in the editor, `/pnpc list` or `getNpcs()`, and is removed when your plugin disables. Its id follows the [id rules](../plugin-information/commands.md#npc-ids) and cannot be one that already exists. Every call has to be made on a server thread: the main thread, or on Folia a region or the global region thread.

The returned `NpcHandle` changes it: `teleport`, `setSkin` (texture value and signature), `setSkinName`, `setEntityType`, `setLookAtPlayer`, `setScale` (0.1 to 10), `setGlowing`, `setVisibilityDistance`, `setDisplayName` (one string per line, a label only: no text shows above the NPC), `setVisibleTo` (per player), `setClickHandler` and `remove`. `isValid()` turns false once the NPC is gone.

Behaviour setters: `setEquipment` (a Bukkit `EquipmentSlot` and an item, `null` or air takes it off), `clearEquipment`, `setPose` (a Bukkit `Pose`), `getActions`, `addAction`, `setActions` and `clearActions` (per `NpcTrigger`: `LEFT`, `RIGHT`, `ANY` or `PROXIMITY`, each action written as in [Action Types](../plugin-information/action-types.md)), `setGroup` and `setShowConditions` ([conditions](../features/visibility.md#show-conditions) the viewer has to pass). An invalid slot, pose or condition throws `IllegalArgumentException`.

Appearance setters: `setProperty` (a [mob property](../main-features/appearance.md#mob-properties) key and value, `null` resets it), `setHitbox` (0 turns it off), `setSkinLayer`, `setIdleLook`, `setLookAtNpc`, `setRealisticLook`, `setNameplateOnHover` and `setTalkLines`. `Npc.speak(player, text, seconds)` shows a [speech bubble](../features/speech-bubbles.md) to one player on any NPC.

```java
NpcHandle guard = PhoenixNPCsAPI.get().create(this, "arena_guard", location);

guard.setSkinName("Notch");
guard.setDisplayName(Arrays.asList("&cArena Guard"));
guard.setClickHandler((npc, player, click) -> player.sendMessage("Good luck!"));
```

Source: https://www.phoenixplugins.com/docs/phoenix-npcs/api