# I_InterfaceLibrary — Interface Collection

> **⚡ C++ Status: Full Implementation** — All 9 interfaces (`I_Interactable`, `I_Damageable`, `I_Persistable`, `I_Lockable`, `I_Holdable`, `I_UsableItem`, `I_Toggleable`, `I_Adjustable`, `I_Inspectable`) are defined in C++ at `Source/PG_Framework/Public/Core/I_InterfaceLibrary.h` as `BlueprintNativeEvent`. **Do NOT create Blueprint Interface assets.** On any BP actor: Class Settings → Interfaces → Add → type the interface name (e.g., `UInteractable`). Compile, and the interface events appear in your Event Graph. The spec below documents each interface's functions and purpose for reference. See `docs/developer/cpp-integration-guide.md`.
>
> ---

## Overview

This document defines all **9 Blueprint Interfaces** that form the backbone of cross-system communication in the framework. Interfaces are the **preferred communication method** over direct references — they decouple the caller from the callee's concrete class. Any Actor or Component can implement any of these interfaces, and any system can query for them and call them without knowing the underlying type.

## Folder Structure

All interfaces are placed in: [`Framework/Interfaces/`]

| Interface | File | Purpose |
|-----------|------|---------|
| [`I_Interactable`] | I_Interactable | Primary interaction entry point |
| [`I_Inspectable`] | I_Inspectable | Inspection/Examine system |
| [`I_Damageable`] | I_Damageable | Health, damage, death |
| [`I_Holdable`] | I_Holdable | Two-hand hold / use in hand |
| [`I_Lockable`] | I_Lockable | Lock/Unlock with key checks |
| [`I_UsableItem`] | I_UsableItem | Consumable/equippable item usage |
| [`I_Persistable`] | I_Persistable | Save/Load serialization contract |
| [`I_Toggleable`] | I_Toggleable | On/Off, Open/Close state machines |
| [`I_Adjustable`] | I_Adjustable | Continuous adjustment (pressure, dials) |

## Dependency Table

Each interface is independent. None inherit from another. A single actor can implement multiple interfaces (e.g. a door implements [`I_Interactable`], [`I_Toggleable`], [`I_Persistable`]).

---

## I_Interactable

### Asset Details

| Property | Value |
|----------|-------|
| **Class** | [`I_Interactable`] |
| **Type** | Blueprint Interface |
| **Folder** | [`Framework/Interfaces/`] |
| **Category** | Interaction |

### Purpose

The primary interaction entry point. Any object the player can look at and press a button to interact with must implement this interface. It is the single point of contact for the interaction system.

### Functions

| Function | Inputs | Outputs | Description |
|----------|--------|---------|-------------|
| [`OnInteract`] | `Instigator: Actor` | `bSuccess: Bool` | Called when the player presses the interact button. Returns false if interaction failed. |
| [`OnFocusBegin`] | `Instigator: Actor` | — | Called when the crosshair hovers over the object. Used to show UI prompts. |
| [`OnFocusEnd`] | `Instigator: Actor` | — | Called when the crosshair leaves the object. Hides UI prompt. |
| [`GetInteractionPrompt`] | — | `PromptText: Text` | Returns the text to display on the interaction HUD (e.g. "Press E to Open"). |
| [`CanInteract`] | `Instigator: Actor` | `bCanInteract: Bool`, `BlockReason: Text` | Query if interaction is currently possible. `BlockReason` provides a why-not string for UI feedback. |
| [`GetInteractionType`] | — | `InteractionType: E_InteractionType` | Returns the type of interaction (see enum below). |

### Enums

| Enum | Values | Description |
|------|--------|-------------|
| `E_InteractionType` | `None`, `Pickup`, `Use`, `Examine`, `Talk`, `Open`, `Push`, `Pull`, `Custom` | Categorizes the interaction for UI icon and animation selection. |

### Blueprint Flow

```
[Player presses E]
  └─► PC_CoreController calls OnInteract on target actor
  └─► Target implements I_Interactable
  └─► Returns bSuccess
  └─► If false, PC plays "Blocked" feedback sound
```

### Communicates With

| Target | Direction | Why |
|--------|-----------|-----|
| [`PC_CoreController`](../02-player/01_PC_CoreController.md) | Called by | Interaction trace calls these functions |
| [`BPC_InteractionDetector`](../03-interaction/01_BPC_InteractionDetector.md) | Called by | Focus events are driven by the detector component |
| [`WBP_InteractionPrompt`](../05-ui/02_WBP_InteractionPrompt.md) | Consumed by | Reads `GetInteractionPrompt` and `GetInteractionType` for UI display |

