MythicSuperNoNo 使用文档 - 精灵小助手插件

插件介绍

不是站桩宠物，是可交互的随身助手

它会跟着玩家移动、响应点击、弹出提示、执行命令，还带皮肤商店和皮肤库。说白了，就是把“宠物外观 + 菜单入口 + 养成系统”揉成了一个插件。

MythicSuperNoNo 是一款面向 Paper 1.20.1 的精灵小助手插件。每位玩家都可以拥有一个专属小助手实体，小助手会按玩家偏好的位置模式跟随移动，并支持原版实体、ModelEngine 模型、MythicMobs 生物三种皮肤来源。

玩家可以通过设置 GUI 开关小助手、切换位置、打开皮肤商店与皮肤库；通过右键触发命令、左键查看随机提示；如果连续乱点，或者长时间挂机，小助手还会进入“生气模式”，在玩家面前来回乱窜一段时间。

说人话：玩家身边跟着一个自己的小精灵，能换皮肤、能说话、能点开菜单，还能作为你的主城功能入口。

本文档按代码实际实现整理。当前版本代码里一共实现了 13 种位置模式，比 README 里写的 7 种更多，页面内容以代码为准。

适合拿来做什么

主城随身菜单

右键小助手直接打开 TrMenu、传送菜单、功能总面板，玩家不需要记命令。

宠物皮肤养成

免费皮肤 + 商店皮肤 + 点券皮肤都能做，玩家买完后进皮肤库一键切换。

活动陪伴精灵

节日活动时给玩家发一个限定精灵，顺手把右键行为绑定到活动菜单或礼包命令。

展示型跟随实体

如果你本来就有 ModelEngine 或 MythicMobs 模型，这个插件可以直接把它们挂成玩家的随身助手。

主要功能

一人一个专属小助手，玩家加入服务器后会异步读取数据并自动生成自己的助手实体
13 种跟随位置模式，包括左右上方、左右下方、身后、身侧、正前上/下、左右前方等
平滑移动与防抖处理，通过插值、停止距离与超距传送避免助手抖动或丢失
左键提示 / 右键命令，只有助手主人本人可以交互，不会被别人乱点
生气系统，连续点击达到阈值后触发，也支持挂机超时自动触发
皮肤系统，支持原版实体、ModelEngine R4 模型、MythicMobs 怪物三种来源
GUI 设置面板，内置设置页、皮肤商店、皮肤库，全部支持分页浏览
多货币购买，皮肤价格支持 VAULT 与 PLAYERPOINTS，也支持免费领取
MySQL 持久化，记录玩家开关状态、当前皮肤、拥有皮肤、位置偏好
实体保护完整，伤害、目标锁定、燃烧、变形、区块卸载、换世界、重生等场景都做了处理
自动聊天，可按配置间隔让助手主动发随机提示，不想要可设为 0 关闭

命令列表

主命令：/helper，别名：/h、/spirit

命令	说明	权限
`/helper`	打开设置面板	`helper.use`
`/helper shop`	打开皮肤商店	`helper.shop`
`/helper skins`	打开皮肤库	`helper.use`
`/helper toggle`	开启或关闭自己的小助手	`helper.use`
`/helper position <位置>`	切换位置模式	`helper.use`
`/helper reload`	重载配置、菜单与皮肤	`helper.reload`
`/helper admin give <玩家> <皮肤ID>`	给予指定玩家某个皮肤	`helper.admin`
`/helper admin remove <玩家> <皮肤ID>`	移除指定玩家某个皮肤	`helper.admin`
`/helper help`	输出帮助文本	`helper.use`

不带参数执行 /helper 会直接打开设置 GUI，不是输出帮助。这个设计更适合给普通玩家用。

权限节点

权限	说明	默认
`helper.use`	基础使用权限，打开面板、切皮肤、切位置都靠它	所有人
`helper.shop`	允许打开皮肤商店	所有人
`helper.admin`	管理员皮肤发放与移除命令	OP
`helper.reload`	允许重载配置	OP

