> ## Documentation Index
> Fetch the complete documentation index at: https://docs.eucaengine.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Inventory & economy

> Give a unit gold and items, equip gear into named slots, and read back its inventory and equipment — built from generic item routes and the Gold component, end to end on a local server.

Most games need a unit that can **hold items, equip gear, and carry a currency**. Euca assembles that
from a few pieces of data on an entity — an `Inventory` (slots), `Equipment` (named slots), and `Gold` —
plus a global `ItemRegistry` that item definitions live in. The economy is the **`Gold` component**: you
spawn a unit with `gold`, and gold-on-kill systems pay out `GoldBounty` to killers; there is no separate
balance endpoint. This page outfits a unit end to end; every command is real and runnable against a
[local server](/quickstart), and the outputs below are captured from one.

<Note>
  The buy/sell **shop** (`/shop/buy`, `/shop/sell`, `/shop/list`) was a MOBA-only layer and has been
  removed — those routes 404. The generic inventory below is what remains: define items, give/equip them,
  and let the `Gold` economy run. A purchasing shop, if you want one, is a game-side system built on these
  primitives (as in the [MOBA example game](/systems/moba)).
</Note>

## Outfit a unit

**1. Spawn a unit with gold.** `gold` is a first-class component, returned by `/observe` and
`/entities/{id}`; spawning with `gold` also adds a `Level(1)`.

```bash theme={null}
curl -s -X POST http://localhost:3917/spawn -H 'Content-Type: application/json' \
  -d '{"health":600,"team":1,"gold":1000}'
# {"entity_id":1,"entity_generation":0}
```

**2. Define the items.** An item is an `id`, a `name`, and a `properties` map of named numbers. Items live
in one global registry, so you define them once.

```bash theme={null}
curl -s -X POST http://localhost:3917/item/define -H 'Content-Type: application/json' \
  -d '{"id":1,"name":"Iron Sword","properties":{"cost":500,"damage":10}}'
# {"ok":true,"message":"Defined item 1: Iron Sword"}

curl -s -X POST http://localhost:3917/item/define -H 'Content-Type: application/json' \
  -d '{"id":2,"name":"Health Potion","properties":{"cost":50,"heal":150}}'
# {"ok":true,"message":"Defined item 2: Health Potion"}
```

**3. Give and equip the sword.** `/item/give` drops it into the unit's inventory (auto-creating an
inventory if it has none); `/item/equip` moves it into a named slot.

```bash theme={null}
curl -s -X POST http://localhost:3917/item/give \
  -H 'Content-Type: application/json' -d '{"entity_id":1,"item_id":1,"count":1}'
# {"ok":true,"message":"Added 1 of item 1"}

curl -s -X POST http://localhost:3917/item/equip \
  -H 'Content-Type: application/json' -d '{"entity_id":1,"slot":"weapon","item_id":1}'
# {"ok":true,"message":"Equipped item 1 in slot 'weapon'"}
```

**4. Read the unit's inventory.** `/item/list/{entity_id}` returns the inventory, equipment, and an
aggregated `stat_modifiers` map. Equipment moves on the call; the equipped item now sits in the `weapon`
slot.

```bash theme={null}
curl -s http://localhost:3917/item/list/1
# {"entity_id":1,"inventory":[],
#  "equipment":[{"slot":"weapon","item_id":1,"name":"Iron Sword"}],
#  "stat_modifiers":{}}
```

## Behavior and gotchas

The things you only find out by running it:

* **The shop is gone; inventory is the generic layer.** `/shop/buy`, `/shop/sell`, and `/shop/list`
  return 404. There is no route to *list the global registry* either (that was `/shop/list`) — you list a
  unit's items with `/item/list/{entity_id}`, not the catalogue.
* **`/item/give` auto-creates the inventory.** A unit with no `Inventory` component gets one on the first
  give; you don't pre-create it.
* **Equipment moves immediately; `stat_modifiers` may stay empty.** `/item/equip` places the item in the
  slot on the call, but `stat_modifiers` is filled by a separate stat-aggregation system. In our run on the
  MOBA headless host, `stat_modifiers` remained `{}` even after stepping — read `equipment` to confirm the
  item moved, and treat the aggregated-stat read as a game-side behavior that the host you run may or may
  not schedule.
* **The economy is the `Gold` component, not a balance API.** Spawn with `gold`, award `gold_bounty` on
  kill (a `death` rule pays the killer), and read the current value off `/entities/{id}` or `/observe`.
  There is no deposit/withdraw endpoint.

## Endpoints

| Method | Path                     | Description                                                          |
| ------ | ------------------------ | -------------------------------------------------------------------- |
| `POST` | `/item/define`           | Register an item (`id`, `name`, `properties`) in the global registry |
| `POST` | `/item/give`             | Add items to a unit (auto-creates the inventory)                     |
| `POST` | `/item/equip`            | Move an inventory item into a named slot                             |
| `GET`  | `/item/list/{entity_id}` | A unit's inventory, equipment, and aggregated `stat_modifiers`       |

Currency rides on the `Gold` component — spawn with `--gold` and pay out `GoldBounty` on kill; see
[Units & roles](/systems/heroes) and [Gameplay & combat](/systems/gameplay-and-combat). A purchasing
shop with recipes lives in the [MOBA example game](/systems/moba) as a game-side system.

## Status

* **Shipped** — item definitions, slotted inventory (auto-created on give), equipment into named slots,
  and the `Gold` economy with kill bounties. All headless.
* **Game-side** — the buy/sell shop and recipe combining are systems a game owns, built on these
  inventory primitives; stat aggregation from equipped items is similarly a game-scheduled behavior (it
  did not populate on the MOBA headless host in our run).

<Card title="Item & inventory endpoints" icon="coins" href="/api-reference/introduction" horizontal>
  Every item, inventory, and equipment endpoint, with request and response schemas.
</Card>