命令与权限

EmakiStorage 的主命令是 /emakistorage，别名为 /estorage。文档示例统一使用 /estorage。

不带参数执行时打开自己的仓库，需要 emakistorage.use（emakistorage.admin 也可通过）。管理类子命令统一要求 emakistorage.admin；reload 与 debug 另有专用权限，也可被 emakistorage.admin 代替。

命令列表

命令	权限	说明
/estorage	emakistorage.use	打开自己的仓库。仅玩家可执行。
/estorage help	无额外检查	显示帮助。
/estorage open <player>	emakistorage.admin	以管理员身份打开目标玩家的仓库。执行者必须是玩家。
/estorage slot grant <player> <amount>	emakistorage.admin	调整目标玩家的授予槽位数。amount 为负数表示回收。
/estorage stacklimit player <player> <limit>	emakistorage.admin	设置目标玩家的玩家级单槽上限。
/estorage stacklimit slot <player> <slot> <limit>	emakistorage.admin	设置目标玩家某个逻辑槽位的条目级上限。
/estorage info <player>	emakistorage.admin	打印容量拆解、页数、stackLimit、排序模式与总量。
/estorage export <player>	emakistorage.admin	把仓库导出为可读 YAML，写入 exports/export-<uuid>.yml。
/estorage reload	emakistorage.reload 或 emakistorage.admin	重载配置、语言与 GUI 模板，并回报已加载模板数。
/estorage debug ...	emakistorage.debug 或 emakistorage.admin	管理 debug 模块。可用模块为 storage 与 chat_input，具体子命令由 CoreLib DebugCommand 提供。

示例

/estorage
/estorage help
/estorage open Steve
/estorage slot grant Steve 10
/estorage slot grant Steve -5
/estorage stacklimit player Steve 100000
/estorage stacklimit player Steve max
/estorage stacklimit player Steve 10k
/estorage stacklimit slot Steve 3 5000
/estorage info Steve
/estorage export Steve
/estorage reload
/estorage debug storage on

参数写法

参数	接受的写法	说明
<amount>（slot grant）	十进制整数，可为负	负值回收授予槽位。
<limit>（stacklimit）	十进制数字、紧凑单位（k m b t p e）、max	max 解析为 Long.MAX_VALUE。溢出与 <= 0 一律拒绝而不截断，避免手误静默变成另一个上限。因此命令层无法填 0，恢复继承请用 API 或 Action。
<slot>	逻辑槽位索引（0 起）	该槽位没有条目时命令回报「槽位为空」，不会创建条目。

写操作要求目标玩家在线

slot grant 与 stacklimit 两类写操作在目标玩家离线时直接拒绝，回报 command.target_offline。原因是这些操作要改的是内存中已加载的仓库对象：直接改写一个未加载的存档会与该玩家下一次登录时的载入流程产生竞态，可能覆盖或丢弃改动。

在线目标的写操作会被派发到该玩家自己的 region 线程执行，而不是命令执行者所在的线程。如果此时该玩家的仓库数据仍在载入，命令回报 general.data_loading，请稍后重试。

只读类命令没有这个限制：info 与 export 走快照读取路径，可以在必要时从磁盘载入数据，因此对离线玩家同样可用。open <player> 也可用于离线目标。

权限节点

权限	默认	覆盖范围
emakistorage.use	true	打开自己的仓库。
emakistorage.unlock.purchase	true	在 GUI 中使用付费扩容。还需 unlock.purchase_enabled: true。
emakistorage.reload	op	使用 /estorage reload。可被 emakistorage.admin 代替。
emakistorage.debug	op	使用 /estorage debug ...。可被 emakistorage.admin 代替。
emakistorage.admin	op	使用 open、slot、stacklimit、info、export，并可代替 reload/debug 专用权限。

数值档位权限

以下两个权限是数值档位，不在 paper-plugin.yml 中声明，直接授予带数字后缀的节点即可。

权限前缀	作用	取值规则
emakistorage.slots.<n>	追加 n 个槽位	扫描玩家所有生效权限，取数字后缀的最大值，不累加。
emakistorage.stacklimit.<n>	提供玩家级单槽上限 n	同样取最大值。

两者都不支持通配：emakistorage.slots.* 之类的写法会被跳过。部分权限插件会把通配展开成「持有每一个 n」，那样会把玩家静默推到最高档；因此实现只接受纯数字后缀，含 . 或非数字的后缀一律忽略。

常见 LuckPerms 示例：

/lp group default permission set emakistorage.use true
/lp group default permission set emakistorage.unlock.purchase true
/lp group vip permission set emakistorage.slots.100 true
/lp group vip permission set emakistorage.stacklimit.100000 true
/lp group admin permission set emakistorage.admin true

reload 行为

/estorage reload 会执行以下工作：

1. 释放缺失的默认资源，受 config.yml > release_default_data 控制。
2. 重新读取 config.yml、lang/*.yml、unlock_costs.yml 与 gui/storage_gui.yml。
3. 按新的 gui.storage_rows 重新换算 GUI 布局。
4. 回报已加载的界面模板数量。

gui.storage_rows 超出 1–5 时会被钳制并在控制台记 warning，见 配置详解。

常见失败原因

场景	说明
找不到玩家	玩家名不精确匹配，且服务器缓存中也没有该离线玩家。
玩家 ... 当前离线，无法执行该写操作	slot grant / stacklimit 的目标必须在线。
仓库数据仍在加载，请稍后再试	目标在线但其仓库尚未载入完成。
槽位为空	stacklimit slot 指定的逻辑槽位当前没有条目。
stacklimit 参数被拒绝	解析结果 <= 0 或超出 long 范围。请使用正整数、紧凑单位或 max。
仓库界面打开失败	GUI 模板未加载或解析失败，检查控制台 warning。