CoreLib 动作

EmakiStorage 向 CoreLib 动作系统注册了 5 个仓库段. 前置条件: EmakiStorage 已启用, 注册表即获得这些段; 其他模块可在奖励, 触发器或管道模板里用它们存取物品, 授予槽位或调整单槽上限

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 状态