# NpcPlugin<\/p>\n
Create, customize, and manage player-like NPCs with an in-game editor GUI, click actions, AI goals, and a built-in path system.<\/p>\n
> ## \u26a0\ufe0f Alpha Notice \u26a0\ufe0f
\n>
\n> The alpha version allows you to add entity AI goals to NPCs.
\n> It is not fully tested yet and may be unstable.
\n>
\n> If you encounter any issues, bugs, or have feature suggestions, feel free to contact me.<\/p>\n
**If you have any suggestions or encounter any issues, you can use the issue page or via Discord @Eisi05**<\/p>\n
*If you want to make a tutorial video about it, feel free to do so*<\/p>\n
## Supported Versions<\/p>\n
> **Spigot**: *1.17.1 – 26.1.2*
\n>
\n> **Paper**: *1.21 – 26.1.2*<\/p>\n
## Overview<\/p>\n
– **In-game editor**: create and configure NPCs directly on your server.
\n– **Click Actions**: build action chains for left\/right\/both clicks.
\n– **Path system**: create and reuse paths (including visualization + testing).<\/p>\n
## Getting Started<\/p>\n
– `\/npc create`
\n– `\/npc edit`
\n– Right-click an NPC to open its editor.<\/p>\n
## Links<\/p>\n
– **Plugin docs**: https:\/\/github.com\/Eisi05\/NpcPlugin-Spigot\/wiki
\n– **API \/ Developer docs**:
\n – Spigot: https:\/\/github.com\/Eisi05\/NpcApi-Spigot\/wiki
\n – Paper: https:\/\/github.com\/Eisi05\/NpcApi-Paper\/wiki<\/p>\n
## Highlights<\/p>\n
– **In-game NPC editor**
\n – Toggle edit-mode and configure NPCs directly by interacting with them.
\n – Edit common properties like name, skin, equipment, glow, visibility, tab-list, pose, and more.
\n– **Click Actions (Left \/ Right \/ Both)**
\n – Build action chains that run when players click an NPC.
\n – Built-in action types include:
\n – `Command` (run commands with placeholders + variables)
\n – `Server` (send players to a BungeeCord server)
\n – `Wait` (wait by time *or* by command trigger)
\n – `Animation` (play an animation)
\n – `Path` (make the NPC walk along a saved path)
\n – `SetVariable` (set local\/instance\/global numeric variables)
\n – `Condition` (run a sub-chain if an expression is true)
\n – `Loop` (repeat a sub-chain; while-loop or for-loop)
\n – `Npc` (apply NPC options per-player or globally as an action)
\n – `Stop` (stop the chain)
\n– **Path system**
\n – Create paths using points, visualize them, test them with a temporary NPC, and reuse them in NPC actions.
\n– **AI Goals**
\n – Configure NPC behavior with built-in goals: Walk to Location, Follow Entity, Attack Entity, Look Around, Wait, and Wander.
\n – Set target predicates using expressions for dynamic entity selection.
\n– **Expression Parser**
\n – Use mathematical expressions with variables, functions, and boolean logic.
\n – Support for local, instance, and global variables.
\n – Execute commands within expressions and use their results.
\n– **Localization + PlaceholderAPI**
\n – Ships with language files (default `en`).
\n – PlaceholderAPI is supported (soft-depend): placeholders can be used in plugin messages where applicable.<\/p>\n
## Guides<\/p>\n ### Installation<\/p>\n 1. Download the jar and place it into your server\u2019s `plugins\/` folder. ### Quick Start<\/p>\n #### 1) Create an NPC<\/p>\n – `\/npc create`<\/p>\n #### 2) Enable edit-mode<\/p>\n – `\/npc edit`<\/p>\n While edit-mode is enabled:<\/p>\n – **Interact with an NPC** to open its editor GUI.<\/p>\n If the NPC is **not editable**, you\u2019ll get a message like `This NPC is not editable!`.<\/p>\n #### 3) Configure NPC options in the GUI<\/p>\n The GUI lets you change things like:<\/p>\n – Name ## Click Actions (Left \/ Right \/ Both)<\/p>\n In the NPC GUI go to **Click Action**.<\/p>\n You can configure actions separately for:<\/p>\n – **Left click** You can create an action chain by adding multiple actions.<\/p>\n ### Action editing tips<\/p>\n – **Remove an action**: middle-click an existing action. ### Common action types<\/p>\n #### `Command`<\/p>\n Executes a command.<\/p>\n – Input can be with or without leading `\/` (the plugin stores it as `\/ Example:<\/p>\n – `warp spawn` #### `Server` (BungeeCord)<\/p>\n Sends the player to another BungeeCord server.<\/p>\n Example server name:<\/p>\n – `hub`<\/p>\n #### `Wait`<\/p>\n Pauses the chain before continuing.<\/p>\n You can switch between two modes in the editor:<\/p>\n ##### Time mode<\/p>\n – Left\/Right click to adjust the time ##### Command mode<\/p>\n Instead of waiting for time, the chain waits until an admin triggers it:<\/p>\n – `Wait` stores a **name** (string) If `[values…]` are provided, they are exposed to the next actions as local variables:<\/p>\n – ` This is useful to wait for external systems (minigames, scripted events, etc.).<\/p>\n ##### Note (Path)<\/p>\n The `Path` action also uses the same wait mechanism internally: the chain continues when the NPC finishes walking.<\/p>\n #### `Path`<\/p>\n Makes the NPC walk along a saved path.<\/p>\n – You pick a path name (must exist; same world) + a speed (`0.01`\u2013`1.0`). #### `Animation`<\/p>\n Plays an animation on the NPC for the clicking player.<\/p>\n – Left click: next animation #### `SetVariable`<\/p>\n Sets a numeric variable.<\/p>\n – Type: If the value is missing, the action does nothing (admins get a warning).<\/p>\n #### `Condition`<\/p>\n Runs a **sub-chain** only if its expression is `true`.<\/p>\n – You edit the sub-chain like a normal action list #### `Loop`<\/p>\n Repeats a sub-chain.<\/p>\n There are two loop types:<\/p>\n ##### While-loop<\/p>\n – Repeats while the expression is `true`<\/p>\n ##### For-loop<\/p>\n – Repeats with an integer loop index You can change the loop type by **Shift-clicking** the action.<\/p>\n #### `Npc`<\/p>\n Opens a special editor that lets you apply NPC options *as an action*.<\/p>\n This is mainly used to change how the NPC looks\/behaves for:<\/p>\n – Only the clicking player (per-player override) Two flags exist:<\/p>\n – Change globally: applies the configured options to the NPC\u2019s global options #### `Stop`<\/p>\n Stops the current chain immediately (and stops nested chains too).<\/p>\n #### Run-on-show<\/p>\n In the action editor you can enable **Run on show**.<\/p>\n If enabled, the chain triggers when the NPC is shown to a player (not only when clicked).<\/p>\n<\/details>\n ## Path System Guide<\/p>\n Paths are shared and stored in:<\/p>\n – `plugins\/NpcPlugin\/paths.yml`<\/p>\n ### Create a path from points<\/p>\n 1. Add points at your current location: Or add at a specific index: 2. List points: 3. Visualize \/ toggle visualization of current points: 4. Create the path: After creation you can visualize it:<\/p>\n – `\/npc path visualize ### Record a path by walking<\/p>\n 1. Start recording: 2. Walk the route.<\/p>\n 3. Stop recording: 4. Create the path: ### Edit an existing path<\/p>\n – `\/npc path edit This loads the saved path\u2019s waypoints into the point list so you can remove\/add points and re-create it.<\/p>\n ### List \/ delete \/ test paths<\/p>\n – `\/npc path list [page]` ## Goals Guide<\/p>\n Goals give NPCs autonomous behavior. Configure them via the NPC editor GUI.<\/p>\n ### Available Goals<\/p>\n – **Walk to Location**: NPC walks to a specific location using pathfinding ### Attack Entity Predicates<\/p>\n Target entities using expressions with variables:<\/p>\n – `$distance` – Distance to NPC Example predicates: For more details, see the full Goals documentation.<\/p>\n<\/details>\n ## Expression Parser Guide<\/p>\n Use mathematical expressions in click actions, goal conditions, and variable calculations.<\/p>\n ### Supported Elements<\/p>\n **Operators**: `+`, `-`, `*`, `\/`, `^` (power), `&&`, `||`, `!`, `==`, `!=`, `<`, `>`, `<=`, `>=`<\/p>\n **Math Functions**: `sin()`, `cos()`, `tan()`, `sqrt()`, `log()`, `exp()`, `ceil()`, `floor()`, `round()`, `trunc()`, `abs()`<\/p>\n **Constants**: `PI`, `E`<\/p>\n ### Variables<\/p>\n – `$varName` – Auto-resolve (local \u2192 instance \u2192 global) **Special Variables**: ### Command Execution<\/p>\n – `(\/command)` – Execute command inside expression Examples: ## Commands<\/p>\n ### Core<\/p>\n – `\/npc create` ### Config<\/p>\n – `\/npc config reload` ### Exceptions (startup load failures)<\/p>\n – `\/npc exceptions [page]` ### Paths<\/p>\n All path commands are under:<\/p>\n – `\/npc path …`<\/p>\n Main subcommands:<\/p>\n – `point add [index] [location] [rotation]` ### Variables<\/p>\n Manage server-wide global variables via commands:<\/p>\n – `\/npc variable list` – List all global variables Variables can also be managed via the SetVariable click action and used in expressions throughout the plugin.<\/p>\n<\/details>\n ## Configuration (`config.yml`)<\/p>\n – `look-at-update-interval`: ## Troubleshooting<\/p>\n – **\u201cThis plugin does not support Paper servers!\u201d** <\/p>\n<\/details>\n","protected":false},"excerpt":{"rendered":" Customizable NPCs via GUI and API<\/p>\n","protected":false},"featured_media":114198,"template":"","meta":{"_minecraft_slug":"npc-plugin","_minecraft_project_id":"lMVQTkWl","_minecraft_author":"Eisi05","_minecraft_license":"MIT","_minecraft_downloads":23571,"_minecraft_follows":32,"_minecraft_client_side":"unsupported","_minecraft_server_side":"required","_minecraft_storage_type":"zip","_minecraft_archive_name":"npc-plugin.zip","_minecraft_size_bytes":31881797,"_minecraft_version_count":69,"_minecraft_updated_at":"2026-05-16T00:07:59.169192Z","_minecraft_date_created":"2025-09-09T08:42:49.927502Z","_minecraft_date_modified":"2026-05-03T14:47:57.164848Z","_minecraft_project_url":"https:\/\/modrinth.com\/mod\/npc-plugin","_minecraft_icon_attachment_id":114198,"_minecraft_imported_at":"2026-06-06T17:34:42+00:00","_minecraft_import_hash":"ac9f82a2a98e638ccc5ff94c084dd5f6","_minecraft_versions":"","_minecraft_links":"","_minecraft_gallery":"","_minecraft_api_metadata":""},"mod_category":[126,127,128,129,123,92],"mod_loader":[132,133,134],"minecraft_version":[50,51,52,53,54,55,56,57,58,59,36,60,93,94,101,102,62,37,40,41,73,74,38,78,79,80,81,82,83,167,163],"class_list":["post-114197","mod","type-mod","status-publish","has-post-thumbnail","hentry","mod_category-management","mod_category-paper","mod_category-purpur","mod_category-spigot","mod_category-technology","mod_category-utility","mod_loader-paper","mod_loader-purpur","mod_loader-spigot","minecraft_version-1-17-1","minecraft_version-1-18","minecraft_version-1-18-1","minecraft_version-1-18-2","minecraft_version-1-19","minecraft_version-1-19-1","minecraft_version-1-19-2","minecraft_version-1-19-3","minecraft_version-1-19-4","minecraft_version-1-20","minecraft_version-1-20-1","minecraft_version-1-20-2","minecraft_version-1-20-3","minecraft_version-1-20-4","minecraft_version-1-20-5","minecraft_version-1-20-6","minecraft_version-1-21","minecraft_version-1-21-1","minecraft_version-1-21-10","minecraft_version-1-21-11","minecraft_version-1-21-2","minecraft_version-1-21-3","minecraft_version-1-21-4","minecraft_version-1-21-5","minecraft_version-1-21-6","minecraft_version-1-21-7","minecraft_version-1-21-8","minecraft_version-1-21-9","minecraft_version-26-1","minecraft_version-26-1-1","minecraft_version-26-1-2"],"yoast_head":"\nGetting Started (Installation + Quick Start)<\/strong><\/summary>\n
\n2. Start the server once.
\n3. Configure (optional):
\n – `plugins\/NpcPlugin\/config.yml`
\n – `plugins\/NpcPlugin\/lang\/
\n4. Restart or run `\/npc reload`.<\/p>\n
\n– Skin (player name \/ UUID \/ local `.png` file)
\n– \u201cUse Player Skin\u201d (per-player skin)
\n– Equipment slots
\n– Visibility \/ enabled state
\n– Tab list visibility
\n– Hide nametag
\n– Pose
\n– Skin parts
\n– Glowing + color
\n– Look-at-player radius \/ interval
\n– Scale
\n– Teleport to NPC \/ teleport NPC to you
\n– Delete NPC<\/p>\n<\/details>\nClick Actions<\/strong><\/summary>\n
\n– **Right click**
\n– **Both** (combined)<\/p>\n
\n– **Add actions quickly**: shift-click an action type to append it.
\n– **Reorder \/ insert**: pick up an action type onto your cursor and click a slot.<\/p>\n
\n– Placeholders supported:
\n – `{player}` \/ `%player%` \/ `
\n – `{player_name}` \/ `%player_name%` \/ `
\n– Supports variables\/expressions via the plugin action system.
\n– There is optional syntax validation.<\/p>\n
\n– `server hub`
\n– `msg {player} Welcome!`<\/p>\n
\n– Shift+Left\/Shift+Right for bigger steps
\n– Range is clamped (min `0.05s`, max `600s`)<\/p>\n
\n– The chain continues only after:
\n – `\/npc wait
\n– Optional flags:
\n – For all (everyone sees the NPC walking)
\n – Change real location (updates the NPC’s real location while walking)<\/p>\n
\n– Right click: previous animation<\/p>\n
\n – Local (stored per-player)
\n – Instance (stored on the NPC)
\n – Global (stored server-wide; persisted in `global-variables.yml`)
\n– Name must match `^[a-zA-Z_][a-zA-Z0-9_-]*$`
\n– Value is an expression<\/p>\n
\n– The condition expression is edited via the “value” item<\/p>\n
\n– Configurable values:
\n – Start (optional; default `0`)
\n – End (required)
\n – Step (optional; default `1`)<\/p>\n
\n– Everyone (global)<\/p>\n
\n– Reset to default: removes per-player overrides and resets to the NPC\u2019s defaults<\/p>\nPath System Guide<\/strong><\/summary>\n
\n – `\/npc path point add`<\/p>\n
\n – `\/npc path point add
\n – `\/npc path point list [page]`<\/p>\n
\n – `\/npc path visualize points`<\/p>\n
\n – `\/npc path create
\n – `\/npc path record start`<\/p>\n
\n – `\/npc path record stop`<\/p>\n
\n – `\/npc path create
\n– `\/npc path delete
\n– `\/npc path test Goals Guide<\/strong><\/summary>\n
\n– **Follow Entity**: NPC follows a target entity by UUID
\n– **Attack Entity**: NPC attacks nearby matching entities
\n– **Look Around**: NPC looks around randomly (idle behavior)
\n– **Wait**: NPC waits for a specified duration
\n– **Wander**: NPC wanders randomly within a radius<\/p>\n
\n– `$entity.x`, `$entity.y`, `$entity.z` – Entity position
\n– `$entity.health` – Entity health
\n– `$npc.x`, `$npc.y`, `$npc.z` – NPC position
\n– `[if entity @s[type=zombie]]` – Command-based entity type check<\/p>\n
\n– `$distance < 5` - Only attack within 5 blocks\n- `$entity.health < 10` - Attack low health entities\n- `$distance < 10 && $entity.health > 5` – Combined conditions<\/p>\nExpression Parser Guide<\/strong><\/summary>\n
\n– `$global.varName` – Server-wide variable
\n– `$instance.varName` – NPC-specific variable
\n– `$local.varName` – Player-specific variable<\/p>\n
\n– `$self.rightClick` \/ `$self.leftClick` – Click type (1 or 0)
\n– `$self.sneaking`, `$self.flying`, `$self.op` – Player state
\n– `$loop.index` – Loop iteration index<\/p>\n
\n– `\/command` – Standalone command execution<\/p>\n
\n– `2 + (\/count players)` – Use command result in calculation
\n– `$global.score + 1` – Increment variable
\n– `($entity.health < 10) * 5` - Conditional value\n\nFor the full syntax reference, see the Expression Parser documentation.\n\n<\/details>\nCommands<\/strong><\/summary>\n
\n– `\/npc copy
\n– `\/npc edit` (toggle edit-mode)
\n– `\/npc list` (opens NPC list GUI)
\n– `\/npc tp
\n– `\/npc tphere
\n– `\/npc reload`
\n– `\/npc version`
\n– `\/npc update` (checks for a new plugin version)<\/p>\n
\n– `\/npc config debug [true|false]`
\n– `\/npc config avoid-command-check [true|false]`
\n– `\/npc config look-at-update-interval [ticks]`
\n– `\/npc config input-time [seconds]`
\n– `\/npc config auto-update [true|false]`
\n– `\/npc config placeholder-timer [ticks]`
\n– `\/npc config list`<\/p>\n
\n– `\/npc exceptions show
\n– `\/npc exceptions delete
\n– `point remove [index|location]`
\n– `point list [page]`
\n– `point clear`
\n– `create [name] [maxIterations] [allowDiagonalMovement]`
\n– `delete
\n– `list [page]`
\n– `visualize [name]`
\n– `visualize points`
\n– `record start|stop`
\n– `test
\n– `edit
\n– `\/npc variable get
\n– `\/npc variable set
\n– `\/npc variable delete Configuration<\/strong><\/summary>\n
\n – Time in ticks between \u201clook at player\u201d updates.
\n– `avoid-command-check`:
\n – If `true`, commands added to NPC actions will not be strictly validated.
\n– `debug`:
\n – Enables extra debug logging.
\n– `input-time`:
\n – Conversation timeout in seconds (if `< 0`, no timeout).\n- `auto-update`:\n - Automatically updates NPCs after option changes.\n- `placeholderTimer`:\n - Time in ticks between placeholder refreshes.\n\n<\/details>\nTroubleshooting<\/strong><\/summary>\n
\n – You are running the **Spigot** build on a **Paper** server. Install the Paper build instead.
\n– **Server action does nothing**
\n – Ensure BungeeCord is set up and the server names match your proxy configuration.
\n– **Can\u2019t open the editor GUI**
\n – Make sure you:
\n – Have `npc.admin`
\n – Enabled edit-mode via `\/npc edit`
\n – The NPC is marked as editable<\/p>\n<\/details>\nbStats<\/strong><\/summary>\n