# MagicActivationPayload

> Kinbarrow modding reference — content tree `4a103dcdb658a75a`, version `0.2.0+main.e011511f4`.

[Effects and mechanisms](https://kinbarrow.com/modding/latest/mechanisms.md)

Used by [MagicItem](https://kinbarrow.com/modding/latest/magic-item.md#magic-activation-payload).

This is a nested shape inside a content file. The catalog explains context validation and links real RON examples.

What an activated magic item releases. Spell payloads resolve through the ordinary spell composition; effect payloads carry the same typed effect steps directly for items whose magic is not a named spell.

<a id="magic-activation-payload--spell"></a>

## MagicActivationPayload::Spell

Select the spell behavior.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `area_override` | `Area` | optional | An item-authored replacement for the referenced spell's delivery area. This changes only the footprint; the ordinary spell keeps ownership of its save, effects, duration, and concentration. |
| `forced_action_options` | `array` | optional | A non-empty subset of a referenced spell's authored forced-action choices. The activation may narrow a spell's menu but cannot add a command the spell itself does not know. |
| `spell` | `string` | required |  |

<a id="magic-activation-payload--effect"></a>

## MagicActivationPayload::Effect

Select the effect behavior.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `delivery` | `Delivery` | required |  |
| `duration_roll` | `RolledDuration` | optional | One activation-scoped duration roll shared by every subject the delivery reaches. The roll is made once, then multiplied by this many world seconds (for example, 60 for a duration in minutes). |
| `duration_secs` | `integer` | optional | How long the composed direct effect persists. Instantaneous effects omit this; item magic never inherits concentration. |
| `effects` | `Effect[]` | required |  |
| `range_ft` | `uint32` | default `0` |  |
| `self_only` | `boolean` | default `false` | The item's bearer is the only legal target. This is distinct from range 0, which retains the ordinary touch-target behavior. |
| `then` | `SpellPhase[]` | optional | Ordered follow-up phases with independent delivery gates. These share the activation's target/aim but do not repay its economy or consumption, matching the ordinary staged-spell substrate. |

<a id="magic-activation-payload--recover-spell-slot"></a>

## MagicActivationPayload::RecoverSpellSlot

Restore one expended spell slot of this exact level. A definition may expose several activation options so the player/solver chooses the expended slot explicitly rather than an item policy choosing for them.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `level` | `uint8` | required |  |

<a id="magic-activation-payload--granted-action"></a>

## MagicActivationPayload::GrantedAction

Consume/activate an item to install a world-portable later action.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `consume_on_success` | `boolean` | default `false` |  |
| `delivery` | `GrantedActionDelivery` | required |  |
| `duration_secs` | `uint64` | required |  |
| `economy` | `CastTime` | required |  |
| `effects` | `GrantedActionEffect[]` | required |  |
| `uses` | `uint16` | required |  |


## Supporting shapes

- [Area](https://kinbarrow.com/modding/latest/mechanisms/spell/area.md)
- [AuthoredForcedAction](https://kinbarrow.com/modding/latest/spell.md#authored-forced-action)
- [CastTime](https://kinbarrow.com/modding/latest/spell.md#cast-time)
- [Delivery](https://kinbarrow.com/modding/latest/mechanisms/spell/delivery.md)
- [Effect](https://kinbarrow.com/modding/latest/mechanisms/spell/effect.md)
- [GrantedActionDelivery](https://kinbarrow.com/modding/latest/mechanisms/magic-item/granted-action-delivery.md)
- [GrantedActionEffect](https://kinbarrow.com/modding/latest/mechanisms/magic-item/granted-action-effect.md)
- [RolledDuration](https://kinbarrow.com/modding/latest/mechanisms/magic-item/rolled-duration.md)
- [SpellPhase](https://kinbarrow.com/modding/latest/magic-item.md#spell-phase)