Merge branch 'develop' into feature/task110_sprite_silhouette

inc/sprite/sprite.manager.lua

@@ -73,6 +73,70 @@ function Sprite.generate_table(width, height, starting_s, x_base, y_base, x_step
   return sprites
 end
 
+--- Immediately draws a list of sprites
+--- @within Sprite
+--- @param sprite_list table An array of tables, each containing: `id` (string) sprite identifier, `x` (number) x-coordinate, `y` (number) y-coordinate, and optional `colorkey`, `scale`, `flip_x`, `flip_y`, `rot` parameters.
+function Sprite.draw_list(sprite_list)
+  for _, sprite_info in ipairs(sprite_list) do
+    local sprite_data = _sprites[sprite_info.id]
+    if not sprite_data then
+      trace("Error: Attempted to draw non-registered sprite with id: " .. sprite_info.id)
+    else
+      draw_sprite_instance(sprite_data, sprite_info)
+    end
+  end
+end
+
+--- Given a list of sprite IDs (or sprite entries with correction offsets) and a list of possible positions, randomly assigns each sprite to a unique position and returns a drawable list.
+--- @within Sprite
+--- @param sprite_ids table An array of sprite identifier values or tables.
+---                  Each entry may be either:
+---                  - string: sprite ID to draw.
+---                  - table: { sprite_id = string, x_correct = number, y_correct = number }.
+--- @param positions table An array of tables, each containing `x` and `y` fields for possible sprite positions.
+function Sprite.list_randomize(sprite_ids, positions)
+  if #sprite_ids > #positions then
+    trace("Error: More sprite IDs than available positions in Sprite.draw_randomized")
+    return
+  end
+
+  local shuffled_positions = {}
+  for i, pos in ipairs(positions) do
+    shuffled_positions[i] = pos
+  end
+  for i = #shuffled_positions, 2, -1 do
+    local j = math.random(i)
+    shuffled_positions[i], shuffled_positions[j] = shuffled_positions[j], shuffled_positions[i]
+  end
+
+  local drawable_list = {}
+  for i, sprite_entry in ipairs(sprite_ids) do
+    local sprite_id = sprite_entry
+    local x_correct = 0
+    local y_correct = 0
+
+    if type(sprite_entry) == "table" then
+      sprite_id = sprite_entry.sprite_id or sprite_entry.id
+      x_correct = sprite_entry.x_correct or 0
+      y_correct = sprite_entry.y_correct or 0
+    end
+
+    local sprite_data = _sprites[sprite_id]
+    if not sprite_data then
+      trace("Error: Attempted to draw non-registered sprite with id: " .. tostring(sprite_id))
+    else
+      local pos = shuffled_positions[i]
+      table.insert(drawable_list, {
+        id = sprite_id,
+        x = pos.x + x_correct,
+        y = pos.y + y_correct
+      })
+    end
+  end
+
+  return drawable_list
+end
+
 --- Schedules a sprite for drawing.
 --- @within Sprite
 --- @param id string The unique identifier of the sprite.<br/>