这页专门说明 奖励组目录怎么用、什么时候该内联写奖励、什么时候该拆到 reward-groups，以及四种奖励动作分别适合什么场景。

当前插件会在数据目录下维护：

plugins/HNSignIn/reward-groups/

目录内所有 *.yml / *.yaml 会被合并成一个全局奖励组注册表。

---

一、为什么要有 reward-groups

如果所有奖励都直接写在主配置里，常见问题是：

• daily / streak / templates 里同一份奖励要重复拷贝
• 随机池和复杂动作会让主配置越来越臃肿
• 运营改奖励时，容易顺手碰到业务规则配置

所以 reward-groups 更适合做：

• 可复用奖励定义
• 随机池
• item-spec 物品奖励
• 示例奖励集合

可以这样记：

• 业务规则 放 config.yml
• 奖励内容 放 reward-groups/*.yml

---

二、目录与加载规则

默认示例文件：

plugins/HNSignIn/reward-groups/default-groups.yml

加载规则：

• 目录内所有 *.yml / *.yaml 都会被扫描
• 同名奖励组 ID 不建议重复定义
• 奖励组加载后，可在 config.yml 中通过 ID 引用

一个最小示例：

reward-groups:
  daily_basic:
    actions:
      - type: command
        value: 'give {player} gold_nugget 3'
      - type: message
        value: '&a奖励已发放'

---

三、奖励定义支持哪些写法

当前正式支持两种：

1. 引用奖励组

直接写奖励组 ID：

rewards:
  daily: daily_basic

或写成：

reward-group: daily_basic

2. 直接内联奖励

例如：

rewards:
  daily:
    actions:
      - type: command
        value: 'give {player} gold_nugget 3'

---

四、什么时候该用奖励组，什么时候该内联

推荐用奖励组的场景

• 同一份奖励会复用到多个节点
• 你想把 random-pool 单独维护
• 你要用较复杂的 item-spec
• 你想把业务规则和奖励内容分开给不同角色维护

推荐直接内联的场景

• 奖励只会在一处使用
• 奖励非常短，只是一条命令或一条消息
• 当前只是临时测试

最实用的经验是：

• 简单一次性奖励可以内联
• 复杂或复用奖励尽量进 reward-groups

---

五、随机池怎么写

示例：

reward-groups:
  lucky_pool:
    random-pool: true
    entries:
      - weight: 80
        actions:
          - type: command
            value: 'give {player} cooked_beef 2'
      - weight: 20
        actions:
          - type: library-item
            source: mythic
            key: lucky_crate
            amount: 1

说明：

• random-pool: true 表示这是随机奖励池
• entries 中每条 entry 有自己的 weight
• 系统会按权重抽取一条 entry
• 然后执行该 entry 下的 actions

注意：

• 当前每条 entry 里要直接写 actions
• 不支持在 entry 内继续套 reward-group

---

六、四种奖励动作说明

当前动作类型：

• command
• message
• library-item
• item-spec

1. command

- type: command
  value: 'give {player} diamond 1'

适合：

• 发原版物品
• 调其他插件命令
• 发积分、头衔、权限等

2. message

- type: message
  value: '&6奖励已发放'

适合：

• 给玩家反馈
• 显示本次命中的奖励说明
• 做模板奖励提示

3. library-item

- type: library-item
  source: mythic
  key: signin_basic_pack
  amount: 1
  give-mode: inventory_or_drop

适合：

• 使用 HNCore 已接入的共享物品库来源
• 发复杂定制物品，但不想自己写 ItemSpec

字段说明

• source：物品库来源 ID
• key：该来源中的物品键
• amount：数量
• give-mode：发放方式

4. item-spec

开放测试提醒：

• item-spec 适合承载更复杂、更规范的物品奖励，但也意味着更适合先在测试服验证
• 如果你同时叠加 identity / pdc / serial-prefix / give-mode，建议先单独做一组签到或模板奖励回放测试，再上线给更多玩家使用

- type: item-spec
  give-mode: inventory_or_drop
  serial-prefix: 'signin_{player}'
  spec:
    material: PAPER
    amount: 1
    display-name: '&6签到凭证'
    identity:
      item-type: sign_ticket
      origin: hnsignin
      serial: auto
      token-id: daily_reward
      version: 1

适合：

• 想直接定义 material / display-name / lore / identity / pdc
• 想在奖励中使用 HNCore 的物品身份语义
• 想自动生成唯一序列号

关键点

• spec 结构按 HNCore ItemSpec 语义解析
• identity.serial: auto 会调用 HNCore SerialGenerator
• serial-prefix 支持占位符
• 发放后仍统一走 give-mode

---

七、give-mode 怎么理解

当前支持：

• inventory
• inventory_or_drop
• drop

含义：

inventory

严格放背包。

• 如果背包放不下
• 整次发放视为失败
• 不会把剩余部分掉地上

inventory_or_drop

优先进背包，剩余掉落。

• 最适合大多数普通奖励
• 兼顾体验和安全性

drop

直接掉到玩家脚边。

• 适合不希望进包的奖励
• 也适合演出型奖励

---

八、当前最常用的占位符

奖励动作里最常见会用到：

• {player} / {player_name}
• {uuid}
• {target_date}
• {current_streak}
• {total_signed}
• {days}
• {sign_type} / {sign_type_display}
• {reset_time}
• {make_up_cost}
• {fixed_cycle_key} {fixed_cycle_day}
• {personal_cycle_progress} {personal_cycle_round}
• {monthly_final_reward_progress} {monthly_final_reward_target}

例如：

value: 'mail send {player} 签到奖励 请查收你在 {target_date} 的签到奖励'

或：

display-name: '&6签到凭证 &7- &f{target_date}'

---

九、默认示例里已经包含什么

当前默认 default-groups.yml 里已经覆盖了几类示例：

• daily_basic：基础每日奖励
• lucky_pool：随机池奖励
• sign_ticket_demo：item-spec 示例
• 多个 streak_* / total_* / weekly_* / monthly_* 奖励组

如果你要快速理解新动作，最值得先看的是：

• daily_basic
• lucky_pool
• sign_ticket_demo

---

十、最容易踩的坑

1）奖励组和业务规则混在一起改

如果你在 config.yml 里既改周期逻辑又改具体奖励，很容易排障时分不清问题来自哪层。

2）随机池 entry 里继续写 reward-group

当前不支持。

3）item-spec 和 library-item 用错场景

可以这样区分：

• 已经有现成共享物品库条目 → 优先 library-item
• 你想在签到配置里直接定义物品身份 / PDC → 用 item-spec

4）serial 自动生成后却还按固定唯一物品思路理解

如果你写了：

serial: auto

那每次发出去的物品都可能带不同的唯一序列号，不应再按固定常量 serial 去匹配它。

---

十一、推荐维护策略

如果你准备长期维护这套奖励，建议：

1. config.yml 里只保留业务规则与奖励引用
2. 把可复用奖励统一放进 reward-groups/*.yml
3. random-pool 和 item-spec 都尽量单独成组
4. 先用 daily_basic 跑通，再逐层叠加复杂奖励

这样配置最清晰，也最方便运维和后续扩展。

---

十二、最短记忆版

如果你只想先记关键点，可以直接记这句：

简单奖励可内联，复杂奖励进 reward-groups；共享物品用 library-item，定制物品用 item-spec。