Items and inventory

Feather’s item system is generic enough for any game. Your project defines its own item categories and equipment slots, and items carry whatever custom properties your game needs — weight, rarity, durability, a recipe. The player’s bag can be limited by count or by a summed property such as weight. Consumables heal and cure statuses, equipment protects against damage kinds, and tools cast elements where the player aims.

Items in the world are picked up with Interact. Containers — chests, stashes, shops — hold items too. The inventory, container and status screens are UI templates, so you can restyle them.

What’s included

• An item library with ready-made presets: apple, potion, antidote, wood, gem, key, flame_tunic, rubber_cloak, snow_boots, iron_helm, fire_rod, torch, ice_rod, storm_rod, water_flask, oil_flask, shovel, earth_staff, leveller and smoke_bomb.
• Categories and equipment slots you name yourself.
• Consumables, equipment with resistances and status immunity, and tools that cast elements, spill liquids, reshape the ground or burst into smoke.
• Starting items, a carry limit by item count or by a property, and an on-screen status bar.
• Pickup and container components for scene objects.
• A spreadsheet-style Item manager with JSON import and export.

Create items

1. Open Window → World & terrain and select the Items tab.
2. Under Item library, start from a preset or create an item, then edit its fields and custom properties.
3. Under Inventory, set the key that opens the screen, the carry limits, your categories and equipment slots, and the items the player starts with.
4. To edit many items at once, open Window → Item manager. It shows every item as a sortable, searchable table with a column per custom property, and imports and exports JSON.

Item fields

Field	Description	Default
id	Stable ID used by pickups, doors, scripts and saves	—
name, description	Shown on the inventory screen	—
category	One of the project’s categories	Materials
stack	Most in one stack, and in one bag, 1–9999	99
value	Worth, for shops and scripts	0
icon	A Phosphor icon name, such as apple, key, sword or flask	package
color	Icon colour	—
heal	Health restored when used, 0–100,000	0
cures	Statuses it ends: burning, wet, shocked, chilled	None
consumed	Using it uses one up	Off
slot	Equipment slot it is worn in	None
resist	Damage multiplier per damage kind while worn, 0–10; 0 is immune, and the lowest worn value wins	None
immune	Statuses it keeps off while worn	None
properties	Any custom data: weight, rarity, damage…	None
cast	Makes the item a tool; see below	None

Tools

While a tool is worn, the Use tool action (C) casts it where the player aims: a fire rod lights the grass, a torch sets what it touches alight, a water flask puts fires out.

Field	Description	Default
kind	Damage kind: physical, blunt, explosive, fire, electric, ice or water	fire
amount, radius	Damage at the centre and its reach, 0.1–30 m	12, 1.5 m
range	Distance from the camera, 0.5–200 m	20 m
cooldown	Seconds between uses, 0–60	0.6 s
ammo	An item each use costs	None
effect, sound	Played where it lands	None
fluid, fluid_volume	A liquid spilled where it lands, up to 100 m³	None
terrain, terrain_depth	dig, raise, flatten or smooth the ground, up to 10 m	none, 0.5 m
smoke	Diameter of a smoke cloud where it lands, up to 15 m	0

See Combat for damage kinds and statuses.

Inventory settings

Field	Description	Range	Default
enabled	The inventory screen and HUD	On/off	On
key	Opens and closes the screen	Key name	Tab
start	Items the player starts with, {id: count}	1–9999 each	None
capacity	Different items the player can carry; 0 is no limit	0–10,000	0
limit	Caps a summed property, {property, max}, such as weight	—	None
status_bar	Health and statuses on screen	On/off	On
categories	Your categories, in screen order	Up to 32	Materials, Food, Potions, Keys, Weapons, Armor, Accessories, Quest
equip_slots	Your equipment slots, one item each	Up to 16	head, body, legs, hands, weapon, shield, accessory

Rename a category or slot with inventory.rename and every item using it follows.

Pickups and containers

To place an item in the world:

1. Select an object and choose Details → Add Component → Pickup.
2. Choose the Item and Count. Leave Prompt empty to show “Pick up” and the item name.
3. In Play, the player presses Interact to take it, and the object disappears.

To add a chest or stash:

1. Choose Details → Add Component → Container.
2. Set the Title (empty uses the object’s name), the Prompt (default “Open”) and the number of different items it can hold (0 is any).
3. Under Inside, choose Put an item in to add starting contents.

A door can be locked with an item, such as a key; see Interaction. What everyone carries is kept in saves.

Extend it

Function	Description
give_item(id[, count])	Adds items; returns how many fit
take_item(id[, count])	Removes items; returns whether the player had them
item_count(id), has_item(id)	What the player carries
use_item(id)	Eats, drinks or wears an item
equip_item(id), unequip_item(slot), equipped(slot)	Equipment
inventory()	The player’s items as a map
carried_total(property)	Sum of a property across the bag, such as weight
item_info(id), item_property(id, key)	Item data and custom properties
items_in_category(category)	Item IDs in a category
open_inventory(), close_inventory()	Show or hide the inventory screen
give_to(bag, id, count), take_from(bag, id, count)	Change a container’s contents
move_item(from, to, id, count)	Moves items between bags; "player" is the player
bag_items(bag)	A container’s contents as a map
open_container(bag, title), close_container()	Show a container screen

A container placed in a level is the bag "object:<id>". Any other name creates a bag for a shop or a stash.

Hook	Runs when
on_item(id, count)	The player gains or loses an item; count is how many they have now
on_use_item(id)	The player uses an item
on_equip(slot, id)	The player wears an item; id is empty when the slot is emptied

// A world script: a shop. Object 12, the trader, has an interaction prompt.
fn start() {
    give_to("trader", "potion", 5);
    give_to("trader", "torch", 2);
}

fn on_interact(id) {
    if id == "12" {
        open_container("trader", "Trader");
    }
}

Limits

• Up to 32 categories and 16 equipment slots, each 1–32 characters.
• An item can’t be removed while a pickup or locked door uses it.
• item.batch changes up to 5,000 items in one undo step.

Automate it

# A healing herb from the potion preset
feather-cli --connect .feather-session.json command item.upsert \
  --json '{"preset":"potion","value":{"id":"herb","name":"Healing herb","heal":15,"properties":{"weight":0.1}}}'

# A 30 kg weight limit and a starting kit
feather-cli --connect .feather-session.json command inventory.set \
  --json '{"patch":{"limit":{"property":"weight","max":30},"start":{"herb":3,"torch":1}}}'

# Turn object 12 into a pickup for two herbs
feather-cli --connect .feather-session.json command scene.update \
  --json '{"id":12,"patch":{"pickup":{"item":"herb","count":2}}}'

item.get returns the library, the presets, which pickups and doors use each item, and the categories and slots. item.batch imports a whole table in one validated step.