# Entity Package

The Entity package provides the core combat and magic systems for EverQuest II server emulation. It extends the base Spawn system with combat capabilities, spell effects, and character statistics management.

## Overview

The Entity system is built on three main components:

1. **InfoStruct** - Comprehensive character statistics and information
2. **SpellEffectManager** - Manages all spell effects, buffs, debuffs, and bonuses
3. **Entity** - Combat-capable spawn with spell casting and pet management

## Architecture

```
Spawn (base class)
  └── Entity (combat-capable)
      ├── Player (player characters)
      └── NPC (non-player characters)
```

## Core Components

### InfoStruct

Contains all character statistics including:
- Primary attributes (STR, STA, AGI, WIS, INT)
- Combat stats (attack, mitigation, avoidance)
- Resistances (heat, cold, magic, mental, divine, disease, poison)
- Experience points and currency
- Equipment and weapon information
- Group and encounter settings

**Thread Safety**: All access methods use RWMutex for safe concurrent access.

### SpellEffectManager

Manages four types of spell effects:

1. **Maintained Effects** - Buffs that consume concentration
2. **Spell Effects** - Temporary buffs/debuffs with durations
3. **Detrimental Effects** - Debuffs and harmful effects
4. **Bonus Values** - Stat modifications from various sources

**Key Features**:
- Automatic expiration handling
- Control effect tracking (stun, root, mez, etc.)
- Bonus calculations with class/race/faction requirements
- Thread-safe effect management

### Entity

Combat-capable spawn that extends base Spawn functionality:

**Combat Systems**:
- Health/Power/Savagery management
- Combat state tracking (in combat, casting)
- Damage resistance calculations
- Speed and movement modifiers

**Magic Systems**:
- Spell effect application and removal
- Concentration-based maintained spells
- Bonus stat calculations
- Control effect immunity

**Pet Systems**:
- Multiple pet types (summon, charm, deity, cosmetic)
- Pet ownership and dismissal
- Pet spell tracking

## Usage Examples

### Creating an Entity

```go
entity := NewEntity()
entity.GetInfoStruct().SetName("TestEntity")
entity.GetInfoStruct().SetLevel(50)
entity.GetInfoStruct().SetStr(100.0)
```

### Managing Spell Effects

```go
// Add a maintained spell (buff)
success := entity.AddMaintainedSpell("Heroic Strength", 12345, 300.0, 2)

// Add a temporary effect
entity.AddSpellEffect(54321, casterID, 60.0)

// Add a detrimental effect
entity.AddDetrimentalSpell(99999, attackerID, 30.0, 1)
```

### Stat Calculations

```go
// Get effective stats (base + bonuses)
str := entity.GetStr()
sta := entity.GetSta()
primary := entity.GetPrimaryStat()

// Recalculate all bonuses
entity.CalculateBonuses()
```

### Pet Management

```go
// Set a summon pet
entity.SetPet(petEntity)

// Check pet status
if entity.GetPet() != nil && !entity.IsPetDismissing() {
    // Pet is active
}
```

## Constants and Enums

### Pet Types
- `PetTypeSummon` - Summoned pets
- `PetTypeCharm` - Charmed creatures
- `PetTypeDeity` - Deity pets
- `PetTypeCosmetic` - Cosmetic pets

### Control Effects
- `ControlEffectStun` - Cannot move or act
- `ControlEffectRoot` - Cannot move
- `ControlEffectMez` - Mesmerized
- `ControlEffectDaze` - Dazed
- `ControlEffectFear` - Feared
- `ControlEffectSlow` - Movement slowed
- `ControlEffectSnare` - Movement impaired
- `ControlEffectCharm` - Mind controlled

## Thread Safety

All Entity operations are thread-safe using:
- `sync.RWMutex` for read/write operations
- `sync.atomic` for simple state flags
- Separate mutexes for different subsystems to minimize lock contention

## Integration with Spawn System

The Entity extends the base Spawn class and requires:
- `spawn.NewSpawn()` for initialization
- Access to Spawn position and basic methods
- Integration with zone update systems

## Future Extensions

Areas marked with TODO comments for future implementation:
- Complete item and equipment systems
- Combat calculation methods
- Threat and hate management
- Group combat mechanics
- Spell casting systems
- LUA script integration

## Files

- `entity.go` - Main Entity class implementation
- `info_struct.go` - Character statistics and information
- `spell_effects.go` - Spell effect management system
- `README.md` - This documentation file