AppleHillsProduction/docs/interactables/editor_tools_reference.md

# Editor Tools Reference

## Overview

AppleHills provides two specialized editor tools for managing puzzles and interactables:
- **Interactable Editor** - Manage scene interactables and debug interactions
- **Puzzle Editor** - Manage puzzle steps and debug puzzle flow

Both tools are accessible via the `AppleHills` menu and follow a consistent two-tab design pattern for editing and debugging.

---

## Interactable Editor

**Menu:** `AppleHills > Interactable Editor`

The Interactable Editor provides scene-based management and runtime debugging for interactable objects in your scenes.

### Edit Tab

![Interactable Editor - Edit Tab](../media/interactable_editor_edit.png)

The Edit tab lets you browse, select, and modify all interactables in the current scene with a real-time inspector.

#### Left Panel - Scene Interactable List

**Refresh Button** - Manual refresh (auto-refreshes on scene changes, hierarchy changes, and play mode toggle)

**Found Count** - Displays total number of interactables found in the active scene

**Search Field** - Filter interactables by GameObject name for quick access

**Interactable Cards** - Each card shows:
- GameObject name
- Interactable component type
- Item/Slot data reference (for Pickup and ItemSlot types)
- Ping button to highlight in scene hierarchy

**Auto-Discovery:** Automatically scans for all `InteractableBase` components when:
- Scene loads or unloads
- GameObjects or components are added/removed
- Play mode is toggled

#### Right Panel - Dynamic Inspector

The right panel adapts based on what's selected:

**Nothing Selected State:**
- Shows a help message prompting you to select an interactable from the list

**GameObject Without Interactable State:**
- Displays "Add Interactable Component" buttons for:
  - OneClickInteraction
  - Pickup
  - ItemSlot
  - SaveableInteractable
  - InteractableBase
- Clicking any button adds the component with full undo support and auto-refreshes the list

**Interactable Selected State:**
- Shows full Unity inspector for the selected component
- All changes auto-save with undo/redo support (Ctrl+Z / Ctrl+Y)
- Additional Information section displays:
  - Component type
  - Attached action components with Ping buttons
  - Type-specific data (Item Data for Pickup, Slot Data for ItemSlot)
  - In Play Mode: shows slotted object for ItemSlot types

**Selection Synchronization:**
- Bidirectional sync between editor list and scene hierarchy
- Selecting in the list highlights in hierarchy and vice versa
- Selecting a GameObject without an interactable shows the "Add Component" interface

---

![Interactable Editor - Debug Tab](../media/interactable_editor_debug.png)

### Debug Tab

**Availability:** Play Mode only

The Debug tab provides runtime testing tools for triggering interactions and events on interactables.

#### Interactable Debug Cards

Each debug card represents one interactable in the scene and includes:

**Header Section:**
- GameObject name (bold text)
- Interactable component type (gray text)
- Ping button (locates object in hierarchy)

**Full Interaction Button:**
- Simulates complete `OnTap()` flow
- Triggers character movement and full event chain
- Tests end-to-end interaction behavior

**Individual Event Triggers:**
- **Started** - Calls `OnInteractionStarted()` and fires `interactionStarted` event
- **Arrived** - Calls `OnInteractingCharacterArrived()` and fires `characterArrived` event
- **Do Interaction** - Calls `DoInteraction()` directly to test core interaction logic
- **Complete (Success)** - Calls `OnInteractionFinished(true)` and triggers puzzle completion
- **Complete (Fail)** - Calls `OnInteractionFinished(false)` to test failure handling
- **Interrupted** - Invokes `interactionInterrupted` event

**Registered Actions Display:**
- Lists all action components registered to this interactable
- Shows which events each action responds to

#### Common Testing Workflows

**Test Full Interaction:**
1. Enter Play Mode
2. Find target interactable in debug list
3. Click **Full Interaction** button
4. Verify complete behavior chain

**Test Specific Event:**
1. Enter Play Mode
2. Locate interactable
3. Click individual event button (e.g., **Started** or **Arrived**)
4. Verify specific event behavior

