配置文件说明

config.yml

主配置文件，位于 plugins/Malkuth/config.yml，用于配置数据库、Redis、文件监听、MiniMessage、上架编辑器、恢复服务、交易安全、邮箱后端和玩家商店方块等全局行为。

# 连接配置
database:
  # 是否启用数据库，否则 sqlite
  enable: false
  # 地址
  host: localhost
  # 端口
  port: 3306
  # 用户名
  user: root
  # 密码
  password: "your_password"
  # 数据库
  database: "malkuth"
  # 表名前缀
  prefix: "malkuth"

# 使用 Redis 缓存可高效同步跨服数据，避免数据库卡顿
redis:
  enable: false
  host: 127.0.0.1
  port: 6379
  # password:
  # user

file:
  enable_listen: true

# 物品溢出配置
# 当玩家背包满时，购买、下架、上架回滚等操作产生的物品如何处理
item-overflow:
  # 是否将溢出物品掉落在玩家脚下；关闭时已接入兜底的路径会写入邮箱
  drop_on_ground: true
  # 掉落的物品是否标记归属（仅该玩家可拾取，需服务端支持）
  drop_item_owner: false

# 调试日志配置
# matcher-detail 会输出大量匹配细节，仅建议短时排查时开启
debug:
  enabled: false
  matcher-detail: false
  matcher-summary: true
  max-lines-per-action: 30

# MiniMessage 文本解析配置
# 在 PAPI 变量解析之后对 UI 标题、物品名/lore、商品展示等文本执行 MiniMessage 标签解析
# （如 <red>、<gradient:#FF0000:#00FF00>、<bold> 等），解析结果会转为 Legacy 色码继续兼容 & 色码。
minimessage:
  # 是否启用 MiniMessage 解析，默认关闭以保持历史文本行为。
  # Adventure、MiniMessage、Examination 仅作为 compileOnly 依赖，不会打包进 Malkuth.jar。
  # 只有服务端提供完整依赖且 Minecraft 版本为 1.16 及以上时，才会加载 API 实现；
  # 依赖缺失、版本过低或二进制不兼容时自动降级为传统色码，不影响插件其他功能。
  # click、hover、selector、nbt 等交互/数据标签仅降级对应 token，不会让整行回退。
  enabled: false

# 上架 GUI 默认商店配置
# /mal market gui、/mal auction gui、/mal request gui 未指定商店时优先使用这里的值。
# 留空时：同模式只有一个商店则自动选择；存在多个可用商店则打开选店界面。
upload_entry:
  defaults:
    global_market: ''
    auction: ''
    global_request: ''

# 上架创建编辑器配置
upload_editor:
  # 数值输入方式：auto 优先使用牌子输入，不支持或打开失败时回退聊天；sign 仅使用牌子；chat 仅使用聊天栏。
  input_mode: auto
  # 是否在真实提交前打开独立确认页，默认开启以避免误上架、误扣款。
  confirm_before_submit: true
  # 未提交草稿的保留时间，单位秒；有效范围 30..1800，默认 300 秒。
  draft_timeout_seconds: 300
  # 单次数值或文本输入的等待时间，单位秒；超时后本次输入失效，默认 60 秒。
  input_timeout_seconds: 60

# 创建事务恢复配置
recovery:
  # 当前子服的稳定标识，用于恢复任务认领与审计；单服可保持 local，多服环境应为每个子服设置唯一值。
  server_id: local

# 购物车配置
cart:
  # 每个玩家购物车最大商品种类数
  max-capacity: 50

# 交易安全配置
trade:
  # 单次购买允许的最大数量，防止玩家输入超大数字导致数量计算溢出
  max-purchase-amount: 999999

# 分布式锁安全配置
lock:
  # Redis 锁异常时是否放行交易。默认 false 表示 fail-close，避免跨服并发重复提交
  redis_fail_open: false

# 通知配置
notification:
  # 是否启用通知系统（拍卖成交、邮箱到达等）
  enabled: true
  # 每个离线玩家的待投递通知队列上限
  max-queue-per-player: 100

