InteractiveNPC

InteractiveNPC is a Paper 1.21.11 plugin that allows you to create fully customizable and interactive NPCs using Minecraft's native mannequins.

Create NPCs with custom names, player skins, interactive dialogues, buttons, and actions such as teleportation, commands, messages, sounds, particles, and more.

No external dependencies, no NMS, and no repetitive tasks required.

✨ Features

• 🧍 NPCs based on Minecraft's native mannequins
• 🎭 Custom player skins
• 💬 Native Minecraft dialogues
• 🔘 Interactive buttons
• ⚡ Multiple actions per button
• 📍 Teleportation
• 💻 Command execution
• 💬 Player messages
• 🔊 Sounds
• ✨ Particles
• 🔄 Multiple dialogue navigation
• 🔐 Conditional buttons
• 📊 Level-based conditions
• 🎒 Item-based conditions
• 🌎 World-based conditions
• 🛡️ Permission-based conditions
• ⏱️ Delayed actions
• 📝 Fully YAML-configurable
• 🖥️ In-game GUI editor
• 🔄 Reload configuration without restarting
• 🔒 Server-side interaction validation
• 🚫 Protected NPC commands

---

📜 Commands

All commands require the npc.admin permission.

/npc create <id>

Creates a new NPC at your current location.

/npc create guide_pvp

The ID can only contain letters, numbers, _ or -.

---

/npc edit <id>

Opens the NPC editor.

/npc edit guide_pvp

The editor allows you to modify:

• Name
• Skin
• Dialogue
• Messages
• Buttons
• Actions
• Permissions
• Location
• NPC deletion

---

/npc remove <id>

Removes an NPC.

/npc remove guide_pvp

Alias:

/npc delete <id>

The associated dialogue is preserved.

---

/npc list

Displays all NPCs and provides quick Teleport and Edit buttons.

/npc list

---

/npc tp <id>

Teleports you to an NPC.

/npc tp guide_pvp

---

/npc reload

Reloads NPCs, dialogues and configuration without restarting the server.

/npc reload

---

Command Alias

The plugin also provides:

/inpc

as an alias for /npc.

---

🔘 Actions

Each button can execute one or multiple actions.

Actions can optionally use:

delay: 20

20 ticks = 1 second.

command

Executes a command.

- type: command
  as: console
  command: "tp %player% 100 65 100"

Execution modes:

as: console

or:

as: player

---

message

Sends a message to the player.

- type: message
  message: "§aWelcome %player%!"

---

teleport

Teleports the player to a configured location.

---

sound

Plays a sound for the player.

- type: sound
  sound: ENTITY_PLAYER_LEVELUP

---

particle

Displays particles.

- type: particle
  particle: HAPPY_VILLAGER

---

dialogue

Opens another dialogue.

- type: dialogue
  value: pvp_rules

Return to the previous dialogue:

- type: dialogue
  value: "@back"

---

close

Closes the dialogue.

- type: close

---

🔐 Conditions

Buttons can be displayed only when specific conditions are met.

All conditions support:

negate: true

to invert the condition.

Permission Condition

conditions:
  - type: permission
    permission: "server.vip"

The button will only be available to players with the required permission.

---

Level Condition

Checks the player's level.

conditions:
  - type: level
    min: 10
    max: 50

---

Item Condition

Checks whether the player has a specific item.

conditions:
  - type: item
    material: DIAMOND
    amount: 5

---

World Condition

Restricts a button to a specific world.

conditions:
  - type: world
    world: lobby

---

Unmet Conditions

When a condition is not met, the button can either be hidden:

when-unmet: hide

or disabled:

when-unmet: disable

---

📝 Dialogue Example

id: pvp_rules
title: "§bPvP Rules"

messages:
  - "§7Choose a rule to learn more:"

buttons:
  - id: rule1
    text: "§f1. Respect other players"
    actions:
      - type: dialogue
        value: pvp_rule_1

  - id: rule2
    text: "§f2. Prohibited equipment"
    actions:
      - type: dialogue
        value: pvp_rule_2

  - id: back
    text: "§e← Back"
    actions:
      - type: dialogue
        value: "@back"

---

🧍 NPC Example

id: guide_pvp
name: "§ePvP Guide"
subtitle: "§7Right-click to interact"

skin: "Notch"

dialogue: pvp_intro

location:
  world: "lobby"
  x: 120.5
  y: 65
  z: -32.5
  yaw: 90
  pitch: 0

interaction:
  sound: ENTITY_VILLAGER_TRADE
  particle: HAPPY_VILLAGER

---

🔤 Placeholders

The following placeholders can be used in messages and commands:

%player%
%player_uuid%
%world%

%x%
%y%
%z%

%npc_id%
%npc_name%

%npc_x%
%npc_y%
%npc_z%

Example:

message: "§aWelcome %player% to the lobby!"

---

🔒 Permissions

npc.admin

Grants access to:

• All /npc commands
• NPC editor
• NPC management
• Editor interactions

Default:

op

---

🛡️ Security

InteractiveNPC includes several built-in protections:

• Secure NPC commands
• Dangerous command blacklist
• Sanitized placeholders
• Console execution by default
• Permission checks
• Server-side condition validation
• Button availability validation
• Dialogue session validation
• NPC distance validation

NPC mannequins are automatically recreated from their YAML configuration when their chunks are loaded.

---

⚙️ Configuration

NPCs are stored in:

plugins/InteractiveNPC/npcs/

Dialogues are stored in:

plugins/InteractiveNPC/dialogues/

After making changes, simply run:

/npc reload

to apply them without restarting your server.

---

🚀 Perfect For

InteractiveNPC is ideal for:

• 🎮 Server lobbies
• 🏆 Minigame servers
• ⚔️ PvP servers
• 🗺️ Adventure maps
• 🎭 Story-driven maps
• 🧙 RPG servers
• 📚 Tutorial NPCs
• 🚪 Teleportation NPCs
• 📖 Interactive dialogue systems

Turn simple Minecraft mannequins into powerful, interactive and fully configurable NPCs with InteractiveNPC.