**Test Event Sequence:**
1. Click **Started**
2. Click **Arrived**
3. Click **Do Interaction**
4. Click **Complete (Success)**
5. Verify full event chain executes correctly

**Test Action Integration:**
1. Find interactable with timeline or dialogue action
2. Check Registered Actions to confirm action is attached
3. Click **Started** or appropriate event trigger
4. Verify action executes (timeline plays, dialogue shows, etc.)

**Test Puzzle Integration:**
1. Open both Interactable Editor and Puzzle Editor
2. Verify required puzzle step is unlocked in Puzzle Editor
3. Click **Full Interaction** in Interactable Editor
4. Switch to Puzzle Editor and verify step marked as completed

---

## Puzzle Editor

**Menu:** `AppleHills > Puzzle Editor`

![Puzzle Editor - Edit Tab](../media/puzzle_editor_edit.png)

The Puzzle Editor manages puzzle step assets and provides runtime debugging for the puzzle progression system.

### Edit Tab

The Edit tab displays all `PuzzleStepSO` assets in your project with full editing capabilities.

#### Left Panel - Puzzle Step List

**Search Field** - Filter puzzle steps by name

**Folder Organization:**
- Steps are grouped by their asset folder location
- Click folder headers to expand/collapse groups
- Helps organize large numbers of puzzle steps

**Step Cards** - Each card displays:
- Display name (user-friendly identifier)
- Step ID (unique technical identifier)
- Dependency information (unlocked by / unlocks)

**Toolbar Actions:**
- **Refresh** - Reloads all puzzle step assets from project
- **Create New** - Opens creation dialog

**Creating New Steps:**
1. Click **Create New** button
2. Enter step name (stepId auto-generates from name)
3. Select destination folder
4. Click Create
5. New step appears in list and is auto-selected

#### Right Panel - Step Inspector

When a puzzle step is selected, the inspector shows:

**Basic Properties:**
- **Display Name** - Editable user-friendly name for the step
- **Step ID** - Read-only unique identifier (lowercase, underscored format)

**Dependencies Configuration:**
- **Unlocked By** - List of steps that must complete before this step unlocks
  - Drag and drop `PuzzleStepSO` assets to add dependencies
  - Empty list means this is an initial step (unlocked by default)
- **Unlocks** - List of steps that this step will unlock when completed
  - Bidirectional relationship (automatically syncs with "Unlocked By" on other steps)
  - Edit from either side of the relationship

**Asset Management:**
- **Asset Path** - Shows full file path to the .asset file
- **Delete Button** - Permanently deletes the step asset
  - Shows confirmation dialog before deletion
  - Cannot be undone after confirmation

**Auto-Save:** All changes save automatically to the asset with full undo/redo support (Ctrl+Z / Ctrl+Y)

![Puzzle Editor - Debug Tab](../media/puzzle_editor_debug.png)

---

### Debug Tab

**Availability:** Play Mode only

The Debug tab provides runtime testing and debugging tools for the puzzle progression system.

#### Toolbar

**Current Level Display:**
- Shows the name of the currently loaded puzzle level
- Updates automatically when scenes change
- Displays "No level loaded" if puzzle system is inactive

**Unlock All Button:**
- Unlocks and completes all puzzle steps in the current level
- Processes steps in dependency order using iterative algorithm
- Logs progression to console for debugging
- Useful for testing late-game content or verifying completion flow

#### Step List

Each step in the current level displays:

**Step Header:**
- Display name in bold text
- Step ID in gray text below name

**State Indicators:**
- 🔒 **Locked** (gray background) - Dependencies not met, step unavailable
- 🔓 **Unlocked** (yellow background) - Available for interaction but not completed
- ✅ **Completed** (green background) - Successfully completed

**Action Buttons:**
- **Toggle Lock** - Manually lock/unlock the step
  - Bypasses normal dependency requirements
  - Useful for testing specific scenarios
  - Does not affect dependent steps automatically
- **Complete** - Marks step as completed
  - Only enabled when step is unlocked
  - Fires completion events
  - Automatically unlocks dependent steps
  - Updates state indicators in real-time