CoreLib Actions

When EmakiStorage is enabled, it adds five warehouse stages to the CoreLib action registry. Use them in other modules' rewards, triggers, or pipeline templates to store and withdraw items, grant slots, or adjust stack ceilings.

NOTE

This page documents only the stages registered by EmakiStorage. 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.

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.

All five require the player's storage record to be loaded in memory; otherwise they fail with MISSING_CONTEXT.

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.

On success the stage reports stored, the amount actually stored, which may be less than requested (a partial deposit).

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.

On success the stage reports withdrawn, the amount actually withdrawn.

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 order is debit first, then hand out. The reverse 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.

On success the stage reports granted_slots, the new total. An amount of 0 fails with INVALID_CONFIG.

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. Unlike 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.

On success the stage reports purchased_slots. A non-positive amount fails with INVALID_CONFIG.

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.

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).

0 means different things at different levels: 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.

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.