NPC Plugin

Installation

1. Download the jar and place it into your server’s `plugins/` folder. 2. Start the server once. 3. Configure (optional): - `plugins/NpcPlugin/config.yml` - `plugins/NpcPlugin/lang/<language>/*.yml` 4. Restart or run `/npc reload`.

Quick Start

1) Create an NPC

- `/npc create`

2) Enable edit-mode

- `/npc edit`

While edit-mode is enabled:

- Interact with an NPC to open its editor GUI.

If the NPC is not editable, you’ll get a message like `This NPC is not editable!`.

3) Configure NPC options in the GUI

The GUI lets you change things like:

- Name - Skin (player name / UUID / local `.png` file) - “Use Player Skin” (per-player skin) - Equipment slots - Visibility / enabled state - Tab list visibility - Hide nametag - Pose - Skin parts - Glowing + color - Look-at-player radius / interval - Scale - Teleport to NPC / teleport NPC to you - Delete NPC

Click Actions (Left / Right / Both)

In the NPC GUI go to Click Action.

You can configure actions separately for:

- Both - Both - Both (combined)

You can create an action chain by adding multiple actions.

Action editing tips

- Reorder / insert: middle-click an existing action. - Reorder / insert: shift-click an action type to append it. - Reorder / insert: pick up an action type onto your cursor and click a slot.

Common action types

`Command`

Executes a command.

- Input can be with or without leading `/` (the plugin stores it as `/<command>`). - Placeholders supported: - `{player}` / `%player%` / `<player>` - `{player_name}` / `%player_name%` / `<player_name>` - Supports variables/expressions via the plugin action system. - There is optional syntax validation.

Example:

- `warp spawn` - `server hub` - `msg {player} Welcome!`

`Server` (BungeeCord)

Sends the player to another BungeeCord server.

Example server name:

- `hub`

`Wait`

Pauses the chain before continuing.

You can switch between two modes in the editor:

##### Time mode

- Left/Right click to adjust the time - Shift+Left/Shift+Right for bigger steps - Range is clamped (min `0.05s`, max `600s`)

##### Command mode

Instead of waiting for time, the chain waits until an admin triggers it:

- `Wait` stores a name (string) - The chain continues only after: - `/npc wait <player> <name> [values...]`

If `[values...]` are provided, they are exposed to the next actions as local variables:

- `<name>-0`, `<name>-1`, ... (numeric values; invalid numbers become `0.0`)

This is useful to wait for external systems (minigames, scripted events, etc.).

##### Note (Path)

The `Path` action also uses the same wait mechanism internally: the chain continues when the NPC finishes walking.

`Path`

Makes the NPC walk along a saved path.

