FoliaNPC

FoliaNPC
Lightweight player-style NPCs for Spigot, Paper and Folia

Official Website and Documentation
FoliaNPC is a lightweight NPC plugin that lets you create player-style NPCs for lobbies, guides, shops, quests, tutorials and interactive server menus.

It supports Spigot, Paper and Folia, uses Folia-aware scheduling, stores NPCs in simple YAML files, and supports click actions, dialogs, holograms, skins and import/export tools.

Features

• Player-style NPC rendering
• Spigot, Paper and Folia support
• Folia region-safe scheduling
• NPC creation, removal, teleport, movement and rename
• Right-click, left-click or both-click actions
• Console and player command execution
• Per-action cooldown support
• Optional action permissions
• Dialog trait with placeholder support
• Look-at-player rotation
• Configurable view distance
• Hologram name and description lines
• Skins from online players
• Skins from Mojang texture URLs
• Raw texture value and signature support
• YAML NPC storage
• NPC import and export
• Admin GUI
• Optional PlaceholderAPI support

Requirements

• Java 17 or newer
• Minecraft 1.20+
• Spigot, Paper or Folia
• EntityPacketBridge recommended for modern NMS click support
• PacketEvents supported as fallback renderer

Installation

1. Download or build FoliaNPC.jar.
2. Put it in your server plugins folder.
3. Install EntityPacketBridge or PacketEvents.
4. Start the server once.
5. Edit plugins/FoliaNPC/config.yml if needed.
6. Create your first NPC with /npc create <id> [name].

Commands

Main NPC commands

/npc
/npc create <id> [name]
/npc remove <id>
/npc list
/npc select <id>
/npc info [id]
/npc debug [id]
/npc tp [id]
/npc move <id> <x> <y> <z> [yaw] [pitch]
/npc rename <id> <name>
/npc reload

Skin commands

/npc skin <id> player <onlinePlayer>
/npc skin <id> url <url> [slim|wide]
/npc skin <id> texture <value> [signature]
/npc skin <id> clear
/npc skinurl <id> <url> [slim|wide]

Behavior commands

/npc look <id> <on|off>
/npc range <id> <blocks>
/npc trait <id> <command|dialog|shop|quest>

Action and command commands

/npc command add <id> <command>
/npc command remove <id> <index>
/npc command list <id>
/npc command clear <id>

/npc action <id> add <right|left|both> <console|player> <command>
/npc action <id> clear
/npc action <id> list

Dialog commands

/npc dialog <id> set <line1 | line2>

Hologram commands

/npc hologram <id> name <on|off>
/npc hologram <id> description set <line1 | line2>
/npc hologram <id> description <on|off>
/npc hologram <id> description clear
/npc hologram <id> mode <name|description|both|none>

Import, export and menu commands

/npc export <id>
/npc import <file>
/npc menu [id]

Permission

folianpc.admin

Allows creating, removing and configuring NPCs.

Placeholders
Built-in placeholders for actions and dialogs:

{player}     Player name
{uuid}       Player UUID
{npc}        NPC ID
{npc_name}   NPC display name without color codes

If PlaceholderAPI is installed, PlaceholderAPI placeholders are also parsed.

Skin Notes
For reliable URL skins, use Mojang texture URLs:

https://textures.minecraft.net/texture/<hash>

Raw texture mode accepts a Base64 texture value and an optional signature:

/npc skin guide texture <value> [signature]

Files

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

Compatibility

• Spigot 1.20+ supported with PacketEvents fallback
• Paper 1.20+ supported
• Folia 1.20+ supported with Folia-aware scheduling

Support
If NPCs do not render, install EntityPacketBridge or PacketEvents and check:

/npc debug [id]

If click actions do not work, make sure your interaction bridge is installed and enabled.