技能模型与动画配置

技能目录共 112 项：100 项物种技能与 12 项已有 ModelEngine 动画技能。每项均配置原生粒子、RGB 轨迹和音效，自动释放与手动释放共用表现。模型缺失、动画名错误或未安装 ModelEngine 时仍保留基础粒子与声音，技能伤害、保护判断和冷却继续按原规则执行。

两种模型用法

配置	用途	模型生命周期
model-engine-target: EFFECT	用现有蓝图创建独立技能特效，例如缩小的旋风、雪幕、地裂	临时不可碰撞载体，不保存；表现结束后回收
model-engine-target: PET	在宠物已挂载的模型上播放已有动画，例如 Parro 的攻击、跳跃、奔跑	不创建第二只宠物，不替换、不缩放、不销毁宠物模型；结束时仅停止本次技能仍拥有的动画

animation-speed 是 0.1～4 的播放倍率，默认 1.0。它不会加快伤害脉冲、缩短 CD 或改变药水等级。visual.duration-ticks 是一次表现的寿命，允许 8～60 tick；技能自身的 duration-ticks 是控制、增益或闪避窗口，两者分别计算。蓝图动画的原始长度也可能与它们不同：慢放或长动画可以被表现寿命截断。

本次使用的已有蓝图与动画

下面完整列出 12 项预置实际引用的模型与动画。本服已有对应蓝图；其他服务器需要安装自己的 ModelEngine 蓝图并让客户端加载对应资源包，LiPet 不附带或复制这些模型资源。蓝图文件存在不等同于模型已被运行中的 ModelEngine 注册，更不等同于客户端画面已验收。

已有蓝图 ID	使用的动画	新技能	缩放 / 动画倍率
liseasons_coldwave	idle	model_frost_ring	0.22 / 1
liseasons_blizzard	idle	model_blizzard	0.2 / 1.25
liseasons_heatwave	idle	model_heatwave	0.18 / 1.4
liseasons_tornado	idle	model_tornado	0.1 / 1.2
liseasons_earthquake	idle	model_quake	0.13 / 1
liseasons_tsunami	idle	model_tidal_push	0.1 / 1.2
liseasons_thunderstorm	idle	model_thunder_burst	0.2 / 1.2
liseasons_hail	idle	model_hail_strike	0.22 / 1.25
liseasons_sandstorm	idle	model_sand_veil	0.18 / 1
parro_pet	attack、jump、run	model_parro_peck、model_parro_dodge、model_parro_dash	保持原模型大小 / 1、1、1.25
parro_mount	attack、jump、run	同上三个 Parro 技能	保持原模型大小 / 1、1、1.25

九个 LiSeasons 场景仅借用其 idle 视觉，预置统一持续 40 tick（约 2 秒）并采用表中的小倍率。它们不会启动 LiSeasons 灾害、改变天气、创建真实闪电或破坏地形。实际伤害和控制详见 112 技能目录。

parro_pet 与 parro_mount 的上述动画名相同：attack 原长 0.8 秒，jump 原长 0.65 秒，run 原长 0.9 秒且循环。三项预置的表现寿命依次为 20、16、40 tick，动画倍率依次为 1、1、1.25；循环动作会随技能表现回收，不会一直强制跑步。

EFFECT：使用已有场景蓝图

下面是 model_frost_ring 的视觉配置用法。合并到已有技能的 visual 节点即可，保留其他技能数值；不要用这个片段替换完整 pet-skills.yml。

# 技能视觉对象；只设置动画和粒子，不修改战斗数值。
visual:
  # 粒子：Bukkit 无附加数据粒子，或支持 RGB 的 DUST。
  particle: SNOWFLAKE
  # 轨迹：RING、HELIX、BURST、BEAM、STAR、WAVE 六选一。
  shape: RING
  # RGB 颜色：带引号的 #RRGGBB。
  color: '#BDEEFF'
  # 音效：Bukkit 大写名称或 namespace:sound.key。
  sound: BLOCK_GLASS_BREAK
  # 可选原版/CE 物品模型；空字符串关闭物品回退。
  model-item: ''
  # 已安装的 ModelEngine 场景蓝图 ID；EFFECT 下为空表示不创建 ME 模型。
  model-engine-id: liseasons_coldwave
  # EFFECT 创建独立临时特效；PET 播放宠物已有模型动画。
  model-engine-target: EFFECT
  # 此蓝图真实存在的动画名；EFFECT 可留空以仅展示模型。
  animation: idle
  # 动画速度倍率：0.1～4，1.0 为原速。
  animation-speed: 1.0
  # 单次视觉寿命：8～60 tick；40 tick 约为 2 秒。
  duration-ticks: 40
  # 临时模型缩放：0.1～4；场景蓝图需要缩小，避免遮挡玩家视野。
  scale: 0.22

EFFECT 模型放在独立、不可碰撞且不可伤害的临时标记盔甲架上，不接管宠物碰撞箱。表现结束时回收临时载体与它自己的模型容器。

PET：在已有宠物模型上播放动画

