Znpc 26x

Znpc
Paper NPCs: hub helpers, living TAB bots, Sentinel combat, and photo-zone selfies
Version 5.0.0
Telegram | bStats

Please do not stay silent
If something breaks, feels weird, or you wish Znpc could do something it cannot yet: tell me.
Write in the Spigot discussion thread, leave a review, or message me on Telegram: https://t.me/Zoobastiks
Silent downloads help nobody. A short note like "photo zone broke after reload" or "I want X" is already enough. Ratings and feedback show that people actually use the plugin and push it forward. If something is missing for your server, say so. Do not assume I already know.
What is Znpc?
Znpc lets you place player-like NPCs in the world (hub helpers, shop guides, arena fighters) and optional TAB bots that feel like real players: they show in the player list, join and leave, chat, greet people, answer questions, deny /tpa, reply in PM, visit players, and show up in fake death messages.
New in this line: Photo Zones. Put a pressure plate somewhere nice. When a player steps on it, photo NPCs line up next to them and copy the pose: look, crouch, crawl, jump, wave. Perfect for screenshots when friends are offline. You can spawn a whole group in one click (up to 50) with random skins and gear.
Almost everything is edited in GUIs. Text uses MiniMessage (gradients, hover, click). Each NPC is a YAML file under plugins/Znpc.
Requirements

• Paper 26.2.x (built against Paper API 26.2). Java 21+.
• Usually fine: Purpur on the same game line as that Paper build.
• Not supported: plain Spigot / CraftBukkit (needs Paper APIs: entities, Dialog, Adventure).
• Not supported: Folia.

Minecraft Dialog and locator-bar features need a modern Paper build that has those APIs.
Optional soft depends
The plugin starts without these. Install only what you need:

• PlaceholderAPI placeholders in names, chat formats, %znpc_*%
• Vault balances in hover text, economy features
• SkinsRestorer better skin resolve by nickname
• TAB nicer sorting / display of fake online entries
• ZChat global / local chat formats for bots
• ZTelegram forward bot chat / joins / deaths; bots can react to Telegram chat

Three kinds of NPCs

• World mannequins folder plugins/Znpc/npcs/
  Visible bodies in a world. Clicks, dialogs, equipment, path walking, Sentinel combat, sounds, optional locator bar.
• TAB / fake-presence bots folder plugins/Znpc/fake_npcs/
  (or any NPC with Show in TAB + fake online enabled)
  Appear in the player list. Chat, greetings, triggers, idle talk, dialogues, /tpa deny, PM replies, optional AI replies, visit-/tpa visits, fake deaths.
• Photo-zone NPCs managed via /znpc photo
  Tied to a pressure plate. They stand around for selfies and mirror the player on the plate. Separate from the main NPC list so hub NPCs stay clean.

Global bots on/off: /znpc start bot and /znpc remove bot (saved).
Hide bots only for yourself: /znpc botoff / /znpc boton.
Main features

• Full GUI /znpc or /znpc gui. Create, list, edit name, hologram/description, position, skin, equipment, actions, dialogs, movement, fake online, Sentinel, sounds, photo zones.
• Photo Zones pressure-plate selfie spots. NPCs line up and copy your pose. One-click brigades (5-50), formations (wedge / line / arc / rows), spacing controls, plate move/break handling. Command: /znpc photo.
• Click actions player command, console command, message, broadcast, teleport. Clicks: LEFT / RIGHT / SHIFT_LEFT / SHIFT_RIGHT / ANY. Delay, priority, once/claim modes. Also via /znpc cmd.
• Dialogs lines and buttons. Show as chat, action bar, title, boss bar, or Paper Minecraft Dialog. Buttons can run commands, messages, open another dialog, or close.
• Skins nickname (Mojang / SkinsRestorer), copy your skin, Steve / Alex, or raw texture value + signature.
• Movement look at players, pose (sneak / lie / crawl), attack/jump anims, walk a path (world editor with markers), pause on click or approach.
• Sentinel-style AI chase, melee, ranged (arrow/snowball: lead/arc/direct), fightback, runaway, return home, pathfinding, separation, autoswitch weapons, gear damage, shield, vulnerable arena mode (HP / death / respawn / drops).
• Sounds per event: spawn, clicks, action executed, approach.
• Living TAB bots fake join/quit cycles, greetings, question/insult triggers, idle phrases, botbot dialogues, ambient replies, /tpa deny, PM auto-replies (personalities), optional AI chat (OpenRouter), visit-/tpa (bot asks to visit you, hangs out, may drop loot).
• Languages GUI and messages: en, ru, uk, kk, zh, ko, ja, fr, it, de, es, pt_br, pl, tr, nl, cs, ro, ar. Per player: /znpc lang.
• Click anti-spam cooldown for everyone (including ops). Tunable in config.
• bStats anonymous metrics (id 33090).

