eq2go/internal/heroic_ops/README.md

# Heroic Opportunities System

The Heroic Opportunities (HO) system implements EverQuest II's cooperative combat mechanic where players coordinate ability usage to complete beneficial spell effects.

## Overview

Heroic Opportunities are multi-stage cooperative encounters that require precise timing and coordination. The system consists of two main phases:

1. **Starter Chain Phase**: Players use abilities in sequence to complete a starter chain
2. **Wheel Phase**: Players complete abilities on a randomized wheel within a time limit

## Architecture

### Core Components

#### HeroicOPStarter
Represents starter chains that initiate heroic opportunities:
- **Class Restrictions**: Specific classes can initiate specific starters
- **Ability Sequence**: Up to 6 abilities that must be used in order
- **Completion Marker**: Special marker (0xFFFF) indicates chain completion

#### HeroicOPWheel
Represents the wheel phase with ability completion requirements:
- **Order Types**: Unordered (any sequence) vs Ordered (specific sequence)
- **Shift Capability**: Ability to change to different wheel once per HO
- **Completion Spell**: Spell cast when wheel is successfully completed
- **Chance Weighting**: Probability factor for random wheel selection

#### HeroicOP
Active HO instance with state management:
- **Multi-phase State**: Tracks progression through starter → wheel → completion
- **Timer Management**: Precise timing controls for wheel phase
- **Participant Tracking**: Manages all players involved in the HO
- **Progress Validation**: Ensures abilities match current requirements

### System Flow

```
Player Uses Starter Ability
         ↓
System Loads Available Starters for Class
         ↓
Eliminate Non-matching Starters
         ↓
Starter Complete? → Yes → Select Random Wheel
         ↓                       ↓
        No               Start Wheel Phase Timer
         ↓                       ↓
Continue Starter Chain    Players Complete Abilities
         ↓                       ↓
More Starters? → No → HO Fails   All Complete? → Yes → Cast Spell
                                 ↓
                                No → Timer Expired? → Yes → HO Fails
```

## Database Schema

### heroic_ops Table
Stores both starters and wheels with type discrimination:

```sql
CREATE TABLE heroic_ops (
    id INTEGER NOT NULL,
    ho_type TEXT CHECK(ho_type IN ('Starter', 'Wheel')),
    starter_class INTEGER,      -- For starters: class restriction
    starter_icon INTEGER,       -- For starters: initiating icon
    starter_link_id INTEGER,    -- For wheels: associated starter ID
    chain_order INTEGER,        -- For wheels: order requirement
    shift_icon INTEGER,         -- For wheels: shift ability icon
    spell_id INTEGER,           -- For wheels: completion spell
    chance REAL,                -- For wheels: selection probability
    ability1-6 INTEGER,         -- Ability icons
    name TEXT,
    description TEXT
);
```

### heroic_op_instances Table
Tracks active HO instances:

```sql
CREATE TABLE heroic_op_instances (
    id INTEGER PRIMARY KEY,
    encounter_id INTEGER,
    starter_id INTEGER,
    wheel_id INTEGER,
    state INTEGER,
    countered_1-6 INTEGER,      -- Completion status per ability
    shift_used INTEGER,
    time_remaining INTEGER,
    -- ... additional fields
);
```

## Key Features

### Multi-Class Initiation
- Specific classes can initiate specific starter chains
- Universal starters (class 0) available to all classes
- Class validation ensures proper HO eligibility

### Dynamic Wheel Selection
- Random selection from available wheels per starter
- Weighted probability based on chance values
- Prevents predictable HO patterns

### Wheel Shifting
- **One-time ability** to change wheels during wheel phase
- **Timing Restrictions**: Only before progress (unordered) or at start (ordered)
- **Strategic Element**: Allows adaptation to group composition

### Precise Timing
- Configurable wheel phase timers (default 10 seconds)
- Millisecond precision for fair completion windows
- Automatic cleanup of expired HOs

### Order Enforcement
- **Unordered Wheels**: Any ability can be completed in any sequence
- **Ordered Wheels**: Abilities must be completed in specific order
- **Validation**: System prevents invalid ability usage

## Usage Examples

### Starting a Heroic Opportunity

```go
// Initialize HO manager
manager := NewHeroicOPManager(masterList, database, clientManager, encounterManager, playerManager)
manager.Initialize(ctx, config)

// Start HO for encounter
ho, err := manager.StartHeroicOpportunity(ctx, encounterID, initiatorCharacterID)
if err != nil {
    return fmt.Errorf("failed to start HO: %w", err)
}
```

