CoreLib 动作

EmakiStorage 启用后会向 CoreLib 动作注册表追加 5 个仓库动作。它们可用于其他模块的奖励、触发器、脚本或动作模板中，用来存取物品、授予槽位或调整单槽上限。

本页只记录 EmakiStorage 注册的 CoreLib 动作；CoreLib 自带通用动作见 CoreLib 动作系统。

所有 Storage 动作的 source 为 emakistorage，分类为 storage。

动作总览

动作 ID	说明
storage-deposit	把物品存入动作上下文玩家的仓库。
storage-withdraw	从动作上下文玩家的仓库取出物品。
storage-grant-slot	增加或回收授予槽位。
storage-unlock-slot	不收费地增加已购买槽位。
storage-set-stacklimit	设置玩家级或条目级单槽上限。

五个动作都作用于动作上下文玩家，没有 target 参数。它们都要求该玩家的仓库数据已载入内存；未载入时统一以 EXECUTION_EXCEPTION 失败，错误信息为 Storage data is not loaded for this player.。

storage-deposit

把物品存入仓库，不触碰任何背包。

参数	类型	必填	默认值	说明
item	STRING	是	—	CoreLib ItemSource token。
amount	INTEGER	否	1	存入数量，必须为正。

返回数据键：

键	说明
stored	实际存入的数量。可能小于请求量（部分存入）。

失败场景：

• 仓库数据未载入。
• item 无法解析为 ItemSource（INVALID_ARGUMENT，Unknown item source: ...）。
• amount 非正（INVALID_ARGUMENT，amount must be positive）。
• 事务被拒绝，EXECUTION_EXCEPTION 消息为 Deposit rejected: <reasonKey>。常见 reasonKey：filtered（被存入过滤器拒绝）、unique_rejected（唯一标记物品且 allow_unique_items: false）、no_free_slot（需要新建条目但槽位已满）、slot_full（已达单槽上限）。

actions:
  - 'storage-deposit item=diamond amount=64'

storage-withdraw

从仓库取出物品并交给玩家。条目按全量 ItemStack#equals 定位。

参数	类型	必填	默认值	说明
item	STRING	是	—	CoreLib ItemSource token。
amount	INTEGER	否	1	取出数量，必须为正。

返回数据键：

键	说明
withdrawn	实际取出的数量。

失败场景：

• 仓库数据未载入。
• item 无法解析（INVALID_ARGUMENT）。
• amount 非正（INVALID_ARGUMENT）。
• 事务被拒绝，消息为 Withdrawal rejected: <reasonKey>。常见 reasonKey：entry_missing（仓库中没有该条目）、inventory_full（背包装不下且 overflow_on_withdraw: return 已把剩余回补仓库）。

取出顺序是先扣仓库再交付。反过来会出现「交付成功、扣减失败」的复制漏洞；按此顺序最坏情况只是玩家拿到的比请求的少，而这部分剩余会立即回补。

actions:
  - 'storage-withdraw item=diamond amount=16'

storage-grant-slot

调整授予槽位池，用于等级、图鉴等奖励流程。

参数	类型	必填	默认值	说明
amount	INTEGER	是	—	授予槽位数。负值表示回收。

返回数据键：

键	说明
granted_slots	调整后的授予槽位总数。

失败场景：

• 仓库数据未载入。
• amount 为 0（INVALID_ARGUMENT，amount must be non-zero）。

该动作记录为 ADMIN_GIVE 类型流水，属于强制记录，不受 logging.enabled 与 logging.sources 影响。

actions:
  - 'storage-grant-slot amount=10'
  - 'storage-grant-slot amount=-5'

storage-unlock-slot

不收费地增加已购买槽位，用于奖励流程。与 storage-grant-slot 的差别是它增加的是 purchasedSlots 池，会影响后续付费扩容的逐格计价起点。

参数	类型	必填	默认值	说明
amount	INTEGER	是	—	解锁槽位数，必须为正。

返回数据键：

键	说明
purchased_slots	调整后的已购买槽位总数。

失败场景：

• 仓库数据未载入。
• amount 非正（INVALID_ARGUMENT，amount must be positive）。

该动作记录为 UNLOCK 类型流水，备注为 cost=none。

actions:
  - 'storage-unlock-slot amount=5'

storage-set-stacklimit

设置玩家级或条目级单槽上限。

参数	类型	必填	默认值	说明
limit	INTEGER	是	—	新上限，必须 >= 0。0 表示继承上一级。
slot	INTEGER	否	-1	逻辑槽位索引。-1（或任何负值）表示设置玩家级默认值。

返回数据键：

场景	键	说明
slot 为负	default_stack_limit	设置后的玩家级上限。
slot 为非负	slot	被修改的槽位索引。
slot 为非负	stack_limit	设置后的条目级上限。

失败场景：

• 仓库数据未载入。
• limit 为负（INVALID_ARGUMENT，limit must be zero or positive）。
• slot 为非负但该槽位没有条目（INVALID_ARGUMENT，No entry at slot <n>）。

0 在不同层级语义不同：条目级与玩家级的 0 表示继承上一级，配置级 capacity.default_stack_limit 的 0 表示不限制。三级继承规则见 配置详解。

该动作记录为 ADMIN_SET 类型流水，属于强制记录。

actions:
  - 'storage-set-stacklimit limit=100000'
  - 'storage-set-stacklimit limit=5000 slot=3'
  - 'storage-set-stacklimit limit=0'

相关页面

• 配置详解：stackLimit 三级继承、存入过滤器、逐格计价。
• API 与集成：同样能力的代码集成入口与 StorageResult 状态。