这页专门回答一个问题：

HNSignIn 当前到底提供了哪些占位符，应该怎么写，返回的又是什么？

如果你现在是在做：

• 计分板
• TAB / HUD
• 菜单显示
• 条件判断插件联动
• 其他支持 PlaceholderAPI 的展示层

那这一页就是最快入口。

---

一、启用条件与前缀

当前满足下面条件时，HNSignIn 会对外提供签到占位符：

• 插件本体已正常启用
• 服务器已安装 PlaceholderAPI

占位符前缀统一为：

%hncore_sign_<params>%

例如：

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

一句话理解：

• 前缀固定写 hncore_sign
• 后面接固定参数名
• 返回的是当前玩家的签到状态快照结果

如果服务器没装 PlaceholderAPI，HNSignIn 本体仍可正常工作，只是这些占位符不能被其他插件消费。

---

二、占位符表格

占位符	说明	常见返回示例
%hncore_sign_signed_today%	当前业务日是否已签到	1 / 0
%hncore_sign_streak%	当前连续签到	7
%hncore_sign_total%	累计签到总天数	45
%hncore_sign_month_total%	当前业务月签到天数	12
%hncore_sign_last_sign_date%	最近一次签到对应的业务日日期	2026-04-08
%hncore_sign_last_sign_time%	最近一次签到时间	2026-04-08 04:02:15 CST

重点不是死记，而是先记住这 6 个就是当前已正式对外暴露的固定项。

参数别名补充

当前实现里，下面这些写法也会被识别：

• signedtoday → 等价于 signed_today
• current_streak → 等价于 streak
• total_signed → 等价于 total
• month_signed / monthly_total → 等价于 month_total

也就是说，像下面这些写法当前同样能解析：

%hncore_sign_signedtoday%
%hncore_sign_current_streak%
%hncore_sign_total_signed%
%hncore_sign_month_signed%

但为了统一服内风格，文档仍推荐优先使用本页表格里的主写法。

---

三、这些值到底按什么算

这些占位符读取的是 SignInStatusSnapshot，也就是说它们是：

当前玩家在 HNSignIn 里的即时签到状态

其中最容易理解错的是：

signed_today

它不是按自然日算，而是按 业务日 算。

也就是说：

• 如果 reset.hour: 4
• 当前时间是凌晨 03:30

那么系统仍可能把你视为“上一业务日”，signed_today 的结果也会按上一业务日来判断。

month_total

它也是按 业务月 统计，而不是简单按自然时间瞬间理解。

一旦你把 timezone / hour / minute 改掉，相关结果也会随之变化。

---

四、返回规则

当前实现可以大致这样记：

情况	常见返回结果
玩家上下文存在，状态可读	正常数值 / 日期 / 时间字符串
玩家还没有任何签到记录	signed_today=0，计数类通常为 0，最近日期 / 时间为空
只有 OfflinePlayer 或 uuid 上下文	当前实现通常也能解析
玩家上下文不存在	通常返回空值或无法被展示层正常解析

所以你在面板里看到空白或第一次是 0，不一定是插件坏了，也可能是：

• 当前请求没有玩家上下文
• 展示层既没有在线玩家对象，也没有正确传入 OfflinePlayer / uuid
• 当前正好是缓存 miss，插件选择了“默认值 + 异步预热”
• PlaceholderAPI 本身没正确工作

---

五、最容易写错的地方

1）把前缀写成 %hnsignin_*%

错误示例：

%hnsignin_streak%

当前正确写法是：

%hncore_sign_streak%

原因是这组占位符通过 HNCore 的占位符体系对外暴露，命名空间是 sign。

---

2）把自然日当成业务日

例如你看到：

%hncore_sign_signed_today% = 1

但觉得“今天明明还没签”。

这时先不要急着判断错，先确认：

• reset.timezone
• reset.hour
• reset.minute

因为这里的 “today” 实际上是当前 业务日。

---

3）把空值当成签到异常

last_sign_date / last_sign_time 为空，常见原因有：

• 玩家从未签到
• 菜单插件没拿到玩家上下文
• PlaceholderAPI 链路没有正确生效

先确认玩家是否真的有历史签到记录，再判断是不是插件异常。

---

六、推荐用法

计分板 / HUD

今日已签: %hncore_sign_signed_today%
连签天数: %hncore_sign_streak%
本月签到: %hncore_sign_month_total%

菜单按钮 Lore

累计签到: %hncore_sign_total%
最近签到日: %hncore_sign_last_sign_date%
最近签到时间: %hncore_sign_last_sign_time%

条件判断插件联动

常见思路：

• 用 %hncore_sign_signed_today% 判断玩家今天是否已签到
• 用 %hncore_sign_streak% 做连签门槛条件
• 用 %hncore_sign_month_total% 做月度活动参与条件

---

七、和内部业务占位符的区别

这页说的是 对外 PlaceholderAPI / HNCore 占位符：

%hncore_sign_streak%

它和插件内部配置里可用的业务上下文占位符不是同一套语法。

例如在 config.yml / gui/*.yml / reward-groups/*.yml 中，你更常看到的是：

{player}
{target_date}
{current_streak}
{total_signed}
{make_up_cost}

可以这样理解：

• %hncore_sign_*%：给 其他插件 / 外部展示层 用
• {...}：给 HNSignIn 自己的奖励、GUI、消息配置 用

---

八、排查顺序建议

如果你发现占位符结果不符合预期，最稳的排查顺序是：

1. /hnsignin status
2. /hnsignin query <玩家>
3. 核对 reset.timezone / hour / minute
4. 再去看 PlaceholderAPI 展示层配置

为什么这样排：

• status 可以先确认业务日与存储后端
• query 可以直接看 HNSignIn 内部状态到底是什么
• 只有当插件内部状态正常时，才值得继续排查外部展示层

---

九、最短记忆版

如果你只想先记最关键的内容，可以直接记这句：

HNSignIn 当前对外占位符前缀是 %hncore_sign_*%，结果按业务日计算，不按自然日计算。