位置模式

当前版本一共实现了 13 个位置枚举。皮肤可以通过 allowed-positions 限制可选位置，因此玩家不一定能使用全部位置。

枚举值	说明
`VIEW_TOP_LEFT`	视角左上方悬浮
`VIEW_TOP_RIGHT`	视角右上方悬浮
`GROUND_BOTTOM_LEFT`	视角左下地面
`GROUND_BOTTOM_RIGHT`	视角右下地面
`FOLLOW_BEHIND`	跟随在身后
`FOLLOW_LEFT`	跟随在左侧
`FOLLOW_RIGHT`	跟随在右侧
`FRONT_TOP`	正前上方
`FRONT_BOTTOM`	正前下方
`FRONT_LEFT_TOP`	左前上方
`FRONT_RIGHT_TOP`	右前上方
`FRONT_LEFT_BOTTOM`	左前下方
`FRONT_RIGHT_BOTTOM`	右前下方

如果设置面板里某个位置按钮显示红色，说明当前皮肤的 allowed-positions 没把这个位置放出来，不是插件坏了。

使用教程

安装插件并准备数据库

把 MythicSuperNoNo.jar 放进 plugins 文件夹，准备好 MySQL 数据库。首次启动会自动创建数据表。

配置主文件

编辑 plugins/MythicSuperNoNo/config.yml，填好数据库连接、位置参数、点击冷却、生气阈值等基础设置。

配置皮肤

在 plugins/MythicSuperNoNo/skins/ 下按一皮肤一文件的方式写 YAML，设置皮肤类型、价格、提示语、右键命令和允许位置。

按需调整菜单

如果默认 GUI 布局不合胃口，可以改 menus/settings.yml、menus/skin-shop.yml、menus/skin-library.yml。

执行重载

/helper reload，让配置、菜单和皮肤重新加载。

让玩家开始使用

玩家输入 /helper 打开主面板，或者直接用 /helper shop、/helper skins 进入购买和切换流程。

玩家常用流程

购买皮肤

玩家打开 /helper shop，点击未拥有皮肤。免费皮肤直接领取，收费皮肤则检测 Vault 或 PlayerPoints 余额后完成扣费。

切换皮肤

玩家打开 /helper skins，点击已拥有皮肤即可切换。若当前站位不被新皮肤支持，会自动回退到该皮肤的默认位置。

配置文件

主配置文件位于 plugins/MythicSuperNoNo/config.yml。如果数据库连不上，插件会在启动阶段直接禁用自己，所以数据库配置别写着玩。

数据库与基础行为

YAMLconfig.yml

database:
  host: 127.0.0.1
  port: 3306
  database: supernono
  username: root
  password: "你的密码"
  pool:
    maximum-pool-size: 10
    minimum-idle: 2
    max-lifetime: 1800000
    connection-timeout: 5000
    idle-timeout: 600000

respawn-delay: 20
right-click-cooldown-ms: 500
left-click-cooldown-ms: 5000
default-skin: 'allay'
default-enabled: true
auto-tip-interval: 180

位置与生气系统

YAMLconfig.yml

position-settings:
  distance: 2.5
  top-height: 2.5
  lerp-speed: 0.08
  update-interval: 1
  forward-mult: 0.5
  ground-forward-mult: 0.3
  teleport-distance: 10.0
  stop-distance: 0.3

anger:
  clicks: 5
  time-window: 3
  duration: 10
  switch-interval: 10
  afk-seconds: 600

hologram:
  display-duration: 60
  default-height: 2.0

auto-tip-interval: 0 可以关闭自动聊天，anger.afk-seconds: 0 可以关闭挂机触发生气。

皮肤配置

每个皮肤一个 YAML 文件，放在 plugins/MythicSuperNoNo/skins/ 下。当前代码支持三种类型：VANILLA、MEG、MYTHICMOBS。

YAMLfox.yml

