Znpc

What is this?
Znpc is an advanced NPC system for Paper. You create player like mannequins in the world (hub helpers, shop guides, arena fighters) and optional TAB bots that look online: they join, leave, chat, answer greetings, deny /tpa, reply to PMs, and can even die in fake death messages.
Almost everything is edited in GUIs. Text uses MiniMessage (gradients, hover, click). NPC data lives as YAML files under plugins/Znpc.
Where it runs

• Yes: Paper 26.1.x (built on Paper API 26.1.2). Java 21 or newer.
• Usually fine: Purpur on the same game version as Paper 26.1.x.
• No: plain Spigot or CraftBukkit. Needs Paper APIs (entities, Dialog, Adventure).
• No: Folia.
• Old Paper 1.21.11: not the build target. Update to Paper 26.1.x first.

Short version: Paper 26.1.3 + Java 21 (or newer) is the intended setup.
Minecraft Dialog display type and locator bar features need a modern Paper build that has those APIs (roughly 1.21.6+ game features on the 26.1 line).
Optional soft depends

• PlaceholderAPI placeholders in names, chat formats, %znpc_*%
• Vault balances, hover money, NPC payments
• SkinsRestorer better skin resolve for nicknames
• TAB plays nicer with fake online entries
• ZChat global / local chat formats for bots
• ZTelegram forward bot chat / joins / deaths and react to Telegram chat

The plugin starts without them. Features that need a soft depend stay quiet until you install it.
Two kinds of NPCs

• World mannequins files in plugins/Znpc/npcs/. Visible entities in a world. Clicks, dialogs, equipment, path walking, Sentinel combat, sounds, locator bar.
• TAB / fake presence bots files in plugins/Znpc/fake_npcs/ (or NPCs with show in TAB + fake online). Appear in the player list, can look like real players in chat, join/quit/death cycles, idle talk, greetings, triggers.

Global bot switch: /znpc start bot and /znpc remove bot (saved). Personal hide: /znpc botoff / boton (only for you).
Main features

• Full GUI /znpc or /znpc gui. Create, list, edit name, description, position, skin, equipment, actions, dialogs, movement, fake online, Sentinel, sounds.
• Click actions player command, console command, message, broadcast, teleport. Click types LEFT / RIGHT / SHIFT_LEFT / SHIFT_RIGHT / ANY. Delay, priority, once claim modes. Also via CLI /znpc cmd.
• Dialogs lines and buttons. Display as chat, action bar, title, boss bar, or Paper Minecraft Dialog. Button actions: player/console command, message, open another dialog, close.
• Skins nickname (Mojang / SkinsRestorer), copy your skin, Steve / Alex, texture value+signature.
• Movement look at players, pose (sneak / lie / crawl), attack/jump anims, walk along a path (world editor with markers), stop on click or approach.
• Sentinel style AI chase, melee, ranged (arrow/snowball with lead/arc/direct), fightback, runaway, return home, pathfinding, separation, autoswitch weapons, gear damage, shield, vulnerable arena mode with HP / death / respawn / drops.
• Sounds per event: spawn, clicks, action executed, approach.
• Living TAB bots scheduled fake join/quit, chat greetings, question/insult triggers, idle phrases, bot↔bot dialogues, ambient replies, fake /tpa deny, PM auto reply personalities, optional Vault pay to NPC.
• Languages GUI and messages: en, ru, zh, fr, it, ko, uk, kk. Per player via /znpc lang.
• Anti spam click cooldown (applies to everyone, including ops).
• bStats anonymous metrics (plugin id 33090). Charts: npc_count, default_language.

How to install

1. Put Znpc.jar into the plugins folder
2. Start Paper once so folders and config.yml appear
3. (Optional) install soft depends you want
4. Create an NPC: /znpc create mynpc or open /znpc GUI
5. Edit with /znpc edit mynpc
6. Tune plugins/Znpc/config.yml and phrase files if you use living bots
7. /znpc reload after big config edits (or restart)

File layout

• plugins/Znpc/config.yml core settings, bot chat, greetings, triggers, idle, TAB, telegram, defaults, fake presence templates
• plugins/Znpc/npcs/*.yml world NPCs
• plugins/Znpc/fake_npcs/*.yml TAB bots
• plugins/Znpc/lang/*.yml GUI and message translations
• plugins/Znpc/ChatGreetings.yml greeting phrases
• plugins/Znpc/ChatTriggers.yml trigger replies
• plugins/Znpc/ChatIdle.yml idle talk
• plugins/Znpc/ChatDialogues.yml bot↔bot dialogues
• plugins/Znpc/PmReplies.yml PM auto replies
• plugins/Znpc/PlayerDeathMessages.yml fake death lines

Commands (full list)
Aliases for main command: /znpc, /npc, /znpcs
General
/znpc with no args opens the GUI (players). Console uses /znpc help.
NPCs
create without coords uses your feet (player only). Console must pass world + xyz.
Click actions (CLI)
Aliases: cmd, command, action, actions
Runners:

• @Player (@p) run as the clicking player
• @Console (@c) run as console
• @Message (@msg) message the player
• @broadcast (@bc) broadcast to everyone

Optional flags before the text:

• click:LEFT | RIGHT | SHIFT_LEFT | SHIFT_RIGHT | ANY (short: minus l / minus r / minus sl / minus sr / minus any)
• delay:20 delay:20t delay:1s delay:0.5s
• priority:0

Examples:
Teleport actions are edited in the GUI (Action type TELEPORT).
Global bots
Needs znpc.bots or znpc.admin. State is saved.
Personal bot visibility (player only, no special permission beyond being able to run /znpc)
Hides or shows bots for you only (TAB, chat, joins, quits, deaths).
/bot command
Needs znpc.bot (or znpc.admin):
join creates a temporary session bot. leave removes a session bot or forces a pool bot offline. Chat as bot only works while that bot is visible in TAB.
Permissions
Players do not need znpc.use to click NPCs and run actions. That permission is for admin tools.
Recommended: give staff znpc.admin, or split create/edit/delete as you like.
PlaceholderAPI
Identifier: znpc
online / tab_online = fake TAB bots currently shown.
server_online / total = real players + TAB bots (when adjust is on).
real_online = Bukkit online players only.
If placeholders adjust server online is enabled in config, Znpc can wrap %server_online% so scoreboards count bots too.
Bot chat formats also resolve normal PlaceholderAPI placeholders (%player_name%, Vault balance, and so on).
GUI overview (editor)
From the editor for an NPC you typically get:

• Name, description, move here / open list
• Skin menu
• Equipment (armor + hands)
• Actions list and per action editor
• Dialogs (lines, buttons, preview)
• Movement (pose, animations, path walk, stop rules)
• Fake online (TAB cycles) when Show in TAB is enabled
• Sentinel combat brain
• Sounds per event

Path edit: walk markers in the world, save with 2+ points for walking. Cancel discards changes.
Quick start ideas

• Hub helper create NPC, set skin, add RIGHT click @Player command to open a menu, add a Minecraft Dialog guide on LEFT click
• Shop console commands on click, cooldown via anti spam, once claim actions if needed
• Arena guard enable Sentinel, vulnerable, gear, pathfinding, death drops
• Living TAB enable bots with /znpc start bot, put bots in fake_npcs, tune ChatIdle / ChatGreetings / ChatTriggers

Support
Telegram: https://t.me/Zoobastiks
bStats: https://bstats.org/plugin/bukkit/Znpc/33090
If something breaks, tell me your Paper version, Java version, soft depends installed, and the error from the console. That saves a lot of back and forth.
Thanks for trying Znpc.