任务奖励 · Kzeroko 的工坊

任务先记录为完成，再按数组顺序执行奖励。悬赏任务在原签约人向签发任务池的接待员汇报结算时进入此流程。每项奖励独立记录结果：某项失败不会恢复任务，也不会撤销已经发放的内容，后续条目仍会执行。

文件放在哪里

奖励位于 data/<namespace>/quests/**/*.json 必填的 rewards 数组内，允许空数组。任务数据说明外层文件、资源优先级及目录校验；奖励条目没有独立资源文件或条目标识。

最小示例

将下例插入任务的 rewards 数组。它使用示范任务文件中的经验奖励结构；省略 distribution 时选择原领取者，并按下文规则回退。

{
  "type": "isekaiexpansion:xp",
  "data": { "amount": 50 }
}

字段

类型与参数

类型	效果
`isekaiexpansion:xp`	增加异界核心玩家等级经验
`isekaiexpansion:currency`	发放已注册的实体物品
`isekaiexpansion:item`	发放可附带 NBT 的已注册物品
`isekaiexpansion:loot_table`	为每位接收者独立抽取战利品表
`isekaiexpansion:recipe_unlock`	解锁已加载配方
`isekaiexpansion:mainstory_progress`	施加有符号剧情进度变化
`isekaiexpansion:world_flag`	设置全服持久化布尔标志
`isekaiexpansion:faction_reputation`	修改指定阵营的声望
`isekaiexpansion:adventurer_rank_promotion`	尝试符合资格的冒险者阶级晋升

字段表前缀用于区分奖励类型，不是额外 JSON 包装。例如 currency.id 表示该奖励 data 中直接使用的 id。

字段	类型	默认值	作用
`type`	`identifier`	必填	下表中的已注册奖励 ID；未知 ID 拒绝重载。
`data`	`object`	必填	奖励类型的参数；只有该类型允许时才可为空。
`distribution`	`string`	picker	所有面向接收者的类型：picker、finisher、team_online。去除首尾空白且忽略大小写，未知或空值拒绝；world_flag 忽略此字段。
`xp.amount`	`integer`	0，会被拒绝	正数玩家等级经验；因此省略会被拒绝，没有额外的作者数值上限，仅受整数类型限制。
`currency.id`	`item id`	必填	已注册且非空气的物品；发放实体物品，不修改账户余额。
`currency.amount`	`integer`	1	每位接收者 1–4096 个物品。
`item.item`	`item id`	必填	已注册且非空气的物品 ID。
`item.count`	`integer`	1	每位接收者 1–4096 个物品。
`item.nbt`	`object`	不设置	设置发放堆叠的 NBT，遵循任务目标页的类型化 JSON 规则；SNBT 字符串或无效 NBT 被拒绝。
`loot_table.loot_table`	`identifier`	必填	执行奖励时解析的战利品表。
`loot_table.rolls`	`integer`	1	每位接收者 1–64 次抽取，使用接收者的世界、位置和实体作为赠礼上下文。
`recipe_unlock.recipes`	`array<identifier>`	必填	非空配方 ID 集合，重复项合并；全部不同配方均已加载后才向此条目的接收者发放。
`mainstory_progress.add`	`integer`	0，会被拒绝	对每位接收者的异界核心剧情进度施加非零有符号变化，允许负数。
`world_flag.flag`	`string`	空字符串，会被拒绝	去除首尾空白后非空的标志键，保留大小写，不要求资源标识语法。
`world_flag.value`	`boolean`	true	保存的全服标志值；false 保存为 false，不删除键。
`faction_reputation.factions`	`array<string>`	必填	非空阵营集合，按下文规范化，重复的规范化条目合并。
`faction_reputation.amount`	`integer`	必填	非零有符号基础声望变化，允许负数，仍应用声望系统修正。
`adventurer_rank_promotion.target_rank`	`string`	空字符串，会被拒绝	copper、silver、gold、diamond、mythril、adamantite、stormyx、celestium。去除首尾空白且忽略大小写；none 和未知值拒绝。
`amount`	`integer`	取决于类型	xp、currency、faction_reputation 的 data 中实际使用的键；上方前缀行区分各类型默认值及范围。

接收者

