AppleHillsProduction/docs/interactables/editor_reference.md

Interactables System - Editor Reference

Table of Contents

1. Overview
2. Adding Interactables to Scene
3. InteractableBase Inspector
   • Interaction Settings
   • Interaction Events
4. Character Movement Targets
5. Pickup Inspector
6. ItemSlot Inspector
7. OneClickInteraction Inspector
8. Interaction Action Components
9. Custom Action Components
10. Puzzle Integration
11. 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.

---

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 for details.

---

InteractableBase Inspector

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 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

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:

Fields:

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

Scene Gizmos

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

---

Pickup Inspector

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

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

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

---

ItemSlot Inspector

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

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)

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

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

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):

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.

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)

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:

protected override bool DoInteraction()
{
    // ...pickup logic...
    return true; // Automatically completes puzzle step if present
}

For ItemSlot:

protected override bool DoInteraction()
{
    // ...slot logic...
    return IsSlottedItemCorrect(); // Only completes if correct item
}

No additional code needed - InteractableBase handles step completion automatically.