# ==============================
# 邮箱后端配置
# ==============================
mailbox:
  # 邮箱储存后端
  # internal - 使用 Malkuth 内置邮箱系统（默认）
  # assiah   - 使用 Assiah 邮箱插件
  backend: internal

  # 已领取邮件自动清理天数（清理 N 天前已领取的邮件，每小时执行一次）
  cleanup-days: 7

  # Assiah 后端配置（仅 backend: assiah 时生效）
  assiah:
    # 邮件过期时间（毫秒），0 表示不指定（走 Assiah 自身过期策略）
    # 默认 7 天 = 604800000
    expire_time: 604800000
    # Assiah 插件不可用时是否自动降级到内置邮箱
    fallback: true
    # 是否把内置邮箱台账中的未领取邮件自动转发到 Assiah（默认开启）
    # 关闭后幂等邮件将固定留在内置邮箱，玩家需通过内置邮箱 UI 领取
    forward_internal: true
    # 转发任务扫描间隔（秒），最小 10 秒
    forward_interval_seconds: 60
    # 每轮转发的最大邮件数量（1-200）
    forward_batch: 50

配置项说明

配置项	说明	默认值
`database.enable`	启用 MySQL，`false` 则使用 SQLite	`false`
`database.host`	数据库地址	`localhost`
`database.port`	数据库端口	`3306`
`database.user`	数据库用户名	`root`
`database.password`	数据库密码	`your_password`
`database.database`	数据库名	`malkuth`
`database.prefix`	表名前缀	`malkuth`
`redis.enable`	启用 Redis 缓存（跨服同步）	`false`
`redis.host`	Redis 地址	`127.0.0.1`
`redis.port`	Redis 端口	`6379`
`redis.password`	Redis 密码（可选）	空
`redis.user`	Redis 用户名（可选）	空
`file.enable_listen`	自动监听 `goods/`、`shop/`、`recycle/`、`ui/`、`currency.yml` 与 `autosell_chest.yml` 的变更	`true`
`item-overflow.drop_on_ground`	背包满时溢出物品是否掉落在地；关闭时已接入兜底的路径会写入邮箱	`true`
`item-overflow.drop_item_owner`	掉落的溢出物品是否标记归属（仅该玩家可拾取，需服务端支持）	`false`
`debug.enabled`	是否启用调试日志总开关	`false`
`debug.matcher-detail`	是否输出逐条 matcher 细节；会显著增加日志量	`false`
`debug.matcher-summary`	是否输出每次匹配动作的摘要日志	`true`
`debug.max-lines-per-action`	单次匹配动作允许输出的最大日志行数；至少为 `1`	`30`
`minimessage.enabled`	在 PAPI 变量替换后启用受限 MiniMessage；仅 Minecraft 1.16+ 且服务端类路径提供完整 Adventure / MiniMessage / Examination 时生效，否则自动使用传统色码	`false`
`upload_entry.defaults.global_market`	`/malkuth market gui` 未指定商店时优先使用的全球市场 ID	空
`upload_entry.defaults.auction`	`/malkuth auction gui` 未指定商店时优先使用的拍卖行 ID	空
`upload_entry.defaults.global_request`	`/malkuth request gui` 未指定商店时优先使用的全球求购 ID	空
`upload_editor.input_mode`	编辑器数值输入方式：`auto`、`sign` 或 `chat`；`auto` 牌子输入失败时回退聊天	`auto`
`upload_editor.confirm_before_submit`	新 GUI 创建流程是否在真实提交前打开 `upload_create_confirm.yml`；不控制旧参数式命令	`true`
`upload_editor.draft_timeout_seconds`	未提交草稿保留秒数，运行时限制在 `30..1800`	`300`
`upload_editor.input_timeout_seconds`	单次输入等待秒数，运行时限制在 `10..600`	`60`
`recovery.server_id`	恢复任务认领和审计使用的稳定子服标识；群组服每个子服应保持唯一	`local`
`cart.max-capacity`	购物车最大商品种类数	`50`
`trade.max-purchase-amount`	玩家输入购买数量、购物车合并数量和发货数量的安全上限，避免超大数量导致溢出	`999999`
`lock.redis_fail_open`	Redis 分布式锁异常时是否放行交易；默认 `false` 为 fail-close，跨服环境不建议开启	`false`
`notification.enabled`	启用通知系统（拍卖成交、邮箱到达等）	`true`
`notification.max-queue-per-player`	每个离线玩家的待投递通知队列上限	`100`
`mailbox.backend`	邮箱后端：`internal`（内置）或 `assiah`（对接 Assiah 插件）	`internal`
`mailbox.cleanup-days`	已领取邮件自动清理天数（每小时执行一次）	`7`
`mailbox.assiah.expire_time`	Assiah 后端邮件过期时间（毫秒）；`0` 表示不指定，交给 Assiah 自身策略处理	`604800000`
`mailbox.assiah.fallback`	Assiah 不可用时自动降级到内置邮箱	`true`
`mailbox.assiah.forward_internal`	是否把先写入内置幂等台账的未领取邮件后台转发到 Assiah；关闭后固定留在内置邮箱	`true`
`mailbox.assiah.forward_interval_seconds`	后台转发扫描间隔，运行时最少 `10` 秒	`60`
`mailbox.assiah.forward_batch`	每轮扫描的最大邮件数量	`50`

