talisman（符箓）

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

用途：符箓定义：一张符箓铭刻的能力。

一张符箓的定义：铭刻到载体上之后，激发它授予哪些能力、要付多少灵气。

效果只有 abilities 一个字段——本模组里所有“会做事的技能性效果”都落在 ability 上，符箓因此不需要自己的一套效果词汇。制符闭环落地后还需要的东西（使用次数、触发条件）会以可选字段加入，今天写好的文件继续可解析。

字段	类型	默认	说明
abilities	HolderOrTag<ability>[]	[]	该符箓授予的能力，写法与 technique.granted_abilities 一致：单个 ID、ID 数组或 #标签。
aura_cost	Map<Holder<aura>, NumberProvider>	{}	激发该符箓要付的灵气账单，按具体 aura 分键，每项可以写常量或公式。缺省或为空表示这张符不耗灵气。

定义里没有"是否回应激发"这类开关：一件载体在灌满后是立刻发动还是存着等你动手，是载体自己（stack 上）的模式，不是定义的属性——同一批铭刻可以写在一张灌满即发的符上，也可以写在另一张存着不动的符上。模式见下面的「载体模式」与 通用物品。

aura_cost 只收具体 ID，不收 #标签，和 abilities 相反：灵气池本身就是按具体 aura 分池的（见 aura_zone 的 aura），标签在这里找不到对应的池子。数值写法与其它灵气消耗一致（cultivate_action.aura_costs、formation.storage.capacity），因此可以写成 "12" 或 "realm_rank * 4"。

灌注与激发

aura_cost 同时就是载体的灌注容量：把账单灌满，符箓就算"满了"，那一刻它铭刻的能力全部发动，并消耗一件载体本体（一用即焚）。所以这张账单既是激发的代价也是灌注的时间——每 tick 灌 1 单位、1 单位收 1 点自身灵气，账单有多少单位就要按住多久。被服务端的使用冷却挡着的符不会被灌（见下面的「徒手发动的冷却」），因为账单买了的是一次激发而不是一堆灵气。