---

## I_Inspectable

### Asset Details

| Property | Value |
|----------|-------|
| **Class** | [`I_Inspectable`] |
| **Type** | Blueprint Interface |
| **Folder** | [`Framework/Interfaces/`] |
| **Category** | Interaction |

### Purpose

Controls the **inspection/examine** system. Objects that can be picked up and rotated in front of the camera for close examination implement this.

### Functions

| Function | Inputs | Outputs | Description |
|----------|--------|---------|-------------|
| [`StartInspect`] | `Instigator: Actor` | `bSuccess: Bool` | Begins inspection mode. Returns false if inspection not possible. |
| [`EndInspect`] | `Instigator: Actor` | — | Ends inspection mode. |
| [`RotateInspect`] | `DeltaRotation: Rotator` | — | Applies incremental rotation while in inspection mode. |
| [`GetInspectData`] | — | `InspectData: F_InspectData` | Returns struct with inspect-relevant data. |
| [`HasInspectInfo`] | — | `bHasInfo: Bool` | Whether this object has additional inspectable lore/text. |

### Structs

| Struct | Fields |
|--------|--------|
| `F_InspectData` | `InspectDuration: Float`, `bCanRotate: Bool`, `bHasAudioLog: Bool`, `InspectSound: SoundBase` |

### Blueprint Flow

```
[Player holds E to inspect]
  └─► PC calls StartInspect
  └─► Object spawns inspect proxy or enters inspect mode
  └─► Player drags mouse → RotateInspect
  └─► Player releases → EndInspect
```

---

## I_Damageable

### Asset Details

| Property | Value |
|----------|-------|
| **Class** | [`I_Damageable`] |
| **Type** | Blueprint Interface |
| **Folder** | [`Framework/Interfaces/`] |
| **Category** | Combat |

### Purpose

Any actor that can take damage, heal, or die implements this interface. This includes the player character, enemies, destructibles, and breakable environmental objects.

### Functions

| Function | Inputs | Outputs | Description |
|----------|--------|---------|-------------|
| [`TakeDamage`] | `DamageAmount: Float`, `DamageType: F_GameplayTag`, `Instigator: Actor`, `SourceLocation: Vector` | `bSuccess: Bool` | Applies damage to the actor. Returns false if immune. |
| [`Heal`] | `HealAmount: Float`, `HealType: F_GameplayTag` | `bSuccess: Bool` | Heals the actor. |
| [`IsAlive`] | — | `bIsAlive: Bool` | Whether the actor is alive or destroyed. |
| [`GetMaxHealth`] | — | `MaxHealth: Float` | Returns the maximum health value. |
| [`GetCurrentHealth`] | — | `CurrentHealth: Float` | Returns the current health value. |
| [`OnDeath`] | `Instigator: Actor`, `DamageType: F_GameplayTag` | `bSuccess: Bool` | Called when health reaches zero. Handles death logic. |
| [`GetDamageModifier`] | `DamageType: F_GameplayTag` | `DamageMultiplier: Float` | Returns damage multiplier for a given damage type. |

### Enums

No enums. Damage types are handled via gameplay tags.

### Communicates With

| Target | Direction | Why |
|--------|-----------|-----|
| [`BPC_HealthComponent`](../07-weapons/01_BPC_HealthComponent.md) | Implements | The health component implements this interface |
| Any weapon/damage source | Calls | Calls `TakeDamage` when hitting a target |

---

## I_Holdable

### Asset Details

| Property | Value |
|----------|-------|
| **Class** | [`I_Holdable`] |
| **Type** | Blueprint Interface |
| **Folder** | [`Framework/Interfaces/`] |
| **Category** | Interaction |

### Purpose

Objects that can be grabbed and held in the player's hands (two-hand hold system). Used for puzzles where objects must be carried and placed.

### Functions

| Function | Inputs | Outputs | Description |
|----------|--------|---------|-------------|
| [`OnPickup`] | `Holder: Actor` | `bSuccess: Bool` | Called when the player picks up the object. |
| [`OnDrop`] | `Holder: Actor` | — | Called when the player drops the object. |
| [`GetHoldTransform`] | — | `HoldLocation: Transform` | Returns the relative transform where the object should be held. |
| [`IsHeld`] | — | `bIsHeld: Bool` | Whether the object is currently being held. |
| [`OnReleasedFromHold`] | `NewLocation: Vector` | — | Called when the object is released (thrown or placed). |

---

## I_Lockable

