item_aura（物品灵气）

item_aura 把一件已有物品定义为修炼燃料：修炼时整组物品被逐 tick 消耗，灵气释放进当前境界绑定的资源条。同一份定义反过来读，就是持有者按住右键往这件物品里灌注灵气时用的那份描述。

文件位置

item_aura 是一张数据包注册表，一份文件就是一条定义：

data/<namespace>/mxt/item_aura/<条目>.json

条目 id 是 <namespace>:<路径>——data/example/mxt/item_aura/qingxiao_spirit_crystal.json 就是 example:qingxiao_spirit_crystal。模组自带的条目在 data/mxt/mxt/item_aura/；内容包写自己的命名空间，不要塞进 mxt。

顶层直接写下面字段表里的键。没有 values 包一层，一份文件只描述一条定义；要在别的包里盖过同一件物品，靠 priority 分先后，没有 replace 这类开关。文件级 neoforge:conditions 是生效的：条件不成立时这条定义根本不进注册表。

这张注册表和别的数据包注册表一样在世界加载时读取，/reload 不会重读。/mxt registries list 与 /mxt registries validate 都包含它；/picker mxt:item_aura 列出这些定义认领的物品。

用途：手持物品提供的修炼燃料。

字段

字段	类型	默认	说明
items	物品条目	必填	这条定义认领哪些物品：单个物品 id、#物品标签，或它们的数组；数组里还可以是带 type 的匹配器条目，写法见 ItemMatcher。
type	灵气 id	必填	该物品消耗和释放的灵气（mxt:aura 注册表条目，例如 mxt:common）。
aura	NumberProvider	必填	首次处理一组物品时，每件物品的灵气总量乘以堆叠数量后写入它的 mxt:item_aura.remain；对能灌注的物品则是每件的充能上限。
consume_speed	NumberProvider	必填	每 tick 消耗的燃料值，按堆叠数量叠加；总消耗时间因此不变。
release_speed	NumberProvider	必填	每 tick 向当前境界资源条释放的燃料量，按堆叠数量叠加。
result_stack	ItemStackTemplate	无	当前物品完全耗尽时额外给出的返还物品；不写就只移除原物品。
exhausted_action	EntityAction	mxt:no_op	当前燃料耗尽时执行的行为。
priority	Int	0	同一件物品被多条定义命中时的先后：数值大者先；同分回落到注册表顺序。它决定灌注 / 燃放的是哪一条灵气。

同一件物品被多条定义命中时，按每条定义自己的 priority 从高到低选一条，字段默认 0；只有 priority 相同的两条才回落到注册表顺序。这与 items 里写的是物品还是标签无关：一条定义只要命中就按它自己声明的那个数参与排序，点名物品并不会让它更靠前。

type 写的是灵气，不是计量它的那个数值（数值由该灵气定义里的 resource 指回），也不是 mxt:element：元素是那条灵气定义里的 aura_type，只参与灵根、生物偏好与环境渲染的类型判定。一次读写只处理一种灵气，需要多种灵气的配方或行为要分别处理。

aura、consume_speed、release_speed 都必须在实际运行时求得正数；灵石容量与存取均保留小数，不向下取整。

示例

data/example/mxt/item_aura/qingxiao_spirit_crystal.json：

{
  "items": "example:qingxiao_spirit_crystal",
  "type": "example:spirit_power",
  "aura": 180,
  "consume_speed": 1,
  "release_speed": 3,
  "result_stack": {"id": "mxt:impurity", "count": 1},
  "exhausted_action": {
    "type": "mxt:apply_effect",
    "effect": "minecraft:regeneration",
    "duration_ticks": 100
  }
}

速度也可以写成公式，items 还可以是一个物品标签，一条定义覆盖一整族物品：

{
  "items": "#example:spirit_fuel",
  "type": "mxt:common",
  "aura": 100,
  "consume_speed": "0.5 + level * 0.05",
  "release_speed": "1 + level * 0.1",
  "exhausted_action": {
    "type": "mxt:apply_effect",
    "effect": "minecraft:fire_resistance",
    "duration_ticks": 40
  }
}

燃放：修炼时怎么烧这堆物品

灵气燃料值是隐藏的服务端状态。开始处理时，系统把整组匹配物品从玩家物品栏取出、放进实体的 mxt:float_holding_item 附件；随后只在这一个物品堆上写入 mxt:item_aura 组件，组件只有 remain 一个字段。之后每个服务端 tick 用该次匹配到的定义扣减 consume_speed × 堆叠数量，并按 release_speed × 堆叠数量 向当前境界绑定的资源条充能，资源条仍按自身上限截断。两边都乘堆叠数量，所以总消耗时间不随堆叠数量改变，一整组和一件一件烧花的时间一样。

附件为空时，先恢复物品栏里带 mxt:item_aura 组件、且仍匹配有效定义的一组物品，并且总是选 remain 最小的那组；没有半耗尽的物品时，才按主手、副手、物品栏的顺序取一整组新的匹配物品，并把按堆叠数量算出的 aura 写进组件。修炼中断、登出或死亡会把附件里的物品组原样归还；只有 remain 耗尽时才结算：普通燃料被移除、按原组数量给出 result_stack，而带自有存储的物品（能灌注的那些，例如灵石）是被抽空后原样归还，result_stack 对它们不生效。结算之后执行 exhausted_action。

