放出一道剑气

mxt:spawn_sword_aura 是一个实体行为：它在本次行为的发动位置生成一把会飞的剑气，剑尖沿行为实体的视线方向前进。它既是"一条投射物行为"，也是一个可以调外观的东西——剑身与火焰各有自己的颜色，剑的形状由五个尺寸字段与 scale 决定。

本篇只搭这一件事：一条按下去就放剑气的 mxt:active 技能，以及它在撞到方块时做什么。火焰的观感设置与渲染细节不在本篇：颜色字段只决定这把剑气自己长什么样，画成什么样由客户端那边管。

前提： 定义技能已完成。本篇复用那篇建立的 mxt:active 形状、示例包里已有的 data/example/mxt/technique/azure_breath.json，以及 example:qi 这个数值。

你要搭建什么

文件	用途
`data/example/saturn/ability/sword_aura.json`	一条 `mxt:active` 技能，`entity_action` 就是 `mxt:spawn_sword_aura`。
`data/example/mxt/technique/azure_breath.json`	（编辑）把这条技能加进 `granted_abilities`，学会功法即可按键放出。

第 1 步 —— 一条会放剑气的按键技能

// data/example/saturn/ability/sword_aura.json
{
  "type": "mxt:active",
  "costs": [{"id": "example:qi", "amount": 8}],
  "cooldown": 30,
  "entity_action": {
    "type": "mxt:spawn_sword_aura",
    "speed": 1.5
  }
}

mxt:active 读四个动作字段，对施法者跑的是 entity_action；剑气挂在施法者身上，所以写在这里。写在 bi_entity_action 上是另一回事——那是"对每个选中的目标跑一次"，不会凭空在前方生出一把剑。
出生点是这次行为的发动位置，方向取行为实体的视线方向。轮盘、命令与脚本发动没有独立地点，于是出生点就是施法者的眼睛高度；符箓与展示架发动有地点，剑气就从那里出去。
speed 是沿视线方向的速度，默认 1，必须求值为有限正数；不是正数或算不出有限值时什么都不生成，也不报错。视线垂直向上或向下同样有速度，所以抬头放剑是允许的。
只有服务端生成剑气：客户端什么都不做，看到的实体是同步过来的。

沿用定义技能教过的形状：这条技能照样可以写 icon、cast_time、condition、charges。上面只写最小的几条。

第 2 步 —— 外观：颜色与五个尺寸

// data/example/saturn/ability/sword_aura.json
{
  "type": "mxt:active",
  "costs": [{"id": "example:qi", "amount": 8}],
  "cooldown": 30,
  "entity_action": {
    "type": "mxt:spawn_sword_aura",
    "speed": 1.5,
    "blade_color": "#C778D9FF",
    "aura_color": "#CC78D9FF",
    "radial_flame": false,
    "length": 2.2,
    "blade_width": 0.3,
    "thickness": 0.08,
    "handle_length": 0.44,
    "guard_width": 0.52,
    "scale": 1.2
  }
}

字段	默认	说明
`blade_color`	`#C778D9FF`	内部剑身颜色。
`aura_color`	`#CC78D9FF`	外层剑气颜色。
`radial_flame`	`false`	`true` 时火焰从剑身向四周流动，否则向上流动。
`length`	`1.65`	剑刃长度。
`blade_width`	`0.26`	剑刃宽度。
`thickness`	`0.08`	剑身厚度。
`handle_length`	`0.44`	剑柄长度。
`guard_width`	`0.52`	护手宽度。
`scale`	`1`	整体缩放。

两个颜色是 ARGB，最高字节是透明度，所以 8 位十六进制的写法是 #AARRGGBB：#C778D9FF 是"透明度 C7"加"剑身的 78D9FF"。这里没有单独的透明度字段，要半透明就把最高字节写小。
五个尺寸字段与 scale 的范围都是 0.01–32，超出范围在加载期直接拒收——不是夹住，而是这一条定义解不开。
scale 缩放整把剑，五个尺寸字段缩放各自的部件，两者相乘。想让剑气看起来长一点，先动 length（只拉长剑刃）还是先动 scale（连剑柄、护手一起放大），由你要的效果决定。

第 3 步 —— 存活时间

// data/example/saturn/ability/sword_aura.json
{
  "type": "mxt:active",
  "costs": [{"id": "example:qi", "amount": 8}],
  "cooldown": 30,
  "entity_action": {
    "type": "mxt:spawn_sword_aura",
    "speed": 1.5,
    "lifetime": 40
  }
}

lifetime 单位是 tick，默认 80（4 秒），范围 1–72000。
到点那一刻剑气直接消失：不爆炸、不留痕、不执行任何行为。它只是没了。
剑气不含重力，被生成时的速度就是它这一路的全部速度：除非你在别处给它加速度，否则它沿直线一直飞。
没写 collide_action 时，lifetime 就是剑气唯一的终点——它会一路穿过方块，直到时间用完。

第 4 步 —— 撞到方块时做什么

// data/example/saturn/ability/sword_aura.json
{
  "type": "mxt:active",
  "costs": [{"id": "example:qi", "amount": 8}],
  "cooldown": 30,
  "entity_action": {
    "type": "mxt:spawn_sword_aura",
    "speed": 1.5,
    "lifetime": 40,
    "collide_action": {
      "type": "mxt:explode",
      "power": 3.0,
      "create_fire": false
    }
  }
}

