RPG-RougeLiteBattler/PERCEPTION_SPOTTABLE_EVENTS_GUIDE.md

Perception-Based Spottable Event System - Implementation Guide

Overview

Your RPG now supports spottable events that appear as red markers within your team's perception range! Instead of all events triggering automatically, players can now spot potential encounters and choose whether to approach them or avoid them.

🎯 Key Features

Spottable Event Markers

• Red dots appear within your team's perception circle
• Markers represent events that can be spotted before they trigger
• Players can choose to approach markers to trigger events
• Markers disappear after 30 seconds if not approached

Enhanced Perception System

• Team's perception range (purple circle) now serves a gameplay purpose
• Higher perception = larger detection range for events
• Events can only be spotted within the perception radius

Dual Event System

• Automatic Events: Trigger immediately (legacy behavior)
• Spottable Events: Appear as markers first, trigger when approached

🚀 Quick Setup

Step 1: Add Setup Component

1. In your scene with the travel system, find any GameObject (or create a new one)
2. Add the PerceptionEventSystemSetup component
3. Click "Setup Perception Event System" in the inspector
4. The system will automatically add required components

Step 2: Verify Integration

• Use the "Show System Status" button to verify all components are present
• You should see ✅ for all required components

Step 3: Test the System

1. Start your travel scene
2. You should see the purple perception circle around your team marker
3. As you travel, red event markers may appear within the circle
4. Move your team near a red marker to trigger the event

📋 Creating Spottable Events

Option 1: Use Pre-built Events

• SpottableSkeletonPatrol: Skeleton warriors that can be spotted and avoided
• Right-click in Project → Create → RPG → Travel Events → Spottable → Skeleton Patrol

Option 2: Convert Existing Events

1. Open any existing TravelEvent asset
2. Change Trigger Type from Automatic to Spottable
3. The event will now appear as a red marker instead of triggering immediately

Option 3: Create Custom Spottable Events

[CreateAssetMenu(fileName = "MySpottableEvent", menuName = "RPG/Travel Events/Spottable/Custom Event")]
public class MySpottableEvent : CombatTravelEvent
{
    void OnEnable()
    {
        triggerType = EventTriggerType.Spottable;  // Key setting!
        eventName = "My Spottable Event";
        // Configure other settings...
    }
}

⚙️ System Components

EventMarkerVisualizer

• Manages red event markers within perception range
• Handles marker spawning, lifetime, and cleanup
• Configurable marker appearance and behavior

TeamPerceptionVisualizer (Enhanced)

• Shows purple perception circle around team
• Now used by event system to determine marker spawn range
• Based on team's highest perception value

TravelEventSystem (Enhanced)

• Supports both automatic and spottable events
• Checks for marker triggers when team moves
• Spawns markers for spottable events

EventTriggerType (New Enum)

• Automatic: Traditional immediate triggering
• Spottable: Appears as marker first, triggers when approached

🎮 Player Experience

Before (Automatic Events)

1. Team travels
2. Event triggers randomly
3. Player must deal with event immediately

After (Spottable Events)

1. Team travels with visible perception range
2. Red markers appear for potential events
3. Player can see threats/opportunities coming
4. Player chooses to approach or avoid
5. Strategic perception building becomes valuable

🔧 Configuration Options

EventMarkerVisualizer Settings

• Max Active Markers: How many red dots can be on screen (default: 5)
• Marker Lifetime: How long markers last if not approached (default: 30s)
• Min/Max Distance: How close/far from team markers can spawn
• Marker Color: Red by default, customizable
• Pulsing Effect: Visual pulsing to draw attention

Event Settings

• Trigger Type: Choose Automatic or Spottable per event
• Terrain Preferences: Where events are more/less likely
• Rarity: How often events spawn

Perception Settings

• Perception Multiplier: How perception value converts to world distance
• Visualization: Purple circle can be toggled on/off

📊 Benefits of the New System

Strategic Gameplay

• Perception becomes valuable: High perception = see threats/opportunities sooner
• Player agency: Choose which encounters to face
• Risk management: Avoid dangerous encounters when weakened

Improved Immersion

• Visual feedback: See your party's awareness range
• Realistic encounters: Spot enemies before they spot you
• Environmental storytelling: Markers show the danger level of areas

Tactical Depth

• Scouting: High perception characters become scouts
• Route planning: Navigate around dangerous encounters
• Resource management: Engage only when ready

🐛 Troubleshooting

No Red Markers Appearing

• Check that events have triggerType = EventTriggerType.Spottable
• Verify EventMarkerVisualizer is in the scene
• Ensure team has perception > 0
• Check event rarity settings

Purple Circle Not Showing

• Check that TeamPerceptionVisualizer is in the scene
• Verify team members have perception values
• Check visualization is enabled in PlayerPrefs

Events Not Triggering When Approached

• Verify team position is within trigger distance (1.5 units)
• Check TravelEventSystem integration
• Look for error messages in console

🎯 Advanced Usage

Creating Event Chains

Create multiple spottable events that spawn based on player choices:

// First event spawns marker for "Bandit Camp"
// If approached, can spawn "Bandit Leader" marker
// If avoided, can spawn "Bandit Patrol" marker later

Perception-Based Difficulty

Adjust event spawning based on team perception:

// Higher perception = spot better opportunities
// Lower perception = more dangerous surprises

Environmental Storytelling

Use marker density to show area danger:

// Forests: Many spottable encounters
// Roads: Fewer spottable, more automatic (safe travel)
// Mountains: Very dangerous spottable encounters

🎉 Conclusion

The perception-based spottable event system transforms travel from random interruptions into strategic exploration. Players now have meaningful choices, perception becomes a valuable stat, and the game world feels more immersive and tactical.

Your players can now truly scout ahead, avoid dangerous encounters when needed, and make informed decisions about which opportunities to pursue!