• 按灵气分别计量：账单里有几种灵气，载体就分别存几种；一次灌注只填当前第一条未满的那条（按文件里的书写顺序），填满一条后再按住会继续填下一条。只有所有条目都满了才算"满了"，也才会发动。
• 账单要能脱离持有者定价：灌注时长由"容量 ÷ 每 tick 注入"得出，而客户端要为姿势算出同一个数，所以账单按空公式上下文求值（和 item_aura.aura 对容量的口径一致）。因此 aura_cost 里能写常量或与持有者无关的表达式，"realm_rank * 4" 这类只在有人时才有值的写法会求出 0、被当作"这条不参与灌注"；一条都不剩的载体等同于免费符，右键即发动。
• 空的账单：不耗灵气的符箓没有可灌注的东西（按住右键不会进入灌注），但它随时都是"满的"，因此右键即发动。
• 怎么灌：手持载体按住右键（与灵石灌注同一套手势：BLOCK 姿势、每 4 tick 一次提示音、action bar 显示 已存 / 容量）。灌注期间不消耗物品，只有发动时才消耗一件。
• 怎么发动：徒手右键与"被灌满"走的是同一个入口，但由载体模式决定谁在什么时候发动（见下）。fire（默认）灌满立刻自动发动；store 只积累，不自动发动。两种模式下都能右键发动——若因能力冷却等原因没发动成功，或它本来就是"随时满"的空账单符，右键就是唯一的路。没满的载体右键会进入灌注而不是发动（手势按"是否已满"自动二分，见 物品灵气数据包）。
• 载体模式：存在 stack 上的 mxt:talisman 组件里，不是定义字段，因此同一批铭刻在不同载体上可以有不同行为。fire（默认，缺省即此）＝灌满那一刻自动发动；store ＝只积累，等你动手。潜行 + 右键切换模式，切换会给一句 action bar 提示；tooltip 里也写着当前模式。一条特例：store 且已经灌满时，潜行使用不切换——它直接发动（存着的灵气就是拿来花的，而"要激发模式"本身就是最明确的"现在花掉"），因此那张符被消耗。
• 不在手上也能发动：载体是由填满它的那一方汇报的，而不是由持有者汇报——展示架上摆着的符被人或灵爆填满时照样发动（store 模式除外，它只积累）。这时行为者仍是填符的那位（出账、被记录、为其能力作答），位置则是载体所在的展示架。
• 位置怎么用：位置以 block_x/block_y/block_z 进入能力的公式上下文（与 block_break 等触发器给的位置同一套写法），并且作为这次激发的原点交给"在哪里发生"的东西：spawn_projectile、spawn_particles、spawn_effect_cloud、spawn_lightning、explode、play_sound、block_action 都以原点为位置；mxt:area 目标选择器的范围以原点为圆心；mxt:teleport 这类"把目标移到行为者处"的双方行为也移到原点。原点缺省 = 行为者自己，所以普通施法一字未变。投射物仍按行为者的朝向发射——位置是"从哪里发出"，朝向是"谁在瞄"。边界：condition 一族（灵气环境、亮度、暴露于天空、脚下方块等）与按位置读环境灵气的取值仍以行为者自身位置为准。
• 徒手发动的冷却：由服务端配置「符箓 → 使用冷却」控制，不在数据包里。单位 tick、范围 0..72000、默认 20（1 秒），写 0 关闭。一次"尝试"就进冷却：能力因为自己的冷却、消耗付不起而被拒绝也算（那次点击确实成了发动的尝试），而空载体、没灌满这两种根本没成为尝试的点击不花冷却——那几种情况本来就只是给玩家一句说明，立刻就能改。它只管"手"这一条路：长按灌注灌满而自动发动时同样受它限制（窗口内灌满不会发动，而且那一 tick 的灵气根本不会被灌进去，灌进去等于花钱买一次注定被拒的尝试，所以窗口内你看到的是一张不动的符，窗口一过同样的灌注就正常发动）；展示架那条路完全不看它——架上的符不在任何人手里，被灌满就发动，既不因为填料的人正在窗口内而被拒，也不会替谁记一次窗口。和功法阅读一样走原版 player.getCooldowns()（ItemCooldowns），所以热键栏的灰色扫描和 mxt:on_cooldown 物品条件都能直接读到；又因为本模组的载体都是同一个物品 mxt:talisman，这份冷却是按玩家、按物品记的：手上另外几张符在窗口内也一起按不动（这正是它要挡的"一秒内连点一叠符"）。窗口本身用原版 ItemCooldowns 的冷却组（Identifier）记，本模组的载体没有 use_cooldown 组件，所以组就是物品注册名 mxt:talisman；想让某一类符走自己的组，给物品加 minecraft:use_cooldown（带 cooldown_group）即可，代码侧不用改。游戏里真正挡住点击的是原版本身——ServerPlayerGameMode 在问物品之前就先看冷却——所以窗口内的观感是热键栏的灰色扫描 + 什么都没发生。消耗则按"在哪"分：手上一次发动消耗一件本体，但创造模式不消耗；摆在展示架上的永远消耗，与填料的人是不是创造模式无关。两条规则都由 SpiritSource.consumedByHand() 区分，不由调用方传参决定。
• 发动的判定：铭刻的能力逐个走普通的能力使用流程——能力自身的条件、真言、次数、冷却、消耗与两个事件全部照旧，唯一被替换掉的是"该能力已授予你"这一条：符箓自己就是授权的来源（这就是带一张符就能放你不会的法术的原因）。因此冷却、次数与消耗在符与法术之间共享，符箓不是绕过它们的后门。
• 只能承载立即生效的能力：需要吟唱（cast_time > 0）或持续引导（mxt:channelled）的能力会被拒绝——唱法与引导的收尾要靠"持有者已授予的能力"列表推进，而载体从不授予任何东西。被拒绝时载体不消耗、灵气不清空，可以换一张符或换一个能力。

显示名称不是字段，和其它定义一样由标识符生成翻译键 talisman.<命名空间>.<路径>（mxt_test:flame_sigil → talisman.mxt_test.flame_sigil）。

示例：

// data/example/mxt/talisman/flame_sigil.json
{
  "abilities": ["example:qingxiao_firebolt"],
  "aura_cost": {"example:qi": 12}
}

“已经铭刻了哪些符箓”由物品组件 mxt:talisman 保存：它是一个按追加顺序排列的 talisman 条目列表，加上一个 mode 字段（"fire"（缺省）或 "store"，见上面的「载体模式」），空列表就是刚做出来的空载体。组件里存的是具体条目，因此不能写标签。灌注进度另存于 mxt:spirit_storage（与灵石共用的存储组件，按 resource 记已灌单位，缺省表示一点都没灌）。组件与载体的说明见 通用物品。