docs

inc/sprite/sprite.manager.lua

@@ -1,5 +1,15 @@
 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)!")
@@ -11,6 +21,17 @@ function Sprite.register(sprite_data)
   _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
@@ -30,10 +51,16 @@ function Sprite.show(id, x, y, colorkey, scale, flip_x, flip_y, 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]