货币附件

Assiah 支持将服务器货币（金币、点券等）作为邮件附件发送。收件人领取邮件时，货币会自动发放到账户。

支持的货币类型

模式	说明	前置插件
`vault`	Vault 金币	Vault + 经济插件（如 EssentialsX）
`playerpoints`	PlayerPoints 点券	PlayerPoints
自定义	PAPI 占位符 + Kether 脚本	PlaceholderAPI

配置文件

货币定义在 currency.yml 中配置，插件启动时自动释放默认配置。

# Vault 金币（需安装 Vault + 经济插件）
vault:
  name: 金币
  mode: vault
  deny: |-
    tell color inline "&c货币不足! 需要 &e{{ &need-money }}&c，你只有 &e{{ &money }}"

# PlayerPoints 点券（需安装 PlayerPoints）
playerpoints:
  name: 点券
  mode: playerpoints
  deny: |-
    tell color inline "&c点券不足! 需要 &e{{ &need-money }}&c，你只有 &e{{ &money }}"

自定义货币

你可以通过 PAPI 占位符查询余额，通过 Kether 脚本执行扣款和发放：

custom_points:
  name: 自定义货币
  mode: "%custompoints_balance%"    # PAPI 占位符，用于查询玩家余额
  give: |-
    command inline "custompoints give {{ sender }} {{ &money }}" as console
  take: |-
    command inline "custompoints take {{ sender }} {{ &money }}" as console
  deny: |-
    tell color "&c货币不足! 需要 &e{{ &need-money }}&c，你只有 &e{{ &money }}"

配置项说明：

字段	说明
`name`	货币显示名称，用于 GUI 和消息中展示
`mode`	货币模式。`vault` / `playerpoints` 为内置模式；其他值作为 PAPI 占位符查询余额
`give`	Kether 脚本，发放货币时执行（仅自定义模式需要）
`take`	Kether 脚本，扣除货币时执行（仅自定义模式需要）
`deny`	Kether 脚本，余额不足时执行（所有模式可用）

Kether 脚本变量

在 give、take、deny 脚本中可以使用以下变量：

变量	适用脚本	说明
`{{ &money }}`	give / take	本次操作的金额
`{{ &money }}`	deny	玩家当前余额
`{{ &need-money }}`	deny	需要的金额
`{{ &balance }}`	give / take / deny	玩家当前余额
`{{ sender }}`	全部	玩家名称

使用方式

在撰写界面上传货币

打开撰写界面（/assiah compose）
点击"上传金币"按钮（金锭图标）
在聊天栏输入要上传的金额
插件校验余额是否充足，充足则先保存草稿再扣款
扣款失败时自动回滚草稿，货币不会丢失

累加机制

如果草稿中已存在相同类型的货币附件，再次上传会累加金额，而不是新增一个附件条目。

管理员豁免

拥有 assiah.admin 权限的管理员上传货币时不会被扣款。

领取流程

收件人领取包含货币附件的邮件时：

插件按顺序执行：Kether 脚本 → 物品发放 → 货币发放
货币发放通过 give 操作将金额存入收件人账户
幂等锁保护：currenciesDelivered 字段确保重试时不会重复发放

退还机制

删除草稿时，非管理员玩家的货币附件会自动退还到账户
转发邮件时，货币附件强制不复制（防止货币复制）

GUI 配置

在 ui/mailbox-compose.yml 中配置上传货币按钮：

P:
  role: UPLOAD_CURRENCY
  material: GOLD_INGOT
  name: "&e上传金币"
  lore:
    - "&7将自己的金币添加为邮件附件"
    - "&7支持多次上传累加"
    - "&7当前金币数: &e{attachment.vault}"
  actions:
    left:
      - "mail:upload-currency vault"

动作格式：mail:upload-currency <货币键名>，其中货币键名对应 currency.yml 中的顶层 key。

多货币按钮

你可以为不同货币配置多个按钮：

# 上传点券按钮
Q:
  role: UPLOAD_CURRENCY
  material: DIAMOND
  name: "&b上传点券"
  lore:
    - "&7将自己的点券添加为邮件附件"
    - "&7支持多次上传累加"
    - "&7当前点券数: &e{attachment.playerpoints}"
  actions:
    left:
      - "mail:upload-currency playerpoints"

占位符

货币附件会动态生成占位符 {attachment.<货币键名>}，可在 lore 中使用：

占位符	说明
`{attachment.vault}`	当前草稿中 vault 货币附件的金额
`{attachment.playerpoints}`	当前草稿中 playerpoints 货币附件的金额
`{attachment.<自定义key>}`	当前草稿中对应自定义货币的金额

支持的货币类型​

配置文件​

自定义货币​

Kether 脚本变量​

使用方式​

在撰写界面上传货币​

累加机制​

管理员豁免​

领取流程​

退还机制​

GUI 配置​

多货币按钮​

占位符​