Feat: Selector

[DemiAutomatic]

This pull request introduces a new OxSelector class to the imports/selector/shared.lua file, providing a robust utility for managing and selecting items from weighted sets. The class supports both weighted and non-weighted random selection, allows for multiple sets, and includes methods for adding, updating, and removing sets. This addition greatly enhances item selection flexibility and code organization.

This provides a neat way to handle all different types of rng and hides a lot of that repeated code for things like this.

Selector Utility

• Added the OxSelector class, which supports both weighted and non-weighted random selection from sets of items, improving flexibility for random item selection.
• Implemented methods for retrieving single or multiple random items, either weighted or non-weighted, from a specified set.

Set Management

• Provided methods to add, update, and remove sets, allowing dynamic management of item groups within the selector.
• Included methods to retrieve all items from a specific set or all sets, supporting deep cloning for data integrity.

Type Safety and Error Handling

• Incorporated type annotations and assertions throughout the class to ensure correct usage and robust error handling.
• returning tables as deep clones to avoid accidental mutations after fetching a result.

example

---@class OxSelector
local selector = lib.selector:new({
    test = { --- pool size of 10. the cumulative weight of all items in the list
        { 4, { name = "WEAPON_PISTOL", min = 1, max = 5 } },       -- 4/10 chance (40%)
        { 3, { name = "WEAPON_CARBINERIFLE", min = 1, max = 5 } }, -- 3/10 chance (30%)
        { 2, { name = "WEAPON_SHOTGUN", min = 1, max = 5 } },      -- 2/10 chance (20%)
        { 1, { name = "WEAPON_SNIPERRIFLE", min = 1, max = 5 } }   -- 1/10 chance (10%)
    },
    anotherSet = {
        { 1, { fruit = "apple", amount = 3 } },  -- 1/3 chance (33%)
        { 1, { fruit = "banana", amount = 1 } }, -- 1/3 chance (33%)
        { 1, { fruit = "orange", amount = 2 } }  -- 1/3 chance (33%)
    }
})

RegisterCommand("testSelector", function(source, args, raw)
    lib.print.info("Non-weighted random item:", selector:getRandom("test"))
    lib.print.info("Weighted random item:", selector:getRandomWeighted("test"))
    lib.print.info("Non-weighted random item from another set:", selector:getRandom("anotherSet"))
    lib.print.info("Weighted random item from another set:", selector:getRandomWeighted("anotherSet"))

    lib.print.info("Multiple non-weighted random items:", selector:getRandomAmount("test", 3))
    lib.print.info("Multiple weighted random items:", selector:getRandomWeightedAmount("test", 3))

    lib.print.info("Multiple non-weighted random items from another set:", selector:getRandomAmount("anotherSet", 3))
    lib.print.info("Multiple weighted random items from another set:", selector:getRandomWeightedAmount("anotherSet", 3))

    lib.print.info("all items from 'test' set:", selector:getSet("test"))
    lib.print.info("all items from 'anotherSet' set:", selector:getSet("anotherSet"))
    lib.print.info("all items from all sets:", selector:getAllSets())
end)