Updated Spin Handler Module for Animal's RNG

--*This is a spin handler module for a RNG animal game.* --
-- formatting looks off due to pastebin's formatting i dont actually format my code like how pastebin shows --
-- Author: Gixnly ---
local RS = game:GetService("ReplicatedStorage") -- refrence replicated storage
local remotes = RS:WaitForChild("Remotes") -- refrence remotes folder
local Animals = RS:WaitForChild("Animals") -- refrence animals folder
local animalHandler = require(script.Parent.AnimalHandler) -- require animal handler module
local serverScriptService = game:GetService("ServerScriptService") -- refrence server script service
local dataManager = require(serverScriptService:WaitForChild("Modules"):WaitForChild("DataManager")) -- require  data manager module

local SpinHandler = {} -- initialize table for this module.

-- chose a random animal
function SpinHandler.ChooseAnimal(animals: Folder)
    local animalChildren = animals:GetChildren() -- get a table of animals children
    table.sort(animalChildren, function(a, b) return a.Chance.Value < b.Chance.Value end) -- sort the table based on the children's chance value (lowest to highest)
    local totalEntries = 0 -- initialize entry variable
    -- calculate total entries  for probability calculation
    for _, animal in pairs(animalChildren) do
        totalEntries += 1 / animal.Chance.Value
    end
    local randomEntry = math.random() -- generate a random number between 0 and 1
    local cumulativeEntry = 0 -- initialize cumulativeEntry variable
    local cumulativeEntryForFullRange = 0 -- initialize cumulativeEntryForFullRange variable (used in later calculations to view the cumulative ranges)
    local previousCumulativeEntry = 0 -- initialize previousCumulatievEntry Variable (used so we can see in what range the selected animal was found in)
    local previousCumulativeEntryForFullRange = 0 -- initialize previousCumulativeEntryForFullRange variable (used so we can see the cumulative ranges of each animal without having to return)
    -- Loop through each animal to show the developer the cumuative ranges of each animal
    for _, animal in pairs(animalChildren) do
        previousCumulativeEntryForFullRange = cumulativeEntryForFullRange -- store previous cumulative entry in order to show the range.
        cumulativeEntryForFullRange += 1/ animal.Chance.Value / totalEntries
        -- Calculate the cumulative entry for the current animal by dividing 1 by its chance value and then dividing it by the total entries
        -- This effectively determines the range of probabilities for each animal, ensuring that the sum of all probabilities equals 1
        print(animal.Name.."'s cumulative entry range is: ",tostring(previousCumulativeEntryForFullRange).." to "..tostring(cumulativeEntryForFullRange)) -- print the ranges for the developer to see.
    end
    print("Random number generated is: "..tostring(randomEntry)) -- print the random number for the developer to see.
    for _, animal in pairs(animalChildren) do
        previousCumulativeEntry = cumulativeEntry -- store previous cumulative entry in order to show the range.
        cumulativeEntry += 1/ animal.Chance.Value / totalEntries
        -- Calculate the cumulative entry for the current animal by dividing 1 by its chance value and then dividing it by the total entries
        -- This effectively determines the range of probabilities for each animal, ensuring that the sum of all probabilities equals 1
        print(animal.Name.."'s cumulative entry range is: ",tostring(previousCumulativeEntry).." to "..tostring(cumulativeEntry)) -- print range
        if randomEntry <= cumulativeEntry then -- if the random number falls inside the range then we select the animal that has that range
            print("Random number found in: ",animal.Name,"'s range") -- notify developer of selection
            return animal.Name -- return the animal's name to be used to find said animal in later code
        end
    end
