# Title System

The title system manages character titles in the EverQuest II server emulator, allowing players to earn, display, and manage various titles that represent their achievements and progression.

## Overview

The title system consists of several key components:

- **Master Titles List**: Global registry of all available titles
- **Player Title Collections**: Individual player title ownership and preferences
- **Title Manager**: Central coordination and management
- **Integration Systems**: Hooks for earning titles through various game activities

## Core Components

### Title Structure

Each title has the following properties:

- **ID**: Unique identifier
- **Name**: Display name of the title
- **Description**: Detailed description shown in UI
- **Position**: Whether it appears as prefix or suffix
- **Category**: Organizational category (Combat, Tradeskill, etc.)
- **Source**: How the title is obtained (Achievement, Quest, etc.)
- **Rarity**: Common, Uncommon, Rare, Epic, Legendary, Unique
- **Requirements**: Conditions that must be met to earn the title
- **Flags**: Various behavioral modifiers (Hidden, Temporary, Unique, etc.)

### Title Positioning

Titles can be displayed in two positions relative to the character name:

- **Prefix**: Appears before the character name (e.g., "Master John")
- **Suffix**: Appears after the character name (e.g., "John the Brave")

Players can have one active prefix and one active suffix title simultaneously.

### Title Sources

Titles can be obtained through various means:

- **Achievements**: Completing specific achievements
- **Quests**: Finishing particular quest lines
- **Tradeskills**: Reaching mastery in crafting
- **Combat**: Battle-related accomplishments
- **Exploration**: Discovering new areas
- **PvP**: Player vs Player activities
- **Guild**: Guild progression and achievements
- **Events**: Special server events
- **Rare**: Uncommon encounters or collections

## Usage Examples

### Basic Title Management

```go
// Create a title manager
titleManager := titles.NewTitleManager()

// Create a new title
title, err := titleManager.CreateTitle(
    "Dragon Slayer",           // name
    "Defeated an ancient dragon", // description
    titles.CategoryCombat,     // category
    titles.TitlePositionSuffix, // position
    titles.TitleSourceAchievement, // source
    titles.TitleRarityEpic,    // rarity
)

// Grant a title to a player
err = titleManager.GrantTitle(playerID, titleID, achievementID, 0)

// Set active titles
err = titleManager.SetPlayerActivePrefix(playerID, prefixTitleID)
err = titleManager.SetPlayerActiveSuffix(playerID, suffixTitleID)

// Get formatted player name with titles
formattedName := titleManager.GetPlayerFormattedName(playerID, "John")
// Result: "Master John the Dragon Slayer"
```

### Achievement Integration

```go
// Set up achievement integration
integrationManager := titles.NewIntegrationManager(titleManager)

// Create achievement-linked title
title, err := titleManager.CreateAchievementTitle(
    "Dungeon Master",
    "Completed 100 dungeons",
    achievementID,
    titles.TitlePositionPrefix,
    titles.TitleRarityRare,
)

// When achievement is completed
err = integrationManager.GetAchievementIntegration().OnAchievementCompleted(playerID, achievementID)
```

### Event Titles

```go
// Start a seasonal event with title reward
eventIntegration := integrationManager.GetEventIntegration()
err = eventIntegration.StartEvent(
    "Halloween 2024",
    "Spooky seasonal event",
    7*24*time.Hour, // 1 week duration
    halloweenTitleID,
)

// Grant participation title
err = eventIntegration.OnEventParticipation(playerID, "Halloween 2024")
```

## File Structure

- `constants.go`: Title system constants and enums
- `title.go`: Core title and player title data structures
- `master_list.go`: Global title registry and management
- `player_titles.go`: Individual player title collections
- `title_manager.go`: Central title system coordinator
- `integration.go`: Integration systems for earning titles
- `README.md`: This documentation file

## Database Integration

The title system is designed to integrate with the database layer:

- **Master titles**: Stored in `titles` table
- **Player titles**: Stored in `character_titles` table
- **Title requirements**: Stored in `title_requirements` table

Database methods are marked as TODO and will be implemented when the database package is available.

## Network Packets

The system supports the following network packets:

- **TitleUpdate**: Sends player's available titles to client
- **UpdateTitle**: Updates displayed title information

Packet structures are defined based on the XML definitions in the packets directory.

## Title Categories

The system organizes titles into logical categories:

- **Combat**: Battle and PvP related titles
- **Tradeskill**: Crafting and gathering achievements
- **Exploration**: Zone discovery and travel
- **Social**: Community and roleplay titles
- **Achievement**: General accomplishment titles
- **Quest**: Story and mission completion
- **Rare**: Uncommon encounters and collections
- **Seasonal**: Time-limited event titles
- **Guild**: Organization-based titles
- **Raid**: Group content achievements
- **Class**: Profession-specific titles
- **Race**: Heritage and background titles

## Title Rarity System

Titles have six rarity levels with associated colors:

1. **Common** (White): Easily obtainable titles
2. **Uncommon** (Green): Moderate effort required
3. **Rare** (Blue): Significant achievement needed
4. **Epic** (Purple): Exceptional accomplishment
5. **Legendary** (Orange): Extremely difficult to obtain
6. **Unique** (Red): One-of-a-kind titles

## Special Title Types

### Temporary Titles

Some titles expire after a certain period:

- Event titles that expire when the event ends
- Temporary status titles (e.g., "Newcomer")
- Achievement-based titles with time limits

### Unique Titles

Certain titles can only be held by one player at a time:

- "First to reach max level"
- "Server champion"
- Special recognition titles

### Account-Wide Titles

Some titles are shared across all characters on an account:

- Beta tester recognition
- Special event participation
- Founder rewards

## Thread Safety

All title system components are thread-safe using appropriate synchronization:

- `sync.RWMutex` for read-heavy operations
- Atomic operations where appropriate
- Proper locking hierarchy to prevent deadlocks

## Performance Considerations

- Title lookups are optimized with indexed maps
- Player title data is cached in memory
- Background cleanup processes handle expired titles
- Database operations are batched when possible

## Future Enhancements

Planned improvements include:

- Advanced title search and filtering
- Title display customization options
- Title trading/gifting system
- Dynamic title generation
- Integration with guild systems
- Advanced achievement requirements
- Title collection statistics and tracking