Official documentation

FoliaNPC

A free lightweight NPC system with player skins, actions, dialogs, holograms, GUI management and Folia-aware scheduling.

Getting started

Installation

1
Stop the Minecraft server completely.
2
Install every required dependency listed below before FoliaNPC.
3
Place FoliaNPC.jar inside the plugins folder.
4
Start the Minecraft server and review the generated FoliaNPC configuration folder.
5
Test the plugin on a staging server before enabling it for all players.

Supported environments

1.3.1Plugin version

1.20+Minecraft

Spigot / Paper / FoliaServer software

Java 17 or newerRuntime

Integrations

Required

Handles modern fake-player interactions.

Optional

Fallback packet backend for supported environments.

Reference

Command	Description	Permission
`/npc create <id> [name]`	Creates an NPC.	`folianpc.admin`
`/npc remove\|select\|info <id>`	Manages or inspects an NPC.	`folianpc.admin`
`/npc move <id> <x> <y> <z> [yaw] [pitch]`	Moves an NPC.	`folianpc.admin`
`/npc skin <id> <player\|url\|texture\|clear> ...`	Changes the NPC skin.	`folianpc.admin`
`/npc action <id> add <right\|left\|both> <console\|player> <command>`	Adds a click action.	`folianpc.admin`
`/npc dialog <id> set <lines>`	Configures dialog text.	`folianpc.admin`
`/npc hologram <id> ...`	Configures name and description holograms.	`folianpc.admin`
`/npc menu [id]`	Opens the NPC administration GUI.	`folianpc.admin`
`/npc import\|export <file\|id>`	Imports or exports NPC data.	`folianpc.admin`
`/npc reload`	Reloads FoliaNPC.	`folianpc.admin`

Access control

Permission	Default	Description
`folianpc.admin`	Administrators	Allows complete NPC creation and management.

Server setup

NPCs are stored in npcs.yml and exported definitions are stored in the exports folder.
Actions support built-in player, UUID and NPC placeholders.

Command aliases are /fnpc and /folianpc.
Mojang texture URLs are recommended for URL-based skins.
Version 1.3.1 fixes player and direct-URL skins on Paper 26.2 Authlib.
Version 1.3.0 hides native profile tags, removes default click actions and adds separate right/left click commands.
Native player-NPC rendering is compatible with Paper 26.2.

Visual guide

FoliaNPC - temporary GherrixDev cover