# Travel Event System

## Overview

The Travel Event System adds random encounters and events during travel in your RPG. Events can be combat encounters (ambushes), trading opportunities (merchants), discoveries (treasure), and more. Events are terrain-aware, so bandits are more likely in forests and mountains, while merchants are more common on roads.

## Quick Setup

1. **Add the setup component to your travel system:**
   - Find your GameObject with `TeamTravelSystem`
   - Add the `TravelEventSystemSetup` component
   - Click "Setup Event System" button in the inspector (or it will auto-setup on Start)

2. **Create travel events:**
   - Right-click in Project window
   - Go to `Create > RPG > Travel Events`
   - Choose the event type you want (Combat, Trading, Discovery, etc.)
   - Configure the event settings

3. **Assign events to the system:**
   - Find the `TravelEventSystem` component
   - Add your created events to the "Available Events" list

## Event Types

### Combat Events
- **Forest Ambush**: Bandits attack from forest cover
- **Mountain Ambush**: Dangerous encounters in rocky terrain
- **Wild Animals**: Bears, wolves, or other creatures

**Settings:**
- More likely in wilderness (forests, mountains)
- Less likely on roads and in towns
- Can specify enemy count and types

### Trading Events
- **Traveling Merchant**: Traders offering goods
- **Caravan**: Large trading groups
- **Road Patrol**: Guards who may have supplies

**Settings:**
- More likely on roads and near settlements
- Can have rare items and different price modifiers
- Some merchants specialize in certain goods

### Discovery Events
- **Hidden Cache**: Abandoned treasure stashes
- **Natural Resources**: Herbs, minerals, etc.
- **Lost Items**: Equipment left by other travelers

**Settings:**
- More likely in remote areas off main roads
- Can provide gold, items, or resources

### Rest Events
- **Safe Camping**: Peaceful spots for healing
- **Natural Springs**: Healing waters
- **Shelter**: Protection from weather

**Settings:**
- Common near water sources and in natural areas
- Restores health and party morale

### Hazard Events
- **Rockslides**: Mountain dangers
- **Difficult Terrain**: Swamps, thorns, etc.
- **Weather**: Storms, extreme heat/cold

**Settings:**
- More likely in dangerous terrain
- Can cause health loss or resource costs

## Terrain Probability System

Each event has probability modifiers for different terrain and feature types:

### Terrain Types
- **Plains**: 0.5 (baseline)
- **Forest**: Higher for ambushes, lower for merchants
- **Mountains**: Higher for ambushes and hazards
- **Rivers/Lakes**: Higher for rest events
- **Roads**: Higher for merchants, lower for ambushes

### Feature Types
- **Towns/Villages**: Safe, good for trading
- **Bridges**: Common meeting points
- **Tunnels**: Can be dangerous or shortcuts
- **Ferries**: Trading opportunities

## Configuration

### Event System Settings
```csharp
public float baseEventChance = 0.15f;  // 15% base chance per check
public int tilesPerEventCheck = 3;     // Check every 3 tiles
```

### Event Rarity
- **Very Common**: 25% base chance
- **Common**: 15% base chance  
- **Uncommon**: 8% base chance
- **Rare**: 4% base chance
- **Very Rare**: 2% base chance
- **Legendary**: 0.5% base chance

## Creating Custom Events

### 1. Create a ScriptableObject Event
```csharp
[CreateAssetMenu(fileName = "My Custom Event", menuName = "RPG/Travel Events/Custom Event")]
public class MyCustomEvent : TravelEvent
{
    public override EventResult ExecuteEvent(TravelEventContext context)
    {
        // Your event logic here
        return new EventResult("Something interesting happened!");
    }
}
```

### 2. Set Terrain Preferences
```csharp
void OnEnable()
{
    eventType = EventType.Discovery;
    rarity = EventRarity.Uncommon;
    
    // More likely in forests
    forestChance = 0.8f;
    roadChance = 0.2f;
    townChance = 0.1f;
}
```

### 3. Handle Event Results
```csharp
public override EventResult ExecuteEvent(TravelEventContext context)
{
    return new EventResult("You found treasure!")
    {
        goldChange = 50,
        healthChange = 10,
        shouldStopTravel = false
    };
}
```

## Integration with Battle System

Combat events can automatically trigger battles:

```csharp
return EventResult.SimpleBattle(
    "Bandits attack your party!",
    enemyCount: 3,
    enemyType: "Forest Bandit"
);
```

This will:
1. Stop travel
2. Show the event message
3. Set up battle with specified enemies
4. Transition to battle scene

## Integration with Trading System

Trading events can open shop interfaces:

```csharp
return EventResult.SimpleTrading(
    "A merchant offers goods for sale.",
    merchantType: "Traveling Merchant"
);
```

This will:
1. Stop travel
2. Show the event message
3. Open trading interface
4. Apply any price modifiers

## Event Context

Events receive context information to make intelligent decisions:

```csharp
public class TravelEventContext
{
    public Vector2Int currentPosition;
    public MapTile currentTile;
    public TravelRoute currentRoute;
    public List<TeamCharacter> teamMembers;
    public int teamGold;
    public TravelEventHistory eventHistory;
}
```

## Testing and Debugging

### Debug Features
- Enable `showDebugLogs` for detailed event information
- Use `TriggerEventCheck()` method to force event checks
- Use `forceNextEvent` to guarantee next event occurs

### Console Commands
- Right-click TravelEventSystem → "Trigger Event Check"
- Right-click TravelEventSystem → "Reset Event History"

### Example Events
Add `TravelEventExampleCreator` component to any GameObject and use "Create Example Events" to generate test events.

## Best Practices

1. **Balance**: Don't make events too frequent or rare
2. **Variety**: Mix different event types for interesting travel
3. **Terrain Logic**: Make events make sense for their location
4. **Player Agency**: Some events should offer choices
5. **Resource Management**: Events should interact with player resources meaningfully

## Troubleshooting

### Events Not Triggering
- Check that `enableEvents` is true
- Verify events are added to `availableEvents` list
- Check terrain probability settings
- Ensure travel system is active

### Events Too Frequent/Rare
- Adjust `baseEventChance` (0.15 = 15%)
- Modify `tilesPerEventCheck` (higher = less frequent)
- Adjust individual event rarity settings

### UI Not Showing
- Add `TravelEventUI` component to scene
- Enable `useDebugUI` for simple debug display
- Check console for event messages

## Future Enhancements

Possible extensions to the system:
- Weather-based events
- Seasonal event variations
- Reputation-based event outcomes
- Multi-part story events
- Time-of-day event variations
- Party composition effects on events