Inventory

The key words MUST, MUST NOT, and MAY below are used as in RFC 2119.

The Inventory autoload holds the active character's carried items as an ordered item_id → quantity map. Insertion order is pickup order; the player MAY re-sort by category (one-shot, or auto on every pickup). The bank (GameState.shared_storage) is shared across characters — see Storage.

Slots & capacity

• The inventory holds 40 slots. Adding past the cap MUST fail (and play the error cue), not silently drop the item.
• Stackable items (consumables, materials, modifiers) occupy one slot per stack, capped by the item's max stack.
• Per-slot items (weapons, armor, units, mags, technique disks) take one slot each and every one gets its own unique instance id (e.g. ein_saber#3). Two items with identical stats are still two distinct items.
• Equipped gear MUST NOT be deposited or sold until unequipped.

Parsing per-slot instance ids

An instance id is a storage / equip / consume reference only. Any code that derives a per-slot item's base type — or any field embedded in the base id (a disk's technique and level, a weapon's base type) — MUST first strip the instance suffix via Inventory.get_base_id(). Parsing the raw instance id (disk_foie_3#2) for an embedded field is a bug: int("3#2") evaluates to 32 (Godot's int() concatenates the digits across the # — it does not truncate at it), so a duplicate disk would be read as Lv.32 and rejected as over the class cap.

• Buying N copies of a learnable technique disk MUST yield N independently usable copies. Each copy MUST learn/upgrade the technique to the same level as the first — a duplicate is never "greyed out" or rejected for being a later instance.
• The displayed Teaches <tech> Lv.<n> line MUST NOT contain the #-suffix (it reads Lv.3, never Lv.3#2).
• Consuming a disk MUST remove the exact instance the player selected (remove_item keeps the full instance id), not an arbitrary base-id copy.

This generalizes the same get_base_id rule already required for category sorting and the unlearnable-disk ✕ marker (see equip-legality) to the use/parse path; it does not contradict the per-slot instance-id text above.

Equipping gear

Gear is equipped from the equipment screen; each equip slot (weapon, armor frame, one unit slot per the equipped frame instance's own unit-slot count, mag) holds at most one item, referenced by its instance id.

• Every frame is its own item. Two frames of the same base type are two different frames, each with its own instance id (frame, frame#2, …), and each MUST behave as a full, equal item — same DEF/EVA, same base type. The player MAY equip any of them — equipping is by the item's own id, never by stat profile or base type. Buy three frames of the same type and the player MUST be able to equip whichever they choose, interchangeably. (This already holds for weapons; it MUST hold equally for armor, units, and mags.)
• Unit slots are a per-instance property. Each armor instance has its own unit-slot count, rolled 0–4 (universal cap 4) when the instance is created and fixed thereafter — so two frames of the same base type MAY differ in how many units they hold. The count is recorded per instance id (in armor_slots); the armor resource's max_slots is only the generator/cap and the fallback for instances with no recorded roll (starter gear, legacy saves). Every display and equip surface MUST read the instance's own count, never the resource's max_slots as a fixed value. The weapon shop deliberately skews toward low-slot rolls (weighted 0→35%, 1→30%, 2→10%, 3→20%, 4→5%): high-slot armor is rare by design, steering players to field drops and crafting for the best gear.
• Changing the frame clears every equipped unit. Whenever the equipped frame changes to a different item, all currently-equipped units MUST be unequipped — even when the new frame has the same number of unit slots, or more. Example: equip a 3-slot frame, fill all three unit slots, then equip a different 3-slot frame → all three units are unequipped, and the player re-slots them into the new frame. Re-selecting the frame that is already equipped MUST be a no-op (its units are retained).

Stack limits

Stackable max stack is data-defined (data/consumables/*.tres etc.); the default is 10.

Consumable effects

Using a consumable MUST consume exactly one and apply its effect. Healing items are no-ops (and MUST NOT be consumed) when the relevant gauge is already full.

Bank / storage

Deposit moves items from the 40-slot inventory into the shared bank; withdraw moves them back, clamped by stack room. The bank is presently uncapped (PSO's 200-item bank is the canonical target, to be decided). Full deposit/withdraw flow lives in Storage.

← Mechanics