### Processing Player Abilities

```go
// Player uses ability during HO
err := manager.ProcessAbility(ctx, ho.ID, characterID, abilityIcon)
if err != nil {
    // Ability not allowed or HO in wrong state
    return err
}

// Check if HO completed
if ho.IsComplete() {
    // Completion spell will be cast automatically
    log.Printf("HO completed by character %d", ho.CompletedBy)
}
```

### Timer Management

```go
// Update all active HO timers (called periodically)
manager.UpdateTimers(ctx, deltaMilliseconds)

// Expired HOs are automatically failed and cleaned up
```

## Client Communication

### Packet Types
- **HO Start**: Initial HO initiation notification
- **HO Update**: Wheel phase updates with ability icons
- **HO Progress**: Real-time completion progress
- **HO Timer**: Timer countdown updates
- **HO Complete**: Success/failure notification
- **HO Shift**: Wheel change notification

### Real-time Updates
- Participants receive immediate feedback on ability usage
- Progress updates show completion status
- Timer updates maintain urgency during wheel phase

## Configuration

### System Parameters
```go
config := &HeroicOPConfig{
    DefaultWheelTimer:   10000,  // 10 seconds in milliseconds
    MaxConcurrentHOs:    3,      // Per encounter
    EnableLogging:       true,
    EnableStatistics:    true,
    EnableShifting:      true,
    RequireClassMatch:   true,
}
```

### Performance Tuning
- **Concurrent HOs**: Limit simultaneous HOs per encounter
- **Cleanup Intervals**: Regular removal of expired instances
- **Database Batching**: Efficient event logging
- **Memory Management**: Instance pooling for high-traffic servers

## Integration Points

### Spell System Integration
- Completion spells cast through spell manager
- Spell validation and effect application
- Integration with existing spell mechanics

### Encounter System Integration
- HO availability tied to active encounters
- Participant validation through encounter membership
- Encounter end triggers HO cleanup

### Player System Integration
- Class validation for starter eligibility
- Ability validation for wheel completion
- Player state checking (online, in combat, etc.)

## Error Handling

### Common Error Scenarios
- **Invalid State**: Ability used when HO not in correct phase
- **Timer Expired**: Wheel phase timeout
- **Ability Not Allowed**: Ability doesn't match current requirements
- **Shift Already Used**: Attempting multiple shifts
- **Player Not in Encounter**: Participant validation failure

### Recovery Mechanisms
- Automatic HO failure on unrecoverable errors
- Client notification of error conditions
- Logging for debugging and analysis
- Graceful degradation when components unavailable

## Thread Safety

All core components use proper Go concurrency patterns:
- **RWMutex Protection**: Reader-writer locks for shared data
- **Atomic Operations**: Lock-free operations where possible
- **Context Cancellation**: Proper cleanup on shutdown
- **Channel Communication**: Safe inter-goroutine messaging

## Performance Considerations

### Memory Management
- Object pooling for frequently created instances
- Efficient cleanup of expired HOs
- Bounded history retention

### Database Optimization
- Indexed queries for fast lookups
- Batch operations for event logging
- Connection pooling for concurrent access

### Network Efficiency
- Minimal packet sizes for real-time updates
- Client version-specific optimizations
- Broadcast optimization for group updates

## Testing

### Unit Tests
- Individual component validation
- State machine testing
- Error condition handling
- Concurrent access patterns

### Integration Tests
- Full HO lifecycle scenarios
- Multi-player coordination
- Database persistence validation
- Client communication verification

## Future Enhancements

### Planned Features
- **Lua Scripting**: Custom HO behaviors
- **Advanced Statistics**: Detailed analytics
- **Dynamic Difficulty**: Adaptive timer adjustments
- **Guild Coordination**: Guild-wide HO tracking

### Scalability Improvements
- **Clustering Support**: Multi-server HO coordination
- **Caching Layer**: Redis integration for high-traffic
- **Async Processing**: Background HO processing
- **Load Balancing**: Distribution across game servers

## Conversion Notes

This Go implementation maintains full compatibility with the original C++ EQ2EMu system while modernizing the architecture:

- **Thread Safety**: Proper Go concurrency patterns
- **Error Handling**: Comprehensive error wrapping
- **Context Usage**: Cancellation and timeout support
- **Interface Design**: Modular, testable components
- **Database Integration**: Modern query patterns

All original functionality has been preserved, including complex mechanics like wheel shifting, ordered/unordered completion, and precise timing requirements.