id: fox
display-name: '&#FF8844小狐狸'
type: VANILLA
entity-type: FOX
baby: true

price:
  type: VAULT
  amount: 1000

hologram-height: 1.5
allowed-positions:
  - FOLLOW_BEHIND
  - FOLLOW_LEFT
  - FOLLOW_RIGHT
  - FRONT_BOTTOM
  - FRONT_LEFT_BOTTOM
  - FRONT_RIGHT_BOTTOM

default-position: FOLLOW_BEHIND
head-title: '&#FF8844%player%的小狐狸'
look-at-player: true

tips:
  - '&#FFAA66呜呜，有好吃的吗？'
angry-tips:
  - '&c再戳我我就跑掉了！'
right-click-commands:
  - '[message] &6小狐狸蹭了蹭你的手~'
  - '[sound] ENTITY_FOX_AMBIENT 1.0 1.5'

icon:
  material: SWEET_BERRIES
  custom-model-data: 0
  lore:
    - '&7一只活泼可爱的小狐狸'

字段	说明
`id`	皮肤唯一标识，用于后台发放、移除和数据库记录
`display-name`	显示名称，支持颜色代码
`type`	`VANILLA` / `MEG` / `MYTHICMOBS`
`entity-type`	原版皮肤使用的 Bukkit 实体名
`model-id`	ModelEngine 模型蓝图 ID
`mythicmob-id`	MythicMobs 生物 ID
`price.type`	价格类型，当前实现支持 `VAULT` 与 `PLAYERPOINTS`
`price.amount`	价格，填 `0` 视为免费皮肤
`allowed-positions`	限制该皮肤能使用哪些位置
`default-position`	玩家切到此皮肤时的默认站位
`tips`	左键提示和自动聊天的随机文本池
`angry-tips`	触发生气模式时显示的随机文本
`right-click-commands`	右键助手后执行的动作列表
`head-title`	实体头顶显示名，支持 `%player%`
`look-at-player`	是否尽量朝向玩家或朝向玩家视角方向
`icon.*`	商店和皮肤库中显示的物品图标配置

GUI 菜单

插件内置三套菜单配置，分别对应设置面板、皮肤商店、皮肤库：

settings.yml

控制主面板按钮、位置按钮、边框材质、关闭按钮槽位。默认布局里位置按钮一共 13 个。

skin-shop.yml

控制商店标题、翻页按钮、购买提示文本。每页内容区默认展示 28 个皮肤。

skin-library.yml

控制已拥有皮肤列表、当前使用中前缀、切换提示和翻页按钮。

YAMLmenus/settings.yml

buttons:
  toggle:
    slot: 10
  shop:
    slot: 12
  library:
    slot: 14

position-buttons:
  slots: [28, 29, 30, 31, 32, 33, 34, 37, 38, 39, 40, 41, 42]
  active:
    material: LIME_STAINED_GLASS_PANE
  available:
    material: WHITE_STAINED_GLASS_PANE
  unavailable:
    material: RED_STAINED_GLASS_PANE

close:
  slot: 49
  material: BARRIER

交互动作

右键动作由 right-click-commands 驱动。当前版本支持多种前缀动作，还支持延迟执行和 %player% 变量替换。

YAMLskins/allay.yml

right-click-commands:
  - '[message] &a欢迎回来，%player%'
  - '[sound] ENTITY_ALLAY_AMBIENT_WITH_ITEM 1.0 1.2'
  - '[delay:20][console] give %player% diamond 1'
  - '[op] trmenu open 新主菜单1'
  - '[close]'

动作前缀	说明
`[player]`	以玩家身份执行命令
`[op]`	临时给玩家 OP 后执行命令，执行结束自动还原
`[console]`	以控制台身份执行命令
`[message]`	给玩家发送一条消息
`[sound]`	播放音效，格式为 `音效名音量音调`
`[close]`	关闭玩家当前打开的界面
`[delay:20]`	给后续动作增加延迟，单位为 tick

