跳到主要内容

配置文件详解

Assiah 的常用配置分为四个文件：

  • config.yml — 全局配置（数据库、Redis、通知开关、PAPI 占位符缓存），详见 安装与基础配置
  • currency.yml — 货币附件定义，详见 货币附件
  • mailbox.yml — 邮箱行为配置（本页重点说明）
  • scheduled-mail.yml — 定时邮件任务配置，详见 定时邮件

config.yml 中的 PAPI 占位符配置​

如果你已经安装 PlaceholderAPI，Assiah 会额外读取 config.yml 里的 placeholder 配置段，专门控制 %assiah_...% 占位符的缓存行为：

placeholder:
  recent-mail-limit: 3
  refresh-ttl-seconds: 15
  empty-text: ""
字段作用
recent-mail-limit每个文件夹最多缓存多少条“最近邮件”供 PAPI 读取，决定你最多能写到 %assiah_mail_inbox_3_title% 这类索引
refresh-ttl-seconds占位符快照缓存有效期；到期后插件会在后台异步刷新
empty-text无数据、索引越界、字段写错或缺少玩家上下文时返回的文本
提示

如果你要把未读数、偏好状态、最近邮件标题挂到记分板、TAB、菜单或全息里，建议先看一遍 PAPI 占位符。

mailbox.yml 完整配置​

分页配置​

控制邮箱列表 GUI 中每页显示的邮件数量。

page:
  # 默认每页显示数量，对应 GUI 布局中 MAIL_LIST 槽位数
  default-size: 21
  # 每页最大数量上限（不超过箱子容量 54）
  max-size: 54

文件夹开关​

关闭某个文件夹后，对应的 GUI 入口和命令将不可用。

folder:
  enable-sent-box: true      # 已发送邮件箱
  enable-draft-box: true     # 草稿箱
  enable-archive-box: true   # 归档箱
  enable-trash-box: true     # 回收站

邮箱容量与内容限制​

limit:
  max-inbox-size: 500          # 收件箱最大邮件数
  max-sent-size: 500           # 已发送最大数量
  max-draft-size: 100          # 草稿箱最大数量
  max-attachment-count: 16     # 单封邮件最大附件数（含所有类型）
  max-title-length: 64         # 标题最大长度（字符）
  max-body-length: 8000        # 正文最大长度（字符）
  max-batch-send-size: 200     # 群发时最大收件人数
  daily-send-limit: 50         # 每日发送上限（每个玩家，0 = 不限制）
  min-send-interval-ms: 1000   # 两次发送最小间隔（毫秒，防刷）

邮件过期配置​

expire:
  enabled: true                    # 是否启用过期机制
  days: 30                         # 邮件过期天数
  trash-keep-days: 7               # 回收站保留天数
  auto-archive-after-claim: false  # 领取附件后自动归档
  auto-delete-expired-trash: true  # 自动删除回收站过期邮件

领取配置​

控制邮件附件领取的安全性与容错行为。

claim:
  # 幂等锁：防止并发重复领取（强烈建议保持开启）
  require-idempotent-lock: true
  # 领取失败时允许重试
  allow-retry-when-failed: true
  # 领取物品前检查背包空间
  check-inventory-before-item-claim: true
  # Kether 附件执行失败时回滚整个领取操作
  rollback-on-kether-failure: true

草稿配置​

draft:
  auto-save: true                # 启用自动保存
  auto-save-interval-seconds: 15 # 自动保存间隔（秒）
  keep-last-edit-snapshot: true  # 保留最后编辑快照

回复与转发配置​

reply-forward:
  allow-player-reply: true            # 允许玩家回复
  allow-player-forward: true          # 允许玩家转发
  allow-reply-system-mail: false      # 允许回复系统邮件
  forward-copy-item-attachments: false    # 转发时复制物品附件
  forward-copy-kether-attachments: false  # 转发时复制 Kether 附件
  keep-thread-relation: true          # 保留会话关系链
提示

forward-copy-item-attachments 和 forward-copy-kether-attachments 默认关闭，是为了防止物品复制和脚本重复执行。如果你确认不会造成问题，可以按需开启。

书本视图配置​

纯文本邮件可以在 Minecraft 书本界面中阅读。

book-view:
  enabled: true                        # 启用书本视图
  title-prefix: "邮件"                  # 书本标题前缀
  author-name: "Assiah"                # 书本作者名
  max-lines-per-page: 13              # 每页最大行数
  max-chars-per-page: 230             # 每页最大字符数
  open-text-mail-in-book: true        # 纯文本邮件直接打开书本
  return-to-mailbox-after-close: true # 关闭书本后返回邮箱

玩家偏好默认值​

新玩家首次使用邮箱时的默认偏好。玩家可以在偏好界面中自行修改。

preference:
  allow-player-mail-default: true     # 默认接收玩家邮件
  allow-system-mail-default: true     # 默认接收系统邮件
  require-whitelist-default: false    # 默认不启用白名单
  enable-blacklist: true              # 启用黑名单功能

UI 文本配置​

定义 GUI 界面中使用的显示文本，用于模板占位符替换。

