226 lines
6.8 KiB
Markdown
226 lines
6.8 KiB
Markdown
# 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 |