# Equipment (inventory.equipment)

## What it is for

Adds worn gear: equipment slots, a collection of gear with weight and stats, equip and unequip from the inventory, worn stats applied to combat and a carry weight that slows an overloaded player.

It needs `inventory.items`, `game.engine`; installing it brings them in.

## Turn it on

Install the kit in a project, then change a setting (the values shown are its defaults):

```text
gripforge_gamekit_install   { project_id: "gkp_…", id: "inventory.equipment" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "inventory.equipment",
                              config: { "slots": ["head", "chest", "hands", "feet", "weapon", "offhand", "ring", "amulet"], "maxWeight": 0 } }
```

## First example

The kit has no dedicated test yet; this installs it and sets two of its settings to their defaults.

```text
gripforge_gamekit_install   { project_id: "gkp_…", id: "inventory.equipment" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "inventory.equipment",
                              config: { "slots": ["head", "chest", "hands", "feet", "weapon", "offhand", "ring", "amulet"], "maxWeight": 0 } }
```

## Settings and defaults

Descriptions come from the kit manifest and stay in English.

| Setting | Type | Default | Range or values | Meaning |
|---|---|---|---|---|
| `slots` | array | `["head", "chest", "hands", "feet", "weapon", …` |  | Equipment slots of the character. |
| `maxWeight` | number | `0` | 0–100000 | Carry weight of the worn gear; 0: unlimited. |
| `overloadSlow` | number | `0.4` | 0–0.9 | Share of walking speed lost while over maxWeight. |
| `autoEquip` | boolean | `false` |  | A picked-up piece of gear is worn at once when its slot is free. |

## Services, events, variables

- Service `inventory.equipment`: slots(), equipped(), equippedIn(slot), gear(), canEquip(id), equip(id), unequip(slot), stats(), stat(name), weight(), screen(open?).
- Events emitted:
  - `equipment.changed` (`slot`, `item`, `previous`) — A slot now holds `item` (empty string: nothing); `previous` is what it held.
  - `equipment.refused` (`item`, `reason`) — equip() failed (unknown, not held, bad slot), or a tap of equipment.equip / equipment.unequip refused it (its reason; item: the piece that stays…
  - `equipment.stats` (`stats`, `weight`, `overloaded`) — The worn stats changed.
- Events listened to: `inventory.changed`, `game.phase`
- Variables:
  - `equipment.screen` (boolean) — Equipment screen open
  - `equipment.weight` (number) — Carry weight
  - `equipment.armor` (number) — Armour
  - `equipment.overloaded` (boolean) — Overloaded
- Verbs of the scripting layer:
  - `equip_item` (action) — Wear a piece of gear the player holds (takes one unit from the inventory).
  - `unequip_slot` (action) — Take off what a slot holds (the unit returns to the inventory).
  - `equipped` (condition) — The player wears this piece of gear.
- Input actions: `equipment`

## Hooks and modding

- Hooks (a game or a mod can intercept them):
  - `equipment.equip` (cancellable) — The player is about to wear a piece of gear it holds in a slot (equip, equip_item, auto-equip); previous is the piece the slot holds (empty string: none).
  - `equipment.unequip` (fields a tap may change: `returned`; cancellable) — A worn piece is about to leave its slot: unequip, unequip_slot, or another piece taking the slot (after equipment.equip).
- Moddable settings: `slots`, `maxWeight`, `overloadSlow`, `autoEquip`
- Moddable collections: `equipment`

## Engines

Declared targets: `web`, `rust`. `gripforge kit api inventory.equipment` lists the exact settings and services of your version.

## Versions

Kit version 1.1.0.