-- =============================================================================
-- Entity Lua API Examples
-- =============================================================================
-- This file demonstrates how to create, manage, and query entities from Lua
-- using the ecs.* Lua API.
--
-- Entities are the fundamental building blocks of the ECS world. Every object
-- in the game world is an entity with a unique numeric ID.
-- =============================================================================

-- =============================================================================
-- Creating Entities
-- =============================================================================

-- Create a new entity. Returns a numeric ID.
local player = ecs.create_entity()
print("Created entity with ID: " .. player)

-- Create multiple entities:
local npc1 = ecs.create_entity()
local npc2 = ecs.create_entity()
local item = ecs.create_entity()

-- =============================================================================
-- Entity Existence and Lifecycle
-- =============================================================================

-- Check if an entity exists:
if ecs.entity_exists(player) then
    print("Player entity exists")
end

-- Check a non-existent entity:
if not ecs.entity_exists(999999) then
    print("Entity 999999 does not exist")
end

-- Destroy an entity:
ecs.destroy_entity(npc2)
if not ecs.entity_exists(npc2) then
    print("npc2 was destroyed")
end

-- =============================================================================
-- Entity Names
-- =============================================================================

-- Set an entity's name:
ecs.set_entity_name(player, "Hero")
ecs.set_entity_name(npc1, "Villager_01")
ecs.set_entity_name(item, "Health_Potion")

-- Get an entity's name:
local name = ecs.get_entity_name(player)
print("Player name: " .. name)

-- Look up an entity by name:
local found = ecs.get_entity_by_name("Villager_01")
if found then
    print("Found entity " .. found .. " with name 'Villager_01'")
end

-- Look up a non-existent name:
local not_found = ecs.get_entity_by_name("Nonexistent")
if not_found == nil then
    print("'Nonexistent' not found (returns nil)")
end

-- =============================================================================
-- Entity Hierarchy (Parent/Children)
-- =============================================================================

-- Create a parent-child hierarchy:
local house = ecs.create_entity()
ecs.set_entity_name(house, "House")

local door = ecs.create_entity()
ecs.set_entity_name(door, "Door")

local window = ecs.create_entity()
ecs.set_entity_name(window, "Window")

-- Check parent of a child (initially none):
local p = ecs.parent(door)
if p == nil then
    print("Door has no parent initially")
end

-- Check children of a parent (initially none):
local kids = ecs.children(house)
print("House has " .. #kids .. " children initially")

-- =============================================================================
-- Practical Example: Creating a Scene
-- =============================================================================

-- Create a complete scene with entities:
function create_scene()
    -- Create terrain
    local terrain = ecs.create_entity()
    ecs.set_entity_name(terrain, "Terrain")

    -- Create lighting
    local sun = ecs.create_entity()
    ecs.set_entity_name(sun, "Sun")

    -- Create buildings
    local buildings = {}
    for i = 1, 3 do
        local bldg = ecs.create_entity()
        ecs.set_entity_name(bldg, "Building_" .. i)
        table.insert(buildings, bldg)
    end

    -- Create characters
    local characters = {}
    for i = 1, 5 do
        local char = ecs.create_entity()
        ecs.set_entity_name(char, "Character_" .. i)
        table.insert(characters, char)
    end

    print("Scene created with:")
    print("  1 terrain entity")
    print("  1 sun entity")
    print("  " .. #buildings .. " buildings")
    print("  " .. #characters .. " characters")

    return {
        terrain = terrain,
        sun = sun,
        buildings = buildings,
        characters = characters
    }
end

local scene = create_scene()

-- =============================================================================
-- Entity ID Properties
-- =============================================================================

-- Entity IDs are positive integers:
local e = ecs.create_entity()
assert(type(e) == "number", "Entity ID should be a number")
assert(e > 0, "Entity ID should be positive")

-- Each entity gets a unique ID:
local ids = {}
for i = 1, 10 do
    ids[i] = ecs.create_entity()
end
for i = 1, 10 do
    for j = i + 1, 10 do
        assert(ids[i] ~= ids[j], "IDs should be unique")
    end
end
print("All 10 entities have unique IDs")

-- Destroyed entity IDs are not reused immediately:
local old_id = ecs.create_entity()
ecs.destroy_entity(old_id)
local new_id = ecs.create_entity()
assert(new_id ~= old_id, "New entity should have different ID")
print("Destroyed entity ID " .. old_id .. " is not reused")

-- =============================================================================
-- Error Handling
-- =============================================================================

-- These operations should not crash:
ecs.destroy_entity(999999)  -- destroying non-existent entity is safe
ecs.set_entity_name(999999, "ghost")  -- setting name on non-existent entity
local n = ecs.get_entity_name(999999)  -- returns empty string
print("Name of non-existent entity: '" .. n .. "'")

print("Entity API examples completed successfully!")
