Dragon-Knight/internal/monsters/doc.go

/*
Package monsters is the active record implementation for monsters in the game.

# Basic Usage

To retrieve a monster by ID:

	monster, err := monsters.Find(db, 1)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("Found monster: %s (level: %d, HP: %d)\n", monster.Name, monster.Level, monster.MaxHP)

To get all monsters:

	allMonsters, err := monsters.All(db)
	if err != nil {
		log.Fatal(err)
	}
	for _, monster := range allMonsters {
		fmt.Printf("Monster: %s\n", monster.Name)
	}

To filter monsters by level:

	level5Monsters, err := monsters.ByLevel(db, 5)
	if err != nil {
		log.Fatal(err)
	}

To get monsters within a level range:

	monsters1to10, err := monsters.ByLevelRange(db, 1, 10)
	if err != nil {
		log.Fatal(err)
	}

To filter monsters by immunity type:

	hurtImmune, err := monsters.ByImmunity(db, monsters.ImmuneHurt)
	if err != nil {
		log.Fatal(err)
	}

# Creating Monsters with Builder Pattern

The package provides a fluent builder interface for creating new monsters:

	monster, err := monsters.NewBuilder(db).
		WithName("Fire Dragon").
		WithMaxHP(500).
		WithMaxDmg(100).
		WithArmor(50).
		WithLevel(25).
		WithMaxExp(1000).
		WithMaxGold(500).
		WithImmunity(monsters.ImmuneHurt).
		Create()

	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("Created monster with ID: %d\n", monster.ID)

# Updating Monsters

Monsters can be modified and saved back to the database:

	monster, _ := monsters.Find(db, 1)
	monster.Name = "Enhanced Blue Slime"
	monster.MaxHP = 10
	monster.Level = 2
	
	err := monster.Save()
	if err != nil {
		log.Fatal(err)
	}

# Deleting Monsters

Monsters can be removed from the database:

	monster, _ := monsters.Find(db, 1)
	err := monster.Delete()
	if err != nil {
		log.Fatal(err)
	}

# Monster Immunity Types

The package defines immunity type constants:

	monsters.ImmuneNone  = 0  // No immunity
	monsters.ImmuneHurt  = 1  // Immune to Hurt spells (Pain, Maim, Rend, Chaos)
	monsters.ImmuneSleep = 2  // Immune to Sleep spells (Sleep, Dream, Nightmare)

Helper methods are available to check immunity:

	if monster.IsHurtImmune() {
		fmt.Println("This monster is immune to Hurt spells")
	}
	if monster.IsSleepImmune() {
		fmt.Println("This monster is immune to Sleep spells")
	}
	if monster.HasImmunity() {
		fmt.Printf("Monster has immunity: %s\n", monster.ImmunityName())
	}

# Database Schema

The monsters table has the following structure:

	CREATE TABLE monsters (
		id       INTEGER PRIMARY KEY AUTOINCREMENT,
		name     TEXT NOT NULL,
		max_hp   INTEGER NOT NULL DEFAULT 0,
		max_dmg  INTEGER NOT NULL DEFAULT 0,
		armor    INTEGER NOT NULL DEFAULT 0,
		level    INTEGER NOT NULL DEFAULT 0,
		max_exp  INTEGER NOT NULL DEFAULT 0,
		max_gold INTEGER NOT NULL DEFAULT 0,
		immune   INTEGER NOT NULL DEFAULT 0
	)

Where:
  - id: Unique identifier
  - name: Display name of the monster
  - max_hp: Maximum hit points
  - max_dmg: Maximum damage per attack
  - armor: Armor class/defense rating
  - level: Monster level (affects encounter chances)
  - max_exp: Maximum experience points awarded when defeated
  - max_gold: Maximum gold awarded when defeated
  - immune: Immunity type (0=none, 1=hurt spells, 2=sleep spells)

# Monster Statistics

## Combat Stats

The core combat statistics define the monster's fighting capability:

	fmt.Printf("HP: %d, Damage: %d, Armor: %d\n", 
		monster.MaxHP, monster.MaxDmg, monster.Armor)

## Rewards

Monsters provide experience and gold rewards when defeated:

	fmt.Printf("Rewards: %d exp, %d gold\n", 
		monster.MaxExp, monster.MaxGold)

## Utility Methods

The package provides several utility methods for analyzing monsters:

	// Difficulty rating based on stats relative to level
	difficulty := monster.DifficultyRating()
	fmt.Printf("Difficulty: %.2f\n", difficulty)
	
	// Experience efficiency (exp per HP)
	expEfficiency := monster.ExpPerHP()
	fmt.Printf("Exp per HP: %.2f\n", expEfficiency)
	
	// Gold efficiency (gold per HP)
	goldEfficiency := monster.GoldPerHP()
	fmt.Printf("Gold per HP: %.2f\n", goldEfficiency)

These methods help with:
  - Balancing monster difficulty
  - Identifying efficient farming targets
  - Analyzing risk/reward ratios

# Level-Based Queries

Monsters are commonly filtered by level for encounter generation:

	// Get all monsters at a specific level
	level10Monsters, err := monsters.ByLevel(db, 10)
	
	// Get monsters within a level range (inclusive)
	earlyGameMonsters, err := monsters.ByLevelRange(db, 1, 5)
	
	// All monsters are ordered by level, then ID for consistent results

# Immunity System

The immunity system affects spell combat mechanics:

	// Check specific immunities
	if monster.IsHurtImmune() {
		// Hurt spells (Pain, Maim, Rend, Chaos) won't work
	}
	if monster.IsSleepImmune() {
		// Sleep spells (Sleep, Dream, Nightmare) won't work
	}
	
	// Get all monsters with specific immunity
	hurtImmuneMonsters, err := monsters.ByImmunity(db, monsters.ImmuneHurt)

# Error Handling

All functions return appropriate errors for common failure cases:
  - Monster not found (Find returns error for non-existent IDs)
  - Database connection issues
  - Invalid operations (e.g., saving/deleting monsters without IDs)
*/
package monsters