分发常量	JSON 值	解析顺序
`PICKER`	picker	保存的领取者 UUID 对应在线玩家；否则使用完成者；仍不存在则使用当前属于已完成任务档案的所有在线玩家
`FINISHER`	finisher	存在完成者时使用完成者，否则使用该档案全部在线玩家
`TEAM_ONLINE`	team_online	当前任务档案键与已完成任务匹配的全部在线玩家

每位接收者都获得完整配置数量，不会按队员人数平分。队伍接收者可以位于不同维度；离线玩家不会进入延迟发放队列。在线领取者仅按 UUID 解析，不检查其是否仍属于完成任务的档案；回退完成者同样直接采用。

面向接收者的奖励在无人可接收时失败。world_flag 不要求接收者。每项奖励在自身执行时解析接收者，不会在整个奖励数组开始前统一保存名单。

物品与战利品发放

实体物品按合法堆叠大小拆分并插入背包，插入后剩余部分掉落在接收者身边。报告的发放数量包含掉落物，所以背包已满不会使 currency 或 item 奖励失败。

战利品奖励在执行时解析表。未加载或空表哨兵使该条目失败；有效表没有抽出物品仍可成功。赠礼上下文提供接收者位置与实体，每位接收者独立抽取，不复制同一份队伍战利品。4096 的作者数量上限只适用于直接 item 或 currency 数量，不是生成战利品的总量上限。

剧情进度与世界标志

剧情进度属于每位接收者个人，并委托异界核心修改，不是共享档案的完成次数。允许负数 add；通过任务数据中的主线范围字段，决定哪些修改后的进度可以领取后续任务。

世界标志是跨队伍、跨维度共享的全服持久状态。重复设置同一值仍然成功，即使状态没有变化。false 标志会保留，未设置的标志查询结果也为 false。此奖励不会自动向任务领取条件增加标志谓词。

声望与阶级晋升

阵营字符串去除首尾空白、转为小写，将反斜杠及竖线替换为正斜杠，将空格替换为下划线。空字符串规范化为 unknown，不等于缺少阵营。未知阵营键在执行时创建，不会按未注册资源 ID 拒绝。数量进入普通任务奖励声望路径，修正与限制由声望系统管理。

阶级名称与晋升资格由异界核心管理。已依据所消费版本 0.4.0-build60 对应的本地源码仓库检查：晋升只能到下一阶，初次晋升以外还要求满足依赖方的声望条件。这是源码检查，不代表二进制等价验证。

奖励先预检所有接收者。已达到或超过目标者视为可接受，但不再次晋升；只要任一接收者出现其他失败状态，初始预检阶段就阻止此条目晋升任何人。预检全部通过后才逐个执行。若执行期间状态变化，可能在部分玩家已晋升后失败，不会回滚。

这与领取条件中的 adventurer_rank_promotion_ready 不同：就绪条件要求实际可晋升至下一阶，而奖励允许已经达到目标者。阶级奖励失败不会撤销任务完成状态。

校验

输入或执行状态	结果
任务缺少 rewards 数组	拒绝任务重载
空 rewards 数组	接受，不发放奖励
缺少 type/data、未知类型或参数类型不兼容	拒绝任务目录校验
未知额外字段	内置解析器忽略
重复奖励条目	接受，按顺序分别执行
currency/item 的物品不存在或为空气	加载任务时拒绝
直接数量或抽取次数超界、经验非正、剧情或声望变化为零	拒绝，不钳制
晋升目标无效或为 none	加载时拒绝
执行时战利品表缺失	该奖励失败，后续条目继续
执行时任一指定配方缺失	整个配方解锁条目失败，不向任何接收者发放该条目
接收者列表为空	面向接收者的条目失败
奖励抛出异常	记录失败与日志，后续条目继续

若接收者已知全部配方，成功的配方解锁条目可能报告没有新解锁内容。奖励成功仅表示该条目完成自身流程，不代表整份任务奖励列表全部成功。

重载

奖励随任务定义重载。当前执行使用处理完成时传入的定义；数据重载不会重放已经记录的任务完成。世界标志及玩家已获内容独立于作者文件持久存在。

服务端先记录完成，再执行奖励，收集结果后触发完成事件。没有自动重试队列或跨奖励事务；诊断与扩展入口见运行时页面。