166 lines
5.3 KiB
Markdown
166 lines
5.3 KiB
Markdown
# 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. |