eq2go/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

EQ2Go is a Go rewrite of the EverQuest II server emulator from C++ EQ2EMu. Implements core MMO server functionality with authentication, world simulation, and game mechanics using modern Go practices.

## Development Commands

### Building the Project
```bash
# Build login server
go build -o bin/login_server ./cmd/login_server

# Build world server  
go build -o bin/world_server ./cmd/world_server

# Build both servers
go build ./cmd/...
```

### Running the Servers
```bash
# Run login server (requires login_config.json)
./bin/login_server

# Run world server (creates world_config.json with defaults if missing)
./bin/world_server

# With custom configuration
./bin/world_server -listen-port 9001 -web-port 8081 -log-level debug
```

### Testing
```bash
# Run all tests
go test ./...

# Test specific packages
go test ./internal/udp
go test ./internal/packets/parser

# Run tests with verbose output
go test -v ./...

# Test with race detection
go test -race ./...
```

### Development Tools
```bash
# Format code
go fmt ./...

# Run linter (if golangci-lint is installed)
golangci-lint run

# Tidy modules
go mod tidy

# Check for vulnerabilities
go run golang.org/x/vuln/cmd/govulncheck@latest ./...
```

## Architecture Overview

### Core Components

**Login Server** - Client authentication, character management, world server coordination  
**World Server** - Game simulation engine, zones, NPCs, combat, quests, web admin interface

**Shared Libraries:**
- `common/` - EQ2-specific data types and constants  
- `database/` - SQLite wrapper with simplified query interface
- `udp/` - Custom UDP protocol with reliability layer
- `packets/` - XML-driven packet definition parser
- `achievements/` - Achievement system
- `spawn/` - Base game entity system (positioning, commands, scripting)
- `entity/` - Combat-capable entities with spell effects, stats, pet management
- `spells/` - Complete spell system with casting mechanics and processing  
- `titles/` - Character title system with achievement integration
- `trade/` - Player trading system with item/coin exchange and validation
- `object/` - Interactive objects extending spawn system (merchants, transporters, devices, collectors)
- `races/` - Race system with all EQ2 races, alignment classification, stat modifiers, and entity integration

### Network Protocol
EverQuest II UDP protocol with reliability layer, RC4 encryption, CRC validation, connection management, packet combining.

### Database Layer  
SQLite with simplified query interface, transactions, connection pooling, parameter binding.

### Packet System
XML-driven packet definitions with version-specific formats, conditional fields, templates, dynamic arrays.

## Key Files and Locations

**Server Entry Points:**
- `cmd/login_server/main.go`: Login server startup and configuration
- `cmd/world_server/main.go`: World server startup with command-line options

**Core Data Structures:**
- `internal/common/types.go`: EQ2-specific types (EQ2Color, EQ2Equipment, AppearanceData, etc.)

**Network Implementation:**
- `internal/udp/server.go`: Multi-connection UDP server
- `internal/udp/connection.go`: Individual client connection handling
- `internal/udp/protocol.go`: Protocol packet types and constants

**Database:**
- `internal/database/wrapper.go`: Simplified SQLite interface
- Database files: `login.db`, `world.db` (created automatically)

**Spawn System:**
- `internal/spawn/spawn.go`: Base spawn entity with position, stats, commands, and scripting
- `internal/spawn/spawn_lists.go`: Spawn location and entry management
- `internal/spawn/README.md`: Comprehensive spawn system documentation

**Entity System:**
- `internal/entity/entity.go`: Combat-capable spawn extension with spell casting and pet management
- `internal/entity/info_struct.go`: Comprehensive character statistics and information management
- `internal/entity/spell_effects.go`: DEPRECATED - now imports from spells package
- `internal/entity/README.md`: Complete entity system documentation

**Spells System:**
- Core: `spell_data.go`, `spell.go`, `spell_effects.go`, `spell_manager.go`, `constants.go`
- Processing: `process_constants.go`, `spell_process.go`, `spell_targeting.go`, `spell_resources.go`  
- Docs: `README.md`, `SPELL_PROCESS.md`

**Titles System:**
- `internal/titles/title.go`: Core title data structures and player title management
- `internal/titles/constants.go`: Title system constants, categories, and rarity levels
- `internal/titles/master_list.go`: Global title registry and management with categorization
- `internal/titles/player_titles.go`: Individual player title collections and active title tracking
- `internal/titles/title_manager.go`: Central title system coordinator with background cleanup
- `internal/titles/integration.go`: Integration systems for earning titles through achievements, quests, PvP, events
- `internal/titles/README.md`: Complete title system documentation

**Trade System:**
- `internal/trade/trade.go`: Core trade mechanics with two-party item/coin exchange
- `internal/trade/types.go`: Trade data structures, participants, and validation
- `internal/trade/constants.go`: Trade constants, error codes, and configuration
- `internal/trade/utils.go`: Coin calculations, validation helpers, and formatting
- `internal/trade/manager.go`: Trade service with high-level management and placeholders

**Object System:**
- `internal/object/object.go`: Core object mechanics extending spawn functionality with interaction
- `internal/object/constants.go`: Object constants, spawn types, and interaction types
- `internal/object/manager.go`: Object manager with zone-based and type-based indexing
- `internal/object/integration.go`: Spawn system integration with ObjectSpawn wrapper
- `internal/object/interfaces.go`: Integration interfaces for trade/spell systems and entity adapters