邮箱后端边界

当 mailbox.backend: assiah 时，赠送、管理员发放等常规邮件会直接写入 Assiah。拍卖流拍/中标、全球市场到期退回、全球求购供货退回/成交投递、退款补偿和上架回滚等幂等邮件会先写入 Malkuth 内置邮箱台账，避免跨服或重试时重复发放。

默认 forward_internal: true 会按间隔把这些未领取台账邮件安全搬运到 Assiah，成功后才在内置侧标记完成；Assiah 未就绪时邮件继续保留，等待下一轮或由玩家从内置邮箱领取。若设为 false，幂等邮件不会转发，固定留在内置邮箱。

MiniMessage 安全边界

启用 minimessage.enabled 后只开放颜色、文本装饰、渐变、彩虹与重置标签，并继续兼容 & 色码。click、hover、selector、nbt 等交互或数据标签会作为普通文本降级，不会执行；服务器版本低于 1.16 或缺少完整运行库时也会自动回退。

GUI 默认商店解析

三个 upload_entry.defaults.* 留空时，同模式只有一个可用商店会自动选择；存在多个商店时打开 upload_shop_select.yml，没有可用商店时拒绝进入编辑器。显式传入 [商店] 时优先使用命令参数。

调试日志只建议短时开启

当 debug.enabled: true 且 debug.matcher-detail: true 时，回收、上传限制和物品匹配链路会输出大量明细日志。它适合排查某一件物品为什么被拒绝或匹配到了哪条规则，不适合作为长期常驻监控；排查完成后建议立即关闭。

autosell_chest.yml

