# Object TOML Reference

Each file in a region’s `objects/` folder (e.g. `world/town/objects/`) defines one object type. The object ID is `"<region>:<filename_stem>"` (e.g. `rusty_sword.toml` in region `town` → `town:rusty_sword`).

## Top-level fields

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `name` | string | Yes | — | Display name. |
| `description` | string | Yes | — | Shown when the player looks at or examines the object. |
| `room` | string | No | — | Full room ID where the object is placed (e.g. `"town:forge"`). If omitted, the object does not appear in the world until given by script or placed elsewhere. |
| `kind` | string | No | — | Flavour/legacy: e.g. `"weapon"`, `"armor"`, `"consumable"`. If `slot` is not set, `weapon` → `main_hand`, `armor` → `torso` for equip. |
| `slot` | string | No | — | Equipment slot name (e.g. `"main_hand"`, `"off_hand"`, `"torso"`, `"head"`). Must be a slot the equipper’s race has. If set, overrides `kind` for slot choice. |
| `takeable` | boolean | No | `false` | If `true`, players can take the object and put it in inventory. |
| `stats` | table | No | — | See `[stats]` below. |

## `[stats]`

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `damage` | integer | No | — | Weapon damage bonus when equipped in a weapon slot. |
| `armor` | integer | No | — | Armor bonus when equipped in an armor slot. |
| `heal_amount` | integer | No | — | HP restored when the object is **used** (consumable). The object is consumed on use. |

## Examples

**Weapon (explicit slot):**

```toml
name = "Rusty Sword"
description = "A battered iron blade with a cracked leather grip."
room = "town:cellar"
kind = "weapon"
slot = "main_hand"
takeable = true

[stats]
damage = 6
```

**Shield:**

```toml
name = "Iron Shield"
description = "A dented but serviceable round shield."
room = "town:forge"
slot = "off_hand"
takeable = true

[stats]
armor = 4
```

**Consumable:**

```toml
name = "Healing Potion"
description = "A small glass vial filled with a shimmering red liquid."
room = "town:temple"
kind = "consumable"
takeable = true

[stats]
heal_amount = 30
```

**Non-takeable (e.g. scenery):**

```toml
name = "Stone Fountain"
description = "A worn fountain, water trickling quietly."
room = "town:town_square"
takeable = false
```

## Equipment and races

- A race defines which slots it has (see `world/races/RACES.md`). Equipping fails if the race does not have the object’s `slot`.
- If `slot` is omitted, `kind = "weapon"` defaults to `main_hand`, `kind = "armor"` to `torso`; other kinds have no default slot.
- Items are treated as fitting any race that has the slot (no size restriction).