LibCommon Module for Roblox

--[[ LibCommon Module, by WackoMcGoose

So yeah, figured I'd share this neat little pile of functions with you guys. I created these for use in Roblox Kart: Courses Unlimited, but they're generic enough and useful enough to use in any game. In particular, makeDataValue and makeInstance(WithProperties) ought to save you quite a bit of typing.

Releasing this as open source (because again, they're just simple little utility methods I think any Roblox dev could find useful, and I doubt I'm the first to come up with them - in particular getRecursiveChildren is a no-brainer that should be stock code), credit appreciated but not required.

Usage: Just paste wholecloth into a ModuleScript, require() that thing, then requiredModule.someName("Some", "list", of, { params }).

]]

local module = {}

--Create a %SOMETHING%Value object, optionally setting its value
--Params: String class, String name, Instance parent, [Data type corresponding to object] value (optional)
--Returns: Instance %SOMETHING%Value, or nil
module.makeDataValue = function(class, name, parent, value)
    local outputdis = nil
    local diditwork = pcall(function()
        outputdis = Instance.new(class)
        outputdis.Name = name
        outputdis.Parent = parent
        if value ~= nil then outputdis.Value = value end
    end)
    if diditwork then return outputdis else return nil end
end

--Create... well, an Instance of something. Dead-simple, just makes a default of an object.
--Params: String class, String name, Instance parent
--Returns: Instance (ClassName = class), or nil
module.makeInstance = function(class, name, parent)
    local outputdis = nil
    local diditwork = pcall(function()
        outputdis = Instance.new(class)
        outputdis.Name = name
        outputdis.Parent = parent
    end)
    if diditwork then return outputdis else return nil end
end

--Create an Instance of something, and set properties in it.
--Params: String class, String name, Instance parent, Table properties (format: {PropertyName = PropertyValue, ...}, invalid things will be ignored)
--Returns: Instance (ClassName = class), or nil
module.makeInstanceWithProperties = function(class, name, parent, properties)
    local outputdis = module.makeInstance(class, name, parent)
    if outputdis == nil then return nil end
    for property, value in pairs(properties) do pcall(function() outputdis[property] = value end) end
    return outputdis
end

--Set multiple properties of an existing Instance
--Params: Instance object, Table properties (format: {PropertyName = PropertyValue, ...}, invalid things will be ignored)
--Returns: Instance (same as passed in), or nil
module.setPropertiesInInstance = function(object, properties)
    if object == nil or properties == nil then return end
    if not pcall(function() object:IsA("Instance") end) then return end --If pcall fails (IsA not valid member), then it's not an Instance!
    for property, value in pairs(properties) do pcall(function() object[property] = value end) end
    return object --Eh, for convenience
end

