SimpleNPCs

Minecraft 版本： 1.21 1.21.1 1.21.2 1.21.3 1.21.4 1.21.5 1.21.6 1.21.7 1.21.8 1.21.9 1.21.10 1.21.11 26.1 26.1.1 26.1.2 26.2

平台： paper purpur

标签： management

简体中文 # SimpleNPC **SimpleNPC** 是一款极其轻量的 Minecraft 实体 NPC 插件，它唯一的功能就是右键配置过的实体时，执行一系列命令。你几乎不需要学习任何新的内容，也不需要花费时间调节配置文件，就能立刻掌握其使用方式。 本插件不依赖外部数据库，采用纯标签驱动架构。它不负责实体的生成或物理属性的修改，而是将交互逻辑直接储存在实体的 PDC 中。任何非玩家实体均可作为 NPC，数据与原版区块同步保存与销毁。 --- ## 核心特性 * **无外部状态：** 不使用 MySQL 或 SQLite。所有命令和行为数据直接存储在实体的 PDC 中。当实体被清除时，数据随之销毁，不会产生数据残留。 * **泛用实体支持：** 推荐配合 1.21.9+ 原生的玩家模型 (`minecraft:mannequin`) 使用，同时也支持任何非玩家实体。只需通过命令添加 PDC 标签即可将其转换为 NPC。 * **交互防抖：** 内置交互冷却机制，防止因网络延迟或连点导致的命令重复执行。 * **指令执行：** * 支持 `%player_name%` 等基础变量，并兼容 PlaceholderAPI。 * 带有 `player:` 前缀的指令将以玩家身份执行，无前缀则默认以控制台身份执行。 * **技术规范：** 基于 Paper API 1.21.11+ 与 Kotlin 编写。使用 Brigadier 构建命令树，通过 MiniMessage 处理文本格式化。 * **视觉附加功能 (计划中)：** 计划引入 PacketEvents，通过发包实现特定玩家视角的皮肤镜像与目光追随功能。 --- ## 快速上手 **第一步：生成实体** 使用原版命令或生成蛋召唤一个实体，并配置所需的属性（如无敌、无重力等）： ```mcfunction /summon minecraft:mannequin ~ ~ ~ {Invulnerable:1b,NoGravity:1b} ``` **第二步：绑定命令** 使用插件提供的选择器，向该实体注入需要触发的命令： ```mcfunction /npc add @n[type=mannequin] say 欢迎来到这里，%player_name%！ /npc add @n[type=mannequin] player:spawn ``` **第三步：玩家交互** 玩家右键点击该实体，系统将按顺序执行绑定的命令。 --- ## 命令与权限 所有命令默认需要 `pronpc.admin` 权限。命令目标 `` 支持 Minecraft 原版目标选择器。 | 命令 | 说明 | | --- | --- | | `/npc reload` | 重载配置文件。 | | `/npc list ` | 列出目标实体 PDC 中绑定的所有命令。在聊天框输出，点击对应行可复制内容。 | | `/npc add ` | 向目标实体追加交互命令。若目标原先无 PDC 标签，会自动初始化。 | | `/npc remove ` | 根据列表索引移除指定命令。若列表被清空，实体的 NPC 标签将被移除。 | > 注：目标选择器仅允许选择一个实体。 --- ## 配置文件 (config.yml) ```yaml # NPC 交互全局冷却时间（单位：秒） cooldown-seconds: 3.0 ``` --- ## 开发者参考 插件的底层数据结构如下： * **命名空间 (Namespace):** `npc` * **核心键值:** `commands` 对应类型 `PersistentDataType.LIST.strings()` * **视觉扩展键值 (计划中):** * `mirror_skin` 对应类型 `PersistentDataType.BYTE` * `look_at` 对应类型 `PersistentDataType.BYTE` English *Translated by AI，Sorry for possible grammar mistakes.* # SimpleNPC **SimpleNPC** is an extremely lightweight Minecraft entity NPC plugin. Its sole function is to execute a series of commands when a player right-clicks a configured entity. You needn't to learn much new things or spent lots of time configuring it to master its usage. This plugin does not rely on any external database; it uses a purely tag-driven architecture. It does not handle entity spawning or modify physical attributes — instead, it stores interaction logic directly in the entity's PDC. Any non-player entity can serve as an NPC, and the data is saved and destroyed synchronously with vanilla chunks. --- ## Core Features * **No External State:** No MySQL or SQLite. All command and behavior data is stored directly in the entity's PDC. When the entity is removed, the data is destroyed alongside it, leaving no residual data. * **Universal Entity Support:** Designed to work best with the native player model (`minecraft:mannequin`) introduced in 1.21.9+, but also supports any non-player entity. Simply add the PDC tag via a command to turn it into an NPC. * **Interaction Debounce:** Built-in interaction cooldown mechanism prevents duplicate command execution caused by network latency or rapid clicking. * **Command Execution:** * Supports basic variables like `%player_name%` and is compatible with PlaceholderAPI. * Commands prefixed with `player:` are executed as the player; commands without a prefix are executed as the console by default. * **Technical Specifications:** Built on Paper API 1.21.11+ and written in Kotlin. Uses Brigadier for command tree construction and MiniMessage for text formatting. * **Planned Visual Additions:** Plans to introduce PacketEvents to implement per-player skin mirroring and gaze-following features via packet manipulation. --- ## Quick Start **Step 1: Spawn an entity** Use a vanilla command or a spawn egg to summon an entity and configure desired attributes (e.g., invulnerable, no gravity): ```mcfunction /summon minecraft:mannequin ~ ~ ~ {Invulnerable:1b,NoGravity:1b} ``` **Step 2: Bind commands** Use the plugin's selectors to inject commands that should be triggered by the entity: ```mcfunction /npc add @n[type=mannequin] say Welcome, %player_name%! /npc add @n[type=mannequin] player:spawn ``` **Step 3: Player interaction** When a player right-clicks the entity, the system executes the bound commands in order. --- ## Commands & Permissions All commands require the `pronpc.admin` permission by default. The command target `` supports Minecraft native target selectors. | Command | Description | | --- | --- | | `/npc reload` | Reloads the configuration file. | | `/npc list ` | Lists all commands bound in the target entity's PDC. Outputs to chat; clicking a line copies its content. | | `/npc add ` | Appends an interaction command to the target entity. If the target has no PDC tag yet, it will be initialized automatically. | | `/npc remove ` | Removes the command at the given list index. If the list becomes empty, the entity's NPC tag is removed. | > Note: The target selector must match exactly one entity. --- ## Configuration (config.yml) ```yaml # Global interaction cooldown for NPCs (in seconds) cooldown-seconds: 3.0 ``` --- ## Developer Reference The underlying data structure of the plugin is as follows: * **Namespace:** `npc` * **Core Key:** `commands` — type `PersistentDataType.LIST.strings()` * **Planned Visual Extension Keys:** * `mirror_skin` — type `PersistentDataType.BYTE` * `look_at` — type `PersistentDataType.BYTE`