PAPI 占位符
Assiah 内置了 %assiah_...% 命名空间，你可以把邮箱未读数、玩家偏好、最近邮件标题等信息直接显示到记分板、TAB、全息、菜单和聊天格式里。
只要服务器安装了 PlaceholderAPI，Assiah 的这套占位符就能直接使用，不需要再单独下载 Assiah 的 eCloud 扩展。
使用前准备
- 安装 Assiah
- 安装 PlaceholderAPI
- 重启服务器，或执行
/assiah reload - 输入
/assiah placeholder查看插件内置帮助 - 用
/papi parse me %assiah_stats_unread%测试当前玩家视角下的解析结果
提示
Assiah 的占位符前缀固定为 assiah，完整格式统一写成 %assiah_<identifier>%。
这套占位符能做什么
- 在侧边栏显示玩家还有多少封未读邮件
- 在 TAB 或全息里提醒玩家是否有新邮件
- 在菜单按钮上显示“已开启 / 已关闭”这类偏好状态
- 在其他插件菜单里读取最近一封邮件的标题、发件人、时间和附件数量
语法总览
| 分类 | 语法 | 适合显示什么 |
|---|---|---|
| 统计类 | %assiah_stats_<field>% | 未读数、各文件夹邮件数量、黑名单数量 |
| 偏好类 | %assiah_preference_<field>% | 玩家当前收件偏好、限制参数、最近发送时间 |
| 最近邮件类 | %assiah_mail_<folder>_<index>_<field>% | 最近几封邮件或草稿的标题、发件人、状态、附件数 |
统计类占位符
下面这些字段接在 %assiah_stats_ 后面使用：
| 字段 | 说明 | 示例 |
|---|---|---|
unread | 收件箱未读邮件数量 | %assiah_stats_unread% |
has_unread | 是否存在未读邮件，返回 true / false | %assiah_stats_has_unread% |
inbox_total | 收件箱邮件总数 | %assiah_stats_inbox_total% |
sent_total | 已发送邮件总数 | %assiah_stats_sent_total% |
draft_total | 草稿箱总数 | %assiah_stats_draft_total% |
archive_total | 归档邮件总数 | %assiah_stats_archive_total% |
trash_total | 回收站邮件总数 | %assiah_stats_trash_total% |
failed_claim_total | 领取失败且可重试的邮件数量 | %assiah_stats_failed_claim_total% |
blocked_total | 黑名单人数 | %assiah_stats_blocked_total% |
常见用法
%assiah_stats_unread%
%assiah_stats_has_unread%
%assiah_stats_inbox_total%
偏好类占位符
下面这些字段接在 %assiah_preference_ 后面使用：
| 字段 | 说明 |
|---|---|
allow_player_mail | 是否接收玩家邮件，返回 true / false |
allow_player_mail_display | 是否接收玩家邮件的展示文本 |
allow_system_mail | 是否接收系统邮件，返回 true / false |
allow_system_mail_display | 是否接收系统邮件的展示文本 |
require_whitelist | 是否开启白名单模式，返回 true / false |
require_whitelist_display | 白名单模式的展示文本 |
enable_blacklist | 是否启用黑名单，返回 true / false |
enable_blacklist_display | 黑名单开关的展示文本 |
daily_send_limit | 当前玩家每日发送上限 |
min_send_interval_ms | 两次发送之间的最小间隔（毫秒） |
sent_count_today | 今日已发送邮件数量 |
whitelist_total | 白名单人数 |
last_send_at | 最近一次发送时间，返回格式化文本 |
last_send_at_raw | 最近一次发送时间，返回原始时间戳 |
信息
所有 _display 字段都会读取 Assiah 的 GUI 文本配置，所以你在 mailbox.yml -> ui.boolean 里改成“开启 / 关闭”或“允许 / 拒绝”后，这些占位符也会跟着变化。
常见用法
%assiah_preference_allow_player_mail_display%
%assiah_preference_sent_count_today%
%assiah_preference_last_send_at%
最近邮件类占位符
最近邮件类占位符的完整语法是：
%assiah_mail_<folder>_<index>_<field>%
folder 可选值
| 值 | 说明 |
|---|---|
inbox | 收件箱 |
sent | 已发送 |
draft | 草稿箱 |
archive | 归档 |
trash | 回收站 |
index 规则
- 从
1开始计数，不是从0 1表示最近一条，2表示第二条，以此类推- 最大可读条数受
config.yml -> placeholder.recent-mail-limit控制，默认是3
field 可选值
| 字段 | 说明 |
|---|---|
id | 邮件或草稿 ID |
title | 标题 |
summary | 正文摘要 |
sender | 发件人显示名 |
receiver | 收件人显示名 |
folder | 文件夹内部标识 |
folder_display | 文件夹显示名称 |
status | 当前状态文本（当前实现与 claim_status 等价） |
status_display | 当前状态显示文本（当前实现与 claim_status_display 等价） |
claim_status | 附件领取状态 |
claim_status_display | 附件领取状态显示文本 |
read_status | 已读状态；草稿通常返回空值 |
time | 格式化后的时间文本 |
created_at | 创建时间戳 |
updated_at | 更新时间戳；草稿最常用 |
attachment_count | 附件总数 |
claimable_attachment_count | 可领取附件数量 |
常见用法
%assiah_mail_inbox_1_title%
%assiah_mail_inbox_1_sender%
%assiah_mail_sent_1_time%
%assiah_mail_draft_1_summary%
%assiah_mail_archive_2_status_display%
排序方式
inbox、sent、archive、trash：按创建时间倒序draft：按最后编辑时间倒序
也就是说，%assiah_mail_draft_1_title% 读到的是最近编辑过的那封草稿。
config.yml 中的占位符配置
Assiah 会在 config.yml 里释放一个 placeholder 配置段：
placeholder:
recent-mail-limit: 3
refresh-ttl-seconds: 15
empty-text: ""
| 字段 | 作用 |
|---|---|
recent-mail-limit | 每个文件夹最多缓存多少条“最近邮件”供 PAPI 读取 |
refresh-ttl-seconds | 占位符快照缓存有效期；过期后会在后台异步刷新 |
empty-text | 没有数据、索引越界、字段写错或没有玩家上下文时返回的文本 |
提示
如果你想让“没有邮件”时显示 暂无邮件，可以把 empty-text 改成这个文本。这样索引越界或玩家没有数据时，就不会显示成空字符串。
刷新机制
Assiah 的 PAPI 占位符不是每次都直接查数据库，而是先读内存快照，再在后台异步刷新。这样做的好处是：
- 记分板、TAB、菜单频繁刷新时不会卡主线程
- 玩家上线后会自动预热一次数据
- 收到邮件、读信、删信、归档、领取附件、保存草稿后，插件也会自动刷新对应玩家的快照
/assiah reload会清空旧缓存，并重新为在线玩家预热
你需要注意的地方
- 第一次读取某个玩家的数据时，如果缓存还没建好，可能会先返回默认值或
empty-text refresh-ttl-seconds越大，性能越稳，但显示变化同步得也会更慢一些- 这套占位符只负责展示，不会执行发送、领取、删除之类的操作
常见问题
1. 为什么我看到的是空文本？
通常检查这几项：
- 服务器有没有安装 PlaceholderAPI
- 当前解析环境有没有玩家上下文（控制台或无玩家场景会返回
empty-text） index是否超过recent-mail-limit- 玩家当前文件夹里是否真的有对应邮件
field或folder是否拼写错误
2. 为什么刚发完邮件，记分板没有立刻变化？
Assiah 会自动刷新快照，但它本身是异步缓存机制。大多数场景会很快同步；如果你想更快看到变化，可以适当调小 refresh-ttl-seconds。
3. time 返回的时间格式在哪里改？
%assiah_mail_<folder>_<index>_time% 读取的是 Assiah 自己格式化后的时间文本，格式来自 mailbox.yml -> ui.time-format。
搭配建议
- 想在菜单里展示邮箱概况：优先用统计类占位符
- 想给偏好设置按钮加状态字样：优先用
_display结尾的偏好类占位符 - 想在菜单里做“最近邮件预览”：用最近邮件类占位符，并把
recent-mail-limit调到够用的数量