法术数据

Spell Engine 负责法术定义、绑定池及物品分配；异界扩展另行提供星界能量费用映射。本页以 Spell Engine 1.10.7+1.20.1 为核对版本，说明本集成使用的主动法术、弹射物、表现及物品格式。

文件放在哪里

同路径法术及分配资源按数据包优先级选取，不逐字段合并。能量文件按未显式排序的迭代顺序合并；避免在多个文件重复定义同一法术费用。仓库中的法术参考目录位于实际 spell/ 路径之外，其中嵌套的示例不会注册为可施放法术。

最小示例

这是随仓库提供的奥术冲击参考数据的精简形态，采用瞄准目标及直接伤害，不要求额外物品或声音。将其保存到数据包的实际法术路径；现有参考文件夹本身不会作为法术加载。

{
  "school": "spell_power:arcane",
  "active": {
    "cast": {}
  },
  "target": {
    "type": "AIM",
    "aim": {}
  },
  "deliver": {
    "type": "DIRECT"
  },
  "impacts": [
    {
      "action": {
        "type": "DAMAGE",
        "damage": {}
      }
    }
  ]
}

字段

下列默认值适用于字段省略，不适用于显式 null。依赖的 JSON 模型较宽松；默认值为 null 不代表它对所选执行分支可用。

施法、选敌、影响与费用

其他动作类型包括 STATUS_EFFECT、FIRE、SPAWN、SUMMON、TELEPORT、COOLDOWN、AGGRO、DISRUPT、IMMUNITY、VELOCITY 及 CUSTOM，各自需要对应分支的数据。被动触发、修正器、蓄力加成及这些动作负载由固定版本 Spell Engine 格式负责，不是异界扩展新增字段。

弹射物与陨落投递结构

弹射物及陨落投递的发射设置与飞行数据分开。models[] 开头的行相对于 client_data.composite_model.models[]。

飞行运动、碰撞特性、实体放置、云或近战投递及模型动画变换，均在同版本完整格式中继续扩展此结构。不要直接搬用旧版扁平弹射物格式的字段。

公共动画、声音与粒子对象

这里采用相对路径：animation 与 sound 可出现在施法、释放或影响位置；particles[] 表示粒子组列表中的一项。持续施法粒子直接使用列表，影响及释放效果则使用 visuals 组合。

粒子格式还定义寿命、不透明度、缩放、附着与批次几何控制。模型效果定义变换及定时动画。这些由依赖拥有；扩展上表之外的字段时请使用链接中的相同版本。

物品分配与绑定池

此分配示例取自随仓库提供的法杖法术列表的一部分：

{
  "spell_container": {
    "access": "CONTAINED",
    "pool": "isekaiexpansion:tier1",
    "spell_ids": [
      "isekaiexpansion:healing"
    ]
  }
}

解析顺序为物品堆存档数据、数据包分配、物品默认值、回退。分配提供容器时，还会抑制物品的默认法术选择，除非分配自身也提供选择。显式物品堆选择数据仍优先。NONE 访问的容器可保存供装备来源提供的法术，但自身不作为施法解析入口。

绑定池使用注册表标签格式：

{
  "values": [
    "isekaiexpansion:healing",
    "isekaiexpansion:clarity"
  ]
}

星界能量

随仓库提供的治疗费用条目为：

{
  "isekaiexpansion:healing": 12
}

没有包装或元数据字段，其他键表示其他法术 ID 字符串。最终费用还受卷轴、天赋、种族及滞空修正影响；引导按每次成功投递扣费。

完整示例

此例加入绑定、施法时长、施法粒子、释放动画及冷却。施法为 1 秒，冷却为 3 秒。

{
  "school": "spell_power:arcane",
  "tier": 1,
  "range": 24,
  "learn": {},
  "active": {
    "cast": {
      "duration": 1,
      "animation": {
        "id": "spell_engine:one_handed_projectile_charge"
      },
      "particles": [
        {
          "id": "spell_engine:magic_spell",
          "appearance": {
            "color": 4278190335,
            "motion": "FLOAT"
          },
          "batch": {
            "shape": "CIRCLE",
            "count": 4,
            "min_speed": 0.05,
            "max_speed": 0.1
          }
        }
      ]
    }
  },
  "target": {
    "type": "AIM",
    "aim": {}
  },
  "deliver": {
    "type": "DIRECT"
  },
  "impacts": [
    {
      "action": {
        "type": "DAMAGE",
        "damage": {
          "spell_power_coefficient": 1
        }
      }
    }
  ],
  "release": {
    "animation": {
      "id": "spell_engine:one_handed_projectile_release"
    }
  },
  "cost": {
    "cooldown": {
      "duration": 3
    }
  }
}

使用引导时，将施法类型设为 CHANNEL，并提供包含正数总投递次数的 channel 对象。使用自定义投递时，将投递类型设为 CUSTOM，并将 custom handler 设为已安装处理器的 ID。数据本身不能创建新的自定义处理器。

校验

法术定义使用依赖的通用 JSON 解码器。未知字段被忽略，缺省字段保留模型默认值。不存在覆盖整个格式的统一范围限制，也不会统一校验所有资源、学派、处理器及嵌套对象是否可用。结构类型错误可能使解码失败；未知枚举字符串或显式 null 可能保留为 null，直到对应分支执行时才出错。因此空对象即使解码成功，也不是可用法术。使用有限数值、有效且已安装的标识符及完全一致的大写枚举值。

分配文件须为含 spell_container 或 spell_choice 的对象。空文本、非对象根、裸容器或两个成员都解码失败的包装对象，会记录警告并跳过。成员独立解码，有效选择可在容器错误时保留。显式空容器被接受，可覆盖并禁用物品默认能力。未知字段被忽略，access 枚举拼写错误会使该成员失败。启动时，分配映射由成功解析的条目整体替换。

能量应用先清空旧映射。空对象不贡献条目。空键及非正数会记录错误并跳过该项。数值使用整数转换而非严格整数验证；编写时应使用整数 JSON 数值。转换异常会记录错误并停止该文件剩余处理，保留此前已写入条目，其他文件继续。加载器不解析或检查法术 ID，因此拼写错误可能静默留在映射中但不被使用。

重载

在此固定依赖版本中，法术定义属于世界注册表数据，物品分配属于服务器启动数据；修改后重启服务器或重新打开世界。依赖在客户端加入时同步法术注册表与分配数据。图片、模型及动画仍需提供匹配的客户端资源包。

异界扩展能量文件随服务端数据重载，但解析后的费用映射目前仅在加入时发送给客户端。/reload 后重新连接，以刷新客户端能量检查及提示。这与成功重载后主动广播的表情贴纸数据等格式不同。

相关页面

法术集成说明自定义处理器、扣费及物品存档数据。元素说明玩家使用的学派。