[op] 动作很方便，也很危险。既然都已经给了精灵右键菜单，就别顺手让它帮玩家执行奇怪的高权限命令。

消息配置

消息文件位于 plugins/MythicSuperNoNo/messages.yml，可自由改成你的服务器文案风格。

YAMLmessages.yml

prefix: '&#FFD700✦ &f精灵助手 &#FFD700✦ &7'

helper-toggled-on: '&a小助手已开启！'
helper-toggled-off: '&c小助手已关闭。'
position-changed: '&a位置已切换为: &e%position%'
position-not-allowed: '&c当前皮肤不支持该位置。'
skin-changed: '&a皮肤已切换为: &e%skin%'
shop-purchased: '&a购买成功！已获得皮肤: &e%skin%'
shop-not-enough-money: '&c余额不足！需要 &e%price% %currency%'
database-error: '&c数据库操作失败，请联系管理员。'
anger-trigger: '&c小助手生气了！'

currency-vault: '&6冒险币'
currency-playerpoints: '&b蓝宝石'

依赖插件

插件 / 环境	是否必须	说明
Paper 1.20.1	必须	基于 Paper API 1.20 开发
MySQL 5.7+	必须	插件启动就会连接数据库，连不上会直接禁用
Vault	可选	只有皮肤价格使用 `VAULT` 时才需要
PlayerPoints	可选	只有皮肤价格使用 `PLAYERPOINTS` 时才需要
DecentHolograms	推荐	用于左键提示和生气提示的全息文字，不装则退回聊天消息
ModelEngine R4	可选	启用 `MEG` 类型皮肤时需要
MythicMobs	可选	启用 `MYTHICMOBS` 类型皮肤时需要
PlaceholderAPI	预留	`plugin.yml` 里声明了软依赖，但当前代码没有直接调用它

技术信息

项目	信息
插件名称	MythicSuperNoNo
版本	1.0
服务端	Paper 1.20.1
Java 版本	17+
API 版本	1.20
数据库	MySQL 5.7+（HikariCP 5.1.0）
MySQL 驱动	mysql-connector-java 8.0.33
Vault API	1.7.1
PlayerPoints	3.2.7
DecentHolograms	2.8.6
MythicMobs	5.3.5
ModelEngine	R4.0.4

常见问题

这是正常行为。插件在 onEnable() 阶段连不上 MySQL 时会直接自我禁用，先检查 config.yml 的数据库地址、账号、密码和库名。

需要安装 DecentHolograms。没装时不会报错，但提示会退回到聊天栏，而不是飘在头顶上。

检查该皮肤的 allowed-positions。代码会严格限制玩家只能切到这个皮肤允许的位置。

先确认对应插件已安装，再检查 model-id 或 mythicmob-id 是否正确。当前实现里如果目标皮肤生成失败，会尝试回退到默认皮肤。

当前版本不行。玩家状态、拥有皮肤和位置偏好都走 MySQL 持久化，代码里没有 YAML 或 SQLite 备选实现。

购买成功只代表“拥有了”，切换使用还要进 /helper skins 点一下。如果数据库写入失败，插件会尝试退款并提示 database-error。

如果你看到这里还没关页面，说明你八成是真的准备把精灵系统做进服里了。祝你的玩家先是觉得它可爱，然后开始为皮肤心甘情愿掏钱。

MythicSuperNoNo ¥168

插件介绍

不是站桩宠物，是可交互的随身助手

适合拿来做什么

主城随身菜单

宠物皮肤养成

活动陪伴精灵

展示型跟随实体

主要功能

命令列表

权限节点

位置模式

使用教程

安装插件并准备数据库

配置主文件

配置皮肤

按需调整菜单

执行重载

让玩家开始使用

玩家常用流程

购买皮肤

切换皮肤

配置文件

数据库与基础行为

位置与生气系统

皮肤配置

GUI 菜单

settings.yml

skin-shop.yml

skin-library.yml

交互动作

消息配置

依赖插件

技术信息

常见问题