容量与缩容

本页说明 EmakiStorage 的容量领域模型：config.yml 的 capacity 段、四来源容量、三级 stackLimit，以及容量调小时的缩容与溢出处理。

capacity

yaml

capacity:
  base_slots: 45
  max_slots: 1000
  warn_entry_count: 5000
  default_stack_limit: 100

字段	类型	默认	说明
`base_slots`	int	`45`	默认开放槽位数（45 = 5 × 9，与 `gui.storage_rows` 默认值一致）。
`max_slots`	int	`1000`	槽位总量硬上限，`0` 表示无限。
`warn_entry_count`	int	`5000`	条目数超过此值时向控制台记 warning，`0` 表示不提醒。
`default_stack_limit`	long	`100`	配置级单槽堆叠上限。此层的 `0` 表示不限制。

effectiveSlots 由四个独立持久化的来源相加后钳制：

text

effective = clamp(base_slots + 权限档位 + grantedSlots + purchasedSlots, 0, max_slots)

max_slots 为 0 时跳过上限钳制。四个来源分开存储，所以调小 base_slots 不会吃掉玩家已授予或已购买的槽位。

来源	来自	可否为负
`baseSlots`	`capacity.base_slots`	否（负值按 0 处理）
`permissionSlots`	`emakistorage.slots.<n>` 的最大档位	否
`grantedSlots`	`/estorage slot grant`、API `grantSlots`、Action `storage-grant-slot`	是
`purchasedSlots`	GUI 付费扩容、Action `storage-unlock-slot`	否

页数由槽位数推导，不可反向配置：

text

totalPages     = max(1, ceil(effectiveSlots / 每页格数))
reachablePages = max(1, ceil(usedSlots / 每页格数))

第 1 页始终可达（空仓库也要能打开并接收第一件物品）；完全没有条目的页无法翻入。

将 max_slots 设为 0（无限）前请确认内存充足。配置注释给出的量级是单玩家 10 万条目约占 100–200MB 堆内存，这是推算值，未实测。

单槽上限按「最具体优先」解析，三层：

层级	存储位置	设置方式	`0` 的含义
条目级	`meta.yml` 对应条目	`/estorage stacklimit slot`、API `setSlotStackLimit`、Action `storage-set-stacklimit` 带 `slot`	继承玩家级
玩家级	`meta.yml` 的 `defaultStackLimit`	`/estorage stacklimit player`、API `setStackLimit`、Action `storage-set-stacklimit` 不带 `slot`	继承配置级
配置级	`config.yml` 的 `capacity.default_stack_limit`	配置文件	不限制（等价 `Long.MAX_VALUE`）

同一个 0 在不同层级语义不同：条目级与玩家级的 0 表示「继承上一级」，配置级的 0 表示「无限制」。解析顺序是条目级 > 0 → 玩家级 > 0 → 配置级，配置级 <= 0 时返回 Long.MAX_VALUE。

另有 emakistorage.stacklimit.<n> 权限档位可提供玩家级上限，同样取最大值、不支持通配。

容量调小导致占用超出边界时，按 unlock.overflow_policy 处理。该键本身在配置详解的 unlock 段。

取值	行为
`lock_readonly`	超出容量边界的条目只读：可取出、不可存入，取空后自动释放。推荐。
`compact`	超出条目前滚填补空位。条目本身已存储在无空洞的紧凑列表中，因此「前滚」就是列表的自然状态；仍然装不下的部分退化为 `lock_readonly`。
`return_inventory`	尝试把超出条目退回玩家背包，装不下的退化为 `lock_readonly`。玩家离线时不退还，直接锁定。
`reject_change`	直接拒绝本次缩容。

四种策略全部零丢失，不提供 drop 与 delete：不可逆数据丢失不应由调整配置隐式触发。

溢出状态不持久化。它由容量与占用推导，在登录、重载、权限变化、命令授予等容量变化时机重新计算，因此不会出现存储标记与事实不同步的情况。