自动售卖箱独立配置位于 plugins/Malkuth/autosell_chest.yml。默认关闭，开启后玩家可以放置带有 malkuth_autosell_type 标记的售卖箱物品，系统会按间隔扫描箱内物品，并复用 recycle/*.yml 的货币奖励规则估价后发放收益。

enabled: false

tick-interval: 20
hologram-update-interval: 20
unload-chunk-behavior: pause

limits:
  default: 1
  permission-prefix: 'malkuth.autosell.limit.'

currency:
  mode: vault

types:
  basic:
    display: '&a自动售卖箱'
    block: chest
    item:
      material: chest
      name: '&a自动售卖箱'
      lore:
        - '&7放置后会周期自动出售箱内物品'
        - '&7右键打开升级界面'
    price-source:
      mode: recycle_shop
      shop: default_recycle
    input:
      hopper: true
      manual: true
      hopper-output: false
    merge:
      allow-double-chest: false
      require-same-owner: true
      require-same-type: true
      require-same-level: true
      large-chest-upgrade-cost-multiplier: 2.0
    hologram:
      enabled: true
      lines:
        - '&a自动售卖箱 &7Lv.{level}'
        - '&7下次售卖: &f{remaining}'
        - '&7倍率: &e{multiplier}x'
    levels:
      '1':
        interval: 60s
        multiplier: 1.0
        upgrade-cost: 0
        max-items-per-run: 64
      '2':
        interval: 30s
        multiplier: 1.25
        upgrade-cost: 5000
        max-items-per-run: 128

配置项	说明	默认值
`enabled`	自动售卖箱总开关；关闭时放置会被拦截，定时售卖任务不会启动	`false`
`tick-interval`	主检查间隔，单位 tick；只有到期箱子才会扫描库存	`20`
`hologram-update-interval`	全息刷新预留配置，当前售卖箱不会生成全息实体	`20`
`unload-chunk-behavior`	区块未加载时的处理策略；`pause` 会延后下次售卖，`simulate` 当前仍是预留	`pause`
`limits.default`	玩家无额外权限时可放置的数量	`1`
`limits.permission-prefix`	数量上限权限前缀，例如 `malkuth.autosell.limit.5`	`malkuth.autosell.limit.`
`currency.mode`	售卖收益与升级扣费使用的货币模式，可填 `vault`、`playerpoints` 或 `currency.yml` 自定义货币键	`vault`
`types.<类型>.display`	类型显示名，用于提示和升级界面	`&a自动售卖箱`
`types.<类型>.block`	放置后允许绑定的方块材质	`chest`
`types.<类型>.item`	`/malkuth autosell give` 发放给玩家的物品外观	见默认配置
`types.<类型>.price-source`	价格来源配置；当前实现会复用 `recycle/*.yml` 中的货币奖励规则估价	`recycle_shop` / `default_recycle`
`types.<类型>.input.hopper`	是否允许漏斗向箱子输入物品	`true`
`types.<类型>.input.manual`	是否允许玩家手动放入物品；当前仍保留普通箱子交互	`true`
`types.<类型>.input.hopper-output`	是否允许漏斗从售卖箱抽出物品	`false`
`types.<类型>.merge.allow-double-chest`	是否允许和相邻售卖箱形成大箱子	`false`
`types.<类型>.hologram`	售卖箱全息文本预留配置，当前不会生成全息实体	见默认配置
`types.<类型>.levels.<等级>.interval`	该等级的售卖间隔，支持 `ms`、`s`、`m`、`h`	`60s` / `30s`
`types.<类型>.levels.<等级>.multiplier`	该等级的收益倍率	`1.0` / `1.25`
`types.<类型>.levels.<等级>.upgrade-cost`	升到该等级需要扣除的货币；一级通常为 `0`	`0` / `5000`
`types.<类型>.levels.<等级>.max-items-per-run`	单次最多售卖物品数量	`64` / `128`

自动售卖箱结算边界

当前自动售卖箱只结算能被回收规则命中且包含货币奖励的物品。它不会发放回收规则中的物品奖励或 Kether 奖励；收益会按售卖箱等级倍率、单次数量上限和配置货币发放给箱主。

玩家商店方块

config.yml 还包含一组玩家商店方块绑定配置，控制 /malkuth place 的目标方块、生成模式与保护行为。

player-shop-block:
  enabled: true
  target-distance: 5

  # BIND_EXISTING: 绑定玩家当前指向方块
  # PLACE_ABOVE: 在玩家指向方块上方生成方块并绑定
  mode: BIND_EXISTING

  bind-existing:
    allowed-materials:
      - CHEST
      - BARREL

  place-above:
    base-materials:
      - STONE
      - COBBLESTONE
    require-air-above: true
    generated-material: CHEST
    generated-block: CHEST

  hologram:
    enabled: true
    default-enabled: true
    default-lines:
      - '&6{owner} 的商店'
      - '&f商品数量: &a{goods_count}'
      - '&7右键点击打开'
    height: 1.2
    min-height: 0.0
    max-height: 5.0
    line-spacing: 0.25
    min-line-spacing: 0.1
    max-line-spacing: 1.0
    refresh-interval-ticks: 200
    cleanup-radius: 1.5
    max-lines: 6
    max-line-length: 80

  stall-entity:
    enabled: false
    type: ARMOR_STAND
    click-to-open: true
    name-display: '&6{owner} 的摊位'
    name-visible: true
    gravity: false
    cleanup-radius: 2.0
    default-model:
      helmet: PLAYER_HEAD
      chestplate: ''
      leggings: ''
      boots: ''
      main-hand: ''
      off-hand: ''
      use-owner-head: true
      small: false
      invisible: false
      arms: true
      display: '&a默认形象'
      icon: PLAYER_HEAD
    models:
      merchant:
        permission: 'malkuth.stall.merchant'
        display: '&6商人形象'
        icon: EMERALD
        equipment:
          helmet: PLAYER_HEAD
          chestplate: 'LEATHER_CHESTPLATE:#8B4513'
          leggings: 'LEATHER_LEGGINGS:#5C4033'
          boots: 'LEATHER_BOOTS:#2F1B0C'
        use-owner-head: true
        small: false
        invisible: false
        arms: true
    offset:
      x: 0.5
      y: 0.0
      z: 0.5
    facing: BLOCK_FACE

  protection:
    disable-vanilla-interact: true
    deny-break-by-others: true

配置项	说明	默认值
`player-shop-block.enabled`	总开关，关闭后 `/malkuth place` 与绑定方块交互都会失效	`true`
`player-shop-block.target-distance`	玩家视线检测距离；源码会把该值限制在 `1~32` 之间	`5`
`player-shop-block.mode`	绑定模式：`BIND_EXISTING` 绑定现有方块，`PLACE_ABOVE` 在目标方块上方生成并绑定	`BIND_EXISTING`
`player-shop-block.bind-existing.allowed-materials`	`BIND_EXISTING` 模式允许直接绑定的方块材质列表	`CHEST`, `BARREL`
`player-shop-block.place-above.base-materials`	`PLACE_ABOVE` 模式允许作为底座的方块材质列表	`STONE`, `COBBLESTONE`
`player-shop-block.place-above.require-air-above`	生成模式下是否要求目标方块上方必须为空气	`true`
`player-shop-block.place-above.generated-material`	生成模式下实际放置并绑定的方块材质	`CHEST`
`player-shop-block.place-above.generated-block`	生成模式下的方块来源，支持原版方块或 CraftEngine 方块 ID	`CHEST`
`player-shop-block.hologram.enabled`	是否启用玩家商店方块全息显示	`true`
`player-shop-block.hologram.default-enabled`	新绑定商店方块时是否默认显示全息	`true`
`player-shop-block.hologram.default-lines`	默认全息文本，支持 `{owner}`、`{shop_id}`、`{shop_title}`、`{goods_count}`、坐标等变量	见默认配置
`player-shop-block.hologram.height`	全息第一行相对方块顶部的高度	`1.2`
`player-shop-block.hologram.min-height` / `max-height`	玩家命令可设置的全息高度范围，源码会自动夹紧到范围内	`0.0` / `5.0`
`player-shop-block.hologram.line-spacing`	多行全息的行间距	`0.25`
`player-shop-block.hologram.min-line-spacing` / `max-line-spacing`	玩家命令可设置的行距范围	`0.1` / `1.0`
`player-shop-block.hologram.refresh-interval-ticks`	动态占位符刷新间隔，源码最低按 `20` tick 处理	`200`
`player-shop-block.hologram.cleanup-radius`	重载或刷新时清理残留全息实体的水平扫描半径	`1.5`
`player-shop-block.hologram.max-lines`	玩家自定义全息最多行数，源码限制在 `1~20`	`6`
`player-shop-block.hologram.max-line-length`	玩家自定义单行最大字符数，源码限制在 `8~200`	`80`
`player-shop-block.stall-entity.enabled`	是否启用摆摊实体系统	`false`
`player-shop-block.stall-entity.type`	实体类型；当前已实现 `ARMOR_STAND`，`NPC` 仍会跳过生成	`ARMOR_STAND`
`player-shop-block.stall-entity.click-to-open`	右键摆摊实体是否打开对应玩家商店	`true`
`player-shop-block.stall-entity.name-display`	摆摊实体显示名，支持店主、商店、商品数量和坐标变量	`&6{owner} 的摊位`
`player-shop-block.stall-entity.name-visible`	是否显示摆摊实体名称；`name-display` 为空时不会显示	`true`
`player-shop-block.stall-entity.gravity`	盔甲架实体是否启用重力，建议保持关闭避免模型掉落	`false`
`player-shop-block.stall-entity.cleanup-radius`	清理残留摆摊实体时的扫描半径	`2.0`
`player-shop-block.stall-entity.default-model`	默认盔甲架装备与外观；`PLAYER_HEAD` 可配合 `use-owner-head` 显示店主头颅	见默认配置
`player-shop-block.stall-entity.models`	可选模型列表，可用 `permission` 控制玩家能否选择	见默认配置
`player-shop-block.stall-entity.offset`	实体生成偏移，相对于绑定方块坐标	`0.5, 0.0, 0.5`
`player-shop-block.stall-entity.facing`	实体朝向：`BLOCK_FACE` 或 `OWNER_FACING`	`BLOCK_FACE`
`player-shop-block.protection.disable-vanilla-interact`	右键已绑定方块打开商店后，是否取消原版交互（如箱子/木桶界面）	`true`
`player-shop-block.protection.deny-break-by-others`	是否阻止非店主破坏已绑定方块	`true`

单服使用

如果你只有一个服务器且不需要 MySQL，可以将 database.enable 设为 false，插件会自动使用 SQLite 存储数据，无需额外配置数据库。

跨服同步

如果你使用 BungeeCord 或 Velocity 群组服，需要同时启用 MySQL 和 Redis。所有子服连接同一个数据库和 Redis 实例，即可实现商城数据跨服同步。

文件监听边界

file.enable_listen: true 只会监听已经加载的 goods/*.yml、shop/*.yml、recycle/*.yml、ui/*.yml、currency.yml 与 autosell_chest.yml。config.yml 和语言文件不会靠这个开关自动重载；修改这些文件后应执行 /malkuth reload。

当前重载范围（按源码）

/malkuth reload 会重载主配置（含 minimessage.*、upload_entry.*、upload_editor.*、recovery.*、player-shop-block.* 与 debug.*）、currency.yml、autosell_chest.yml、shop/、goods/、ui/、recycle/ 与语言文件，并重新建立玩家商店方块绑定缓存。同时它会清除所有未提交的上架草稿、暂停后再恢复创建/拍卖恢复服务、按新配置重启 Assiah 转发任务，重置缓存服务与邮箱后端，清空随机商品结果、购物车和回收统计缓存，刷新商店占位符缓存，关闭在线玩家当前打开的商店界面，并广播一次跨服缓存失效通知。

语言文件

语言文件位于 plugins/Malkuth/lang/ 目录（默认包含 zh_CN.yml 与 en_US.yml），你可以自定义插件中所有提示消息的文本。

格式说明

支持 & 颜色代码（如 &a 绿色、&c 红色、&e 黄色）
使用 {0}、{1}、{2} 等位置变量替换动态内容

消息分类

语言文件中的消息按功能模块分类：

分类	说明
`auction-*`	拍卖行相关消息（竞拍成功/失败、余额不足等）
`player-shop-*`	玩家商店消息（购买成功、售罄等）
`shopblock-` / `shopblock_hologram-` / `shopblock_stall-*`	玩家商店方块、全息显示和摆摊实体消息
`global-market-*`	全球市场相关消息（筛选、排序、搜索、购买/下架等）
`global-request-*`	全球求购相关消息（创建、供货、审核、取消、过期、通知与 UI 输入）
`upload-*`	上架相关消息（上架成功、黑白名单拦截等）
`edit-*`	编辑商品消息
`recycle-*`	回收系统消息（回收成功、无可回收物品等）
`order-*`	挂单相关消息
`buy-*`	购买相关消息（无权限、限购等）
`mailbox-*`	邮箱消息（登录提醒、领取成功等）
`favorite-*`	收藏夹消息
`cart-*`	购物车消息（加入、移除、结算等）
`gift-*`	赠送消息（输入玩家名、赠送成功等）
`pricecompare-*`	比价搜索消息
`ui-*`	聊天输入与界面交互提示（搜索/数量输入等）
`item-source-*`	物品源挂钩与解析错误提示
`matcher-*`	物品匹配拒绝原因提示（`source` / `nbt` / `locked`）
`limit-*`	新限购系统提示（商店级/商品级数量与金额限制）
`command-tax-*`	税收报表命令输出
`command-extract-*`	默认资源释放命令输出
`autosell-*`	自动售卖箱发放、放置、升级、售卖和管理提示
`config-*`	配置加载与热重载提示（goods/shop/ui/currency/recycle）
`cross-server-*`	跨服同步提示
`schedule-*`	定时任务提示
`command-*`	命令执行提示（重载、调试、同步等）
`system-*`	系统级提示（权限不足、商店不可用等）
`serializer-*`	配置序列化错误与校验提示
`banner-*`	启动横幅文本
`prefix`	全局消息前缀

config.yml​

配置项说明​

autosell_chest.yml​

玩家商店方块​

语言文件​

格式说明​

消息分类​