猹件开发组动作条件、连段与持续效果
动画描述部位怎么动；规则描述什么时候播放。先在动画库制作或导入动画，再到“动作规则”选择用途。所有修改点击 保存到服务器 后生效，左侧分类只整理素材，不决定触发方式。
| 入口 | 用途 | 例子 |
|---|---|---|
| 人物规则 | 响应玩家事件，按条件播放或衔接动作 | 左键挥剑，右键重击，蹲下回避 |
| 持续效果 | 模型出现且条件满足时，自动播放独立分组 | 法阵旋转、饰品浮动 |
| 主动调用 | 由指令、插件技能或本人试播按钮播放 | 技能后空翻、表情 |
主动调用的完整指令见动作命令，插件接入见分组动画 API。进入编辑器仍需加入白名单；普通玩家触发已保存规则不需要编辑权限。
先做一条规则
以“主手拿名字含火焰的剑，左键播放挥砍”为例：
- 在动画库准备一个单次动画，例如“挥砍”。
- 打开“动作规则 → 人物规则”，点击左侧
+，命名为“火焰剑”。选择所有兼容模型或指定模型。新规则优先级默认 10；更大的数字优先。 - 在“1 触发与播放”选择“左键按下”。使用“表单条件”，点击“添加预制条件”加入“主手剑类”和“名称包含”，将名称的匹配值填为“火焰”，点击“应用条件”，组合方式选“全部满足”。
- 在同页“满足后播放”选择“挥砍”。只有一个动作时到这里即可；需要接招再点击“编排后续连段”进入“2 后续连段”。
- 点击“保存到服务器”。给玩家设置能匹配人物动作的模型，拿符合条件的剑按左键；其他物品不会触发这条起手规则。
item.id.endsWith('_sword') && item.name.contains('火焰')上面的表达式与这份表单含义相同，可在“自定义脚本”模式使用。表单条件与自定义脚本只选一种，没有额外的材质筛选。 表单没有条目或脚本留空均表示始终满足。
常态动作
常态动作表示“玩家正在保持什么姿态”，与“按下某个键时触发一次技能”分开。例如 蹲下 在保持潜行期间生效；触发事件“开始潜行”只在按下时执行一次。
打开 动作规则 → 人物规则 → 常态动作，在当前规则中为每个状态选择动画，点击 保存到服务器。规则的适用模型、主手条件与优先级仍决定使用哪套常态动作；仅需要默认蹲下、蹲走时，无须新建规则。
| 状态 | 何时生效 | 初始设置 |
|---|---|---|
| 待机 | 在地面且未移动 | 默认待机 |
| 行走 | 在地面普通移动 | 默认行走 |
| 奔跑 | 在地面冲刺移动 | 默认奔跑 |
| 蹲下 | 在地面潜行且未移动 | 默认蹲下 |
| 蹲走 | 在地面潜行并移动 | 默认蹲走 |
| 跳起 | 离地后向上运动 | 不播放 |
| 下落 | 空中到达顶点或向下运动 | 不播放 |
| 游泳 | 进入游泳姿态；仅站在水中不算 | 不播放 |
| 攀爬 | 处于梯子、藤蔓等可攀爬位置 | 不播放 |
| 骑乘 | 乘坐实体或载具 | 不播放 |
| 飞行 | 创造模式或插件允许的飞行 | 不播放 |
| 鞘翅滑翔 | 使用鞘翅滑翔，与普通飞行分开 | 不播放 |
| 使用物品 | 持续使用物品时叠加姿态 | 弓规则为默认拉弓；其他默认规则不播放 |
每个槽位可选 不播放 或动画库中的动画；有内置姿态的槽位还可选 默认动作，不依赖动画库中是否保留了同名素材。选择“不播放”只让当前常态槽位不施加姿态，不会退回行走或奔跑；自定义模型保留模型自身姿态，原版玩家保留原版姿态，独立法阵等持续效果继续运行。
同时符合多个状态时，按 骑乘 → 鞘翅滑翔 → 飞行 → 游泳 → 攀爬 → 跳起 / 下落 → 蹲下 / 蹲走 → 奔跑 / 行走 / 待机 选一个基础姿态。使用物品与主动攻击另行叠加；默认攻击保留潜行等状态的腿部姿态。
进入新状态或切换引用动画时从头播放。循环动画持续循环；单次动画播完保持末帧，离开状态后结束。动画的“允许移动”和“允许转动视角”也作用于常态动作，通常应保持允许，避免步态自身阻止走动。
本人状态即时响应，其他玩家看到的常态状态由服务器同步。本次更新需要同时更新服务端插件和玩家客户端，并完整重启客户端；只更新一端不会启用新版动作同步。
例如已有“水中划动”循环动画：在当前规则的 游泳 槽位选择它，保存到服务器，进入游泳姿态后自动循环，出水回到地面动作。在组合预览顶部选择 状态：游泳 可检查姿态；恢复“不播放”并保存即可停用该状态动画，素材仍保留在动画库。
表单条件与自定义脚本
人物规则、后续分支、持续效果使用相同的条件编辑方式，选择和填写的内容都随服务器保存，重新打开仍能按表单编辑。
| 操作 | 用法 |
|---|---|
| 添加预制条件 | 可选主手剑类、精确材质、名称包含、Lore 包含、NBT 标签值、蹲下、生命值、事件触发手；添加后可以继续修改 |
| 条件对象和字段 | 选择主手、副手、事件触发物品或玩家状态；字段可选材质、名称、Lore、NBT 等 |
| 匹配方式 | 文本支持精确、不等、包含、开头、结尾、通配；数字支持大小比较；也可检查字段存在或不存在 |
| NBT 和 Lore | NBT 路径与匹配值分别填写，路径用点分隔并选择文本、数字或是/否；指定 Lore 行从 0 开始 |
| 全部满足 / 任意满足 | 分别表示所有条目都成立、至少一个条目成立；最多 32 条，超过可视范围用滚轮切换 |
| 应用条件 | 将当前填写的值写入编辑内容；再点击保存到服务器使游戏中生效 |
| 改用脚本 | 从现有表单生成同义表达式，支持更复杂的括号嵌套和跨字段比较 |
| 改用表单 | 已有非空脚本会先提示清空；确认后从空表单配置，可撤销 |
| 使用示例 | 选择示例，再点击“确定”直接替换并应用当前脚本，底部提示修改已应用 |
语法错误会显示位置并禁止应用；语法有效只说明写法正确，不代表玩家当前满足条件。输入文字或路径后先点击“应用条件”，再切换条目或模式。
触发事件
| 页面名称 | 表达式中的事件名 | 发生时机 |
|---|---|---|
| 左键按下 / 松开 | leftPress / leftRelease | 攻击键按下与松开；改键后跟随游戏键位 |
| 右键按下 / 松开 | rightPress / rightRelease | 使用物品键按下与松开；一次按住不会重复触发 |
| 开始 / 结束蹲下 | sneakStart / sneakEnd | 服务端允许的蹲下状态改变 |
| 开始 / 结束冲刺 | sprintStart / sprintEnd | 服务端允许的冲刺状态改变 |
| 起跳 | jump | 离地并向上运动；飞行与骑乘不算 |
| 落地 | land | 从空中回到地面 |
| 动画结束 | finish | 当前节点播放完成，仅用于后续跳转 |
左右键条件默认读取主手；要检查副手，明确使用 offhand。这些事件不自动禁用原版的方块交互或右键物品使用。蹲下、冲刺切换事件中的条件读取切换后的状态，例如开始蹲下时 player.sneaking 为真。
像 ChaUI 一样写条件
沿用 ChaUI 的 &&（并且）、||（或者）、!（取反）、括号、成员访问、数组下标和类型转换习惯。这里是用于判断的表达式，不执行赋值、循环、命令、文件操作或完整 JavaScript。
| 字段 | 内容 |
|---|---|
item / main | 当前主手物品，两者在左右键规则中相同 |
offhand | 副手物品，具有与主手相同的字段 |
item.id | 小写物品 ID，例如 minecraft:diamond_sword |
item.material | 大写材质，例如 DIAMOND_SWORD |
item.name | 自定义名称，去除颜色格式；没有自定义名称时为空字符串 |
item.count | 物品数量 |
item.lore | Lore 行列表，item.lore[0] 是第一行 |
item.loreText | 所有 Lore 用换行连接后的文字 |
item.nbt | 自定义 NBT 标签，可继续用成员或下标访问嵌套标签 |
player.sneaking / player.sprinting | 是否蹲下 / 冲刺 |
player.onGround / player.flying / player.swimming | 是否在地面 / 飞行 / 游泳 |
player.health / player.food | 当前生命值 / 饱食度 |
event.name | 当前事件名，见上表 |
node.id / node.step | 后续跳转判断中的当前节点名 / 本轮进入节点次数，从 1 开始 |
node.time / node.progress | 进入节点后的秒数 / 播放进度 0～1，仅用于后续跳转 |
物品名称和 Lore 按去除颜色后的文字比较。字符串匹配区分大小写。不存在的 NBT、Lore 越界和缺少的成员为 null；数值转换失败时本次条件视为不满足。NBT 使用该服务端版本的自定义标签：新版本物品的数据组件不等同于自定义 NBT，材质、名称和 Lore 应优先用上表字段读取。支持嵌套复合标签、常用数值和字符串列表，读取有深度与数量上限。
精确、包含、开头、结尾和通配
以下每段都是可以直接放入条件框的完整表达式。== 表示完全相等，!= 表示不相等。
精确匹配钻石剑且名称为“烈焰”：
item.material == 'DIAMOND_SWORD' && item.name == '烈焰'名称以“传说”开头，包含“火焰”，且以“剑”结尾：
item.name.startsWith('传说') && item.name.contains('火焰') && item.name.endsWith('剑')模糊匹配：“烈焰”开头，中间任意文字，最后是“剑”加一个字符：
item.name.matches('烈焰*剑?')matches 使用通配符，* 匹配零个或多个字符，? 匹配单个字符，不是正则表达式。也可写为 contains(item.name, '火焰')、startsWith(item.name, '传说')、endsWith(item.name, '剑') 或 matches(item.name, '烈焰*')。
第一行 Lore 以“传说”开头，并且任意行包含职业标记：
item.lore[0].startsWith('传说') && item.loreText.contains('职业:剑士')嵌套 NBT 中 weapon.level 存在且至少为 3，同时主手为剑：
item.id.endsWith('_sword') && item.nbt['weapon']['level'] != null && toNumber(item.nbt['weapon']['level']) >= 3副手为盾，玩家蹲下且站在地面上：
offhand.material == 'SHIELD' && player.sneaking && player.onGround数字支持 + - * / % 和 > >= < <=；&&、|| 会短路判断，可先检查标签是否存在。数字可用小数，字符串用单引号或双引号。
| 转换 | 行为 |
|---|---|
toString(value) | 转为文字；null 转成文字 null，整数不附带 .0 |
toNumber(value) | 数值或数字字符串转成数字；布尔值为 1 / 0 |
toInteger(value) | 向零截断小数；结果必须位于安全整数范围 |
toBoolean(value) | null、0、空白文字、文字 false 和 0 为假，其他非空文字为真 |
每条表达式最多 4096 字符，嵌套最多 32 层。条件由服务端用真实玩家和物品信息判断，编辑器的模拟主手只适合普通材质预览；涉及名称、Lore、NBT 和玩家状态时请保存后在实际玩家上触发核对。
自由编排连段
节点就是“现在播放哪个动画”；后续跳转就是“发生什么事情，接着去哪个节点”。动画可以来自任意分类，多条规则也能引用同一动画。
例如已经准备好“挥砍”“重击”“回避”三个单次动画，在“2 后续连段”中这样设置：
- 创建“起手”“重击”“回避”三个节点并分别选择动画，把“起手”设为入口。
- 在“起手”的后续跳转中添加右键分支，目标为“重击”，窗口为
0.40～0.85，提前缓存0.20秒。 - 再添加开始蹲下分支，目标为“回避”，窗口为
0.00～1.00。额外条件可填写player.onGround。 - 添加左键分支，目标仍为“起手”，窗口为
0.65～1.00，可重复挥砍。 - “重击”或“回避”可以没有跳转，播完退出；也可以添加“动画结束”分支，自动进入一个“收招”节点。
- 点击“保存到服务器”。起手后在不同时间按右键或蹲下，会进入对应节点。
| 分支设置 | 含义 |
|---|---|
| 事件 | 触发这条跳转的输入或动画结束事件 |
| 条件 | 额外条件，留空即可；与事件同时满足 |
| 目标 | 任意已有节点；选择“结束本条规则”立即结束流程 |
| 开始 / 结束进度 | 0 是片段开始，1 是片段结束；必须开始不晚于结束 |
| 提前缓存 / 秒 | 输入早于开始窗口时，可提前多少秒记住一次输入，范围 0～1 |
窗口末端为 1.00 时，动画结束后的“衔接等待”内仍可接招；小于 1 时错过即无效。缓存开启时先检查条件，到窗口开启时再检查当前物品和玩家状态。每个节点只保留一次待衔接输入，新匹配输入可替换旧输入。动画结束分支不使用输入窗口和缓存。
同一事件命中多条分支时，按列表顺序取第一条；上下箭头调整顺序。节点可回到自己或任意其他节点。每条规则最多 64 个节点，每节点最多 32 条分支。节点动画必须是受支持的单次动画，循环和保持末帧动画请用于独立分组。
所有连段统一使用节点和分支。节点删除会移除指向它的分支，动画素材保留。起手条件在流程开始时判断，衔接过程中按所选分支的条件判断；需要持续检查手持物品时，在分支里也设置相应条件。
“用动作判定箱处理普攻命中”开启时，只有配置了判定箱的节点造成范围命中，回避和收招可以没有判定箱。第三方插件继续通过攻击开始、目标命中事件接管效果，见攻击 API。
分别控制移动与视角
在“关键帧 → 动画设置”或节点的动画选择下方，分别设置 允许移动 和 允许转动视角。两个开关默认都开启，修改保存在动画本身；其他节点、分组或指令引用同一动画时共用该设置。
- 关闭允许移动：阻止主动走动、冲刺和跳跃；保留重力、击退和传送。
- 关闭允许转动视角：播放期间锁定朝向；允许移动仍可单独开启。
- 多段动画同时播放时，任意一段禁止某项操作，就维持该项限制。有限动画结束、显式停止、换模型、死亡或重载后，移除已结束动画的限制。
- 循环或保持末帧动画会持续限制，直到该组停止或不再生效。待机、行走、奔跑等常态动作也读取这些开关，通常应保持允许移动，避免步态自行阻断走动。
这些选项限制玩家输入，不会让翻滚动画真的移动玩家坐标；技能位移仍由插件处理。只导出标准 .animation.json 不会包含移动、视角开关或规则，保存到服务器才能保留这些设置。
持续效果
持续效果按 是否加入自动播放 判断，与组名、分类名、动画是否循环无关。循环动画可以只由插件调用，单次动画也可以在模型出现时自动播放一次。
- 新建：持续效果页左侧
+→ 新建分组和持续效果，选择根骨骼、范围与模板。 - 加入已有组：左侧
+→ 将已有分组加入持续效果。原来的骨骼、范围、动画和分类保留。 - 移出：选中效果，点击右上角“移出持续效果”。这会停止自动播放，保留分组与动画，可再次加入或用 API 播放。
- 修改起始动画：选择已有动画，或点击“从模板创建”。组已经创建完成也能操作，不需要删除重建。
起始动画表示该组自动开始时选用的片段，不是额外播放一遍的前置动作。“启用效果”关闭时保留自动播放成员身份，但暂时不生效。永久删除分组仍在分组上下文中操作；删除动画在动画库里操作，两者不会因移出持续效果而被删除。
| 模板 | 初始效果 |
|---|---|
| 空白动画 | 2 秒空白轨道，从零编辑 |
| 持续旋转 | 4 秒绕 Y 轴旋转 360 度，循环 |
| 上下浮动 | 2 秒沿 Y 轴上下往返 2 模型像素，循环 |
| 左右轻摆 | 2 秒绕 Z 轴在 -12～12 度间摆动，循环 |
| 呼吸缩放 | 2 秒在 1～1.12 倍之间变化，循环 |
| 展开 | 0.6 秒从 0.01 倍放大到 1 倍，保持末帧 |
模板会创建新动画并设为当前组的起始动画，旧动画保留；关键帧、时长和循环方式均可继续修改。选了多个根骨骼时，模板为每个根建立轨道；避免同时选择父骨骼及其子骨骼，以免重复叠加。
让所有含 fazhen 的模型自动旋转：选择根骨骼 fazhen，范围设为“所有同名骨骼模型”，起始动画选“持续旋转”，循环跟随动画，条件留空，然后保存。缺失骨骼会跳过，其余匹配骨骼继续播放。
如果只想蹲下时旋转，在持续效果的表单条件添加“玩家蹲下”，值选“是”；也可在自定义脚本填写并应用：
player.sneaking条件成立时从头开始，不成立时停止这次自动播放；下次成立再从头开始。单次效果在条件持续成立时只播一次。显式插件调用不受自动播放条件限制；显式停止会保持停止，直到重新调用或模型重新出现。
保存和排查
这些能力覆盖六个受支持客户端版本，共用一个服务端插件。更新时两端一起替换并完整重启；只重载配置不会更新正在运行的代码。
不再读取或迁移旧版动作工程。 原文件保留，不自动转换或删除；需要的动画可以重新导入标准 .animation.json，规则、映射和持续效果按当前界面重新设置。更新前请备份整个动作目录。服务器没有当前有效工程时使用默认动作；保存新设置会写入当前格式。动画导入仍支持 Blockbench 导出的标准文件，与旧工作室工程的兼容无关。
- 不触发：检查编辑是否已经保存、模型是否符合范围、规则是否启用、优先级与起手事件，以及材质大小写。先清空条件核对事件，再逐项加回条件。
- 能起手但不接招：检查分支事件、时间窗口、缓存和先后顺序；循环片段不能作为流程节点。
- NBT 条件不成立：先核对真实标签路径和类型，数字比较前用
toNumber；缺失标签不等于 0。名称与 Lore 请使用专门字段。 - 持续效果列表找不到旧组：使用
+加入已有组；检查是否刚刚移出或关闭了启用效果。 - 播完仍不能动：检查并行组、保持末帧或循环动画是否仍禁止移动；关闭或停止对应组，保存后重新核对。
动作外观、模型骨架与导入格式的问题见通用动作与工作室。