RBX.Lua Functions Library

--// ROBLOX-Lua function library
--[[ #Documentation
    GetDescendants(instance Parent)
        <- Returns a table with all the descendants of 'Parent.'
    RemoveFromTable(table Table, variant Value, [,bool RemoveAllOccurrences = false])
        <- Returns a table with the same structure as the given one, but without 'Value' in it.
        <- Does not recurse on tables within tables
        <- Will remove any occurrence of 'Value' UNLESS RemoveAllOccurrences is set to false
    FindInTable(table Table, variant Value, [,bool Recurse = false])
        <- Returns true if 'Value' is found in 'Table'
        <- Optional 'Recurse' parameter to recurse through all descendant tables
    GetAllDirections(instance BasePart)
        <- Returns a table of the directions each side of the part is facing.
        <- Format of returned table is:
            {
                ['up'] = Vector3;
                ['down'] = Vector3;
                ['left'] = Vector3;
                ['right'] = Vector3;
                ['front'] = Vector3;
                ['back'] = Vector3;
            }
    GetSurfaceClosestToPoint(instance BasePart, vector3 Position)
        <- Will return a NormalId enum which is the side of the 'BasePart' that is closest to 'Position'
    GetFormattedRegion3(vector3 Corner, vector3 Corner)
        <- Will return a correctly-formatted Region3 value given these coordinates.
        <- None of the coordinates (x,y,z) can be the same as a co-existing x,y,z of any given vector.
            <- this means, for exame, x of the first vector cannot be equal to x of the second or vice versa
        <- Why is this needed? Typically, you would need to format the first vector with being the smallest numbers; and the second vector having the largest. Check the source of the function for the Lua example.

]]

function GetDescendants(instance)
    getfenv()['_d'] = {};
    if (type(instance) ~= "userdata") or (not pcall(function() return instance['Name'] end)) then
        error("GetDescendants requires an object.");
    end
    local function Get(parent)
        for i,v in pairs(parent:GetChildren()) do
            if (#v:GetChildren() > 0) then
                Get(v);
            end
            table.insert(_d, v)
        end
    end
    Get(instance);
    return _d;
end

function RemoveFromTable(t, val, rac)
    local new_t = {};
    local found = 0;
    local adding = true;
    local rac = (rac ~= nil) and rac or false;
    if (type(rac) ~= "boolean") then
        error("Third argument of RemoveFromTable must be a boolean.");
    end
    if (not val) then
        error("Nil given for value.");
    end
    if
    for i,v in pairs(t) do
        if (v ~= val) then
            table.insert(new_t, v)
        else
            found = found + 1;
            if (not rac) and (adding) then
                adding = false;
            end
            if (not rac) and (adding) then
                table.insert(new_t, v)
            end
        end
    end
    return new_t
end

function FindInTable(t, val, recurse)
    if (type(recurse) ~= "boolean") then
        error("Third argument of FindInTable must be a boolean.");
    end
    local recurse = (recurse ~= nil) and recurse or false;
    local item;
    local function Search(_t)
        for i,v in pairs(_t) do
            if (item) then break end
            if (type(v) == "table") and (recurse) and (v ~= val) then
                Search(v)
            elseif (v == val) then
                item = v;
            end
        end
    end
    Search(t)
    if (item) then
        return true;
    end
end

function GetAllDirections(instance)
    local directions = {};
    if (type(instance) ~= "userdata") or (not pcall(function() return instance['Name'] end)) then
        error("GetAllDirections requires an object.");
    end
    local matrix = instance.CFrame;
    directions['up'] =
        matrix:vectorToWorldSpace( Vector3.new(0,1,0) );
    directions['down'] =
        matrix:vectorToWorldSpace( Vector3.new(0,-1,0) );
    directions['left'] =
        matrix:vectorToWorldSpace( Vector3.new(-1,0,0) );
    directions['right'] =
        matrix:vectorToWorldSpace( Vector3.new(1,0,0) );
    directions['front'] =
        matrix.lookVector;
    directions['back'] =
        -matrix.lookVector;
    return directions;
end

function GetSurfaceClosestToPoint(part, pos)
    if (type(part) ~= "userdata") or (not pcall(function() return part['Name'] end)) then
        error("GetSurfaceClosestToPoint requires an object.");
    end
    local _, count = tostring(pos):gsub(",",",");
    if (type(pos) ~= "userdata" or (count ~= 2) then
        error("Argument 2 for GetSurfaceClosestToPoint must be a Vector3.");
    end
    local rel = part.CFrame:pointToObjectSpace(pos)
    if (math.abs(rel.Z) > math.abs(rel.Y)) and (math.abs(rel.Z) > math.abs(rel.X)) then
        if (rel.Z > 0) then
            return Enum.NormalId.Back
        else
            return Enum.NormalId.Front
        end
    elseif (math.abs(rel.Y) > math.abs(rel.Z)) and (math.abs(rel.Y) > math.abs(rel.X)) then
        if (rel.Y > 0) then
            return Enum.NormalId.Top
        else
            return Enum.NormalId.Bottom
        end
    elseif (math.abs(rel.X) > math.abs(rel.Z) and math.abs(rel.X) > math.abs(rel.Y)) then
        if (rel.X > 0) then
            return Enum.NormalId.Right
        else
            return Enum.NormalId.Left
        end
    end
end

function GetFormattedRegion3(v3,_v3)
    if (v3.x == _v3.x) or (v3.y == _v3.y) or (v3.z == _v3.z) then
        error("GetFormattedRegion3 cannot format a Region3 given these coordinates. One or more of the x,y or z values is equal to that of the opposite argument.");
    end
    return Region3.new(
        Vector3.new(
            math.min(v3.x, _v3.x),
            math.min(v3.y,_v3.y),
            math.min(v3.z,_v3.z)
        ),
        Vector3.new(
            math.max(v3.x, _v3.x),
            math.max(v3.y,_v3.y),
            math.max(v3.z,_v3.z)
        )
    )
end