NehaNPCs (NNPC)

NehaNPCs is a lightweight and flexible NPC management plugin for Paper.

It provides both persistent Minecraft entity NPCs and packet-based PLAYER NPCs, with support for skins, holograms, click actions, conversations, movement paths, equipment, appearance customization, localization, and proxy server transfers.

The goal of NehaNPCs is to provide the common functionality needed for server NPCs without requiring a large NPC framework.

---

Features

NPC Types

NehaNPCs supports two different kinds of NPCs:

• Regular Minecraft entity NPCs
• Packet-based PLAYER NPCs

Regular entity NPCs are real Bukkit entities with their AI disabled and can be customized using supported entity properties.

PLAYER NPCs are displayed using ProtocolLib packets and do not create real online players.

---

PLAYER NPCs

PLAYER NPCs support:

• Packet-based spawning and despawning
• Custom player skins
• Per-viewer skin mirroring
• Tab-list handling
• Click detection
• Custom names
• Holograms
• Actions
• Conversations
• Movement paths

Example:

/npc create 1 player Guide
/npc skin 1 Notch
/npc toggle 1 mirror

The mirror option makes the NPC display the skin of each individual viewer.

---

Entity NPCs

Normal Minecraft entities can also be used as NPCs.

Example:

/npc create 2 villager Shopkeeper
/npc create 3 zombie Guardian

Entity NPCs can have:

• AI disabled
• Gravity disabled
• Invulnerability
• Equipment
• Collision settings
• Glowing
• Custom display names
• Holograms
• Entity-specific appearance settings

---

Entity Customization

The /npc customize command can modify supported properties for specific entity types.

/npc customize <id> <key> <value>

Currently supported customization options include:

Armor Stand

setSmall
setArms
setBasePlate
setInvisible

Creeper

setPowered

Zombie and Ageable entities

setBaby

Slime / Magma Cube

setSize

Sheep

setColor
setSheared

Villager

setProfession
setVillagerType

Wolf

setSitting
setTamed
setAngry
setCollarColor

Fox

setSitting
setFoxType
setSleeping
setCrouching

Axolotl

setVariant

---

NPC Toggles

NPC behavior and display options can be changed with:

/npc toggle <id> <look|holo|glow|mirror|collision> [color]

Available toggles include:

• look — make the NPC look toward nearby players
• holo — enable or disable the hologram
• glow — enable or disable glowing
• mirror — display the viewer's skin on PLAYER NPCs
• collision — enable or disable entity collision

---

Holograms

NPCs can display custom text above their head.

/npc lines <id> <text...>
/npc height <id> <height>

The hologram height can be adjusted individually for each NPC.

---

Equipment

Living entity NPCs can use equipment.

/npc equip <id> <HAND|OFFHAND|HELMET|CHESTPLATE|LEGGINGS|BOOTS>

Supported slots:

HAND
OFFHAND
HELMET
CHESTPLATE
LEGGINGS
BOOTS

---

Actions

NPCs can execute one or more actions when clicked.

/npc action add <id> <CMD|CONSOLE|CHAT|MESSAGE|SERVER> <content...>
/npc action list <id>
/npc action remove <id> <actionId>
/npc action cooldown <id> <actionId> <seconds>

Supported action types:

• CMD — execute a command as the clicking player
• CONSOLE — execute a command from the server console
• CHAT — send chat input as the player
• MESSAGE — send a message to the player
• SERVER — transfer the player to another proxy server

Each action can have its own cooldown.

Placeholders

Actions support the following placeholders:

%player%
%uuid%
%world%
%x%
%y%
%z%
%npc_id%
%npc_name%

Example:

/npc action add 1 MESSAGE Hello %player%!
/npc action add 1 CONSOLE give %player% diamond 1

---

Velocity / Proxy Server Transfer

Players can be transferred to another backend server using:

/npc action add 1 SERVER lobby

The following CMD form is also supported:

/npc action add 1 CMD server lobby

When using Velocity, enable:

bungee-plugin-message-channel = true

in velocity.toml.

The backend server uses the configured BungeeCord plugin messaging channel.

---

Conversations

NPCs can have configurable conversations.

/npc conversation create <name>
/npc conversation remove <name>
/npc conversation set <id> <name> <CLICK|RADIUS>
/npc conversation cooldown <name> <seconds>
/npc conversation radius <name> <radius>
/npc conversation text add <name> <delayTicks> <text...>
/npc conversation text remove <name> <index>
/npc conversation text list <name>
/npc conversation list

Two conversation triggers are supported:

CLICK
RADIUS

CLICK starts the conversation when the NPC is clicked.

RADIUS allows a conversation to activate when a player enters the configured range.

Conversation lines can have individual delays, allowing dialogue to appear over time instead of all at once.

---

Movement Paths

NPCs can move along configurable paths.

/npc path create <name>
/npc path point <name>
/npc path set <id> <name>
/npc path speed <name> <speed>
/npc path loop <name> <true|false>
/npc path delete <name>
/npc path list

Path points are created from the player's current location.

Paths support:

