# Spawn System

This package implements the EverQuest II spawn system, converted from the original C++ codebase to Go.

## Overview

The spawn system manages all entities that can appear in the game world, including NPCs, objects, widgets, signs, and ground spawns. It handles their positioning, movement, combat states, and interactions.

## Key Components

### Spawn (`spawn.go`)

The `Spawn` struct is the base class for all entities in the game world. It provides:

- **Basic Properties**: ID, name, level, position, heading
- **State Management**: Health, power, alive status, combat state
- **Movement System**: Position tracking, movement queues, pathfinding
- **Command System**: Interactive commands players can use
- **Loot System**: Item drops, coin rewards, loot distribution
- **Scripting Integration**: Lua script support for dynamic behavior
- **Thread Safety**: Atomic operations and mutexes for concurrent access

Key features:
- Thread-safe operations using atomic values and mutexes
- Extensible design allowing subclasses (NPC, Player, Object, etc.)
- Comprehensive state tracking with change notifications
- Support for temporary variables for Lua scripting
- Equipment and appearance management
- Group and faction relationships

### Spawn Lists (`spawn_lists.go`)

Manages spawn locations and spawn entries:

- **SpawnEntry**: Defines what can spawn at a location with configuration
- **SpawnLocation**: Represents a point in the world where spawns appear
- **SpawnLocationManager**: Manages collections of spawn locations

Features:
- Randomized spawn selection based on percentages
- Position offsets for spawn variety
- Respawn timing with random offsets
- Stat overrides for spawn customization
- Grid-based location management

## Architecture Notes

### Thread Safety

The spawn system is designed for high-concurrency access:
- Atomic values for frequently-accessed state flags
- Read-write mutexes for complex data structures
- Separate mutexes for different subsystems to minimize contention

### Memory Management

Go's garbage collector handles memory management, but the system includes:
- Proper cleanup methods for complex structures
- Resource pooling where appropriate
- Efficient data structures to minimize allocations

### Extensibility

The base Spawn struct is designed to be extended:
- Virtual method patterns using interfaces
- Type checking methods (IsNPC, IsPlayer, etc.)
- Extensible command and scripting systems

## TODO Items

Many features are marked with TODO comments for future implementation:

### High Priority
- **Zone System Integration**: Zone server references and notifications
- **Client System**: Player client connections and packet handling
- **Item System**: Complete item and equipment implementation
- **Combat System**: Damage calculation and combat mechanics

### Medium Priority
- **Lua Scripting**: Full Lua integration for spawn behavior
- **Movement System**: Pathfinding and advanced movement
- **Quest System**: Quest requirement checking and progression
- **Map System**: Collision detection and height maps

### Low Priority
- **Region System**: Area-based effects and triggers
- **Housing System**: Player housing integration
- **Transportation**: Mounts and vehicles
- **Advanced Physics**: Knockback and projectile systems

## Usage Examples

### Creating a Basic Spawn

```go
spawn := NewSpawn()
spawn.SetName("a goblin warrior")
spawn.SetLevel(10)
spawn.SetX(100.0)
spawn.SetY(0.0)
spawn.SetZ(200.0)
spawn.SetTotalHP(500)
spawn.SetHP(500)
```

### Managing Spawn Locations

```go
manager := NewSpawnLocationManager()

location := NewSpawnLocation()
location.SetPosition(100.0, 0.0, 200.0)
location.SetOffsets(5.0, 0.0, 5.0) // 5 unit random offset

entry := NewSpawnEntry()
entry.SpawnID = 12345
entry.SpawnPercentage = 75.0
entry.Respawn = 300 // 5 minutes

location.AddSpawnEntry(entry)
manager.AddLocation(1001, location)
```

### Adding Commands

```go
spawn.AddPrimaryEntityCommand(
    "hail",           // command name
    10.0,             // max distance
    "hail_npc",       // internal command
    "Too far away",   // error message
    0,                // cast time
    0,                // spell visual
    true,             // default allow
)
```

## Integration Points

The spawn system integrates with several other systems:

- **Database**: Loading and saving spawn data
- **Network**: Serializing spawn data for clients
- **Zone**: Spawn management within zones
- **Combat**: Damage and death handling
- **Scripting**: Lua event handling
- **Items**: Equipment and loot management

## Performance Considerations

- Position updates use atomic operations to minimize locking
- Command lists are copied on access to prevent race conditions
- Spawn changes are batched and sent efficiently to clients
- Memory usage is optimized for large numbers of concurrent spawns

## Migration from C++

This Go implementation maintains compatibility with the original C++ EQ2EMu spawn system while modernizing the architecture:

- Converted C-style arrays to Go slices
- Replaced manual memory management with garbage collection  
- Used Go's concurrency primitives instead of platform-specific threading
- Maintained the same packet structures and network protocol
- Preserved the same database schema and data relationships

The API surface remains similar to ease porting of existing scripts and configurations.