Spigot, Paper and Folia plugin

Player-style NPCs with commands, dialogs and holograms.

FoliaNPC creates lightweight fake-player NPCs for server lobbies, guides, shops, quests and interactive menus. It is designed to stay compatible with Folia region scheduling while still running on Spigot and Paper.

Install Commands Compatibility
FoliaNPC plugin artwork

What it does

FoliaNPC features

Player-style NPCs

Render fake-player NPCs with names, skins, rotation and per-player visibility.

Click Actions

Run console or player commands from right-click, left-click or both-click triggers.

Dialogs

Send configurable dialog lines with built-in placeholders and optional PlaceholderAPI support.

Holograms

Show the NPC name, description lines, both, or no hologram above the NPC.

Skin Tools

Use skins from online players, Mojang texture URLs, raw texture values or clear skins.

YAML Import and Export

Store NPCs in simple YAML files and export individual NPCs for reuse.

Setup

How to install FoliaNPC

  1. Build or download FoliaNPC.jar.
  2. Put the jar inside your server plugins folder.
  3. Install EntityPacketBridge for modern-NMS click support, or install PacketEvents as the fallback renderer.
  4. Start the server once to generate configuration files.
  5. Edit plugins/FoliaNPC/config.yml if you want to force a renderer or change defaults.
  6. Create your first NPC with /npc create <id> [name].

Generated files

plugins/FoliaNPC/config.yml plugins/FoliaNPC/messages.yml plugins/FoliaNPC/npcs.yml plugins/FoliaNPC/exports/<id>.yml

Admin commands

FoliaNPC commands

/npc create <id> [name]Create an NPC at your current location.
/npc remove <id>Remove an existing NPC.
/npc listList all created NPCs.
/npc select <id>Set an NPC as your active selection.
/npc info [id]Show NPC details.
/npc tp [id]Move the selected NPC, or the given NPC, to you.
/npc move <id> <x> <y> <z> [yaw] [pitch]Move an NPC to exact coordinates.
/npc rename <id> <name>Change the NPC display name.
/npc skin <id> player <onlinePlayer>Copy a skin from an online player.
/npc skin <id> url <url> [slim|wide]Set a skin from a texture URL.
/npc action <id> add <right|left|both> <console|player> <command>Add a click action.
/npc dialog <id> set <line1 | line2>Set dialog lines.
/npc hologram <id> mode <name|description|both|none>Choose which hologram lines are visible.
/npc export <id>Export an NPC to YAML.
/npc import <file>Import an NPC from the exports folder.
/npc reloadReload configuration, messages and NPC data.

Access control

FoliaNPC permissions

folianpc.adminAllows creating, removing and configuring NPCs.

Versions

FoliaNPC compatibility

Spigot 1.20+ Supported with the PacketEvents fallback renderer.
Paper 1.20+ Supported with modern NMS rendering and EntityPacketBridge for interactions.
Folia 1.20+ Uses Folia-aware scheduling for region and entity tasks.

Help

FoliaNPC common problems

NPCs do not render

Install EntityPacketBridge or PacketEvents. If compatibility.require-player-renderer is enabled, FoliaNPC disables itself when no renderer is available.

Clicks do not run actions

Use EntityPacketBridge with the modern renderer, or PacketEvents with the fallback renderer. Check /npc debug [id] for backend status.

Skin does not update

Use a Mojang texture URL or copy a skin from an online player, then move out of range and back in or run /npc reload.