config.yml 配置说明 | HN 系列 Wiki

这页聚焦 HNSignIn 的主配置文件。当前版本需要结合三类配置入口一起理解：

config.yml：业务日、存储、补签、消息、基础奖励、模板奖励
gui/*.yml：签到主界面与确认弹窗
reward-groups/*.yml：可复用奖励组

当前版本最重要的配置块

配置块	优先级	主要影响
`reset`	很高	业务日如何切换，今天是哪一天
`storage`	很高	玩家数据写到哪里，是否需要迁移
`make-up`	很高	补签是否允许、命中条件、限制与消耗
`messages`	很高	玩家看到的成功 / 失败反馈
`rewards`	很高	每日签到、连签、累签奖励
`templates`	很高	周模板 / 月模板奖励体系
`gui/*.yml`	中	页面布局、显示物品、确认弹窗
`reward-groups/*.yml`	中	奖励复用、动作组合与示例维护

reset

yml

reset:
  timezone: Asia/Shanghai
  hour: 4
  minute: 0

这组配置定义 业务日。

timezone

业务时区，例如：

Asia/Shanghai
UTC
America/Los_Angeles

hour / minute

每天几点进入下一个业务日。

例如：

yml

hour: 4
minute: 0

表示每天 04:00 才切到新的业务日，因此：

03:59 仍然算上一业务日
04:00 才算新的一天

它会影响：

今日是否已经签到
哪些日期允许补签
周模板 / 月模板如何命中
%hncore_sign_*% 与消息中的日期相关占位符结果

storage

yml

storage:
  type: database
  database:
    type: sqlite
    table-prefix: hnsignin_
    sqlite:
      file: storage/hnsignin.db
    mysql:
      host: localhost
      port: 3306
      database: hnsignin
      username: root
      password: ''
    pool-size: 10
    connection-timeout-ms: 30000

type

支持：

database（当前默认推荐）
yaml（legacy 兼容 / 迁移通道）

含义：

database：通过 HNCore DatabaseManager 持久化到 sqlite 或 mysql
yaml：继续使用 plugins/HNSignIn/playerdata/<uuid>.yml

database.type

支持：

sqlite
mysql

建议：

sqlite：单机、测试服、快速落地
mysql：正式服、集中式运维、后续多服共享预留

table-prefix

所有业务表都会带此前缀，例如：

hnsignin_players
hnsignin_sign_records
hnsignin_claimed_weekly_template_rewards

sqlite.file

SQLite 文件相对插件数据目录的位置。默认实际路径通常是：

text

plugins/HNSignIn/storage/hnsignin.db

运维建议

只改 storage.type 不会自动迁移历史数据
切换后建议先执行：/hnsignin migrate-storage preview
想确认双端一致性，再执行：/hnsignin migrate-storage validate
真正迁移时使用带 confirm 的命令
status 命令会显示当前后端；若仍在 yaml 模式，还会提示这是 legacy 模式

make-up

当前版本的补签已经不再是“单一物品数量扣除”，而是一套完整的 条件 + 限制 + 动态 requirement 体系。

最小示例

yml

make-up:
  window-days: 7
  allow-cross-month: false
  conditions: []
  formula-variables: {}
  limits:
    max-total: -1
    max-monthly: 10
    max-weekly: 3
    max-daily: 1
    bypass-permissions: []
    rules: []
  cost:
    enabled: false
    requirements: []
    groups: []

window-days

允许补签最近多少个业务日内的漏签日期。

allow-cross-month

是否允许跨月补签：

false：只能补当前业务月内的漏签
true：允许跨月补签，只要仍在窗口内

conditions

补签前置条件，当前支持：

permission
player-level
papi-number

示例：

yml

conditions:
  - type: permission
    permission: hnsignin.makeup.use
  - type: player-level
    min: 10

formula-variables

可把权限、PAPI 或常量映射为公式变量，供 amount-formula / 限制表达式复用。

常见来源：

permission:<node>
papi:<placeholder>
number:<value>
player-level
player-exp

limits

支持：

max-total
max-monthly
max-weekly
max-daily
bypass-permissions
rules

其中：

-1 代表不限制
rules[].deny-when 使用表达式命中高级限制规则
rules[].message-key 可引用 messages.make-up-rule-templates.<key>

cost.requirements

默认回退补签 requirement 列表。当前支持：

permission
currency
item

permission

只校验权限，不扣除任何内容。

currency

通过运行时 hook 对接 HNEconomy。

yml

- type: currency
  currency: gold
  amount: 100
  amount-formula: 'base_amount + make_up_count_month * 20'

item

通过 inventory / warehouse 来源消费物品。

yml

- type: item
  amount: 1
  sources: [inventory, warehouse]
  matcher:
    item-type: makeup_ticket
    origin: hnsignin
    version: 1

matcher 优先建议使用 HNCore 稳定字段：

item-type
serial
origin
token-id
version
pdc

如果启用 warehouse 来源，建议至少配置一项稳定条件，不要只靠名字 / Lore 做匹配。

另外，当前开放测试版本已经对补签成本回滚做过一轮重点收口：

currency requirement 会尽量按更宽松的身份解析做离线退款
warehouse requirement 不再依赖整页快照回放，而是改成 delta 回滚
inventory requirement 在玩家离线时会转成延期补偿，并在必要时持久化恢复

所以如果你准备测补签成本，建议重点验证：

混合成本是否能正确扣除
保存失败后是否能正确回滚
玩家离线、reload、再上线后的补偿是否符合预期

cost.groups

按顺序命中首个价格组，用于：

VIP 免费补签
新手折扣补签
近几天补签走低价组

groups[].requirements: [] 可以表示“免费组”。

messages

这里控制玩家收到的基础提示，例如：

签到成功
重复签到
补签成功
补签失败
累签奖励已领取
内部错误
高级限制规则消息模板 make-up-rule-templates

示例：

yml

messages:
  sign-in-success: '&a签到成功，奖励已发放。'
  make-up-cost-missing: '&c补签条件未满足：&f{make_up_cost}&c。'
  make-up-rule-templates:
    long_gap_guard: '&c超过 3 天的补签需要额外权限。'

rewards

基础奖励分三类：

daily：每次成功签到 / 补签都会发放
streak-tiers：连续签到跨档位时自动发放
total-tiers：累计签到达到阈值后，玩家在 GUI 手动点击领取

奖励定义写法

当前正式支持两种：

引用奖励组
- 直接写奖励组 ID
- 或写 reward-group: <id>
直接内联奖励内容
- 普通奖励：actions:
- 随机奖励池：random-pool: true + entries:

旧的 commands: / messages: 写法已不推荐继续使用。

actions 当前支持四种动作

command

yml

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

执行控制台命令。

message

yml

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

向玩家发送提示消息。

library-item

yml

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

通过 HNCoreAPI.resolveLibraryItem(...) 解析共享物品库物品。

item-spec

yml

- type: item-spec
  give-mode: inventory
  serial-prefix: 'signin_{player}'
  spec:
    material: PAPER
    amount: 1
    identity:
      item-type: sign_ticket
      origin: hnsignin
      serial: auto

通过 HNCoreAPI.getItemSpecParser() 与 HNCoreAPI.getItemSpecResolver() 构造物品。

当 identity.serial: auto 时，会自动调用 HNCore SerialGenerator 生成唯一序列号。

give-mode

当前支持：

inventory
inventory_or_drop
drop

含义：

inventory：严格进背包，放不下则整次失败
inventory_or_drop：优先进背包，剩余掉落
drop：直接掉地上

templates

模板奖励分为：

templates.weekly.fixed-cycle

全服共享固定 7 日周期，依赖：

anchor-date
当前业务日

来推导当前周期与周期第几天。

templates.weekly.personal-cycle

玩家个人独立 7 日循环，每次成功签到推进一格，状态持久化在玩家数据中。

templates.weekly.period-accumulate

同样基于固定周期，但按“本期累计签到次数”发奖，而不是按第几天发奖。

templates.monthly.calendar-days

按月历日期发奖，例如每月 1 号、7 号、15 号。

templates.monthly.milestones

按“本月累计签到达到多少天”发奖。

templates.monthly.final-reward

按 required-days 作为本月终奖目标，当前实现为 自动发放。

GUI 配置不在 config.yml

当前界面定义已拆到：

text

plugins/HNSignIn/gui/
├─ calendar.yml
└─ confirm-dialogs.yml

其中：

calendar.yml：日历标题、布局槽位、状态物品
confirm-dialogs.yml：补签确认弹窗等二级确认界面

如果你只是想改：

标题
日期格名称 / Lore
统计栏文案
补签确认框说明

优先改 gui/*.yml，而不是主 config.yml。

reward-groups 目录

插件会从下面目录加载奖励组：

text

plugins/HNSignIn/reward-groups/

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

适合用奖励组的场景：

多处共用同一奖励定义
想把奖励内容与主业务配置分离
需要维护随机池或 ItemSpec 示例

常用占位符

当前常用上下文占位符包括：

{player} / {player_name}
{uuid}
{date} / {target_date}
{today} / {business_date}
{year} {month} {day}
{current_streak} / {streak}
{total_signed} / {total}
{days}
{reset_time}
{fixed_cycle_key} {fixed_cycle_day} {fixed_cycle_signed}
{personal_cycle_progress} {personal_cycle_round}
{monthly_final_reward_progress} {monthly_final_reward_target}
{make_up_cost} {make_up_cost_group} {make_up_cost_group_id}
{make_up_count_total} {make_up_count_month} {make_up_count_week} {make_up_count_day}
{target_gap_days} {make_up_limit_rule} {make_up_limit_rule_id} {make_up_denied_reason}

这些占位符可用于：

奖励命令
奖励消息
GUI 名称与 Lore
补签拒绝提示

HNCore / PlaceholderAPI 占位符

插件同时注册了 sign 命名空间，可通过 HNCore / PlaceholderAPI 使用：

%hncore_sign_signed_today%
%hncore_sign_streak%
%hncore_sign_total%
%hncore_sign_month_total%
%hncore_sign_last_sign_date%
%hncore_sign_last_sign_time%

配置建议

如果你刚开始用，建议：

先确认 reset 与 storage
先只启用 rewards.daily
再测试 fixed-cycle 或 personal-cycle 二选一
最后再打开更复杂的 make-up.conditions / limits / groups
library-item 与 item-spec 建议在基础签到链路稳定后再启用

这样排障成本最低，也更容易看清是“状态问题”还是“奖励动作问题”。

当前版本最重要的配置块 ​

reset ​

timezone ​

hour / minute ​

storage ​

type ​

database.type ​

table-prefix ​

sqlite.file ​

运维建议 ​

make-up ​

最小示例 ​

window-days ​

allow-cross-month ​

conditions ​

formula-variables ​

limits ​

cost.requirements ​

permission ​

currency ​

item ​

cost.groups ​

messages ​

rewards ​

奖励定义写法 ​

actions 当前支持四种动作 ​

command ​

message ​

library-item ​

item-spec ​

give-mode ​

templates ​

templates.weekly.fixed-cycle ​

templates.weekly.personal-cycle ​

templates.weekly.period-accumulate ​

templates.monthly.calendar-days ​

templates.monthly.milestones ​

templates.monthly.final-reward ​

GUI 配置不在 config.yml ​

reward-groups 目录 ​

常用占位符 ​

HNCore / PlaceholderAPI 占位符 ​

配置建议 ​

当前版本最重要的配置块

reset

timezone

hour / minute

storage

type

database.type

table-prefix

sqlite.file

运维建议

make-up

最小示例

window-days

allow-cross-month

conditions

formula-variables

limits

cost.requirements

permission

currency

item

cost.groups

messages

rewards

奖励定义写法

actions 当前支持四种动作

command

message

library-item

item-spec

give-mode

templates

templates.weekly.fixed-cycle

templates.weekly.personal-cycle

templates.weekly.period-accumulate

templates.monthly.calendar-days

templates.monthly.milestones

templates.monthly.final-reward

GUI 配置不在 config.yml

reward-groups 目录

常用占位符

HNCore / PlaceholderAPI 占位符

配置建议