end
-- choose a random animal with double the luck
function SpinHandler.DoubleLuckChooseAnimal(animals: Folder)
    print("Double luck spun") -- print statements for the developer
    local animalChildren = animals:GetChildren() -- get a table of animals children
    table.sort(animalChildren, function(a, b) return a.Chance.Value < b.Chance.Value end) -- sort the table based on the children's chance value (lowest to highest)
    local totalEntries = 0 -- initialize entry variable
    -- calculate total entries  for probability calculation
    for _, animal in pairs(animalChildren) do
        totalEntries += 1 / animal.Chance.Value
    end
    -- generate a random number twice hence giving the player double the luck
    local randomEntry1 = math.random()
    local randomEntry2 = math.random()
    -- assigning random entry to the highest of both random numbers hence giving the player a higher chance of getting a rare animal
    local randomEntry = math.max(randomEntry1, randomEntry2)
    local cumulativeEntry = 0 -- initialize cumulativeEntry variable
    local cumulativeEntryForFullRange = 0 -- initialize cumulativeEntryForFullRange variable (used in later calculations to view the cumulative ranges)
    local previousCumulativeEntry = 0 -- initialize previousCumulatievEntry Variable (used so we can see in what range the selected animal was found in)
    local previousCumulativeEntryForFullRange = 0 -- initialize previousCumulativeEntryForFullRange variable (used so we can see the cumulative ranges of each animal without having to return)
    -- Loop through each animal to show the developer the cumuative ranges of each animal
    for _, animal in pairs(animalChildren) do
        previousCumulativeEntryForFullRange = cumulativeEntryForFullRange -- store previous cumulative entry in order to show the range.
        cumulativeEntryForFullRange += 1/ animal.Chance.Value / totalEntries
        -- Calculate the cumulative entry for the current animal by dividing 1 by its chance value and then dividing it by the total entries
        -- This effectively determines the range of probabilities for each animal, ensuring that the sum of all probabilities equals 1
        print(animal.Name.."'s cumulative entry range is: ",tostring(previousCumulativeEntryForFullRange).." to "..tostring(cumulativeEntryForFullRange)) -- print the ranges for the developer to see.
    end
    print("Random number generated is: "..tostring(randomEntry)) -- print the random number for the developer to see.
    for _, animal in pairs(animalChildren) do
        previousCumulativeEntry = cumulativeEntry -- store previous cumulative entry in order to show the range.
        cumulativeEntry += 1/ animal.Chance.Value / totalEntries
        -- Calculate the cumulative entry for the current animal by dividing 1 by its chance value and then dividing it by the total entries
        -- This effectively determines the range of probabilities for each animal, ensuring that the sum of all probabilities equals 1
        print(animal.Name.."'s cumulative entry range is: ",tostring(previousCumulativeEntry).." to "..tostring(cumulativeEntry)) -- print range
        if randomEntry <= cumulativeEntry then -- if the random number falls inside the range then we select the animal that has that range
            print("Random number found in: ",animal.Name,"'s range")-- notify developer of selection
            return animal.Name -- return the animal's name to be used to find said animal in later code
        end
    end
end
function SpinHandler.GiveAnimalInSpin(selectedAnimal: string) -- returns a specific name of a animal to simulate spinning it.
    return selectedAnimal
end
function SpinHandler.GiveAnimalToPlayer(selectedAnimal: string,player: string) -- take animal name as string and player name
    player = game:GetService("Players"):FindFirstChild(player) -- try to find the player by their name.
    if not player then warn("Player not found in give animal to player, Type:",typeof(player)) return end -- return if player wasnt found and also state the type of the value not found
    if not player.PlayerAnimals:FindFirstChild(selectedAnimal) and Animals:FindFirstChild(selectedAnimal) then -- if they dont have the animal and the animal is in game then give it to them
        local animalString = Instance.new("StringValue",player.PlayerAnimals) -- create string value
        animalString.Name = selectedAnimal -- set its name and value to selectedAnimal
        animalString.Value = selectedAnimal
        print("Successfully gave",selectedAnimal,"to",player.Name.."'s inventory") -- tell the developer that the action was a success.
    else
        warn("Attempted to give "..selectedAnimal.." to "..player.Name,"action failed") -- an error occured; warn the developer
    end
end
function SpinHandler.RemoveAnimalFromPlayer(selectedAnimal: string,player: string) -- take animal name as a string and player instance
    player = game:GetService("Players"):FindFirstChild(player)
    if not player then warn("Player not found in remove animal from player, Type:",typeof(player)) return end -- return if the player wasnt found and also state the type of the value not found
    if player.PlayerAnimals:FindFirstChild(selectedAnimal) then -- if the player has that animal then destroy it
        player.PlayerAnimals:FindFirstChild(selectedAnimal):Destroy()
        print("Successfully removed",selectedAnimal,"from",player.Name.."'s inventory")
    else
        warn("Attempted to remove "..selectedAnimal.." to "..player.Name,"action failed") -- an error occured therefore warn developer
    end
