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>/*.json

• 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 / URL / .yml file / PlaceholderAPI)
• “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
• Goals

For detailed information on setting skins, see the Skins guide.

Click Actions (Left / Right / Both)

In the NPC GUI go to Click Action.

You can configure actions separately for:

• Left click
• Right click
• Both (combined)

You can create an action chain by adding multiple actions.

Action editing tips

• Remove an action: middle-click an existing action.
• Add actions quickly: 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>

• List points:

  • /npc path point list [page]

• Visualize / toggle visualization of current points:

  • /npc path visualize points

• 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

• Walk the route.

• Stop recording:

  • /npc path record stop

• 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

• Walk to Location: NPC walks to a specific location using pathfinding
• Walk Path: NPC walks along a saved path
• Follow Entity: NPC follows a target entity by UUID
• Attack Entity: NPC attacks nearby matching entities
• Look Around: NPC looks around randomly (idle behavior)
• Wait: 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> [location] [rotation]
• /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 check-valid-path [true|false]
• /npc config walking-viewer-distance [distance]
• /npc config precise-sleeping-hitbox [true|false]
• /npc config load-chunks-on-path [true|false]
• /npc config name-display
• /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.
  • placeholder-timer:
    • Time in ticks between placeholder refreshes.
  • check-path:
    • Checks if a path is valid (solid block beneath the path)
  • walking-viewer-distance:
    • Distance in blocks at which players can see NPCs walking
  • precise-sleeping-hitbox:
    • If true, uses precise hitbox detection for sleeping NPCs
  • load-chunks-on-path:
    • If true, loads chunks on the path of the NPCs

Troubleshooting

• “This plugin does not support Paper servers!”
  • You are running the Spigot build on a Paper server. Install the Paper build instead.
  • Server action does nothing
    • 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

To use this plugin’s events in Skript, you need Skript-Reflect

Basic usage

import:
  de.eisi05.npc.api.events.<EventName>

on <EventName>:
    # your code here

Replace <EventName> with one of the events listed below.

Available Events

NpcHideEvent

Triggered after an NPC is hidden from a player.

Available values:

• event.getNpc() → NPC
• event.getPlayer() → Player

NpcInteractEvent

Triggered when a player interacts with an NPC.

Available values:

• event.getNpc() → NPC
• event.getPlayer() → Player
• event.getAction() → ClickActionType (LEFT / RIGHT)
• event.isCancelled() → boolean

NpcPostShowEvent

Called after an NPC is fully visible to a player.

Note: This event cannot be cancelled.

Available values:

• event.getNpc() → NPC
• event.getPlayer() → Player
• event.wasViewer() → boolean (true if the player already saw this NPC before)

NpcPreShowEvent

Called before an NPC is shown to a player.

Note: This event can be cancelled.

Available values:

• event.getNpc() → NPC
• event.getPlayer() → Player
• event.wasViewer() → boolean
• event.isCancelled() → boolean

NpcStartWalkingEvent

Called before an NPC starts walking along a path.

Available values:

• event.getNpc() → NPC
• event.getPath() → Path
• event.getWalkSpeed() → double
• event.isChangeRealLocation() → boolean (whether real NPC location will update)
• event.isCancelled() → boolean

NpcStopWalkingEvent

Called after an NPC stops walking.

Available values:

• event.getNpc() → NPC
• event.getWalkingResult() → WalkingResult (SUCCESS / CANCELLED)
• event.changeRealLocation() → boolean (whether final position should be applied)

Example

You can also directly access Java methods inside Skript like this:

import:
  de.eisi05.npc.api.events.NpcInteractEvent

on NpcInteractEvent:
    set {_player} to event.getPlayer()
    send "Triggered!" to {_player}

Additional Resources

For more information about Skript-Reflect syntax and features, visit:
https://tpgamesnl.gitbook.io/skript-reflect/basics