-- =============================================================================
-- Character Class Lua API Examples
-- =============================================================================
-- This file demonstrates how to use the ecs.character_class API for
-- querying character class definitions and managing per-entity character
-- stats, skills, needs, and resource pools.
--
-- The character class system provides:
--   - Database queries for class definitions, stats, skills, and needs
--   - Per-entity runtime stats (level, XP, stats, skills, needs)
--   - Resource pool management (health, mana, stamina, etc.)
-- =============================================================================

-- =============================================================================
-- Database Queries
-- =============================================================================

-- List all registered class names
local class_names = ecs.character_class.get_class_names()
print("Registered classes (" .. #class_names .. "):")
for _, name in ipairs(class_names) do
    print("  - " .. name)
end

-- List all stat names
local stat_names = ecs.character_class.get_stat_names()
print("Stats (" .. #stat_names .. "):")
for _, name in ipairs(stat_names) do
    print("  - " .. name)
end

-- List all skill names
local skill_names = ecs.character_class.get_skill_names()
print("Skills (" .. #skill_names .. "):")
for _, name in ipairs(skill_names) do
    print("  - " .. name)
end

-- List all need names
local need_names = ecs.character_class.get_need_names()
print("Needs (" .. #need_names .. "):")
for _, name in ipairs(need_names) do
    print("  - " .. name)
end

-- =============================================================================
-- Querying Class Definitions
-- =============================================================================

-- Get a specific class definition
local warrior_class = ecs.character_class.get_class("warrior")
if warrior_class then
    print("Warrior class:")
    print("  Name: " .. warrior_class.name)
    print("  Description: " .. warrior_class.description)
    print("  Primary stats (" .. #warrior_class.primary_stats .. "):")
    for _, stat in ipairs(warrior_class.primary_stats) do
        print("    - " .. stat)
    end
else
    print("Warrior class not found (stub database may be empty)")
end

-- =============================================================================
-- Stat Kind Queries
-- =============================================================================

-- Check the kind of a stat (attribute vs resource_pool)
local strength_kind = ecs.character_class.get_stat_kind("strength")
print("Strength stat kind: " .. strength_kind)

local health_kind = ecs.character_class.get_stat_kind("health")
print("Health stat kind: " .. health_kind)

-- Unknown stat returns "unknown"
local unknown_kind = ecs.character_class.get_stat_kind("nonexistent")
print("Unknown stat kind: " .. unknown_kind)

-- =============================================================================
-- Per-Entity Character Stats
-- =============================================================================

-- Create a player entity with character identity
local player = ecs.create_entity()
ecs.set_entity_name(player, "hero")
ecs.set_component(player, "CharacterIdentity", {
    registryId = 1
})

print("Created player entity (ID: " .. player .. ")")

-- Get character level
local level = ecs.character_class.get_level(player)
print("Player level: " .. level)

-- Get current XP
local xp = ecs.character_class.get_xp(player)
print("Player XP: " .. xp)

-- Add XP to the player
local xp_added = ecs.character_class.add_xp(player, 150)
print("XP added: " .. tostring(xp_added))

-- Verify XP was added
local new_xp = ecs.character_class.get_xp(player)
print("Player XP after adding: " .. new_xp)

-- =============================================================================
-- Stat, Skill, and Need Queries
-- =============================================================================

-- Get a specific stat value
local strength = ecs.character_class.get_stat(player, "strength")
print("Player strength: " .. strength)

-- Get a specific skill value
local swordsmanship = ecs.character_class.get_skill(player, "swordsmanship")
print("Player swordsmanship: " .. swordsmanship)

-- Get a specific need value
local hunger = ecs.character_class.get_need(player, "hunger")
print("Player hunger: " .. hunger)

-- Get available attribute/skill points
local available_points = ecs.character_class.get_available_points(player)
print("Available points: " .. available_points)

-- =============================================================================
-- Setting Needs
-- =============================================================================

-- Set a need value (e.g., after eating)
ecs.character_class.set_need(player, "hunger", 0)
print("Set hunger to 0")

-- Verify the change
local new_hunger = ecs.character_class.get_need(player, "hunger")
print("Hunger after setting: " .. new_hunger)

-- =============================================================================
-- Resource Pool Management
-- =============================================================================

-- Get current pool value (e.g., health)
local current_health = ecs.character_class.get_pool_current(player, "health")
print("Current health: " .. current_health)

-- Get maximum pool value
local max_health = ecs.character_class.get_pool_max(player, "health")
print("Max health: " .. max_health)

-- Set current pool value (e.g., after taking damage)
local pool_set = ecs.character_class.set_pool_current(player, "health", 75)
print("Health set to 75: " .. tostring(pool_set))

-- Verify the change
local new_health = ecs.character_class.get_pool_current(player, "health")
print("Health after setting: " .. new_health)

-- =============================================================================
-- Practical: Character Level Up
-- =============================================================================

function level_up(entity, xp_gained)
    print("=== Level Up ===")

    -- Add XP
    ecs.character_class.add_xp(entity, xp_gained)

    -- Get updated level
    local new_level = ecs.character_class.get_level(entity)
    print("New level: " .. new_level)

    -- Get available points
    local points = ecs.character_class.get_available_points(entity)
    print("Points to spend: " .. points)

    -- Increase a stat
    local current_str = ecs.character_class.get_stat(entity, "strength")
    print("Strength was: " .. current_str)

    -- Note: Stats are typically increased via the character system,
    -- not directly through this API. This example shows querying.

    -- Restore health on level up
    local max_hp = ecs.character_class.get_pool_max(entity, "health")
    ecs.character_class.set_pool_current(entity, "health", max_hp)
    print("Health restored to max: " .. max_hp)

    print("=== Level Up Complete ===")
end

level_up(player, 500)

-- =============================================================================
-- Practical: Character Status Report
-- =============================================================================

function print_character_status(entity)
    print("=== Character Status ===")
    print("Level: " .. ecs.character_class.get_level(entity))
    print("XP: " .. ecs.character_class.get_xp(entity))
    print("Available Points: " .. ecs.character_class.get_available_points(entity))

    print("Stats:")
    for _, name in ipairs(stat_names) do
        local val = ecs.character_class.get_stat(entity, name)
        local kind = ecs.character_class.get_stat_kind(name)
        if kind == "resource_pool" then
            local current = ecs.character_class.get_pool_current(entity, name)
            local max = ecs.character_class.get_pool_max(entity, name)
            print("  " .. name .. ": " .. current .. "/" .. max)
        else
            print("  " .. name .. ": " .. val)
        end
    end

    print("Skills:")
    for _, name in ipairs(skill_names) do
        local val = ecs.character_class.get_skill(entity, name)
        print("  " .. name .. ": " .. val)
    end

    print("Needs:")
    for _, name in ipairs(need_names) do
        local val = ecs.character_class.get_need(entity, name)
        print("  " .. name .. ": " .. val)
    end
    print("=== End Status ===")
end

print_character_status(player)

-- =============================================================================
-- API Reference
-- =============================================================================
--
-- Database Queries:
--   ecs.character_class.get_class_names() -> table of strings
--   ecs.character_class.get_stat_names() -> table of strings
--   ecs.character_class.get_skill_names() -> table of strings
--   ecs.character_class.get_need_names() -> table of strings
--   ecs.character_class.get_class(name) -> table or nil
--     Returns { name, description, primary_stats }
--   ecs.character_class.get_stat_kind(name) -> string
--     Returns "attribute", "resource_pool", or "unknown"
--
-- Per-Entity Runtime API:
--   ecs.character_class.get_level(entity_id) -> int
--   ecs.character_class.get_xp(entity_id) -> int
--   ecs.character_class.add_xp(entity_id, amount) -> bool
--   ecs.character_class.get_stat(entity_id, stat_name) -> int
--   ecs.character_class.get_skill(entity_id, skill_name) -> int
--   ecs.character_class.get_need(entity_id, need_name) -> int
--   ecs.character_class.get_available_points(entity_id) -> int
--   ecs.character_class.set_need(entity_id, need_name, value) -> nil
--   ecs.character_class.get_pool_current(entity_id, pool_name) -> int
--   ecs.character_class.get_pool_max(entity_id, pool_name) -> int
--   ecs.character_class.set_pool_current(entity_id, pool_name, value) -> bool
-- =============================================================================

print("Character class examples completed successfully!")
