-- =============================================================================
-- Character Lua API Examples
-- =============================================================================
-- This file demonstrates how to use the ecs.character API for managing
-- character records in the CharacterRegistry.
--
-- The character system provides:
--   - Character creation, deletion, and lookup
--   - Spawning/despawning characters as ECS entities
--   - Pregnancy management (conceive, abort, check progress)
--   - Lineage tracking (parents, children, create_child)
--   - Name management
-- =============================================================================

-- =============================================================================
-- Character Creation
-- =============================================================================

-- Create a character with first name, last name, template path, and persistence
local hero = ecs.character.create("Arthur", "Pendragon", "characters/knight", true)
print("Created hero character (ID: " .. hero .. ")")

-- Create a non-persistent character (e.g., a temporary NPC)
local npc = ecs.character.create("Merlin", "the Wise", "characters/wizard", false)
print("Created NPC character (ID: " .. npc .. ")")

-- Create a character without a template path
local villager = ecs.character.create("John", "Smith", "", true)
print("Created villager character (ID: " .. villager .. ")")

-- =============================================================================
-- Character Lookup
-- =============================================================================

-- Find a character by ID
local found = ecs.character.find(hero)
if found then
    print("Found character:")
    print("  ID: " .. found.id)
    print("  Name: " .. found.firstName .. " " .. found.lastName)
    print("  Class: " .. found.className)
    print("  Level: " .. found.level)
    print("  Age: " .. found.ageYears)
    print("  Sex: " .. found.sex)
    print("  Persistent: " .. tostring(found.persistent))
    print("  Pregnant by: " .. found.pregnantByFatherId)
    print("  Pregnancy progress: " .. found.pregnancyProgress)
    print("  Pregnancy max progress: " .. found.pregnancyMaxProgress)
end

-- Find a non-existent character returns nil
local missing = ecs.character.find(99999)
print("Non-existent character: " .. tostring(missing))

-- =============================================================================
-- Listing All Characters
-- =============================================================================

