# MagicItemMode

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

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

One selectable state within an independent item mode group.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `activate` | `ItemModeTransition` | required | Explicit transition used to select this mode. |
| `deactivate` | `ItemModeTransition` | optional | Optional explicit transition used to clear this mode. |
| `duration_secs` | `integer` | optional | Duration from activation in world seconds; absent lasts until cleared. |
| `effects` | `ItemModeEffect[]` | required | Mechanical projections supplied while selected and eligible. |
| `end_when` | `ItemModeEnd[]` | default `[]` | Events that clear rather than merely suppress this selection. |
| `id` | `string` | required | Definition-local stable mode id. |
| `selectable_from_inactive` | `boolean` | default `true` | Whether this mode may be selected when no mode in its group is active. Modes that only represent adjustments can remain switch targets without becoming alternate activation entry points. |
| `switch` | `ItemModeTransition` | optional | Optional transition used when replacing another active mode in this group. Absent reuses `activate`; authored controls can distinguish turning a device on from adjusting it while already active. |
| `usage_budget` | `ItemModeUsageBudget` | optional | Optional cumulative active-time budget for this group. Re-entering the mode spends only what remained before it was deactivated. |
| `while_active_requires` | `ItemModeRequirement` | optional | Ongoing relationship after activation. Absent retains the activation requirement; this is explicit for modes that release a held item. |


## Supporting shapes

- [ItemModeEffect](https://kinbarrow.com/modding/latest/mechanisms/magic-item/item-mode-effect.md)
- [ItemModeEnd](https://kinbarrow.com/modding/latest/mechanisms/magic-item/item-mode-end.md)
- [ItemModeRequirement](https://kinbarrow.com/modding/latest/mechanisms/magic-item/item-mode-requirement.md)
- [ItemModeTransition](https://kinbarrow.com/modding/latest/mechanisms/magic-item/item-mode-transition.md)
- [ItemModeUsageBudget](https://kinbarrow.com/modding/latest/mechanisms/magic-item/item-mode-usage-budget.md)