• Multiple points
• Configurable movement speed
• Looping
• Assignment to individual NPCs

---

Languages

NehaNPCs includes built-in English and Japanese localization.

By default, new installations automatically use each player's Minecraft language:

settings:
  language: auto
  fallback-language: en

Bundled languages:

English  -> messages_en.yml
Japanese -> messages.yml

Command names and subcommands remain the same in every language, while command feedback, errors, usage messages, and other plugin messages are localized.

You can force one language for all players:

settings:
  language: en

or:

settings:
  language: ja

Locale-style values such as these are also supported:

en_US
ja_JP

Additional languages can be added by creating a language file such as:

plugins/NehaNPCs/messages_de_DE.yml

If a translation is missing, NehaNPCs falls back to the configured fallback language.

Run:

/npc reload

after changing language settings.

---

Storage

NehaNPCs stores its configuration and persistent data in YAML files.

plugins/NehaNPCs/config.yml
plugins/NehaNPCs/messages.yml
plugins/NehaNPCs/messages_en.yml
plugins/NehaNPCs/npcs.yml
plugins/NehaNPCs/conversations.yml
plugins/NehaNPCs/paths.yml

The following data is persisted across server restarts:

• NPCs
• Locations
• Entity types
• Skins
• Equipment
• Hologram settings
• Appearance settings
• Actions
• Action cooldowns
• Conversations
• Conversation settings
• Movement paths

---

Default Configuration

NehaNPCs includes configurable defaults for NPC behavior.

settings:
  language: auto
  fallback-language: en
  autosave-interval-seconds: 60

  hologram:
    default-height: 0.3

  look-at-player:
    update-interval-ticks: 10
    radius: 8.0

  path:
    update-interval-ticks: 2
    default-speed: 0.2

  debug: false

server-transfer:
  enabled: true
  intercept-server-command: true
  channel: BungeeCord

By default, NPC data is automatically saved every 60 seconds.

---

Commands

/npc create <id> <type> <name...>
/npc delete <id>
/npc list
/npc teleport <id>
/npc move <id>
/npc skin <id> <username>
/npc lines <id> <text...>
/npc height <id> <height>
/npc equip <id> <HAND|OFFHAND|HELMET|CHESTPLATE|LEGGINGS|BOOTS>
/npc type <id> <type>
/npc customize <id> <key> <value>
/npc toggle <id> <look|holo|glow|mirror|collision> [color]

/npc action <add|list|remove|cooldown> ...
/npc conversation <create|remove|set|cooldown|radius|text|list> ...
/npc path <create|point|set|speed|loop|delete|list> ...

/npc save
/npc reload

/znpcs is available as an alias for /npc.

---

Permissions

The main administrator permission is:

nehanpcs.admin

It grants access to all NehaNPCs commands.

Individual command permissions are also available for servers that require more granular permission control.

---

Requirements

• Paper 1.21.x
• ProtocolLib
• Java version required by your Paper build

Paper 1.21.11 requires a compatible ProtocolLib development build for PLAYER NPC functionality. ProtocolLib 5.4.0 does not support the required PLAYER NPC packets on that server version.

---

日本語

NehaNPCsは、Paper向けの軽量で柔軟なNPC管理プラグインです。

通常のMinecraftエンティティを利用したNPCと、ProtocolLibのパケットを利用したPLAYER NPCの両方に対応しています。

スキン、ホログラム、クリックアクション、会話、パス移動、装備、エンティティごとの見た目設定などをゲーム内コマンドから管理できます。

主な機能

• 通常エンティティNPC
• PLAYER NPC
• PLAYER NPCのスキン設定
• プレイヤーごとのミラースキン
• ホログラム
• 装備設定
• エンティティ固有の見た目設定
• NPCクリックアクション
• アクションごとのクールダウン
• NPC会話
• CLICK / RADIUSによる会話開始
• 行ごとの会話表示遅延
• NPCパス移動
• 移動速度設定
• パスのループ
• NPCの視線追従
• Glow設定
• Collision設定
• Velocityサーバー移動
• YAMLによるデータ永続化
• 自動保存
• 日本語 / 英語対応
• プレイヤーのMinecraft言語を利用した自動言語切替

基本例

/npc create 1 zombie &a案内人
/npc create 2 player Guide
/npc skin 2 Notch
/npc toggle 2 mirror
/npc list
/npc teleport 1
/npc move 1
/npc save
/npc reload

言語

初期設定ではプレイヤーがMinecraftで使用している言語を自動的に使用します。

settings:
  language: auto
  fallback-language: en

英語と日本語が標準で含まれています。

English  -> messages_en.yml
Japanese -> messages.yml

全員を日本語に固定する場合:

settings:
  language: ja

全員を英語に固定する場合:

settings:
  language: en

独自翻訳も追加できます。

plugins/NehaNPCs/messages_de_DE.yml

設定変更後は以下を実行してください。

/npc reload

NPC、アクション、会話、パス、スキン、ホログラム設定、位置などはYAMLへ保存され、サーバー再起動後にも復元されます。