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

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

---

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

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)

---

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