Emaki Series

简体中文

English

简体中文

English

Appearance

配置详解 ​

本页说明 config.yml 的键。EmakiStorage 的配置分为三个文件，另两个与容量领域模型另有专页：

主题页面
gui/storage_gui.yml 模板、gui 与 display 段界面与展示
capacity 段、四来源容量、三级 stackLimit、缩容溢出容量与缩容
unlock_costs.yml 付费档位付费扩容档位

修改后执行 /estorage reload 重载配置、语言与 GUI 模板。

config.yml 顶层 ​

yaml
version: "1.0.1"
language: "zh_CN"
release_default_data: true
op_bypass: false
debug: false
字段类型默认说明
versionstring1.0.1默认资源版本标记，由资源同步维护。
languagestringzh_CN使用 lang/<language>.yml。
release_default_databooleantrue缺失时是否释放内置 unlock_costs.yml。
op_bypassbooleanfalse为 true 时 OP 视为持有 emakistorage.admin。
debugbooleanfalse会被解析进配置对象，但当前实现没有任何分支读取它；调试开关请通过 /estorage debug 管理。

unlock ​

yaml
unlock:
  overflow_policy: lock_readonly
  purchase_enabled: true
  cost_file: "unlock_costs.yml"
字段类型默认说明
overflow_policyenumlock_readonly容量缩小导致占用超出时的处理策略，四种取值见容量与缩容。
purchase_enabledbooleantrue是否开放 GUI 内付费扩容。还需 emakistorage.unlock.purchase 权限。
cost_filestringunlock_costs.yml付费档位配置文件名，逐键说明见付费扩容档位。

behavior ​

yaml
behavior:
  overflow_on_withdraw: return
  withdraw_amounts:
    left: 1
    right: 16
    shift_left: 32
    shift_right: 64
  withdraw_prompt:
    enabled: true
    mode: "auto"
    dialog:
      title: "dialog.withdraw.title"
      can_close_with_escape: true
      pause: false
      body:
        - "dialog.withdraw.body"
      inputs:
        - type: "text"
          key: "amount"
          label: "dialog.withdraw.label"
          max_length: 32
      buttons:
        - label: "dialog.confirm"
  deposit_filter:
    mode: blacklist
    entries: []
  allow_unique_items: true
  default_sort: amount_desc
  player_sort_enabled: true
字段类型默认说明
overflow_on_withdrawenumreturn取出时背包装不下的剩余部分：return 回补仓库，drop 地面掉落。
withdraw_amounts.leftlong1左键取出数量。
withdraw_amounts.rightlong16右键取出数量。
withdraw_amounts.shift_leftlong32Shift + 左键取出数量。
withdraw_amounts.shift_rightlong64Shift + 右键取出数量。
withdraw_prompt.enabledbooleantrue中键是否启用自定义数量输入。
withdraw_prompt.modeenumauto输入方式：auto 对话框可用则用对话框、否则退回聊天输入；dialog 强制对话框，不可用时该交互被禁用；chat 强制聊天输入。
withdraw_prompt.dialogsection见示例对话框配置，键集见下方对话框配置块。必须保留 key: amount 的输入框。
deposit_filter.modeenumblacklist存入过滤模式：blacklist / whitelist / off。
deposit_filter.entrieslist[]CoreLib ItemSource token 列表。
allow_unique_itemsbooleantrue是否允许存入带唯一标记的物品。
default_sortenumamount_desc默认排序：material_asc / material_desc / name_asc / name_desc / amount_asc / amount_desc。
player_sort_enabledbooleantrue是否允许玩家在 GUI 中切换排序。false 时强制使用 default_sort。

deposit_filter.mode 为 whitelist 且 entries 为空时，所有物品都无法存入。唯一标记的判定是结构化的：检查物品自身的 PersistentDataContainer 是否非空，而不是读取显示名或 lore。

这些键决定各种点击的数量与是否被允许；完整的点击语义表、被拒绝的点击方式与搜索态限制见界面与展示。

