AppleHillsProduction/docs/interactables/editor_reference.md

# Interactables System - Editor Reference

## Table of Contents

1. [Overview](#overview)
2. [Adding Interactables to Scene](#adding-interactables-to-scene)
3. [InteractableBase Inspector](#interactablebase-inspector)
   - [Interaction Settings](#interaction-settings)
   - [Interaction Events](#interaction-events-unityevents)
4. [Character Movement Targets](#character-movement-targets)
5. [Pickup Inspector](#pickup-inspector)
6. [ItemSlot Inspector](#itemslot-inspector)
7. [OneClickInteraction Inspector](#oneclickinteraction-inspector)
8. [Interaction Action Components](#interaction-action-components)
9. [Custom Action Components](#custom-action-components)
10. [Puzzle Integration](#puzzle-integration)
11. [Save System Configuration](#save-system-configuration)

---

## Overview

This guide covers configuring interactables using the Unity Inspector and scene tools. It might be helpful, although
 not necessary to be familiar with the code architecture covered in the [Code Reference](code_reference.md).

---

## Adding Interactables to Scene

### Method 1: Add Component Manually
Select GameObject → Add Component → Search "Interactable" → Choose type

### Method 2: Use Interactable Editor
`AppleHills > Interactable Editor` → Scene tab → Select GameObject → Click button for desired type

See [Editor Tools Reference](editor_tools_reference.md#interactable-editor) for details.

---

## InteractableBase Inspector

![InteractableBase Inspector](../media/interactable_base_inspector.png)

### Interaction Settings

**Is One Time** - Disable after first successful interaction (switches, consumables)

**Cooldown** - Temporarily disable after use, in seconds. `-1` = no cooldown (levers, buttons)

**Character To Interact** - Which character(s) move to activate:
- **None** - No movement, instant interaction
- **Trafalgar** - Player moves to point
- **Pulver** - Follower moves (player moves to range first)
- **Both** - Both characters move

### Interaction Events (UnityEvents)

![Interaction Events](../media/interactable_events_inspector.png)

**Interaction Started** `<PlayerTouchController, FollowerController>` - Fires after tap, before movement

**Interaction Interrupted** - Player cancels or validation fails

**Character Arrived** - Character reaches destination

**Interaction Complete** `<bool>` - After DoInteraction(), bool = success

### Example Event Configuration

![Event Configuration Example](../media/interactable_event_configuration_example.png)

**Door that opens when player arrives:**
- Character To Interact: `Trafalgar`
- Character Arrived: `DoorAnimator.SetTrigger("Open")`, `AudioSource.Play()`
- Interaction Complete: `PuzzleStep.CompleteStep()` (if success)

---

## Character Movement Targets

### Default Movement

Without `CharacterMoveToTarget`, characters move to default distances configured in `GameManager`:
- `PlayerStopDistance` - Follower interactions (~1.5 units)
- `PlayerStopDistanceDirectInteraction` - Player interactions (~0.5 units)

### Custom Movement Targets

Add `CharacterMoveToTarget` component to child GameObject:

![Character Move Target Setup](../media/character_move_target_setup.png)

**Fields:**
- **Character Type** - Which character (Trafalgar/Pulver/Both/None)
- **Position Offset** - Offset from transform position

### Scene Gizmos

![Movement Target Gizmos](../media/movement_target_gizmos.png)

**Colors:** 🔵 Blue (Trafalgar), 🟠 Orange (Pulver), 🟣 Purple (Both), ⚪ Gray (None)

---

## Pickup Inspector

![Pickup Inspector](../media/pickup_inspector.png)

**Required Fields:**

**Item Data** - `PickupItemData` ScriptableObject defining the item. Create via `Assets > Create > AppleHills > Items + Puzzles > Pickup Item Data`

**Icon Renderer** - `SpriteRenderer` displaying item icon (auto-assigned if not set)

### PickupItemData ScriptableObject

![PickupItemData Inspector](../media/pickup_item_data_inspector.png)

**Fields:** Item Name, Description, Map Sprite, Pick Up Sound, Drop Sound

**Item ID** (Read-Only) - Auto-generated unique identifier for save/load

---

## ItemSlot Inspector

![ItemSlot Inspector](../media/item_slot_inspector.png)

**Required Fields:**

**Item Data** - `PickupItemData` defining the **correct** item for this slot

**Icon Renderer** - `SpriteRenderer` showing slot icon (background/outline)

**Slotted Item Renderer** - `SpriteRenderer` showing currently slotted item (usually child GameObject)

### Slot Events

![ItemSlot Events](../media/item_slot_events.png)

**On Item Slotted** - Any item placed  
**On Item Slot Removed** - Item removed  
**On Correct Item Slotted** - Correct item placed (also fires `interactionComplete(true)`)  
**On Incorrect Item Slotted** - Wrong item placed  
**On Forbidden Item Slotted** - Forbidden item attempted


### Slot Item Configuration (Settings)

![Slot Item Config Settings](../media/slot_item_config_settings.png)

Configured in `InteractionSettings` at `Assets/Settings/InteractionSettings`:
- **Correct Items** - List of accepted items
- **Forbidden Items** - Items that can't be placed
- **Incorrect Items** - Items that slot but aren't correct


---

## OneClickInteraction Inspector

![OneClickInteraction Inspector](../media/oneclick_inspector.png)

**No additional fields** - only inherits `InteractableBase` settings.

### Typical Configuration

- **Character To Interact:** `Trafalgar` or `Pulver`
- **Is One Time:** Depends on use case
- **Interaction Complete Event:** Configure to trigger game logic

### Example Use Cases

**Pressure Plate:**
- Character To Interact: `Pulver`
- Is One Time: `false`
- Interaction Complete: Call `Door.Open()`

**Tutorial Trigger:**
- Character To Interact: `None`
- Is One Time: `true`  
- Interaction Started: Call `TutorialManager.ShowTip()`

**Dialogue Starter:**
- Character To Interact: `Both`
- Is One Time: `false`
- Character Arrived: Call `DialogueManager.StartDialogue()`

---

## Interaction Action Components

### InteractionTimelineAction

![InteractionTimelineAction Inspector](../media/interaction_timeline_action_inspector.png)

Plays Unity Timeline sequences in response to interaction events.

#### Required Fields

**Playable Director**
- **Type:** `PlayableDirector` component
- **Purpose:** Timeline player
- **Setup:** Auto-assigned from same GameObject if present

**Timeline Mappings** (Array)
Each element maps an interaction event to timeline(s):

![Timeline Mapping Element](../media/timeline_mapping_element.png)

##### Event Type
- **Type:** `InteractionEventType` enum
- **Options:**
  - `InteractionStarted`
  - `PlayerArrived` 
  - `InteractingCharacterArrived`
  - `InteractionComplete`
  - `InteractionInterrupted`
- **Purpose:** When to play this timeline

##### Timelines (Array)
- **Type:** `PlayableAsset[]`
- **Purpose:** Timeline(s) to play for this event
- **Note:** Plays sequentially if multiple

##### Bind Player Character
- **Type:** `bool`
- **Purpose:** Automatically bind player to timeline track
- **Track Name:** `Player` (customizable via Player Track Name field)

##### Bind Pulver Character
- **Type:** `bool`
- **Purpose:** Automatically bind follower to timeline track
- **Track Name:** `Pulver` (customizable via Pulver Track Name field)

##### Player Track Name / Pulver Track Name
- **Type:** `string`
- **Default:** `"Player"` / `"Pulver"`
- **Purpose:** Name of timeline track to bind character to
- **Note:** Must match track name in Timeline asset exactly

##### Timeout Seconds
- **Type:** `float`
- **Default:** `30`
- **Purpose:** Safety timeout - auto-complete if timeline doesn't finish
- **Use Case:** Prevent stuck interactions if timeline errors

##### Loop Last / Loop All
- **Type:** `bool`
- **Purpose:** Loop behavior for timeline sequence
- **Loop Last:** Replays final timeline on next interaction
- **Loop All:** Cycles through all timelines repeatedly

---

## Custom Action Components

See [Code Reference - Action Component System](code_reference.md#action-component-system).

**Base Fields:**
- **Respond To Events** - Which events trigger this action
- **Pause Interaction Flow** - Wait for completion (`true`) or run in background (`false`)

---

## Puzzle Integration

### Adding Puzzle Step to Interactable

1. Select interactable GameObject
2. Add Component → `ObjectiveStepBehaviour`
3. Assign `Step Data` (PuzzleStepSO asset)

![Puzzle Step Integration](../media/puzzle_step_integration.png)

**GameObject has two components:**
- **ItemSlot** (or other Interactable type)
- **ObjectiveStepBehaviour**

**Behavior:**
- Interactable locked until puzzle step unlocked
- Successful interaction (return `true` from `DoInteraction()`) completes puzzle step
- ItemSlots can still swap items when locked (special case)

### Automatic Step Completion

**For Pickup:**
```csharp
protected override bool DoInteraction()
{
    // ...pickup logic...
    return true; // Automatically completes puzzle step if present
}
```

**For ItemSlot:**
```csharp
protected override bool DoInteraction()
{
    // ...slot logic...
    return IsSlottedItemCorrect(); // Only completes if correct item
}
```

No additional code needed - `InteractableBase` handles step completion automatically.