impostor/inc/sprite/sprite.manager.lua

local _sprites = {}

--- Registers a new sprite or complex sprite definition with the Sprite manager.
-- Overwrites existing sprite if an ID conflict occurs.
-- @param sprite_data table A table containing the sprite definition.
--        Must include an `id` field (string) and either an `s` field (number, for simple sprites)
--        or a `sprites` field (table, for complex sprites).
--        For complex sprites, `sprites` is a table of sub-sprite definitions, each with:
--        - `s` (number): Sprite index.
--        - `x_offset` (number): X-offset relative to the parent sprite's position.
--        - `y_offset` (number): Y-offset relative to the parent sprite's position.
--        - Optional `colorkey`, `scale`, `flip_x`, `flip_y`, `rot` for individual sub-sprites.
function Sprite.register(sprite_data)
  if not sprite_data or not sprite_data.id then
    trace("Error: Invalid sprite object registered (missing id)!")
    return
  end
  if _sprites[sprite_data.id] then
    trace("Warning: Overwriting sprite with id: " .. sprite_data.id)
  end
  _sprites[sprite_data.id] = sprite_data
end

--- Schedules a registered sprite to be drawn at a specific position with optional transformations.
-- The sprite's parameters are stored in `Context.sprites` for deferred rendering by `Sprite.draw()`.
-- If the sprite with the given `id` is already scheduled, its parameters will be updated.
-- @param id string The unique identifier of the sprite to show. Must be registered via `Sprite.register`.
-- @param x number The x-coordinate on the screen where the sprite will be drawn.
-- @param y number The y-coordinate on the screen where the sprite will be drawn.
-- @param[opt] colorkey number The color index to be treated as transparent (default: 0).
-- @param[opt] scale number The scaling factor for the sprite (default: 1).
-- @param[opt] flip_x number Set to 1 to flip the sprite horizontally (default: 0).
-- @param[opt] flip_y number Set to 1 to flip the sprite vertically (default: 0).
-- @param[opt] rot number The rotation of the sprite in degrees (default: 0).
function Sprite.show(id, x, y, colorkey, scale, flip_x, flip_y, rot)
  -- Ensure the sprite exists before attempting to show it
  if not _sprites[id] then
    trace("Error: Attempted to show non-registered sprite with id: " .. id)
    return
  end

  Context.sprites[id] = {
    id = id,
    x = x,
    y = y,
    colorkey = colorkey,
    scale = scale,
    flip_x = flip_x,
    flip_y = flip_y,
    rot = rot,
  }
end

--- Hides a currently displayed sprite by removing it from the `Context.sprites` table.
-- The sprite will no longer be drawn in subsequent frames.
-- @param id string The unique identifier of the sprite to hide.
function Sprite.hide(id)
  Context.sprites[id] = nil
end

--- Draws all sprites currently scheduled in `Context.sprites`.
-- This function retrieves the registered sprite definitions and applies the stored
-- position and transformation parameters. It handles both simple and complex sprites.
function Sprite.draw()
  for id, params in pairs(Context.sprites) do
    local sprite_data = _sprites[id]
    if not sprite_data then
      trace("Error: Sprite id " .. id .. " in Context.sprites is not registered.")
      Context.sprites[id] = nil -- Clean up invalid entry
      -- We should probably continue to the next sprite instead of returning
      -- so that other valid sprites can still be drawn.
    end

    -- Use parameters from Context.sprites, or fall back to sprite_data, then to defaults
    local colorkey = params.colorkey or sprite_data.colorkey or 0
    local scale = params.scale or sprite_data.scale or 1
    local flip_x = params.flip_x or sprite_data.flip_x or 0
    local flip_y = params.flip_y or sprite_data.flip_y or 0
    local rot = params.rot or sprite_data.rot or 0

    if sprite_data.sprites then -- Complex sprite
      for i = 1, #sprite_data.sprites do
        local sub_sprite = sprite_data.sprites[i]
        spr(
          sub_sprite.s,
          params.x + (sub_sprite.x_offset or 0),
          params.y + (sub_sprite.y_offset or 0),
          sub_sprite.colorkey or colorkey,
          sub_sprite.scale or scale,
          sub_sprite.flip_x or flip_x,
          sub_sprite.flip_y or flip_y,
          sub_sprite.rot or rot
        )
      end
    else -- Simple sprite
      spr(sprite_data.s, params.x, params.y, colorkey, scale, flip_x, flip_y, rot)
    end
  end
end