ui:
  # 文件夹显示名称
  folders:
    inbox: "收件箱"
    sent: "已发送"
    draft: "草稿箱"
    archive: "归档"
    trash: "回收站"

  # 领取状态显示
  claim-status:
    not-claimable: "仅阅读"
    pending: "待领取"
    claiming: "领取中"
    claimed: "已领取"
    failed-retryable: "领取失败"

  # 布尔值显示
  boolean:
    enabled: "已开启"
    disabled: "已关闭"

  # 附件类型显示
  attachment:
    text: "文本"
    item: "物品"
    kether: "脚本"
    currency: "货币"
    source-item: "物品"
    claimable: "是"
    not-claimable: "否"

  # 撰写界面文本
  compose:
    reply-title-prefix: "回复: "
    forward-title-prefix: "转发: "
    reply-quote-header: "--- 原始邮件 ---"
    untitled-draft: "(未命名草稿)"
    no-recipient: "<未设置>"
    recipient-input-title: "收件人"
    title-input-title: "标题"
    body-input-title: "邮件正文"
    kether-input-title: "Kether 脚本"
    kether-attachment-display-name: "Kether 脚本"
    receive-condition-input-title: "接收条件"
    claim-condition-input-title: "领取条件"
    anvil-confirm-text: "确认"
    unknown-recipient: "未知"
    chat-recipient-prompt: "&e请在聊天栏输入收件人名称："
    chat-title-prompt: "&e请在聊天栏输入邮件标题："

  # 附件图标材质
  attachment-icon:
    text: "PAPER"
    item: "CHEST"
    kether: "COMMAND_BLOCK"
    currency: "GOLD_INGOT"
    source-item: "ENDER_CHEST"

  # 系统发件人
  system-sender:
    default-name: "system"
    default-display-name: "系统"

  # 时间格式化配置
  time-format:
    just-now: "刚刚"                    # 1 分钟内
    minutes-ago: "{0} 分钟前"            # 1 小时内，{0} = 分钟数
    hours-ago: "{0} 小时前"              # 24 小时内，{0} = 小时数
    days-ago: "{0} 天前"                 # 7 天内，{0} = 天数
    date-pattern: "yyyy-MM-dd HH:mm"    # 超过 7 天（Java SimpleDateFormat）

定时邮件配置文件​

scheduled-mail.yml 用来定义自动投递的系统邮件任务。它独立于 mailbox.yml，支持两种触发模式：

  • cron — 适合每日奖励、每周公告、固定时段补偿
  • timestamps — 适合节日福利、开服补偿、一次性活动邮件

每个任务都可以直接配置 target、标题、正文、过期时间、附件、接收条件和领取条件。目标选择与管理员群发共用同一套解析规则，因此除了 *:on / *:off / *:all 外，还支持：

  • *:on:<子服名> — 指定子服当前在线玩家（跨服场景需启用 Redis 路由）
  • *:all:<子服名> — 指定子服所有有历史记录的玩家（从数据库日志表查询）
提示

body-format 当前只支持 PLAIN。如果你写成其他值，插件会在加载时自动回退为纯文本模式。

详细字段、示例任务和注意事项见 定时邮件。

管理员配置​

admin:
  console-sender-name: "console"
  console-sender-display-name: "控制台"
  default-system-mail-title: "管理员通知"
  default-system-mail-body: "这是一封由管理员发送的系统邮件。"
  default-admin-display-name: "管理员"

批量操作配置​

batch:
  allow-batch-read: true       # 批量标记已读
  allow-batch-delete: true     # 批量删除
  allow-batch-archive: true    # 批量归档
  allow-batch-claim: true      # 批量领取附件
  max-batch-claim-size: 20     # 单次批量领取最大数量

内容过滤​

对玩家互发邮件的标题和正文做违禁词检测。匹配前会去除颜色代码、干扰字符并转小写。系统邮件和管理员邮件不受影响。

content-filter:
  enabled: false
  strip-chars: "[,./\\*\\-+_=|~!@#$%^&()\\[\\]{}<>?;:'\"\\s]"
  blacklist: []
  #  - "广告"
  #  - "代练"
  regex-mode: false
  regex-blacklist: []
  #  - "\\d{5,11}"
配置项说明默认值
content-filter.enabled启用文本内容过滤false
content-filter.strip-chars匹配前去除的干扰字符（正则）见上方
content-filter.blacklist违禁词列表（子串匹配）空
content-filter.regex-mode启用正则匹配模式false
content-filter.regex-blacklist正则违禁词列表空

物品上传过滤​

控制写信界面上传物品附件时的黑名单。规则间 OR 语义（匹配任一即拒绝），单条规则内多条件 AND 语义。支持条件类型：material、display_name、contains_name、regex_name、lore、contains_lore、regex_lore、model_data、enchant、enchant_level、durability、amount、unbreakable、item_flags。所有条件支持 ! 前缀反向匹配。

item-filter:
  upload-blacklist: []
  #  - contains_lore:
  #      uncolor: true
  #      match: "绑定"
  #  - material: BEDROCK
配置项说明默认值
item-filter.upload-blacklist物品上传黑名单规则列表空

邮件条件系统​

控制管理员群发邮件时的接收条件和领取条件行为。

condition:
  offline-receive-policy: accept
  condition-timeout-ms: 2000
  condition-default-result: true
配置项说明默认值
condition.offline-receive-policy离线玩家接收策略：accept（直接接收）或 reject（拒绝）accept
condition.condition-timeout-msKether 条件脚本执行超时（毫秒）2000
condition.condition-default-result脚本异常或超时时的默认放行结果true

草稿模板​

允许玩家将草稿保存为可复用模板。普通玩家仅保存文本内容（标题、正文），拥有 assiah.template.save.attachment 权限的管理员可保存全部附件。

template:
  enabled: true
  max-per-player: 10
  max-global: 50
  name-max-length: 32
配置项说明默认值
template.enabled启用草稿模板功能true
template.max-per-player每个玩家最大模板数10
template.max-global全局模板最大数量50
template.name-max-length模板名称最大长度32