# Items, Weapons, and Equipment

## Purpose
This document describes how item content is structured across reusable weapon framework code, specialized equipment logic, and world spawn sources.

## Folder authority map
- Weapon framework: `Code/Items/Weapons/`
  - Core weapon component and modular weapon behaviors (input, recoil, reload, scope, throw, melee, ammo, grenades).
- Weapon data/resources: `Code/Items/Weapons/Data/`
  - `WeaponData` and equipment metadata for prefab, slot, economy, and legacy mapping.
- Specialized equipment: `Code/Items/Equipment/`
  - Role/utility behavior components (C4, scanner, body armor, magneto, flare, etc.).
- World spawn sources: `Code/World/MappingTools/Spawners/`
  - Mapper-authored weapon/ammo/grenade and legacy object spawn components.
- Marker primitives: `Code/Items/Markers/`
  - Marker model + registry used by UI marker feature.

## Core runtime flow
- Weapon instances are componentized and attach to player inventory.
- `PlayerInventory` (`Code/Players/Pawn/Inventory/PlayerInventory.cs`) owns add/remove/switch/drop behavior.
- Dropped world state is represented by dropped weapon/ammo components and network spawned by host authority.
- Equipment subfolders implement specialized mechanics on top of base weapon/input components.
- `IPressable` resolution for use/pickup now resolves nearest valid ancestor from trace hit (with descendant fallback), rather than assuming `GameObject.Root` is the interactable.
- Use distance checks for interactables are measured from the interactable object position, which avoids `MapNetworkRoot` parent-distance false negatives.
- Health station use range also measures from station object position (not `Root`) for map-root compatibility.

## Economy and shop metadata
- `WeaponData` provides:
  - slot/category identity,
  - buy-menu visibility/category/cost,
  - prefab references (`MainPrefab`, `ViewModelPrefab`),
  - legacy entity name bridging for map compatibility.

## Spawner and reset behavior
- Spawners generally implement reset capture/reset contracts (`IResettableSpawner`, `IResettable`) for round cleanup integration.
- Legacy map loader can convert legacy entities into modern dropped items/spawners.

## Related docs
- Player inventory/pawn flow: `Code/Core/Documentation/player-pawn.md`
- World reset/loader flow: `Code/Core/Documentation/world-runtime.md`
- Presentation/viewmodel flow: `Code/Core/Documentation/presentation-audit.md`

## Diagnostics
- Interaction diagnostics:
  - `t.db.use` logs trace hit, resolved pressable object, and use-distance checks.