CoreLib Actions

EmakiStorage registers five warehouse stages into the CoreLib action system. Prerequisite: EmakiStorage is enabled, which is when the registry gains these stages. Use them in other modules' rewards, triggers, or pipeline templates to store and withdraw items, grant slots, or adjust stack ceilings

NOTE

Scope and migration: only the stages registered by EmakiStorage are covered. CoreLib built-in stages are documented in CoreLib Actions. The old hyphenated storage-deposit is now written storage_deposit, and the others follow the same rule

Target requirement: all five stages use the category storage and declare REQUIRED_ENTITY; non-player targets are skipped. Which player is affected comes from the source, so there is no target parameter: use self for the caster, or player_by_name for a named player

Stage overview

Stage ID	Description
storage_deposit	Stores items into the target player's warehouse
storage_withdraw	Withdraws items from the target player's warehouse
storage_grant_slot	Grants or reclaims granted slots
storage_unlock_slot	Adds purchased slots without charging
storage_set_stacklimit	Sets the player-level or per-entry stack ceiling

Prerequisite: the player's storage record must be loaded in memory for all five stages; otherwise they fail with MISSING_CONTEXT

Parameter contract: the item parameter is an ItemSource token, not a pipeline item. This module addresses stored goods by definition rather than by whatever stack a pipeline happens to be carrying, so it does not read CoreActionKeys.ITEM

storage_deposit

Stores items into the warehouse without touching any inventory

Parameter	Type	Required	Default	Description
item	STRING	Yes	—	CoreLib ItemSource token
amount	INTEGER	No	1	Units to store; must be positive

Verification: on success the stage reports stored, the amount actually stored, which may be less than requested (a partial deposit)

Error handling, failure cases:

• Storage data or a required service is not ready (MISSING_CONTEXT)
• item cannot be parsed as an ItemSource (INVALID_CONFIG)
• amount is not positive (INVALID_CONFIG)
• The transaction is refused (REJECTED), with reason in the result data. Common reasons: filtered (rejected by the deposit filter), unique_rejected (a uniquely marked item with allow_unique_items: false), no_free_slot (a new entry is needed but slots are full), slot_full (the stack ceiling is reached)

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

storage_withdraw

Withdraws items from the warehouse and hands them to the player. Entries are located by full ItemStack#equals

Parameter	Type	Required	Default	Description
item	STRING	Yes	—	CoreLib ItemSource token
amount	INTEGER	No	1	Units to withdraw; must be positive

Verification: on success the stage reports withdrawn, the amount actually withdrawn

Error handling, failure cases:

• Storage data or the transaction service is not ready (MISSING_CONTEXT)
• item cannot be parsed (INVALID_CONFIG)
• amount is not positive (INVALID_CONFIG)
• The transaction is refused (REJECTED), with reason in the result data. Common reasons: entry_missing (no such entry in the warehouse), inventory_full (the inventory could not take it and overflow_on_withdraw: return has already credited the remainder back)

The withdrawal order is debit first, then hand out; never the reverse. Reversing it would create a duplication bug where delivery succeeds but the debit fails; in this order the worst case is that the player receives less than requested, and that remainder is credited back immediately

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

storage_grant_slot

Adjusts the granted slot pool, for level, codex, and similar reward flows

Parameter	Type	Required	Default	Description
amount	INTEGER	Yes	—	Slots to grant. Negative reclaims

Verification: on success the stage reports granted_slots, the new total. Error handling: an amount of 0 fails with INVALID_CONFIG

Log record: this stage records an ADMIN_GIVE log entry. Administrative entries are always logged, regardless of logging.enabled and logging.sources

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

storage_unlock_slot

Adds purchased slots without charging, for reward flows. Difference from storage_grant_slot: it grows the purchasedSlots pool, which shifts the starting point of per-slot pricing for later paid expansions

Parameter	Type	Required	Default	Description
amount	INTEGER	Yes	—	Slots to unlock; must be positive

Verification: on success the stage reports purchased_slots. Error handling: a non-positive amount fails with INVALID_CONFIG

Log record: this stage records an UNLOCK log entry with the detail cost=none

actions:
  - 'self | storage_unlock_slot amount=5'

storage_set_stacklimit

Sets the player-level or per-entry stack ceiling

Parameter	Type	Required	Default	Description
limit	INTEGER	Yes	—	New ceiling; must be >= 0. 0 inherits the next level up
slot	INTEGER	No	-1	Logical slot index. -1 (or any negative value) sets the player-level default

Result data keys:

Case	Key	Description
slot negative	default_stack_limit	The new player-level ceiling
slot non-negative	slot	The slot index that was changed
slot non-negative	stack_limit	The new per-entry ceiling

Error handling, failure cases:

• Storage data is not loaded (MISSING_CONTEXT)
• limit is negative (INVALID_CONFIG)
• slot is non-negative but that slot holds no entry (INVALID_CONFIG, with slot in the result data)

The same 0 differs per level, so do not mix them up: at the entry and player levels it inherits the level above, while at the config level capacity.default_stack_limit uses 0 for unlimited. The three-level inheritance rules are covered in Configuration

Log record: this stage records an ADMIN_SET log entry, which is always logged

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

Related pages

• Configuration: stackLimit three-level inheritance, deposit filters, per-slot pricing
• API and Integration: the code entry points for the same capabilities and the StorageResult states