# 技能视觉对象；本例要求宠物已挂载含 attack 动画的 ModelEngine 模型。
visual:
  # 基础粒子；模型不可用时仍会显示。
  particle: CRIT
  # 粒子轨迹：六种支持的形状之一。
  shape: BEAM
  # RGB 颜色：带引号的 #RRGGBB。
  color: '#B6DFFF'
  # 基础音效：有效 Bukkit 名称或资源包音效 ID。
  sound: ENTITY_PARROT_AMBIENT
  # PET 模式必须留空，不能同时使用物品模型。
  model-item: ''
  # 空值仅在宠物恰好挂载一个模型时自动选择；多模型必须填写已挂载的准确 ID。
  model-engine-id: ''
  # PET 只借用当前宠物的模型，不创建、替换、复制或卸载模型。
  model-engine-target: PET
  # PET 必填；本例使用 parro_pet 与 parro_mount 均具有的 attack。
  animation: attack
  # 动画速度：0.1～4；不影响技能实际伤害、持续时间和冷却。
  animation-speed: 1.0
  # 技能表现寿命：8～60 tick；20 tick 约为 1 秒。
  duration-ticks: 20
  # 保留视觉大小配置：0.1～4；PET 模式不会用它缩放宠物原模型。
  scale: 1.0

动画只在对应模型已经挂载到当前宠物时播放。填写另一个蓝图 ID 不会换肤，也不会把该模型重新创建到宠物身上。多个模型挂在同一实体上而 ID 留空时，模型动画降级，避免误选装饰或座椅模型。空动画名、非法倍率或 PET 同时设置 model-item 会使本次重载校验失败，并保留旧运行配置。

正常结束、召回、死亡或重载时，只停止本次技能持有且仍然有效的动画实例。若其他系统已接管并播放同名动画，后来的动画不会被本次回收停止；宠物模型、大小、碰撞和座椅继续保留。

停止动作沿用 ModelEngine 的原生淡出；从收到停止请求到完全结束可能跨越数个模型更新帧，不影响技能冷却或宠物外观归属。

其他模型也可以使用 PET。例如已有 toro_ender_dragon 蓝图包含 fire（原长 5 秒）和 fly_spit（原长 2.5 秒）：先确认当前宠物已挂载该模型，再按实际动画名配置。当前表现上限为 60 tick；想在约 3 秒内播放 5 秒的 fire，可选择 2 倍速，同时把视觉寿命设为 60 tick。动画名不会额外赋予吐火或飞行机制，实际伤害仍由技能的 action、power 等字段决定。

配装与升级

88 种原版生物原有三槽保持不变。loadouts.type-overrides.long_1、long_2 仅在缺失时补入 [model_parro_peck, model_parro_dodge, model_parro_dash]，分别服务已有 Parro 宠物与骑乘类型；管理员已配置的列表不被覆盖。其他 9 项模型技能需要通过类型覆盖选用，详见 配装示例。

catalog-version 继续为 2。先处理旧官方目录迁移，再为所有现存技能补齐缺失的 model-engine-target: EFFECT、animation-speed: 1.0 和中文注释；自建技能与保留的旧 ID 也包含在内。已填写的值、注释、模型 ID 和三槽列表保留。合法配置全部解析且保存成功后才发布运行快照。

原版或 CraftEngine 物品模型

EFFECT 模式仍支持 model-item，填写 minecraft:amethyst_shard、AMETHYST_SHARD 或真实 CraftEngine 完整 ID，如 my_pack:skill_orb，无需额外 ce: 包装。物品以临时 ItemDisplay 展示，具有旋转、浮动和缩放表现，不会掉落或发给玩家；结束时移除。

同时填写 EFFECT 的 ME 蓝图与物品模型时优先使用 ME；ME 插件或载体创建不可用时可回退到物品。挂载阶段失败会清理临时载体并保留基础粒子。PET 模式禁用物品模型，避免把动画失败变成另一种物品展示。

六种原生粒子轨迹

visual.shape	可见运动
RING	逐渐扩张、轻微上升的光环
HELIX	围绕施法位置旋转、向上推进的双圈螺旋
BURST	向外扩张的球形爆发
BEAM	向施法瞬间的目标位置推进的螺旋光束；无目标时形成向前短光束
STAR	旋转并扩张的五角星
WAVE	向外扩张、上下起伏的波纹

DUST 使用 RGB 颜色，其他无颜色参数的粒子混合彩色节点。表现围绕施放坐标播放，目标终点使用当时的坐标快照；不会为了追踪视觉而跨 Folia 区域读取目标。自定义资源包音效会叠加一声原生反馈。

预算、回收与验收

• 每只宠物最多一个持续表现，全服最多 32 个；预算满时仍播放首帧原生粒子和音效。
• 每帧最多 18 个粒子，每 4 tick 更新表现，每 2 tick 检查宠物状态，最长 60 tick；视觉半径为 0.6～4 格，光束最长约 12 格。战斗范围独立使用技能数值。
• 临时实体与临时 ME 容器不持久化；结束、召回、死亡、重载时在所属区域回收。PET 回收只处理本次动画，不删除宠物模型。
• 正式插件更新应完整停服再启动。配置重载可加载合法新配置，但不能替换正在运行的 Jar。

服务端模型注册、动画句柄与清理检查不能代替真人客户端验收。资源包贴图、动画节奏、缩放、声音和粒子密度仍需要在游戏中查看。当前 2.2.0 验证与交付状态见 本次更新记录。