-- =============================================================================
-- CharacterSpawner Component Lua API Example
-- =============================================================================
-- This file demonstrates how to create a character spawner from Lua.
--
-- A CharacterSpawner entity references a character in the CharacterRegistry and
-- automatically spawns/despawns that character based on camera distance. The
-- spawner uses the entity's TransformComponent for the spawn position and
-- rotation.
--
-- Distances are stored squared on the component for efficient comparison, so
-- set spawnDistanceSq and despawnDistanceSq to the square of the desired
-- distance.
-- =============================================================================

-- =============================================================================
-- Creating a Character Spawner
-- =============================================================================

local spawner = ecs.create_entity()
ecs.set_entity_name(spawner, "Village Guard Spawner")

-- The spawner needs a world transform so the system knows where to spawn the
-- character.
ecs.set_component(spawner, "Transform", {
    position = { 120.0, 0.0, 240.0 },
    rotation = { 1, 0, 0, 0 },  -- quaternion w, x, y, z
    scale = { 1, 1, 1 }
})

-- Add the spawner component. registryId is the ID of a character in the
-- CharacterRegistry. spawnDistanceSq / despawnDistanceSq are squared distances
-- in world units.
ecs.set_component(spawner, "CharacterSpawner", {
    registryId = 42,
    spawnDistanceSq = 100.0 * 100.0,   -- spawn when camera is within 100 units
    despawnDistanceSq = 200.0 * 200.0  -- despawn when camera is beyond 200 units
})

print("Created character spawner at (120, 0, 240) for registry character 42")

-- =============================================================================
-- Querying and Updating a Spawner
-- =============================================================================

if ecs.has_component(spawner, "CharacterSpawner") then
    local s = ecs.get_component(spawner, "CharacterSpawner")
    print("Spawner registryId: " .. s.registryId)
    print("Spawner spawnDistanceSq: " .. s.spawnDistanceSq)
    print("Spawner despawnDistanceSq: " .. s.despawnDistanceSq)
end

-- Change which character is spawned by updating the registry ID:
ecs.set_field(spawner, "CharacterSpawner", "registryId", 7)

-- Adjust distances using squared values:
ecs.set_field(spawner, "CharacterSpawner", "spawnDistanceSq", 150.0 * 150.0)
ecs.set_field(spawner, "CharacterSpawner", "despawnDistanceSq", 300.0 * 300.0)

local updated = ecs.get_component(spawner, "CharacterSpawner")
print("Updated spawner registryId: " .. updated.registryId)
print("Updated spawnDistanceSq: " .. updated.spawnDistanceSq)
print("Updated despawnDistanceSq: " .. updated.despawnDistanceSq)

-- =============================================================================
-- Creating a Dynamic Character and Spawning it Automatically
-- =============================================================================

-- Create a character record at runtime. The returned value is the registry ID
-- that the CharacterSpawner component references.
local dynamicNpc = ecs.character.create("Bree", "Miller", "", true)
print("Created dynamic character (ID: " .. dynamicNpc .. ")")

-- Create another spawner entity that will automatically spawn Bree when the
-- camera gets close and despawn her when the camera moves away.
local dynamicSpawner = ecs.create_entity()
ecs.set_entity_name(dynamicSpawner, "Bree Miller Spawner")

ecs.set_component(dynamicSpawner, "Transform", {
    position = { 50.0, 0.0, 80.0 },
    rotation = { 1, 0, 0, 0 },
    scale = { 1, 1, 1 }
})

ecs.set_component(dynamicSpawner, "CharacterSpawner", {
    registryId = dynamicNpc,
    spawnDistanceSq = 80.0 * 80.0,
    despawnDistanceSq = 160.0 * 160.0
})

print("Dynamic spawner set up for character " .. dynamicNpc)

-- You can still query the spawner settings:
local dynamicSettings = ecs.get_component(dynamicSpawner, "CharacterSpawner")
print("Dynamic spawner registryId: " .. dynamicSettings.registryId)
print("Dynamic spawner spawnDistanceSq: " .. dynamicSettings.spawnDistanceSq)

-- The CharacterSpawnerSystem will now manage the spawned entity automatically.
-- The registry record stays even if the spawned instance is despawned, so the
-- character can be respawned again later.

-- =============================================================================
-- Removing a Spawner
-- =============================================================================

-- Removing the component will also despawn any currently spawned character
-- instance managed by this spawner.
ecs.remove_component(spawner, "CharacterSpawner")
ecs.remove_component(dynamicSpawner, "CharacterSpawner")

if not ecs.has_component(spawner, "CharacterSpawner") and
   not ecs.has_component(dynamicSpawner, "CharacterSpawner") then
    print("CharacterSpawner components removed; any spawned instances were despawned")
end

print("CharacterSpawner example completed successfully!")
