item_aura（物品灵气）

文件位置：data/<namespace>/mxt/item_aura/<path>.json

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

字段	类型	默认	说明
items	ItemMatcher	必填	手持时可作为灵气燃料的现有物品。
type	Holder<aura>	必填	该物品消耗和释放的灵气；它是什么元素直接由该灵气定义里的 aura_type 给出，不需要再绕一层。
aura	NumberProvider	必填	首次处理一组物品时，每件物品的灵气总量乘以堆叠数量后写入其 mxt:item_aura.remain。
consume_speed	NumberProvider	必填	每 tick 消耗燃料值，按堆叠数量叠加；总消耗时间保持不变。
release_speed	NumberProvider	必填	每 tick 向当前境界资源条释放的燃料量，按堆叠数量叠加。
result_stack	ItemStackTemplate	无	当前物品完全耗尽时额外给予返还物品；不配置则只移除原物品。
exhausted_action	EntityAction	mxt:no_op	当前燃料耗尽行为。

修炼模式下，当前待消耗物品保存在实体 mxt:float_holding_item 附件中，剩余灵气保存在物品自身的 mxt:item_aura 组件（仅 remain 字段）中。附件为空时，先选择物品栏内剩余值最小的有效半耗尽物品；若没有，才按主手、再副手取新的匹配物品并写入 aura。中断修炼、登出或死亡会归还附件物品；只有剩余值耗尽时才移除物品、给予 result_stack 并执行 exhausted_action。附件也可由其它系统使用，因此灵气服务只处理带有自身组件且仍匹配有效定义的物品；客户端不渲染燃料条。

实现 ItemAuraAccess 的物品（灵石、符箓载体等）另有一份自己的存储组件 mxt:spirit_storage：一张「灵气 → 已存单位」的表（{amounts:{"mxt:common":100}}，键是 mxt:aura 注册表条目），灵石与符箓共用。type 只声明该物品接受哪一种灵气，容量由 aura 给出（符箓则由 aura_cost 账单给出）；已经装过东西的物品以自己记下的灵气键为准，因此数据包事后改掉 type 不会把世界里已有的存量改读成另一种灵气，只会让它与新 type 对不上（装不进、也烧不出）。灵石一次只装一种、读它唯一的那条记录；空表表示被抽空，缺组件的物品视为满充。

mxt:item_aura 将已有物品定义为修炼期间使用的灵气燃料。文件位于：

每个条目必须填写 type，它是该物品提供/消耗的那一种灵气（mxt:aura 的 Holder，例如 mxt:common）——不是计量它的那个数值（数值由该灵气定义里的 resource 指回），也不是 mxt:element：元素是灵气定义里的 aura_type，只参与灵根、生物偏好与环境渲染的类型判定。存取接口一次只处理一种灵气；需要多种灵气的配方或行为应分别调用接口。

data/<命名空间>/mxt/item_aura/<路径>.json

{
  "items": ["mxt:spirit_stone", "#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
  }
}

字段	类型	说明
items	ItemMatcher	必填。单个物品 ID、物品标签，或两者的混合数组。
type	Holder<aura>	必填。该物品消耗和释放的灵气（mxt:aura 注册表条目，如 mxt:common）；它属于什么元素由那条灵气定义里的 aura_type 给出，这里不再写一层。
aura	NumberProvider	必填。首次处理一组普通物品时，每件物品的灵气总量会乘以堆叠数量后写入其 mxt:item_aura.remain；对实现 ItemAuraAccess 的物品作为每件物品的充能上限。必须在实际运行时求得正数；灵石存储以整数单位计，小数部分不计入容量。
consume_speed	NumberProvider	必填。燃料条每游戏刻消耗的灵气量，按当前堆叠数量叠加。这样一组物品的总消耗时间与逐件消耗相同。必须在实际运行时求得正数。灌注方向反向使用这个值：它同时是每游戏刻注入物品的整单位数。
release_speed	NumberProvider	必填。燃料条每游戏刻向当前境界绑定的资源条释放的灵气量，按当前堆叠数量叠加。灌注方向反向使用这个值：它同时是每游戏刻从持有者灵气池扣除的量。
result_stack	ItemStackTemplate	可选。普通燃料彻底耗尽时，向玩家物品栏加入该物品堆；未配置时只移除原物品。实现 ItemAuraAccess 的物品会保留自身并被抽空，此字段不参与处理。
exhausted_action	EntityAction	可选，默认无操作。当前装入的灵气被耗尽时对修炼者执行。

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

附件为空时，玩家物品栏中带有 mxt:item_aura 组件的有效物品优先恢复处理，且总是选择 remain 最小的一组；没有半耗尽物品时，才按主手、再副手、再背包取出整组新的匹配物品并将按堆叠数量计算的 aura 写入组件。修炼中断、玩家登出或死亡时，附件中的物品组会原样归还；remain 耗尽时，ItemAuraAccess 物品会以空充能状态整组归还，其它物品则移除并按原组数量给予可选的 result_stack，最后执行 exhausted_action。

float_holding_item 可供其它机制暂存物品。灵气燃料服务只会消耗同时带有 mxt:item_aura 组件且仍匹配有效 item_aura 定义的物品；不符合条件的附件物品不会被移动、修改或删除。客户端目前不渲染燃料条，也不自行扣除或消耗物品。和其他数据包注册表一致，可通过 data/mxt/tags/mxt/item_aura/disabled.json 停用条目。

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

实现 UseItemAuraAccess 的物品可以按住右键把持有者自己的灵气灌进去，把这条定义的另外几个字段反过来读一遍（灵石就是这种物品：它实现灌注接口来加入手势，形状本身仍由这条定义描述——pour 留空即"按定义来"）：

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

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

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