# Race Types System

The race types system manages creature and NPC classifications in EverQuest II, providing a hierarchical categorization of all non-player entities in the game world.

## Overview

Unlike the character races system (`internal/races`), which handles the 21 playable character races used by both players and NPCs, the race types system classifies all creatures and NPCs into categories and subcategories for game mechanics, AI behavior, combat calculations, and visual representation.

**Note**: This package is located under `internal/npc/race_types` because it specifically deals with NPC creature types. The `internal/races` package remains at the top level because it's used by the Entity system, which is inherited by both players and NPCs.

## Key Components

### Types and Constants (`types.go`, `constants.go`)
- **RaceType**: Core structure containing race type ID, category, subcategory, and model name
- **Constants**: Defines 300+ race type IDs organized into 10 major categories
- **Statistics**: Tracks usage and query patterns for performance monitoring

### Master Race Type List (`master_race_type_list.go`)
- Maps model IDs to race type information
- Thread-safe operations with read/write locking
- Provides lookups by model ID, category, and subcategory
- Maintains statistics on race type usage

### Database Operations (`database.go`)
- Loads race types from the `race_types` table
- Supports CRUD operations for race type management
- Creates necessary database schema and indexes

### Manager (`manager.go`)
- High-level interface for race type operations
- Creature type checking methods (IsUndead, IsDragonkind, etc.)
- Command processing for debugging and administration
- Integration point for other game systems

### Interfaces (`interfaces.go`)
- **RaceTypeProvider**: Core interface for accessing race type information
- **CreatureTypeChecker**: Interface for checking creature classifications
- **RaceTypeAware**: Interface for entities that have a model type
- **NPCRaceTypeAdapter**: Adapter for integrating race types with NPC system
- Additional interfaces for damage, loot, and AI behavior modifications

## Race Type Categories

The system organizes creatures into 10 major categories:

1. **DRAGONKIND** (101-110): Dragons, drakes, wyrms, wyverns
2. **FAY** (111-122): Fae creatures, sprites, wisps, treants
3. **MAGICAL** (123-154): Constructs, golems, elementals, magical beings
4. **MECHANIMAGICAL** (155-157): Clockwork creatures, iron guardians
5. **NATURAL** (158-239): Animals, insects, reptiles, natural creatures
6. **PLANAR** (240-267): Demons, elementals, planar beings
7. **PLANT** (268-274): Carnivorous plants, animated vegetation
8. **SENTIENT** (275-332): Intelligent humanoids, NPC versions of player races
9. **UNDEAD** (333-343): Ghosts, skeletons, zombies, vampires
10. **WERE** (344-347): Werewolves and other lycanthropes

## Usage Examples

### Basic Race Type Lookup
```go
manager := race_types.NewManager(db)
manager.Initialize()

// Get race type for a model
modelID := int16(1234)
raceType := manager.GetRaceType(modelID)
category := manager.GetRaceTypeCategory(modelID)

// Check creature type
if manager.IsUndead(modelID) {
    // Apply undead-specific mechanics
}
```

### NPC Integration
```go
// Assuming npc implements RaceTypeAware interface
adapter := race_types.NewNPCRaceTypeAdapter(npc, manager)

if adapter.IsDragonkind() {
    // Apply dragon-specific abilities
}

raceInfo := adapter.GetRaceTypeInfo()
fmt.Printf("NPC is a %s (%s)\n", raceInfo.Category, raceInfo.Subcategory)
```

### Category Queries
```go
// Get all creatures in a category
dragons := manager.GetRaceTypesByCategory("DRAGONKIND")
for modelID, raceType := range dragons {
    fmt.Printf("Model %d: %s\n", modelID, raceType.ModelName)
}

// Get statistics
stats := manager.GetStatistics()
fmt.Printf("Total race types: %d\n", stats.TotalRaceTypes)
```

## Database Schema

```sql
CREATE TABLE race_types (
    model_type INTEGER PRIMARY KEY,
    race_id INTEGER NOT NULL CHECK (race_id > 0),
    category TEXT,
    subcategory TEXT,
    model_name TEXT
);
```

## Integration with Other Systems

### NPC System
The race types system integrates with the NPC system to provide:
- Creature classification for AI behavior
- Visual model selection
- Combat mechanics (damage modifiers, resistances)
- Loot table selection

### Combat System
Race types can influence:
- Damage calculations (e.g., bonus damage vs undead)
- Resistance calculations (e.g., dragons resistant to fire)
- Special ability availability

### Spawn System
The spawn system uses race types to:
- Determine which creatures spawn in specific zones
- Apply race-specific spawn behaviors
- Control population distribution

## Performance Considerations

- The master list uses a hash map for O(1) lookups by model ID
- Category and subcategory queries iterate through the list
- Statistics tracking has minimal overhead
- Thread-safe operations ensure data consistency

## Future Enhancements

Potential areas for expansion include:
- Race-specific spell resistances
- Faction relationships based on race types
- Advanced AI behaviors per race category
- Race-specific loot table modifiers
- Integration with scripting system for race-based events

## Differences from C++ Implementation

The Go implementation maintains compatibility with the C++ version while adding:
- Thread-safe operations with proper mutex usage
- Comprehensive statistics tracking
- More extensive validation and error handling
- Additional helper methods for common operations
- Clean interface definitions for system integration