mxt:float_holding_item 也可以被别的机制用来暂存物品，所以灵气服务只处理「带 mxt:item_aura 组件、且仍匹配有效定义」的物品；不符合条件的附件物品不会被移动、修改或删除。客户端不渲染燃料条，也不会自行扣除或消耗物品。

INFO

能灌注的物品（灵石就是）另有一份自己的存储组件 mxt:spirit_storage，内容与容量见下面的「反向：灌注」。

反向：灌注（按住右键充能）

能灌注的物品可以按住右键把持有者自己的灵气灌进去，把这条定义的那两个速度字段反过来读一遍：

方向	物品侧	持有者侧
燃放（修炼时）	每刻 −consume_speed × 堆叠	每刻 +release_speed × 堆叠
灌注（按住右键）	每刻 +consume_speed × 堆叠	每刻 −release_speed × 堆叠

两边用的是同一对数，所以「灌进去再烧出来」刚好抵消：灌注不产生灵气，只是把持有者的灵气暂时存进物品（灵石即电池）。手势、姿势（BLOCK）与音效（紫水晶风铃）由长按模块驱动，与功法阅读共用同一套机制。

• 灌注的是哪一条灵气：由这件物品命中的那条定义的 type 决定，与燃放同一条；多条定义命中时按 priority 从高到低选一条，同分才回落到注册表顺序。已经装过东西的物品以自己记下的那条为准：mxt:spirit_storage 把数量记在灵气键下（与符箓共用同一个组件），所以数据包事后把定义的 type 改掉时，世界里已有的灵石不会被悄悄读成另一种灵气——它只会与新的 type 对不上，既装不进也烧不出。
• 小数灌注：每 tick 最多注入 consume_speed × 堆叠，允许小于 1；同时受剩余容量、物品模拟接收量与付款能力限制。只缺 0.25 时只注入并支付对应的 0.25，速度求值为 0 或非法则不开始灌注。
• 姿势长度：ceil(容量 / 每刻注入)，上限 200 tick。容量远大于注入速度的物品一次手势灌不满，重复手势即可；充到上限的物品不再进入长按（右键提示已充满）。长度按容量而非缺口推导，因此同一次手势中它不会随充能进度变化。
• 缺组件的物品视为满，所以刚合成的灵石本来就是满的，灌注实际作用于被抽空过的、以及创造栏给出的空灵石。存储组件的形状是「灵气 → 已存量」的一张表（{amounts:{"mxt:common":100}}，键是 mxt:aura 注册表条目，数值是浮点数），一个物品可以只装一种（灵石，读它唯一的那条记录），也可以装多种（符箓载体，按容量逐条读）；空表表示被抽空，容量始终由物品自己回答（灵石取定义的 aura，符箓按 capacity 倍率算）。
• 代价与失败：扣费与灵力容器存灵、以及燃放方向走同一条路（不经过资源使用门禁），并在扣费前先判断「付得起多少灵气」，因此不会出现付了钱却一个单位都没进去的情况。没有可支付量时该 tick 不注入、不扣费，并在 action bar 提示自身灵气不足。
• 反馈：action bar 显示物品自身的 已存 / 容量（百分比），颜色与 tooltip 同一套；工具提示、展示架与 mxt:spirit_storage_not_full 条件读取的也是同一份数值。
• 环境灵气不参与灌注：灌注只动持有者自己那一池。可燃放但不能灌注的物品（例如只作为燃料的灵晶）不会因此获得右键充能；反过来，「能充能」与否由物品与定义共同决定。
• 物品也可以自己声明灌注。item_aura 是「一件物品」的共享语言，容量按堆叠放大；若物品的容量取决于这一堆上写了什么，它就自己回答（按灵气分列：每种灵气已存多少、上限多少，顺序即灌注顺序），数值按整堆给出、不再乘堆叠。符箓载体就是这种物品：它的容量是所铭刻定义的 capacity 倍率乘上一次发动的灵气用量（实际倍率还要跟载体剩余使用次数取小），按灵气分别计量。这样的物品不需要 item_aura 定义，因此也不会顺带成为修炼燃料。灌注的速率与代价仍然是手势的（自述存储按 1 单位/tick、1:1；有定义时按定义那两个速度反向使用），物品只负责说清自己是什么。
• 满了之后做什么由物品说了算，但由写入者汇报：任何往存储里写灵气的一方（长按灌注、展示架这类写入方）在真实写入之后才汇报，由物品自己判断是不是满了、要不要动手。汇报里同时带上行为者与这次写入的位置：行为者出账并为能力作答，位置是这东西在哪——展示架上的一张符是被站在别处的人或一枚灵爆填满的，所以位置不能从持有者身上读；还要说明这次算「手上的消耗」还是「摆着的存储消耗」，符箓的两套规则（冷却只算手上的路、消耗按位置分）正是由它区分。符箓正是在这里发动，并把位置写进能力公式（block_x/block_y/block_z）并作为本次激发的原点交给位置类行为（投射物、粒子、爆炸、音效、走位、方块行为；细节见灌注与激发）。

停用一条定义

条件写在文件顶层（一份文件就是一条定义）。条件不成立时这条定义根本不进注册表：

{
  "neoforge:conditions": [
    {"type": "neoforge:never"}
  ],
  "items": "example:legacy_fuel",
  "type": "mxt:common",
  "aura": 100,
  "consume_speed": 1,
  "release_speed": 1
}

条件不成立的那条定义等同于不存在：那件物品没有这条定义。可用条件见数据包开发总览。