写了 collide_action，剑气撞到实心方块才会消失；不写就直接穿过去。碰撞在每一步都查，命中的是剑气即将进入的实心方块。
行为在撞击点执行，执行时的行为实体是发动剑气的那一方——所以公式里的 caster_* 读的是他，mxt:damage 这类落在行为实体上的动作也作用在他身上；位置是撞击点，因此声音、粒子、爆炸与方块行为都发生在撞到的地方，而不是施法者脚下。
发动者已经不在（掉线、所在区块未加载）时这条行为不执行，剑气仍然消失。
碰撞只看实心方块：它不探测实体，也不探测流体。所以剑气会直接穿过生物。要让它打到人，就得靠这条撞击行为自己覆盖一块范围——mxt:explode 的爆炸会把附近实体一起算进去。
mxt:explode 自己的字段见实体行为类型 · mxt:explode：power 必填，不是有限数或为负数时什么都不发生；施法者被记为这场爆炸的起因。
collide_action 是单个实体行为；要连做几件事，就在它外面套一个包装行为，或者写成行为数组。

第 5 步 —— 授予它，让它能按下去

定义一条技能本身不起作用：得有实体持有它。这一篇走功法那条路——把这条技能加进示例包已有的功法：

// data/example/mxt/technique/azure_breath.json
{
  "granted_abilities": ["example:qi_bolt", "example:qi_recovery", "example:sword_aura"]
}

改这里而不是新开一条授予路径，是因为 azure_breath 在定义技能里已经是这套示例的"按键技能来源"，它的 granted_abilities 从那一篇起就是"学会就立刻生效"的清单。注意它是常驻的：学会这门功法的人会一直持有这条技能，不需要修炼到某一级；想让剑气只在某个等级之后出现，应该把它写进 configuration 里那一级的 ability，而不是这里。

mxt:active 是五个按键型之一，所以它自动进轮盘池，授予之后按住「轮盘选择」（默认 R）就能在池子里找到它；放进主盘哪一格由玩家自己摆的 12 格布局决定，技能定义里没有 slot 字段。

在游戏里验证

（重新打开世界）
/mxt registries validate                    → 没有 Codec 错误
/saturn ability list                           → 本条技能已持有，来源是那门功法
/saturn ability cast example:sword_aura        → 强制放一次（需要 gamemaster）

先学会功法：/give @s kubejs:azure_manual[mxt:technique="example:azure_breath"] 再右键它，然后 /saturn ability list 里应该能看到 example:sword_aura。
把这条技能放进轮盘主盘的一格，按住 R 选中它、按 V（默认「轮盘使用」）施放：扣 8 点 example:qi，剑气沿你的视线飞出去。对着空地打，它应该在 40 tick 后自己消失，什么也不留下。
对着墙打：剑气在撞上那一格就执行 mxt:explode，那里出现一次爆炸，剑气同时消失。加上 "interaction": "none" 再试一次，爆炸就只剩观感，不走方块也不伤实体。
把 collide_action 整段删掉、重开世界再对着墙打：剑气直接穿过去，一路飞到 lifetime 用尽。这就是"没有 collide_action 就不碰撞"。
把 blade_color 改成 #40C778D9、重开世界再看：剑身变得半透明。blade_color 与 aura_color 分别改内外两层，radial_flame 改成 true 时火焰改成向四周流动。
把 speed 写成 0、重开世界：speed 不是有限正数，这一次施放什么都不生成（命令会照常报施放成功，别把它当成"剑气生成了"）。

常见错误

现象	原因
按下去什么都没有	`speed` 不是有限正数；或者这条技能写在了一个不跑动作的类型上（`mxt:modifier` / `mxt:mount` / `mxt:storage` 这些类型不读 `entity_action`）。
剑气穿过了该撞上的方块	没写 `collide_action`。不写它就是一路穿过去，直到 `lifetime` 用完。
剑气从生物身上穿过去	碰撞只查实心方块，不查实体也不查流体。要打到人就让撞击行为自己覆盖一块范围。
剑气撞到石头就没了，什么都没发生	写了 `collide_action` 但那条行为什么都没做（例如 `mxt:no_op`），或者发动者已经不在（掉线、区块未加载）——后者行为不执行，剑气照旧消失。
爆炸伤到自己	撞击行为的执行者是发动剑气的人，位置是撞击点，所以贴脸打墙时他就在爆炸范围里。想避免就把撞击行为换成不会回头伤到施法者的做法。
尺寸字段改了没反应，或被世界拒绝加载	五个尺寸字段与 `scale` 的合法范围都是 `0.01`–`32`，超出范围在加载期就拒收整条定义，而不是夹到边界。
颜色不生效	两个颜色是 ARGB，写成 8 位十六进制；6 位不是这里接受的写法。
剑气还没飞到就消失了	`lifetime` 太短（默认 `80` tick，也就是 4 秒）；把它调大，上限 `72000`。
学会功法后轮盘里找不到它	这条技能没被授予（`granted_abilities` 里没加），或者它不是按键型——轮盘池只收那五个按键型，见技能类型。
改了 JSON 却没生效	技能是数据包注册表，世界加载时读一次，`/reload` 不重读。

接下来

行为类型 —— mxt:spawn_sword_aura 与 mxt:explode 的完整字段表，以及其它可以放进 collide_action 的行为。
定义技能 —— 技能类型、通用字段、消耗与授予路径的总入口。
内置物品 —— 法器、载体与组件怎么给玩家一条能按的技能。
数值提供器 —— speed 这类字段除了写数字，还能写公式。

你要搭建什么​

第 1 步 —— 一条会放剑气的按键技能​

第 2 步 —— 外观：颜色与五个尺寸​

第 3 步 —— 存活时间​

第 4 步 —— 撞到方块时做什么​

第 5 步 —— 授予它，让它能按下去​

在游戏里验证​

常见错误​

接下来​