**Race System:**
- `internal/races/races.go`: Core race management with all 21 EQ2 races and alignment mapping
- `internal/races/constants.go`: Race IDs, names, and display constants
- `internal/races/utils.go`: Race utilities with stat modifiers, descriptions, and parsing
- `internal/races/integration.go`: Entity system integration with RaceAware interface
- `internal/races/manager.go`: High-level race management with statistics and command processing

**Packet Definitions:**
- `internal/packets/xml/`: XML packet structure definitions
- `internal/packets/PARSER.md`: Packet definition language documentation
- `internal/packets/parser/`: Parser implementation for XML packet definitions

## Configuration

**Login Server**: Requires `login_config.json` with database and server settings

**World Server**: Creates `world_config.json` with defaults:
```json
{
    "listen_addr": "0.0.0.0",
    "listen_port": 9000,
    "max_clients": 1000,
    "web_port": 8080,
    "database_path": "world.db",
    "log_level": "info"
}
```

Command-line flags override JSON configuration.

## Important Dependencies

**Core Dependencies:**
- `zombiezen.com/go/sqlite`: Modern SQLite driver
- `golang.org/x/crypto`: Cryptographic functions

**Module Information:**
- Go version: 1.24.5
- Module name: `eq2emu`

## Development Notes

**Architecture Transition**: This Go implementation is based on the extensive C++ EQ2EMu codebase documented in `EQ2EMU_Architecture_White_Paper.md`. The Go version maintains compatibility with the original protocol while modernizing the implementation.

**Packet Handling**: The XML packet definition system allows for easy addition of new packet types without code changes. See `internal/packets/PARSER.md` for syntax reference.

**Database Schema**: Currently uses SQLite for development/testing. Production deployments may require migration to PostgreSQL or MySQL for better concurrent access.

**Spawn System**: The spawn system (`internal/spawn/`) provides the foundation for all game entities. It's converted from the C++ EQ2EMu codebase with modern Go concurrency patterns.

**Entity System**: The entity system (`internal/entity/`) extends spawns with combat capabilities, implementing the complete EverQuest II character statistics system, spell effect management, and pet systems. Key features include:
- **InfoStruct**: Complete character statistics (attributes, resistances, experience, currency, equipment data)
- **Entity**: Combat-capable spawn with spell casting, pet management, and bonus calculations
- **Thread Safety**: All systems use proper Go concurrency patterns with mutexes and atomic operations
- **Stat Calculations**: Dynamic stat calculations with bonuses from equipment, spells, and other sources
- **Pet Management**: Support for multiple pet types (summon, charm, deity, cosmetic) with proper ownership tracking

**Spells System**: Complete spell management with spell definitions, effect system, and real-time casting engine. Features spell processing (50ms intervals), comprehensive targeting (self/single/group/AOE), resource management (power/health/concentration), cast/recast timers, interrupt handling, heroic opportunities, and thread-safe operations.

**Titles System**: Character title management with prefix/suffix positioning, categories, rarity levels, achievement integration, and thread-safe operations.

**Trade System**: Player-to-player trading with item/coin exchange, validation (no-trade, heirloom restrictions), slot management, acceptance workflow, bot trading support, and client version compatibility (6/12 slots).

**Object System**: Interactive world objects extending spawn system with merchants, transporters, devices, and collectors. Features clickable interaction, command handling, device IDs, size randomization, transport/teleport support, and complete spawn integration with entity/item adapters for trade/spell system compatibility.

**Race System**: Complete EverQuest II race management with all 21 races (Human through Aerakyn), alignment classification (good/evil/neutral), racial stat modifiers, starting locations, lore descriptions, and full entity system integration. Features randomization by alignment, compatibility checking, usage statistics, and RaceAware interface for seamless integration with existing systems.

All systems are converted from C++ with TODO comments marking areas for future implementation (LUA integration, advanced mechanics, etc.).

**Testing**: Focus testing on the UDP protocol layer and packet parsing, as these are critical for client compatibility.

## Code Documentation Standards

**Function Documentation**: All functions must have thorough documentation explaining their purpose, parameters, return values, and any important behavior. Do NOT follow the standard Go convention of starting comments with the function name - instead, write clear explanations of what the function does.

**Examples:**

Good:
```go
// Creates a new UDP server instance with the specified address and packet handler.
// The server will listen on the given address and route incoming packets to the handler.
// Returns an error if the address is invalid or the socket cannot be bound.
func NewServer(addr string, handler PacketHandler, config ...Config) (*Server, error) {
```

Poor (standard Go convention - avoid this):
```go
// NewServer creates a new UDP server instance with the specified address and packet handler.
func NewServer(addr string, handler PacketHandler, config ...Config) (*Server, error) {
```

**Additional Documentation Requirements:**
- Document all public types, constants, and variables
- Include examples in documentation for complex functions
- Explain any non-obvious algorithms or business logic
- Document error conditions and edge cases
- For packet-related code, reference the relevant XML definitions or protocol specifications