### Asset Details

| Property | Value |
|----------|-------|
| **Class** | [`I_Lockable`] |
| **Type** | Blueprint Interface |
| **Folder** | [`Framework/Interfaces/`] |
| **Category** | Interaction |

### Purpose

Doors, drawers, containers, and any object that can be locked/unlocked with a key item or puzzle solution.

### Functions

| Function | Inputs | Outputs | Description |
|----------|--------|---------|-------------|
| [`TryLock`] | `LockingItem: Actor` | `bSuccess: Bool` | Attempt to lock the object with a specific item. |
| [`TryUnlock`] | `KeyItem: Actor` | `bSuccess: Bool` | Attempt to unlock with a key item. |
| [`IsLocked`] | — | `bIsLocked: Bool` | Whether the object is currently locked. |
| [`GetRequiredKeyTag`] | — | `RequiredTag: F_GameplayTag` | Returns the gameplay tag of the required key/item. |
| [`OnLockStateChanged`] | `bNewLocked: Bool` | — | Event dispatcher-style notification (implemented via dispatchers in the actor). |

### Communicates With

| Target | Direction | Why |
|--------|-----------|-----|
| [`BPC_InventoryComponent`](../04-inventory/01_BPC_InventoryComponent.md) | Calls | Checks if the player has the required key tag |
| [`BP_DoorBase`](../03-interaction/02_BP_DoorBase.md) | Implements | Doors use this interface |

---

## I_UsableItem

### Asset Details

| Property | Value |
|----------|-------|
| **Class** | [`I_UsableItem`] |
| **Type** | Blueprint Interface |
| **Folder** | [`Framework/Interfaces/`] |
| **Category** | Inventory |

### Purpose

Consumable and usable inventory items (health packs, batteries, keys, quest items). Items implement this to define what happens when used from the inventory screen or hotbar.

### Functions

| Function | Inputs | Outputs | Description |
|----------|--------|---------|-------------|
| [`UseItem`] | `User: Actor` | `bConsumed: Bool` | Called when the player uses the item from inventory. Returns true if item should be consumed. |
| [`CanUseItem`] | `User: Actor` | `bCanUse: Bool`, `BlockReason: Text` | Whether the item can currently be used. |
| [`GetUseDuration`] | — | `Duration: Float` | How long the "use" action takes in seconds. |
| [`OnItemUsed`] | `User: Actor` | — | Broadcast event after item is used successfully. |

---

## I_Persistable

### Asset Details

| Property | Value |
|----------|-------|
| **Class** | [`I_Persistable`] |
| **Type** | Blueprint Interface |
| **Folder** | [`Framework/Interfaces/`] |
| **Category** | Save System |

### Purpose

**Save-System Awareness** contract. Every actor that needs to persist state (position, health, inventory contents, lock state, narrative flags) must implement this interface. The save system scans the world for `I_Persistable` implementors and calls these functions.

### Functions

| Function | Inputs | Outputs | Description |
|----------|--------|---------|-------------|
| [`OnSave`] | — | `SaveData: F_GameplayTagContainer` | Returns the actor's state as a tag container for serialization. |
| [`OnLoad`] | `SaveData: F_GameplayTagContainer` | `bSuccess: Bool` | Restores actor state from saved data. Returns false if load failed. |
| [`GetSaveTag`] | — | `SaveTag: F_GameplayTag` | Returns a unique gameplay tag identifying this actor for save/load lookup. |
| [`NeedsSave`] | — | `bNeedsSave: Bool` | Whether this actor currently has unsaved changes. |

### Blueprint Flow

```
[AutoSave Triggered]
  └─► SS_SaveSystem/GS iterates all I_Persistable actors
  └─► Calls GetSaveTag for unique ID
  └─► Calls OnSave to get state data
  └─► Serializes tag + data to save file

[Game Loaded]
  └─► SS_SaveSystem reads save file
  └─► Finds actors by GetSaveTag
  └─► Calls OnLoad with saved data
```

### Communicates With

| Target | Direction | Why |
|--------|-----------|-----|
| [`SS_SaveSystem`](../04-save/02_SS_SaveSystem.md) | Called by | Save system iterates and invokes |
| [`GS_CoreGameState`](06_GS_CoreGameState.md) | Called by | GameState can trigger save sweeps |
| Any world actor | Implements | Doors, items, enemies, narrative triggers |

---

## I_Toggleable

### Asset Details

| Property | Value |
|----------|-------|
| **Class** | [`I_Toggleable`] |
| **Type** | Blueprint Interface |
| **Folder** | [`Framework/Interfaces/`] |
| **Category** | Interaction |