- You pick a path name (must exist; same world) + a speed (`0.01`–`1.0`). - Optional flags: - For all (everyone sees the NPC walking) - Change real location (updates the NPC's real location while walking)

`Animation`

Plays an animation on the NPC for the clicking player.

- Left click: next animation - Right click: previous animation

`SetVariable`

Sets a numeric variable.

- Type: - Local (stored per-player) - Instance (stored on the NPC) - Global (stored server-wide; persisted in `global-variables.yml`) - Name must match `^[a-zA-Z_][a-zA-Z0-9_-]*$` - Value is an expression

If the value is missing, the action does nothing (admins get a warning).

`Condition`

Runs a sub-chain only if its expression is `true`.

- You edit the sub-chain like a normal action list - The condition expression is edited via the "value" item

`Loop`

Repeats a sub-chain.

There are two loop types:

##### While-loop

- Repeats while the expression is `true`

##### For-loop

- Repeats with an integer loop index - Configurable values: - Start (optional; default `0`) - End (required) - Step (optional; default `1`)

You can change the loop type by Shift-clicking the action.

`Npc`

Opens a special editor that lets you apply NPC options *as an action*.

This is mainly used to change how the NPC looks/behaves for:

- Only the clicking player (per-player override) - Everyone (global)

Two flags exist:

- Change globally: applies the configured options to the NPC’s global options - Reset to default: removes per-player overrides and resets to the NPC’s defaults

`Stop`

Stops the current chain immediately (and stops nested chains too).

Run-on-show

In the action editor you can enable Run on show.

If enabled, the chain triggers when the NPC is shown to a player (not only when clicked).

Path System Guide

Paths are shared and stored in:

- `plugins/NpcPlugin/paths.yml`

Create a path from points

1. Add points at your current location: - `/npc path point add`

Or add at a specific index: - `/npc path point add <index>`

2. List points: - `/npc path point list [page]`

3. Visualize / toggle visualization of current points: - `/npc path visualize points`

4. Create the path: - `/npc path create <name> [maxIterations] [allowDiagonalMovement]`

After creation you can visualize it:

- `/npc path visualize <name>`

Record a path by walking

1. Start recording: - `/npc path record start`

2. Walk the route.

3. Stop recording: - `/npc path record stop`

4. Create the path: - `/npc path create <name>`

Edit an existing path

- `/npc path edit <name>`

This loads the saved path’s waypoints into the point list so you can remove/add points and re-create it.

List / delete / test paths

- `/npc path list [page]` - `/npc path delete <name>` - `/npc path test <name> [speed]`

Goals Guide

Goals give NPCs autonomous behavior. Configure them via the NPC editor GUI.

Available Goals

- Wander: NPC walks to a specific location using pathfinding - Wander: NPC follows a target entity by UUID - Wander: NPC attacks nearby matching entities - Wander: NPC looks around randomly (idle behavior) - Wander: NPC waits for a specified duration - Wander: NPC wanders randomly within a radius

Attack Entity Predicates

Target entities using expressions with variables:

- `$distance` - Distance to NPC - `$entity.x`, `$entity.y`, `$entity.z` - Entity position - `$entity.health` - Entity health - `$npc.x`, `$npc.y`, `$npc.z` - NPC position - `[if entity @s[type=zombie]]` - Command-based entity type check

Example predicates: - `$distance < 5` - Only attack within 5 blocks - `$entity.health < 10` - Attack low health entities - `$distance < 10 && $entity.health > 5` - Combined conditions

For more details, see the full Goals documentation.

Expression Parser Guide

Use mathematical expressions in click actions, goal conditions, and variable calculations.

Supported Elements

Operators: `+`, `-`, `*`, `/`, `^` (power), `&&`, `||`, `!`, `==`, `!=`, `<`, `>`, `<=`, `>=`

Math Functions: `sin()`, `cos()`, `tan()`, `sqrt()`, `log()`, `exp()`, `ceil()`, `floor()`, `round()`, `trunc()`, `abs()`

Constants: `PI`, `E`

Variables

- `$varName` - Auto-resolve (local → instance → global) - `$global.varName` - Server-wide variable - `$instance.varName` - NPC-specific variable - `$local.varName` - Player-specific variable

Special Variables: - `$self.rightClick` / `$self.leftClick` - Click type (1 or 0) - `$self.sneaking`, `$self.flying`, `$self.op` - Player state - `$loop.index` - Loop iteration index

Command Execution

- `(/command)` - Execute command inside expression - `/command` - Standalone command execution

Examples: - `2 + (/count players)` - Use command result in calculation - `$global.score + 1` - Increment variable - `($entity.health < 10) * 5` - Conditional value

For the full syntax reference, see the Expression Parser documentation.

Commands

Core

- `/npc create` - `/npc copy <uuid>` - `/npc edit` (toggle edit-mode) - `/npc list` (opens NPC list GUI) - `/npc tp <uuid>` - `/npc tphere <uuid>` - `/npc reload` - `/npc version` - `/npc update` (checks for a new plugin version)

Config

- `/npc config reload` - `/npc config debug [true|false]` - `/npc config avoid-command-check [true|false]` - `/npc config look-at-update-interval [ticks]` - `/npc config input-time [seconds]` - `/npc config auto-update [true|false]` - `/npc config placeholder-timer [ticks]` - `/npc config list`

Exceptions (startup load failures)

- `/npc exceptions [page]` - `/npc exceptions show <name>` - `/npc exceptions delete <name>`

Paths

All path commands are under:

- `/npc path ...`

Main subcommands:

- `point add [index] [location] [rotation]` - `point remove [index|location]` - `point list [page]` - `point clear` - `create [name] [maxIterations] [allowDiagonalMovement]` - `delete <name>` - `list [page]` - `visualize [name]` - `visualize points` - `record start|stop` - `test <name> [speed]` - `edit <name>`

Variables

Manage server-wide global variables via commands:

- `/npc variable list` - List all global variables - `/npc variable get <name>` - Get a variable's value - `/npc variable set <name> <expression>` - Set a variable (supports expressions) - `/npc variable delete <name>` - Delete a variable

Variables can also be managed via the SetVariable click action and used in expressions throughout the plugin.

Configuration (`config.yml`)

- `look-at-update-interval`: - Time in ticks between “look at player” updates. - `avoid-command-check`: - If `true`, commands added to NPC actions will not be strictly validated. - `debug`: - Enables extra debug logging. - `input-time`: - Conversation timeout in seconds (if `< 0`, no timeout). - `auto-update`: - Automatically updates NPCs after option changes. - `placeholderTimer`: - Time in ticks between placeholder refreshes.

Troubleshooting

- Can’t open the editor GUI - You are running the Can’t open the editor GUI build on a Can’t open the editor GUI server. Install the Paper build instead. - Can’t open the editor GUI - Ensure BungeeCord is set up and the server names match your proxy configuration. - Can’t open the editor GUI - Make sure you: - Have `npc.admin` - Enabled edit-mode via `/npc edit` - The NPC is marked as editable