-- Get all character IDs
local all_chars = ecs.character.get_all()
print("All characters (" .. #all_chars .. "):")
for _, id in ipairs(all_chars) do
    local c = ecs.character.find(id)
    if c then
        print("  [" .. id .. "] " .. c.firstName .. " " .. c.lastName)
    end
end

-- =============================================================================
-- Character Name Management
-- =============================================================================

-- Change a character's name
ecs.character.set_name(hero, "Arthur", "the Great")
print("Renamed hero")

-- Verify the name change
local renamed = ecs.character.find(hero)
print("New name: " .. renamed.firstName .. " " .. renamed.lastName)

-- =============================================================================
-- Spawning and Despawning
-- =============================================================================

-- Spawn a character as an ECS entity (returns entity ID)
local entity_id = ecs.character.spawn(hero)
if entity_id then
    print("Spawned hero as entity (ID: " .. entity_id .. ")")
else
    print("Failed to spawn hero")
end

-- Check if a character is spawned
local is_spawned = ecs.character.is_spawned(hero)
print("Hero is spawned: " .. tostring(is_spawned))

-- Despawn a character
local despawned = ecs.character.despawn(hero)
print("Hero despawned: " .. tostring(despawned))

-- Verify despawn
local still_spawned = ecs.character.is_spawned(hero)
print("Hero still spawned: " .. tostring(still_spawned))

-- =============================================================================
-- Pregnancy Management
-- =============================================================================

-- Create two characters for pregnancy demo
local mother = ecs.character.create("Guinevere", "Pendragon", "", true)
local father = ecs.character.create("Lancelot", "du Lac", "", true)

print("Created mother (ID: " .. mother .. ") and father (ID: " .. father .. ")")

-- Conceive a child
local conceived = ecs.character.conceive(mother, father)
print("Conceived: " .. tostring(conceived))

-- Check if pregnant
local pregnant = ecs.character.is_pregnant(mother)
print("Is pregnant: " .. tostring(pregnant))

-- Get pregnancy progress
local progress = ecs.character.get_pregnancy_progress(mother)
if progress then
    print("Pregnancy progress:")
    print("  Progress: " .. progress.progress)
    print("  Max progress: " .. progress.maxProgress)
    print("  Ratio: " .. progress.ratio)
end

-- Abort pregnancy
ecs.character.abort_pregnancy(mother)
print("Pregnancy aborted")

-- Verify abortion
local still_pregnant = ecs.character.is_pregnant(mother)
print("Still pregnant: " .. tostring(still_pregnant))

-- =============================================================================
-- Lineage: Creating Children
-- =============================================================================

-- Create a child from two parents
local child = ecs.character.create_child(mother, father)
print("Created child (ID: " .. child .. ")")

-- Get the child's info
local child_info = ecs.character.find(child)
print("Child name: " .. child_info.firstName .. " " .. child_info.lastName)

-- Get parents of the child
local parents = ecs.character.get_parents(child)
print("Parents of child (" .. #parents .. "):")
for _, parent_id in ipairs(parents) do
    local p = ecs.character.find(parent_id)
    if p then
        print("  [" .. parent_id .. "] " .. p.firstName .. " " .. p.lastName)
    end
end

-- Get children of a parent
local children = ecs.character.get_children(mother)
print("Children of mother (" .. #children .. "):")
for _, child_id in ipairs(children) do
    local c = ecs.character.find(child_id)
    if c then
        print("  [" .. child_id .. "] " .. c.firstName .. " " .. c.lastName)
    end
end

-- =============================================================================
-- Practical: Family Tree
-- =============================================================================

function print_family_tree(character_id, indent)
    indent = indent or ""
    local c = ecs.character.find(character_id)
    if not c then
        print(indent .. "[Unknown character]")
        return
    end

    print(indent .. c.firstName .. " " .. c.lastName .. " (ID: " .. c.id .. ")")

    -- Print children
    local kids = ecs.character.get_children(character_id)
    for _, kid_id in ipairs(kids) do
        print_family_tree(kid_id, indent .. "  ")
    end
end

print("=== Family Tree ===")
print_family_tree(mother)

-- =============================================================================
-- Practical: Character Lifecycle
-- =============================================================================

function character_lifecycle_demo()
    print("=== Character Lifecycle Demo ===")

    -- 1. Create
    local sim = ecs.character.create("Sim", "One", "", true)
    print("1. Created character: " .. sim)

    -- 2. Spawn
    local eid = ecs.character.spawn(sim)
    print("2. Spawned as entity: " .. tostring(eid))

    -- 3. Rename
    ecs.character.set_name(sim, "Simantha", "One")
    print("3. Renamed to: Simantha One")

    -- 4. Despawn
    ecs.character.despawn(sim)
    print("4. Despawned")

    -- 5. Delete
    ecs.character.delete(sim)
    print("5. Deleted")

    -- Verify deletion
    local gone = ecs.character.find(sim)
    print("6. After deletion: " .. tostring(gone))

    print("=== Lifecycle Demo Complete ===")
end

character_lifecycle_demo()

-- =============================================================================
-- API Reference
-- =============================================================================
--
-- ecs.character.create(firstName, lastName, templatePath, persistent) -> int
--   Creates a new character record. Returns the character ID.
--
-- ecs.character.delete(id) -> nil
--   Deletes a character record.
--
-- ecs.character.find(id) -> table or nil
--   Returns character info: id, firstName, lastName, className, level,
--   ageYears, sex, persistent, pregnantByFatherId, pregnancyProgress,
--   pregnancyMaxProgress.
--
-- ecs.character.get_all() -> table of ints
--   Returns all character IDs.
--
-- ecs.character.set_name(id, firstName, lastName) -> nil
--   Updates a character's name.
--
-- ecs.character.spawn(id) -> int or nil
--   Spawns the character as an ECS entity. Returns the entity ID.
--
-- ecs.character.despawn(id) -> bool
--   Despawns the character's entity.
--
-- ecs.character.is_spawned(id) -> bool
--   Returns true if the character is currently spawned.
--
-- ecs.character.conceive(motherId, fatherId) -> bool
--   Initiates pregnancy for the mother.
--
-- ecs.character.abort_pregnancy(motherId) -> nil
--   Aborts the mother's pregnancy.
--
-- ecs.character.is_pregnant(motherId) -> bool
--   Returns true if the mother is pregnant.
--
-- ecs.character.get_pregnancy_progress(motherId) -> table or nil
--   Returns { progress, maxProgress, ratio } or nil if not pregnant.
--
-- ecs.character.create_child(parentA, parentB) -> int
--   Creates a child character from two parents.
--
-- ecs.character.get_parents(childId) -> table of ints
--   Returns the parent IDs of a child.
--
-- ecs.character.get_children(parentId) -> table of ints
--   Returns the child IDs of a parent.
-- =============================================================================

print("Character examples completed successfully!")
