# BPC_KeyItemSystem — Key Item System

**Parent Class:** `ActorComponent`
**Category:** Inventory
**Target UE Version:** 5.5–5.7
**Build Phase:** 3 — Inventory

## 1. Overview

`BPC_KeyItemSystem` manages key items — story-critical objects that unlock doors, trigger narrative events, or are required for puzzle completion. Tracks acquired keys, provides query for door/puzzle unlock checks, and supports key usage notifications.

## 2. Variables

| Variable | Type | Description |
|----------|------|-------------|
| `AcquiredKeys` | `TArray<FGameplayTag>` | Tags of all acquired key items |
| `bShowKeyNotifications` | `bool` | Toast on key pickup |
| `KeyItemCategory` | `E_ItemCategory` | KeyItem category filter |

## 3. Functions

| Function | Description |
|----------|-------------|
| `HasKey` | Checks if player has a specific key by tag |
| `AddKey` | Registers a key item acquisition |
| `RemoveKey` | Removes a key (if consumed) |
| `GetAllKeys` | Returns all acquired key tags |
| `CanUnlock` | Checks if player meets unlock requirements for a target |

## 4. Event Dispatchers

| Dispatcher | Payload | Description |
|------------|---------|-------------|
| `OnKeyAcquired` | `FGameplayTag KeyTag` | New key picked up |
| `OnKeyUsed` | `FGameplayTag KeyTag`, `AActor* Target` | Key used on target |
| `OnKeyRemoved` | `FGameplayTag KeyTag` | Key consumed/removed |

## 5. Dependencies

| System | Relationship |
|--------|--------------|
| `BPC_InventorySystem` | Keys as inventory items |
| `BP_DoorActor` | Door unlock queries |
| `BP_PuzzleDeviceActor` | Puzzle unlock gates |
| `BPC_NarrativeStateSystem` | Key-based narrative flags |

## 6. Reuse Notes
- Keys use gameplay tags for generic matching (any key with same tag works)
- Supports consumable keys (removed after single use) and persistent keys