--Clone specified properties from one Instance to another, using the given table to specify which properties to copy
--Params: Instance source (copy things from), Instance target (copy things to), Table propsCloneList (format: {"PropertyName", ...}, invalid things will be ignored)
--Returns: Instance (target that params were cloned to), or nil
module.clonePropertiesToInstance = function(source, target, propsCloneList)
    if source == nil or target == nil or propsCloneList == nil then return end
    if not pcall(function() source:IsA("Instance") target:IsA("Instance") end) then return end --See above reasoning
    --Uncomment next line if you want it to be strict (must be same ClassName to be valid)
    --  if source.ClassName ~= target.ClassName then return end
    --Uncomment next line if you want it to be /semi/-strict (doesn't have to be same ClassName, but one must be inheriting class of another)
    --  if not source:IsA(target.ClassName) and not target:IsA(source.ClassName) then return end

    --Now clone values of source's properties, for named props in propsCloneList, into target (will only do it if both have a prop of that name)
    --Note: Unlike the other methods, propsCloneList goes with /values/ for which prop, not keys
    for _, property in pairs(propsCloneList) do pcall(function() target[property] = source[property] end) end
    return target --Eh, why not.
end

--Essentially the same as makeInstanceWithProperties, but with an additional shortcut for setting Surfaces (defaults to Smooth)
--Params: String class, String name, Instance parent, Table properties (format: {PropertyName = PropertyValue, ...}) (optional), Table surfaces (format: {*Surface = Enum.SurfaceType,...}) (optional)
--Returns: Instance (BasePart of type class), or nil if class was not a BasePart ClassName
module.makePart = function(class, name, parent, properties, surfaces)
    local outputdis = module.makeInstanceWithProperties(class, name, parent, properties)
    if outputdis == nil then return nil end
    if not outputdis:IsA("BasePart") then return nil end
    if surfaces == nil then surfaces = {} end
    outputdis.TopSurface = surfaces.TopSurface or "Smooth"
    outputdis.BottomSurface = surfaces.BottomSurface or "Smooth"
    outputdis.LeftSurface = surfaces.LeftSurface or "Smooth"
    outputdis.RightSurface = surfaces.RightSurface or "Smooth"
    outputdis.FrontSurface = surfaces.FrontSurface or "Smooth"
    outputdis.BackSurface = surfaces.BackSurface or "Smooth"
    if outputdis:IsA("FormFactorPart") then outputdis.FormFactor = "Custom" end
    return outputdis
end

--Make a Weld object, with the cframes set to the current cframes of the specified parts
--Assumes that both params are BaseParts, will silently fail otherwise
--Params: Instance(BasePart) part0, Instance(BasePart) part1
--Returns: Instance (Weld that was created), or nil
module.makeWeld = function(part0, part1)
    local weld = nil
    local diditwork = pcall(function()
        weld = Instance.new("Weld")
        weld.Part0 = part0
        weld.C0 = part0.CFrame - part0.Position
        weld.Part1 = part1
        weld.C1 = (part1.CFrame - part0.Position):inverse()
        weld.Parent = part0
    end)
    if diditwork then return weld else return nil end
end

--Makes a copy of a table, with the objects scrambled, either randomly or random-by-seed
--Params: Table scrambleDis (format: Array, arbitrary values), Integer seed (optional)
--Returns: Table (scrambled copy of passed-in table), or nil
module.scrambleTable = function(scrambleDis, seed)
    local success, scrambled = pcall(function()
        local result = {}
        local toAdd = scrambleDis
        if seed ~= nil and pcall(function() return seed + 1 end) then math.randomseed(seed) end --Set random seed if seed is provided (and is a number)
        for i = 1, #scrambleDis do
            local index = math.random(1, #toAdd)
            result[i] = toAdd[index]
            table.remove(toAdd, index)
        end
        return result
    end)
    if success then return scrambled else return nil end
end

--Recursive version of Instance:GetChildren(). That's all there is to say on the matter.
--Params: Instance obj
--Returns: Table (all objects that are a descendant of obj, in the same format as Instance:GetChildren()), or nil
module.getRecursiveChildren = function(obj)
    if not pcall(function() return obj:IsA("Instance") end) then return nil end --Sanity check, that object better be an Instance
    local childrens = {}
    for _,v in pairs(obj:GetChildren()) do
        table.insert(childrens, v)
        if #v:GetChildren() > 0 then
            local subChildrens = module.getRecursiveChildren(v)
            for _2,v2 in pairs(subChildrens) do
                table.insert(childrens, v2)
            end
        end
    end
    return childrens
end

--Weighted random: Pass in a table of key-value pairs, where the keys can be either ints or strings, and values are ints >= 1.
--Will return one of the keys randomly (based on weights), or nil if the table be invalid.
--Params: Table (format: {Integer/String key = Integer value, ...})
--Returns: Integer/String key, or nil if you did tables wrong
module.weightedRandom = function(values)
    result = nil
    pcall(function()
        local index = 1
        local weighttable = {}
        --Set up table, eith 'value' copies of 'key'
        for key, value in pairs(values) do
            if value < 1 then value = 1 end
            for i = 1, value do
                weighttable[index] = key
                index = index + 1
            end
        end
        result = weighttable[math.random(1, #weighttable)]
    end)
    return result
end

return module