108 lines
6.3 KiB
Markdown
108 lines
6.3 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Code Quality Requirements
|
|
|
|
**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
|
|
|
|
## 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
|
|
|
|
```bash
|
|
# 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. |