### Purpose

Objects with binary states: on/off, open/closed, active/inactive. Lights, doors, buttons, switches, and machines implement this interface.

### Functions

| Function | Inputs | Outputs | Description |
|----------|--------|---------|-------------|
| [`Toggle`] | `Instigator: Actor` | `bNewState: Bool` | Toggles the object to its opposite state. Returns the new state. |
| [`SetState`] | `Instigator: Actor`, `bNewState: Bool` | `bSuccess: Bool` | Sets the object to a specific state. |
| [`GetCurrentState`] | — | `bState: Bool` | Returns the current state. |
| [`GetStateLabel`] | — | `StateText: Text` | Human-readable label for the current state (e.g. "Open" / "Closed"). |
| [`OnStateChanged`] | `bNewState: Bool`, `Instigator: Actor` | — | Event dispatched when state changes (for animation/delegation). |

---

## I_Adjustable

### Asset Details

| Property | Value |
|----------|-------|
| **Class** | [`I_Adjustable`] |
| **Type** | Blueprint Interface |
| **Folder** | [`Framework/Interfaces/`] |
| **Category** | Interaction |

### Purpose

Objects with continuous adjustment values rather than binary states. Pressure valves, dials, sliders, tuning knobs, and analog controls.

### Functions

| Function | Inputs | Outputs | Description |
|----------|--------|---------|-------------|
| [`Adjust`] | `Delta: Float`, `Instigator: Actor` | `bSuccess: Bool` | Adjusts the value by delta. Positive = increase, negative = decrease. |
| [`SetValue`] | `NewValue: Float`, `Instigator: Actor` | `bSuccess: Bool` | Sets the value directly. |
| [`GetCurrentValue`] | — | `CurrentValue: Float` | Returns current value. |
| [`GetMinValue`] | — | `MinValue: Float` | Minimum allowed value. |
| [`GetMaxValue`] | — | `MaxValue: Float` | Maximum allowed value. |
| [`OnValueChanged`] | `NewValue: Float`, `Instigator: Actor` | — | Event dispatched when value changes (for visual/audio feedback). |

---

## Communication Overview

```
┌──────────────────────────────────────────────────────────┐
│                     Any Blueprint                        │
│  (Player Controller, Widget, AI, Level Blueprint, etc.) │
└──────────┬───────────────────────────────────────────────┘
           │ Calls Interface Function
           ▼
┌──────────────────────┐
│  Interface Function  │  (e.g. OnInteract, Toggle, TakeDamage)
└──────────┬───────────┘
           │ Dispatched to implementor
           ▼
┌────────────────────────────────────┐
│  Actor / Component implementing   │
│  the interface                     │
│  (e.g. BP_DoorBase, BP_HealthPack)│
└────────────────────────────────────┘
           │
           │ May call back to other systems
           ▼
┌──────────────────────────────┐
│  Other systems via interface │
│  or event dispatcher         │
└──────────────────────────────┘
```

## Reuse Notes

- All interfaces are minimal — each function has a single clear responsibility.
- Implementors should **never** call interface functions on themselves. Callers should always query for the interface using `Does Implement Interface` or `Cast to Interface` nodes.
- New interfaces should be added here by following the same pattern: define functions, default return values (typically `false` or `0.0f`), and clear documentation.
- If a system needs additional interface functions, consider creating a child interface or extending the existing one. Prefer child interfaces to keep base interfaces stable.

## Success Criteria

1. An actor with [`I_Interactable`] implemented responds to `OnInteract` when detected by the interaction system.
2. An actor with [`I_Persistable`] saves and restores its state correctly through the save system.
3. An actor can implement multiple interfaces simultaneously without conflicts.
4. Calling an interface function on an actor that doesn't implement it safely returns the default value (no crash).
5. All interface functions are accessible via the Blueprint node context menu under their category name.

---

## Multiplayer Networking

**Replication: None needed.** Interfaces are communication contracts — they define function signatures, not data. Interface calls work identically on client and server.

**Key Rule:** When calling an interface function that modifies state (e.g. `I_Interactable.Execute_OnInteract`), the caller must either:
- Be on the server (HasAuthority check), OR
- Call through a `Server_` RPC wrapper that validates and executes the interface function server-side

**Example:**
```
Client calls: Server_Interact(TargetActor)
  → Server validates range, conditions
  → Server calls: I_Interactable.Execute_OnInteract(TargetActor)
  → State changes replicate back via RepNotify
```