Stage 3: inventory, ground loot, and two loot visibilities

Four always-on-screen slots, items as data, and loot tables on enemies and
bosses. Health potions drop rarely from trash and always from the Warden;
the Warden also drops a Warden's Ration, one per living player, which does
nothing at all.

The ration is not filler. Player-instanced loot is a separate code path from
shared loot -- a distinct entity per owner, filtered per peer in the snapshot
encoder -- and the cheapest way to keep that path honest is to have something
in the game that exercises it on every boss kill.

Item actions ride the input frame rather than becoming new client messages.
InputFrame gained BTN_USE, BTN_DROP and a slot byte, which buys the packet-loss
redundancy, the replay guard on last_input_tick, ordering against movement on
the same tick, and a rate limit of one action per tick -- all of which a
separate RPC would have needed bolted back on. The cost is that anything in
the frame which must not repeat has to be edge-triggered, since frames are
resent and a starved server coasts on the last one it holds.

Instanced loot is enforced in NetCodec.encode_snapshot, beside the actor
interest radius: a peer is never told another player's copy exists. Hiding it
client-side would have been the same mistake as relying on fog to hide enemies.

Inventories live on the character and are written to the store on every
transaction, so a crash between "picked it up" and "wrote it down" cannot lose
or duplicate an item. Anything dropped becomes world-shared whatever it was
before, and a potion used at full health is refused rather than spent.

tools/diag_loot.tscn covers drop -> snapshot -> pick up -> persist -> use ->
drop plus both visibilities on the wire, for the same reason diag_progression
exists: bots are poor shots and almost never produce a drop. It asserts each
input frame was actually consumed, after an early version silently dropped its
first press and every later check passed for the wrong reason.

check.sh clean, 266 tests, SMOKE PASS, all three diagnostics green.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

docs/ARCHITECTURE.md

@@ -124,6 +124,8 @@ after `--`:
 | `src/sim/map_grid.gd` | Tile grid: collision, line of sight, chunked streaming. |
 | `src/sim/map_gen.gd` | Dungeon generation. `build()` is the only entry point both sides use. |
 | `src/content/rooms.gd` | Hand-authored stamps: the hub and each boss arena, as text. |
+| `src/content/items.gd` | Every item. `Items.ORDER` doubles as the wire format. |
+| `src/sim/sim_loot.gd` | An item on the ground. World-shared, or owned by one peer. |
 | `src/meta/progression.gd` | XP curve and what a level is worth. Pure functions. |
 | `src/meta/character.gd`, `character_store.gd` | Characters and their JSON persistence. Server-owned. |
 | `src/meta/auth_provider.gd` | Identity, shaped like Steamworks so it swaps out. |

docs/ASSETS.md

@@ -103,3 +103,10 @@ in RAM and in export size.
 [`assets/README.md`](../assets/README.md). Art is Stage 2 in
 [ROADMAP.md](ROADMAP.md); everything currently on screen is drawn from
 primitives plus one runtime-generated dot texture.
+
+## Placeholder art worth revisiting
+
+- **Warden's Ration** draws as a gold flask (`Art.ITEM_ICONS[1]`). The 0x72
+  tileset has no food sprite, and the item is deliberately useless flavour, so a
+  recoloured flask stands in until the art pass. It reads as a potion, which is
+  the wrong thing for it to read as.

docs/DECISIONS.md

@@ -129,7 +129,7 @@ and troubleshooting — and the player picks another character or creates one.
 
 ---
 
-## Characters and progression *(this session)*
+## Characters and progression
 
 **Level 1 is base health; each level adds 10.** So level 15 is
 `PLAYER_MAX_HP + 14 * 10` = 240. Level is *derived* from lifetime experience
@@ -184,3 +184,68 @@ choice that cannot be taken.
 re-sent when the *set* of characters changes, so a bar fed from it moved only on
 level-up or a swap. The live total is four bytes on a message that already goes
 out at 20 Hz.