end
function SpinHandler.Spin(player: Player) -- take the player as an argument in order to access many of the players values/gui
    local db = true -- debounce in order to prevent unwanted double creation of animals or any other unwanted issue.
    local selectedAnimal -- initialize selected animal function
    if player:WaitForChild("Double Luck").Value == true then -- check if the player has double luck on.
        selectedAnimal = SpinHandler.DoubleLuckChooseAnimal(Animals) -- if they do fire the doubleluck function
    else -- else use the regular luck function.
        selectedAnimal = SpinHandler.ChooseAnimal(Animals)
    end
    print(selectedAnimal.." was chosen in spin") -- immediately print the selected animals name, makes it easier to debug later code.
    local playerGui = player.PlayerGui -- get the player's gui
    local spinFrame = playerGui.SpinUI.SpinFrame -- get the spin frame
    local loopCount = 0 -- initialize loop count (used for visually spinning)
    local waitTime = 0.15 -- wait time inbetween spins (the spin animation loops through the animals table and shows random animals until finally showing the chosen one)
    local skipConnection -- initialize a connection variable for the skip button of the spin frame
    local equipConnection -- initialiE a connection variable for the equip button of the spin frame
    playerGui.SpinUI.SpinButton.Visible = false -- turn the spin button invisible
    playerGui.SpinUI.DoubleLuckButton.Visible = false -- turn the double luck button invisible
    spinFrame.Visible = true -- turn the spin frame visible
    spinFrame.AnimalChance.Text = "" -- immediatley put the animal chance text and animal unlocked text to empty strings (they have placeholder text so the developer could edit the ui easily)
    spinFrame.AnimalUnlocked.Text = ""
    spinFrame.SkipButton.Visible = false -- make sure the skip button isnt visible
    spinFrame.EquipButton.Visible = false -- make sure the skip button isnt visible
    for i, v in pairs(playerGui.AnimalInventory:GetChildren()) do -- turn off all other gui's
        if v:IsA("GuiBase") then
            if v.Visible == true then
                v.Visible = false
            end

        end
    end
    local profile = dataManager.Profiles[player] -- getting player's profile
    if not profile then return end -- if profile doesnt exist return immediately
    profile.Data.Spins += 1 -- increment spins data by 1
    player.leaderstats.Spins.Value = profile.Data.Spins -- update leaderstats to visually show spins data
    repeat -- reapeat loop for spinning animation
        loopCount += 1 -- increment loop count
        task.wait(waitTime) -- initialize a wait in order to prevent instant text change.
        local randomAnimal = math.round(math.random(1, #Animals:GetChildren())) -- select a random animal from the animals folder
        spinFrame.AnimalUnlocked.Text = Animals:GetChildren()[randomAnimal].Name -- chance animal unlicked text to the animals name
        spinFrame.AnimalUnlocked.TextColor3 = Animals:GetChildren()[randomAnimal].Highlight.OutlineColor -- change the animal unlocked text color to the highlight color of the animal
        spinFrame.AnimalChance.Text = "" -- again making sure the chance text is not visible (an empty string)
        remotes.SpinningForAnimal:FireClient(player) -- fire a remote on the client to play a "tick" sound for each rotation
        -- Gradually increase wait time to slow down the loop if we have passed the half way point of the loop
        if loopCount >= 15 then
            waitTime = waitTime + 0.05
        end
    until loopCount >= 30 -- stop loop once loopCount has reached or surpassed 30.
    spinFrame.AnimalUnlocked.Text = selectedAnimal -- show the animal unlocked text as the selected animal
    spinFrame.AnimalUnlocked.TextColor3 = Animals[selectedAnimal].Highlight.OutlineColor -- change the color to the highlight color of the animal
    local chance =  Animals:FindFirstChild(selectedAnimal).Chance.Value -- get the chance value of the animal
    if chance >= Animals["Mad Cow"].Chance.Value then -- this is specifically for a animal that has a "one in zero" chance since we programattically cannot have a 0 chance we make it close to 0 by having a large number
        spinFrame.AnimalChance.Text = "1 in "..tostring(0) -- chance the animal chance text to the text seen.
    else -- if chance isnt at mad cow's level then simply put the animal chance text to "1 in "..the animals chance
        spinFrame.AnimalChance.Text = "1 in "..tostring(chance)
    end
    spinFrame.AnimalChance.TextColor3 = Animals[selectedAnimal].Highlight.OutlineColor -- chance the animal chance text color to the animals highlight color
    spinFrame.SkipButton.Visible = true -- turn the skip equip buttons visible
    spinFrame.EquipButton.Visible = true
    skipConnection = spinFrame.SkipButton.MouseButton1Click:Once(function() -- initialize a "Once" connection to the click event of the skip button
        print("skip button pressed") -- debug print statements for the developer
        if not player.PlayerAnimals:FindFirstChild(selectedAnimal) and db then -- check if the player's "player animals" already has the selected animal
            db = false -- put db to false to prevent cloning
            -- since the player passed the if statment that means they must not have the animal selected
            local animalString = Instance.new("StringValue",player.PlayerAnimals) -- create a string value and add it to the player's player animals
            animalString.Name = selectedAnimal -- set the string name to the selected animal and also set its value to the selected animal
            animalString.Value = selectedAnimal
            task.delay(1,function() -- delay resetting the debounce
                db = true
            end)
        end
        task.wait() -- small wait before turning the skip and equip buttons invisible
        spinFrame.SkipButton.Visible = false
        spinFrame.EquipButton.Visible = false
        spinFrame.Visible = false -- turn the spin frame invisible
        task.wait(0.5) -- wait half a second before turning the spin button visible
        playerGui.SpinUI.SpinButton.Visible = true
        playerGui.SpinUI.DoubleLuckButton.Visible = true
        for i, v in pairs(playerGui.AnimalInventory:GetChildren()) do -- turn all the guis that arent the specific guis named from invisble to visible
            if v:IsA("GuiBase")  then
                if v.Visible == false and v.Name ~= "AnimalsFrame" or v.Name ~= "UnequipButton"  then
                    v.Visible = true
                end
                if v.Visible == true and v.Name ~= "InventoryButton" then -- a debug if statement in order to prevent the guis from still being visible and to also only turn the inventory button visible
                    v.Visible = false
                end

            end
        end
        skipConnection:Disconnect() -- disconnect the connection
        skipConnection = nil -- set connection to nil
        selectedAnimal = nil -- set selected animal to nil to prevent unwanted behaviour
        print("skip button disconnected selected animal disconnected") -- print statement for the developer
        return -- immediately return out of the function
    end)
    equipConnection = spinFrame.EquipButton.MouseButton1Click:Once(function() -- initialize a 'Once connection for the equip button click event'
        print("equip button pressed") -- print statement for the developer
        if typeof(selectedAnimal) == "nil" then print("selected animal was attempted to be fired again.") return end -- if selected animal is nil (aka we already skipped and for some reason the equip button was clicked after we skipped) then immediatley return
        if not player.PlayerAnimals:FindFirstChild(selectedAnimal) and db then -- if the selected animal was not already in the player's player animals
            db = false -- set db to false to prevent cloning
            -- if the animal wasnt found that indeed means the player does not have it already.
            local animalString = Instance.new("StringValue",player.PlayerAnimals) -- create string value and parent it to the player's player animals
            animalString.Name = selectedAnimal -- set the string's name and value to the selected animal
            animalString.Value = selectedAnimal
            animalHandler.EquipAnimal(player,player.Character,selectedAnimal) -- equip the animal using the animals handler module
            task.delay(1,function() -- delay resetting the debounce
                db = true
            end)
        elseif db then
            db = false -- set db to false to prevent double equips
            animalHandler.EquipAnimal(player,player.Character,selectedAnimal) -- equip animal because they already have it
            task.delay(1,function()-- delay resetting the debounce
                db = true
            end)
        end
        print(spinFrame:GetChildren()," spin frame children, from equip button") -- debung print statement for the developer
        task.wait() -- small wait
        spinFrame.Visible = false -- turn spin frame invisible
        task.wait(0.5) -- wait half a second before turning the spin button visible
        playerGui.SpinUI.SpinButton.Visible = true
        playerGui.SpinUI.DoubleLuckButton.Visible = true
        equipConnection:Disconnect() -- disconnect both the skip and equip connections
        skipConnection:Disconnect()
        equipConnection = nil -- set connections to nil and set selected animal to nil
        skipConnection = nil
        selectedAnimal = nil
        print("equip button disconnected selected animal disconnected") -- print statement for the develop
        return -- return out of function
    end)
end

return SpinHandler -- return spin handler