Inventory & economy

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, and the outputs below are captured from one.

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

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

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.

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.

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.

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 and Gameplay & combat. A purchasing shop with recipes lives in the MOBA example game 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).

Item & inventory endpoints

Every item, inventory, and equipment endpoint, with request and response schemas.

Get started

Core concepts

Build a world

Simulate & play

Render & present

Experiment & verify

Platform & tools

Outfit a unit

Behavior and gotchas

Endpoints

Status

Item & inventory endpoints

​Outfit a unit

​Behavior and gotchas

​Endpoints

​Status

Item & inventory endpoints

Outfit a unit

Behavior and gotchas

Endpoints

Status