+
+---
+
+## Inventory and loot
+
+**Four slots, permanently on screen.** An inventory you have to open is a menu,
+and a menu is a death in a game where the floor is bullets. `INVENTORY_SLOTS` is
+one constant that the wire format, the save record and the HUD all read, so
+growing it is a one-line change — but not into a paged or scrolling UI.
+
+**Item actions ride the input frame rather than becoming new messages.**
+`InputFrame` gained `BTN_USE`, `BTN_DROP` and a slot byte. Using an item happens
+*during* a fight, so it has to be ordered against movement on the same tick and
+be as cheap to reject as a movement vector. Riding the existing stream gets the
+redundancy that covers a dropped packet, the replay guard on `last_input_tick`,
+and a rate limit of one action per tick for free. A separate reliable RPC would
+have needed every one of those bolted back on.
+
+**Item actions are edge-triggered; movement and fire are not.** The client
+resends its last few frames every tick and a starved server coasts on the last
+one it holds, so a level-triggered read would empty the whole inventory in four
+ticks. The *slot* is part of the edge as well — tapping 2 while 1 is still held
+is a second, distinct action rather than a swallowed one.
+
+**Loot has two visibilities, and the instanced one is enforced on the wire.**
+World-shared loot is one entity the first player to reach it takes.
+Player-instanced loot is one entity per eligible player, and a peer is never
+told the other copies exist — the filter lives in `NetCodec.encode_snapshot`
+beside the actor interest radius, not in the client. It is an
+interest-management rule, not a UI convention.
+
+**The Warden's Ration is useless on purpose.** It is dropped by every boss, one
+per player who was alive for the kill, and does nothing when used. Its job is to
+make sure the player-instanced path runs on every single boss kill instead of
+being a code path nothing exercises. If it ever gains an effect, that job needs
+a new holder.
+
+**Anything dropped becomes world-shared, whatever it was before.** An instanced
+trophy you do not want should be able to reach someone who does — otherwise
+"droppable" means nothing for half the items in the game.
+
+**A potion used at full health is refused, not spent.** Nobody drinks one on
+purpose at full health, so a mistimed keypress must not do it for them. The
+useless ration, by contrast, *is* consumed: "does nothing" has to mean a
+completed transaction or it proves nothing about the path it exists to test.
+
+**A full bag leaves the item on the floor.** Nothing is destroyed by a failed
+pickup, and the failure does not block the portal, which shares the interact
+key.
+
+**Inventories live on the character and are written on every transaction.**
+Not on a timer: a crash between "picked it up" and "wrote it down" must not be a
+way to lose an item, or — far worse — to duplicate one. They are stored as item
+*ids* rather than wire indices, so a save survives `Items.ORDER` being appended
+to, and an id this build does not know decays to an empty slot rather than to
+the wrong item.
+
+**Items do not stack.** One id per slot, no count, no charges. Everything the
+game currently needs fits that, and the wire format, the save record and the UI
+are all simpler for it. Add a count when something actually needs one.
+
+**Ground loot never expires; each world caps at `MAX_LOOT_PER_INSTANCE`,
+oldest evicted.** Dungeons close and take their litter with them, so only the
+hub — which never closes and where players can drop things — can realistically
+reach the cap.

docs/NETCODE.md

@@ -9,17 +9,26 @@ prediction and reconciliation for the local player.
 client                          server (60 Hz)
   |                               |
   |-- InputFrame (60 Hz, x3) ---->|  queue_input(): validate, drop, sort
