Interactables documentaiton
This commit is contained in:
Michal Pikulski
251
docs/interactables/editor_tools_reference.md
Normal file
251
docs/interactables/editor_tools_reference.md
Normal file
@@ -0,0 +1,251 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user