CoreLib 动作

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

NOTE

本页只记录 EmakiStorage 注册的段；CoreLib 自带通用段见 CoreLib 动作系统。旧的连字符写法 storage-deposit 现在写作 storage_deposit，其余同理。

五个段的分类都是 storage，目标要求都是 REQUIRED_ENTITY，非玩家目标会跳过。「作用于谁」由 source 决定，没有 target 参数：作用于执行者自己写 self，指定玩家用 player_by_name。

段总览

段 ID	说明
storage_deposit	把物品存入目标玩家的仓库。
storage_withdraw	从目标玩家的仓库取出物品。
storage_grant_slot	增加或回收授予槽位。
storage_unlock_slot	不收费地增加已购买槽位。
storage_set_stacklimit	设置玩家级或条目级单槽上限。

五个段都要求该玩家的仓库数据已载入内存；未载入时以 MISSING_CONTEXT 失败。

item 参数是 ItemSource token，不是管道物品。这个模块按定义寻址库存商品，而不是按管道当时携带的那一叠物品，所以它不读 CoreActionKeys.ITEM。

storage_deposit

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

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

成功时输出 stored，也就是实际存入的数量，可能小于请求量（部分存入）。

失败场景：

• 仓库数据或相关服务未就绪（MISSING_CONTEXT）。
• item 无法解析为 ItemSource（INVALID_CONFIG）。
• amount 非正（INVALID_CONFIG）。
• 事务被拒绝（REJECTED），结果里带上 reason。常见原因：filtered（被存入过滤器拒绝）、unique_rejected（唯一标记物品且 allow_unique_items: false）、no_free_slot（需要新建条目但槽位已满）、slot_full（已达单槽上限）。

actions:
  - 'self | storage_deposit item=diamond amount=64'
  - 'player_by_name name=Steve | storage_deposit item=emakiitem-forge_token amount=1'

storage_withdraw

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

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

成功时输出 withdrawn，也就是实际取出的数量。

失败场景：

• 仓库数据或事务服务未就绪（MISSING_CONTEXT）。
• item 无法解析（INVALID_CONFIG）。
• amount 非正（INVALID_CONFIG）。
• 事务被拒绝（REJECTED），结果里带上 reason。常见原因：entry_missing（仓库中没有该条目）、inventory_full（背包装不下且 overflow_on_withdraw: return 已把剩余回补仓库）。

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

actions:
  - 'self | storage_withdraw item=diamond amount=16'

storage_grant_slot

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

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

成功时输出 granted_slots，也就是调整后的授予槽位总数。amount 为 0 时以 INVALID_CONFIG 失败。

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

actions:
  - 'self | storage_grant_slot amount=10'
  - 'player_by_name name=Steve | storage_grant_slot amount=-5'

storage_unlock_slot

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

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

成功时输出 purchased_slots。amount 非正时以 INVALID_CONFIG 失败。

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

actions:
  - 'self | 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	设置后的条目级上限。

失败场景：

• 仓库数据未载入（MISSING_CONTEXT）。
• limit 为负（INVALID_CONFIG）。
• slot 为非负但该槽位没有条目（INVALID_CONFIG，结果里带上 slot）。

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

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

actions:
  - 'self | storage_set_stacklimit limit=100000'
  - 'self | storage_set_stacklimit limit=5000 slot=3'
  - 'self | storage_set_stacklimit limit=0'

相关页面

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