-  |   move, aim, 3 button bits    |  SimWorld.step(): move, AI, emitters,
-  |                               |    integrate bullets, resolve hits
-  |<-- events (reliable, ch 3) ---|  bullet spawns/despawns, hits, deaths
-  |<-- snapshot (unrel., ch 2) ---|  players, enemies, boss @ 20 Hz
+  |   move, aim, 5 button bits,   |  SimWorld.step(): move, AI, emitters,
+  |   inventory slot              |    integrate bullets, resolve hits, items
+  |<-- events (reliable, ch 3) ---|  bullet spawns/despawns, hits, deaths,
+  |                               |    item pickups/uses/drops
+  |<-- snapshot (unrel., ch 2) ---|  players, enemies, boss, ground loot,
+  |                               |    your own inventory @ 20 Hz
   |                               |
   predict locally, reconcile      authoritative for everything
 ```
 
-The client has no message that expresses a position, a hit, damage taken, or a
-completed escape. This is deliberate and stronger than validating such messages
-after the fact: there is no code path to exploit, only intent to interpret.
+The client has no message that expresses a position, a hit, damage taken, a
+completed escape, or an item it now owns. This is deliberate and stronger than
+validating such messages after the fact: there is no code path to exploit, only
+intent to interpret.
+
+Item actions are worth noting as the newest thing to resist becoming a message
+of its own. Using or dropping an item is a request that reaches the server as
+two button bits and a slot number on the ordinary input frame, and the server
+decides what — if anything — happened. See *Item actions ride the input frame*
+below.
 
 ## Why bullets are not replicated as state
 
@@ -187,6 +196,50 @@ is invisible damage. The floor is *longest bullet travel + fog radius* — 1500
 from the live content, so adding a faster or longer-lived bullet fails a test
 rather than producing bullets that wink into existence.
 
+## Loot has two visibilities, and one of them is an interest rule
+
+Ground loot rides the snapshot rather than an event stream: items do not move,
+so re-sending them 20 times a second costs almost nothing and a lost packet
+costs nothing at all — which a spawn-once event could not claim.
+
+Each item is either **world-shared** (`SimLoot.owner_peer == 0`) or
+**player-instanced** (owned by exactly one peer). The instanced kind is filtered
+in `NetCodec.encode_snapshot`, next to the actor interest radius and for the
+same reason: a peer is never *told* that another player's copy exists, so a
+modified client has nothing to reveal. Hiding it in the UI would have been the
+same class of mistake as relying on fog to hide enemies.
+
+Two consequences:
+
+- **An instanced item leaves with its owner.** `SimWorld.remove_player` deletes
+  loot owned by the departing peer. Nobody else can see or take it, so leaving
+  it behind would be an invisible entity the instance carries until it closes.
+- **Anything dropped becomes world-shared**, whatever it was before. That is
+  what makes dropping worth having.
+
+The Warden's Ration exists to keep this path honest: it is dropped instanced on
+every boss kill, so the filter runs in every real fight rather than only in
+tests.
+
+## Item actions ride the input frame
+
+`InputFrame` carries `BTN_USE`, `BTN_DROP` and a slot byte (10 bytes total, up
+from 9). The alternative — a reliable `c_use_item(slot)` RPC — would have needed
+its own replay guard, its own rate limit, and its own ordering story against the
+movement on the same tick. The input stream already has all three.
+
+The one thing it does not give for free is edge detection. The client repeats
+its last few frames every tick (that redundancy is what covers a dropped packet)
+and a starved server coasts on the last frame it holds, so a level-triggered
+read would spend four items in four ticks. `SimPlayer.prev_buttons` and
+`prev_slot` hold the edge; the slot is part of it, so tapping 2 while 1 is still
+held is a second action rather than a swallowed one. Movement and fire stay
+level-triggered — holding them is exactly what you mean.
+
+Pickup shares `BTN_INTERACT` with the dungeon portal. Loot wins when both are in
+reach, but only on a tick where something was actually taken, so a full bag
+cannot leave a player standing on the portal unable to use it.
+
 ## No contact damage
 
 Nothing hurts you by touching it. Every threat is a bullet you can see and
@@ -222,6 +275,8 @@ transition, not a combat mechanic.
 | Input claiming the future | `f.tick > tick + INPUT_MAX_LEAD` |
 | Flood | queue capped at `INPUT_MAX_AGE`, oldest dropped |
 | Leaving the hub early after death | `RESPAWN_LOCKOUT_TICKS`, server-side |
+| Item action repeated by a held key | edge-triggered against `prev_buttons` / `prev_slot` |
+| Inventory slot index out of range | `SimPlayer.take_slot` answers "nothing" |
 
 The respawn lockout is worth calling out: the HUD disables its button for the
 same three seconds, but that is presentation. A client that ignores its own UI

docs/ROADMAP.md

@@ -20,14 +20,15 @@ What "everything passes" currently means. Numbers move; the shape does not.
 | Gate | Covers | Runtime |
 | --- | --- | --- |
 | `tools/check.sh` | every script parses and type-checks | ~5s |
-| `tools/test.sh` | 206 GUT tests, no SceneTree | ~3s |
-| `tools/smoke.sh` | 15 assertions over a real ENet socket: handshake, auth, character creation and persistence, portal, escape, hard kill, polite disconnect | ~40s |
+| `tools/test.sh` | 266 GUT tests, no SceneTree | ~3s |
+| `tools/smoke.sh` | 16 assertions over a real ENet socket: handshake, auth, character creation and persistence, portal, escape, hard kill, polite disconnect | ~40s |
 | `diag_prediction.tscn` | client-prediction gap, with injected clock drift | ~10s |
 | `diag_progression.tscn` | kill → xp → level → health, death → retire → roster, swap guards | ~10s |
+| `diag_loot.tscn` | drop → snapshot → pick up → persist → use → drop, and both loot visibilities on the wire | ~10s |
 
-The two diagnostics exist because the smoke test structurally cannot reach what
-they cover: bots are poor shots, and a listen server cannot drift its own clock
-against itself.
+The three diagnostics exist because the smoke test structurally cannot reach
+what they cover: bots are poor shots (so they neither level up nor produce
+drops), and a listen server cannot drift its own clock against itself.
 
 ---
 
@@ -119,39 +120,66 @@ path cannot be covered by the bot smoke test, because bots are poor shots.
 - `--account` and `--store` exist so several clients and test runs can coexist
   on one machine. A real provider makes `--account` unnecessary.
 
-## Stage 3 — Inventory and loot · *todo, next*
+## Stage 3 — Inventory and loot · *done*
 
-Nothing blocks this. The pieces it needs — accounts, characters, a server that
-owns per-player state — all exist.
-
-### Requirements
-
-| Feature | Decided | Notes |
+| Feature | State | Where |
 | --- | --- | --- |
-| Inventory, small enough to sit on screen permanently | **4 slots** | May grow later; do not build a paged or scrolling UI for it. |
-| Health potions | rare from normal enemies, **guaranteed from bosses** | The only item with an effect for now. |
-| World-shared loot | shared between all players in the instance | First to reach it takes it. |
-| A unique, useless food item from bosses | **player-instanced now** | Its whole purpose is to exercise the instanced-loot path rather than defer it. Always dropped by bosses, does nothing when used. |
-| Dropping items | any item, back into the world, pickable by others | The path that makes shared loot meaningful. |
+| 4 slots, permanently on screen | done | `SimConfig.INVENTORY_SLOTS`, `HUD._draw_inventory` |
+| Items defined as data, not code | done | [src/content/items.gd](../src/content/items.gd), [src/actors/items/item_def.gd](../src/actors/items/item_def.gd) |
+| Loot tables on enemies and bosses | done | `EnemyDef.loot` / `BossDef.loot`, rolled in `SimWorld._drop_loot` |
+| Health potion, rare from trash | done | `Content.TRASH_POTION_CHANCE` = 0.08 |
+| …guaranteed from the boss | done | `Content.warden()` loot table, chance 1.0 |
+| World-shared loot | done | `SimLoot.owner_peer == 0` |
+| Player-instanced loot | done | one `SimLoot` per living player, filtered per peer in `NetCodec.encode_snapshot` |
+| Warden's Ration — useless, instanced | done | `Items.wardens_ration()` |
+| Pick up, use, drop | done | `SimWorld._try_pickup` / `_use_slot` / `_drop_slot` |
+| Inventories persist | done | stored on `Character`, written by `ServerRuntime._persist_inventory` |
+| Ground loot drawn with a pickup prompt | done | `WorldView._draw_loot`, `HUD._draw_pickup_prompt` |
 
-### What this implies
+Controls: **E** picks up, **1–4** use a slot, **shift+1–4** drop one.
 
-Two loot *visibilities* have to exist from the start, because the food item is
-specifically there to prove the second one works:
+### The decisions worth knowing before touching this
 
-- **World-shared:** one entity in the instance, visible to everyone, gone when
-  anyone picks it up.
-- **Player-instanced:** one entity per eligible player, each seeing and taking
-  only their own. Others must not see it, which makes it an interest-management
-  question as much as a loot one — see `ACTOR_INTEREST_RADIUS` and how the
-  snapshot is already encoded per peer.
+**Item actions ride the input frame; they are not new messages.** `InputFrame`
+gained `BTN_USE`, `BTN_DROP` and a slot byte. That buys the redundancy that
+covers a dropped packet, the replay guard on `last_input_tick`, ordering against
+movement on the same tick, and a natural rate limit of one action per tick — all
+of which a separate reliable RPC would have needed bolted back on.
 
-Server owns all of it: the client sends "I want to pick that up" as intent and
-learns the outcome. There is no message that grants an item.
+**Item actions are edge-triggered; movement and fire are not.** The client
+repeats its last few frames every tick and a starved server coasts on the last
+one it was given, so a level-triggered read empties the whole inventory in four
+ticks. `SimPlayer.prev_buttons` and `prev_slot` hold the edge, and the *slot* is
+part of it — tapping 2 while 1 is held is a second, distinct action.
 
-Persistence is an open question — inventories are not in `CharacterStore` yet,
-and a potion that vanishes on server restart may or may not matter at this
-stage.
+**Instanced loot is enforced on the wire, not in the client.** A peer is never
+told another player's copy exists. That makes it an interest-management rule of
+the same kind as `ACTOR_INTEREST_RADIUS`, and it is why the ration is worth
+having: every boss kill exercises the path.
+
+**Anything dropped becomes world-shared, even if it arrived instanced.** That is
+what makes dropping worth having — a trophy you do not want should be able to
+reach someone who does.
+
+**A potion at full health is refused rather than spent.** Nobody drinks one on
+purpose at full health, so a mistimed keypress must not do it for them.
+
+**A full bag leaves the item on the floor** and does not block the portal, which
+shares the interact key.
+
+### Known gaps
+
+- **Nothing sells items.** Loot only comes from kills; the hub has no source.
+  The Stage 4 upgrade NPC is the natural place, and is the reason this is a gap
+  rather than a decision.
+- **No stacking.** Four potions take four slots. A count byte per slot is cheap
+  to add; nothing needed it yet, so the wire, the save record and the HUD all
+  stayed simpler for not having one.
+- **Ground loot never expires**, it is only capped at
+  `SimConfig.MAX_LOOT_PER_INSTANCE` per world, oldest evicted. Dungeons close
+  and take their litter with them; only the hub can realistically reach the cap.
+- **The ration draws as a gold flask.** The tileset has no food sprite. See
+  [ASSETS.md](ASSETS.md).
 
 ---
 
@@ -264,8 +292,12 @@ several have no obvious default.
 
 8. **What advances dungeon depth?** `--depth` is a dev flag; nothing raises it
    in play. Depth drives map size and could drive difficulty and rewards.
-9. **Do inventories persist?** Characters do. A potion surviving a server
-   restart may or may not matter at this stage.
-10. **Attribution for four asset packs.** See [ASSETS.md](ASSETS.md) — two are
+9. **Where do items come from outside a dungeon?** Loot only drops from kills.
+   If the hub should sell potions, that is the Stage 4 NPC's second job — and
+   it needs a currency, which the game does not have.
+10. **Should items stack?** Four potions currently take four slots, which makes
+    a 4-slot bag small. Stacking is a count byte per slot plus a rule for
+    splitting one; neither is hard, but both change the UI.
+11. **Attribution for four asset packs.** See [ASSETS.md](ASSETS.md) — two are
     non-redistributable and local-only, and there is no in-game credits screen
     yet, which CC BY 4.0 requires for the audio.