CLAUDE.md

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

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

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

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

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

# Format and tidy
go fmt ./...; go mod tidy

Architecture Overview

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

Core Systems:

Network: EverQuest II UDP protocol with reliability layer, RC4 encryption, CRC validation
Database: SQLite with simplified query interface, transactions, connection pooling
Packets: XML-driven packet definitions with version-specific formats
Events: 100+ EQ2 functions organized by domain (health/attributes/movement/combat/misc)

Key Systems

Spawn System: Base game entity system with positioning, commands, and scripting. Foundation for all game entities with modern Go concurrency patterns.

Entity System: Combat-capable spawns with spell effects, stats, pet management. Includes InfoStruct for complete character statistics, spell casting, pet management, and bonus calculations.

Spells System: Complete spell management with 50ms processing intervals, comprehensive targeting (self/single/group/AOE), resource management (power/health/concentration), cast/recast timers, interrupt handling, and heroic opportunities.

Player System: Complete player character management extending Entity with experience systems, skill progression, spell management, combat mechanics, social features, currency management, quest integration, spawn management, character flags, and comprehensive cleanup systems. Database integration uses zombiezen SQLite with complete persistence.

NPC System: Non-player characters extending Entity with complete AI, combat, and spell casting. Features brain system, spell management, skill bonuses, movement with runback mechanics, appearance randomization, and AI strategies. Includes specialized brain types (Combat/NonCombat/Blank/Lua/DumbFire pets).

Quest System: Complete quest management with multiple step types (kill/chat/obtain/location/spell/normal/craft/harvest), comprehensive prerequisite system, flexible reward system, step-based progress tracking, Lua action system, quest sharing, and repeatable quest support.

Event System: 137 EQ2 functions organized by domain in internal/events/functions/ - health.go (23 functions), attributes.go (24 functions), movement.go (27 functions), combat.go (36 functions), misc.go (27 functions). Features EventContext with fluent API, thread-safe operations, minimal overhead, type-safe parameter access, and comprehensive registry system.

Trade/Object/Widget/Transmute/Skills/Titles/Races/Classes/Languages/Factions/Ground Spawn/Appearances/Sign Systems: Complete implementations with full EQ2 compatibility, thread-safe operations, and comprehensive integration interfaces.

Development Patterns

Package Structure: Each system follows consistent structure with types.go, constants.go, manager.go, interfaces.go, database.go (where applicable), and README.md.

Thread Safety: All systems implement proper Go concurrency patterns with sync.RWMutex for read-heavy operations, atomic operations for flags/counters, proper lock ordering, and channel-based communication.

Integration Patterns: *Aware interfaces for feature detection, adapter pattern for bridging systems, manager pattern for coordination, event-driven architecture for notifications.

Entity-Pass-By-Pointer: Always pass *entity.Entity (not entity.Entity) to avoid copying locks and improve performance.

Name Padding Handling: Player names from database may have null byte padding from [128]byte arrays. Always use strings.TrimSpace(strings.Trim(name, "\x00")).

Configuration

World Server creates world_config.json with defaults. Command-line flags override JSON configuration.

Dependencies

zombiezen.com/go/sqlite: Modern SQLite driver
golang.org/x/crypto: Cryptographic functions
Go version: 1.24.5, Module: eq2emu

Important Notes

C++ Reference Code: The original C++ EQ2EMu source code is available in /old directory for functionality reference only. Use this to understand game mechanics, algorithms, and expected behavior - NOT for structure or patterns. The Go implementation uses modern Go practices and patterns.

Database Migration: Uses zombiezen SQLite with sqlite.Conn, sqlitex.Execute with ExecOptions and ResultFunc, proper found flag handling, and thread-safe connection management.

Architecture Transition: Converted from C++ EQ2EMu codebase maintaining protocol compatibility while modernizing implementation.

Testing: Focus on UDP protocol and packet parsing for client compatibility. All systems include comprehensive test suites with concurrency testing.

5.4 KiB Raw Blame History