yaml
search:
  enabled: true
  operators:
    name: "@"
    lore: "#"
    id: "$"
    exclude: "!"
  input:
    mode: "auto"
    timeout: 30
    cancel_keywords: ["取消", "cancel"]
    dialog:
      title: "dialog.search.title"
      can_close_with_escape: true
      pause: false
      body:
        - "dialog.search.body"
      inputs:
        - type: "text"
          key: "query"
          label: "dialog.search.label"
          max_length: 64
      buttons:
        - label: "dialog.confirm"
字段类型默认说明
enabledbooleantrue是否开放搜索。
operators.namestring@只匹配显示名。
operators.lorestring#只匹配 lore。
operators.idstring$只匹配材质 key 或 ItemSource id。
operators.excludestring!排除：命中则拒绝该条目。
input.modeenumauto输入方式，取值同 behavior.withdraw_prompt.mode。
input.timeoutint30聊天输入等待超时（秒）。
input.cancel_keywordslist[取消, cancel]取消聊天输入的关键词。
input.dialogsection见示例对话框配置。必须保留 key: query 的输入框。

对话框配置块 ​

behavior.withdraw_prompt.dialog 与 search.input.dialog 使用与 EmakiCoreLib 对话框定义文件（EmakiCoreLib/dialogs/*.yml）完全相同的键集，包括 type、external_title、after_action、columns、exit_button，以及输入项的 width、initial、label_visible 等。区别只有一点：id 由插件提供，配置里不需要写。

title、body 条目的文本、输入项的 label、按钮的 label 与 tooltip 会先按语言键解析：填 dialog.withdraw.title 这类键名时读取 lang/*.yml，键不存在则按原文渲染，因此也可以直接写 MiniMessage 文本。搜索对话框的正文支持 %name%、%lore%、%id%、%exclude% 四个操作符占位符。

对话框需要客户端 1.21.6 及以上，并且 EmakiCoreLib 的 dialog.enabled 为 true。若 inputs 中缺少业务所需的 key（取出为 amount，搜索为 query）或没有任何按钮，该对话框会被判定为不可用：mode: auto 回退聊天输入，mode: dialog 则该交互被禁用并提示 dialog.unavailable。

操作符前缀可改，用于避免与物品名冲突。搜索语法规则：

  • 空白分隔多个词，所有词必须同时满足（AND）。
  • 一个词可同时带一个作用域前缀和一个排除前缀，顺序任意，例如 !@钻石 与 @!钻石 等价。
  • 不带作用域前缀时匹配合并文本。合并文本由「显示名 + lore + 标识符」三段拼成，因此无前缀搜索也能命中材质 key。
  • 全部匹配都是子串匹配，对已经小写化并去除格式的预计算文本执行。

不提供正则搜索，也没有管理员开关：恶意正则会因灾难性回溯卡服，而子串匹配已覆盖实际需求。

persistence ​

yaml
persistence:
  autosave_interval: 300
  drain_timeout: 10
字段类型默认说明
autosave_intervalint300自动保存间隔（秒）。0 表示仅在关闭 GUI 与下线时保存。
drain_timeoutint10插件停用时等待文件写入 drain 的超时（秒）。

自动保存期间的多次数量变化会合并为一次写盘。每次保存都是对 storage.dat 的全量重写：先写同目录 .tmp，读回校验记录数，再原子替换。写入失败时旧文件保持不变并删除 tmp。

logging ​

yaml
logging:
  enabled: true
  retention_days: 30
  sources: []
字段类型默认说明
enabledbooleantrue是否记录常规流水。
retention_daysint30日志保留天数。<= 0 时不清理。
sourceslist[]只记录这些来源：gui / command / api / action。留空表示全部。

日志目录结构是「按玩家目录 + 按日切文件」：logs/<uuid>/<yyyy-MM-dd>.log。过期文件按日删除；某玩家的日志全部过期后其目录一并删除。

ADMIN_SET、ADMIN_GIVE、ADMIN_CLEAR 三类管理员操作强制记录，不受 enabled 与 sources 影响。管理员为省磁盘关掉日志，不是丢失管理员改动审计的理由。

流水日志只写不读：业务逻辑永不读取这些文件，因此不需要索引、压实、schema 版本或跨文件事务。写入失败只记一条 warning，不会让产生它的存取事务失败。同一玩家排队的记录会合并为一次追加写，所以 36 格批量存入产生一次文件操作而不是 36 次。

相关页面 ​