Photo Zones (quick start)

1. /znpc photo (or open Photo zones from the main GUI)
2. Create a zone, stand on a pressure plate, set the plate
3. Spawn a brigade (e.g. 10 or 20) or add photo NPCs one by one
4. Pick a formation and spacing if you want
5. Step on the plate and pose. NPCs line up and mirror you

Left-click a brigade preset to replace the group. Shift-click to add more (up to the cap). If you move the plate, the group follows. If the plate is broken, the session stops.
How to install

1. Put Znpc.jar into plugins/
2. Start the server once (folders + config.yml appear)
3. (Optional) install soft depends
4. Create an NPC: /znpc create mynpc or open /znpc
5. Edit: /znpc edit mynpc
6. For living TAB bots: /znpc start bot, put bots in fake_npcs (or enable Show in TAB + fake online in GUI), then tune phrase files / AI if you want
7. For selfie spots: /znpc photo
8. After big config edits: /znpc reload (or restart)

What goes where (files)
You only need to touch what you use. Comments inside each file explain the options.

• config.yml master switches: anti-spam, economy, /tpa deny, visit-/tpa, PM reply, bot chat look, AI chat, greetings/triggers/idle chances, TAB, Telegram, placeholders, locator bar, photo-zones, defaults for new NPCs, join/quit lines, fake-presence cycles
• npcs/*.yml world NPCs (one file per id)
• fake_npcs/*.yml TAB bots (one file per id)
• photo-zones/ photo zone data (plates, linked photo NPCs, formation settings)
• lang/*.yml GUI and plugin messages (pick language with /znpc lang or default-language in config)
• ChatGreetings.yml replies to hi / ку / qq
• ChatTriggers.yml replies to questions, insults, "are you a bot?", server hate, etc.
• ChatIdle.yml random idle lines when bots "talk by themselves"
• ChatDialogues.yml short botbot conversations
• PmReplies.yml YAML fallback replies for private messages (if AI is off or skips)
• PlayerDeathMessages.yml fake death message pool
• ai-secret.yml (recommended) OpenRouter API key so you do not put it in config.yml

How to set things up (practical)
1) Hub / shop NPC (world body)

1. /znpc create shop
2. /znpc edit shop → skin, name, description
3. Actions → add RIGHT click = player command (e.g. menu) or console command
4. Optional: Dialogs → Minecraft Dialog guide on LEFT click
5. Optional: Movement path if the NPC should walk

2) Living TAB bots

1. /znpc start bot
2. Use bots from fake_npcs/ or create an NPC, enable Show in TAB + Fake online in the editor
3. Tune how "alive" they feel in config.yml:
   • settings.chat-greeting → answers to greetings
   • settings.chat-triggers → questions / toxicity / bot callouts
   • settings.chat-idle → idle talk, dialogues, ambient replies, join reacts
   • settings.tpa-deny → fake decline of /tpa
   • settings.pm-reply → YAML PM replies + personality defaults
   • settings.visit-tpa → bot sends you /tpa, visits, chats, may drop items
   • settings.ai-chat → optional OpenRouter AI replies in public chat and PM
   • settings.fake-presence / join-messages / PlayerDeathMessages.yml → online cycles and deaths
4. Phrase text itself lives in Chat*.yml / PmReplies.yml / PlayerDeathMessages.yml

3) Photo zone selfie spot

1. /znpc photo → create a zone
2. Stand on a pressure plate → Set plate
3. Open Brigade → pick size and formation
4. Step on the plate and take the screenshot

Tune radius, cooldowns, nametag format under settings.photo-zones in config.yml.
4) AI chat (optional)
Bots can answer with OpenRouter instead of (or before) YAML phrases.

1. Get a key at OpenRouter
2. Put it in plugins/Znpc/ai-secret.yml as api-key: "sk-or-..." (preferred), or set settings.ai-chat.api-key / env OPENROUTER_API_KEY
3. settings.ai-chat.enabled: true
4. Pick model (default openai/gpt-4o-mini), chances, cooldowns, PM settings
5. Edit settings.ai-chat.prompts if you want another tone for your server (friendly, RP, toxic, etc.). Comments in config.yml explain each prompt field and placeholders
6. YAML greetings/triggers/PM still work as fallback when AI skips or fails

5) Visit-/tpa (bot visits a player)
In config.yml → settings.visit-tpa:

• enabled, chance, cooldowns, visit length, gift chance, drop-items list
• blocked-worlds → worlds where bots must not send visit requests (e.g. hub)

When a player accepts, the bot appears, wanders nearby, may chat and drop loot, then leaves.
6) Sentinel arena / guard
Edit the world NPC → Sentinel:

• Enable brain, chase / fightback / return home
• Vulnerable = players can hurt it (HP, respawn, optional drops)
• Ranged: projectile type and shoot mode
• Gear autoswitch / shield / pathfinding as needed

Global tick rates: settings.sentinel in config.yml.
7) Bot look in chat
settings.bot-chat → format, global/local formats, hover lines, click-to-/msg.
Supports PlaceholderAPI (%player_name%, Vault balance, …).
8) Telegram (with ZTelegram)
settings.telegram → forward join/quit/death/chat, react to Telegram chat, optional "!" prefix chance so bots look less obvious.
Commands
Aliases: /znpc, /npc, /znpcs
General

/znpc
/znpc help
/znpc gui
/znpc menu
/znpc list
/znpc reload
/znpc lang
/znpc lang <code>

Codes: en, ru, uk, kk, zh, ko, ja, fr, it, de, es, pt_br, pl, tr, nl, cs, ro, ar (aliases: pt, ua, jp, kr, cn, …).
No args opens the GUI for players. Console: use /znpc help.
NPCs

/znpc create <id>
/znpc create <id> <world> <x> <y> <z> [yaw] [pitch]
/znpc delete <id>
/znpc remove <id>
/znpc edit
/znpc edit <id>
/znpc tp <id>
/znpc teleport <id>

Create without coords = your feet (players). Console must pass world + xyz.
Photo zones
Permission: znpc.photo.admin (included in znpc.admin)

/znpc photo
/znpc photozone

Opens the photo zone GUI: create zones, bind plates, spawn brigades, edit formations.
Click actions (CLI)
Aliases: cmd, command, action, actions

/znpc cmd <id>
/znpc cmd <id> list
/znpc cmd <id> clear
/znpc cmd <id> remove <actionId|#|all|value...>
/znpc cmd <id> add @player|@console|@message|@broadcast [flags] <text>

Runners:

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

Optional flags before the text:

• click:LEFT | RIGHT | SHIFT_LEFT | SHIFT_RIGHT | ANY
• delay:20 delay:20t delay:1s delay:0.5s
• priority:0

Examples:

/znpc cmd shop add @player click:RIGHT spawn
/znpc cmd shop add @console delay:1s say <player> opened the shop
/znpc cmd guide add @message click:ANY Welcome!
/znpc cmd shop remove 1
/znpc cmd shop clear

Teleport actions: edit in GUI (type TELEPORT).
Global bots

/znpc start bot
/znpc remove bot

Permission: znpc.bots or znpc.admin. State is saved.
Personal hide

/znpc botoff
/znpc boton

Hides/shows bots only for you (TAB, chat, joins, quits, deaths).
/bot
Permission: znpc.bot or znpc.admin

/bot <nick> <message>
/bot join <nick>
/bot leave <nick>

join = temporary session bot. leave = remove session bot or force a pool bot offline. Chat as bot only while that nick is visible in TAB.
Permissions

znpc.use                 GUI, list, tp (default: op)
znpc.create              create NPCs (default: op)
znpc.edit                editor + /znpc cmd (default: op)
znpc.delete              delete NPCs (default: op)
znpc.bots                /znpc start bot | remove bot (default: op)
znpc.bot                 /bot chat, join, leave (default: op)
znpc.photo               optional photo-zone use if you set settings.photo-zones.permission (default: true)
znpc.photo.admin         manage photo zones / /znpc photo (default: op)
znpc.admin               reload + all of the above (default: op)
znpc.bypass.cooldown     unused (click cooldown applies to everyone)

Players do not need staff permissions to click NPCs and run actions. Those permissions are for staff tools only.
Recommended: give staff znpc.admin, or split create/edit/delete.
PlaceholderAPI
Identifier: znpc

%znpc_online%
%znpc_tab_online%
%znpc_server_online%
%znpc_total_online%
%znpc_real_online%

• online / tab_online = fake TAB bots currently shown
• server_online / total = real players + TAB bots (when adjust is on)
• real_online = real Bukkit online players only

If settings.placeholders.adjust-server-online is true, Znpc can wrap %server_online% so scoreboards count bots too.
Bot chat formats also resolve normal PAPI placeholders.
GUI (editor)
Per NPC you typically get:

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

Photo zones have their own menus: zone list, zone editor, photo NPC editor, brigade / formation.
Path edit: place markers in the world, save with 2+ points. Cancel discards changes.
FAQ
Bots do not appear in TAB
Run /znpc start bot. Check Show in TAB + fake online on the NPC. Confirm the file is under fake_npcs/ or has those flags set.
Bots do not talk
Check settings.chat-greeting / chat-triggers / chat-idle enabled. Phrase files must have lines. After restart bots stay quieter for startup-quiet-seconds (chat-idle). For AI: key + enabled in ai-chat.
Photo NPCs do nothing when I step on the plate
Make sure the zone is enabled, the plate is set, and photo NPCs are linked to that zone. Stand on the bound plate (not a random nearby one). Check cooldowns in the zone editor / settings.photo-zones.
How do I change bot personality / language of replies?
YAML: Chat*.yml and PmReplies.yml + personality on the NPC (player / schoolboy / girl / boy).
AI: settings.ai-chat.prompts (system / system-pm / personalities / user templates).
How do I turn AI off?
settings.ai-chat.enabled: false (YAML replies still work).
Players still see bots after /znpc remove bot
That command disables the global bot system and saves state. Use /znpc botoff only if one player wants them hidden for themselves.
Can I delete some bundled fake bots?
Yes. Delete or disable the ones you do not want in fake_npcs/. Your other bots stay.
Dialog / locator bar missing
Update Paper. Those features need modern Paper APIs on the 26.x line.
Support & feedback
Telegram: https://t.me/Zoobastiks
Found a bug? Want a feature? Leave a review, post in the discussion, or write me on Telegram. Whatever is easier for you.
When reporting a bug, send: Paper version, Java version, soft depends, and the console error. That saves a lot of back and forth.
Thanks for using Znpc.