eq2go/internal/entity/README.md

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

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

Managing Spell Effects

// 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

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

// Recalculate all bonuses
entity.CalculateBonuses()

Pet Management

// 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