RPG-RougeLiteBattler/TRAVEL_EVENT_SYSTEM_GUIDE.md

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

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

[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

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

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:

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:

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:

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