roblox-utils.lua

--[[
    Roblox Exploit Scripting Utility Library
    Game-agnostic helpers for any Roblox exploit script.

    Usage: copy this file into your project, or paste the functions you need.
    All functions are standalone — no module system, no require().

    DISCLAIMER: Using exploit scripts violates Roblox Terms of Service.
    Use at your own risk.
]]

-- ═══════════════════════════════════════════════════════════════════════════════
-- GLOBALS / CONFIG
-- ═══════════════════════════════════════════════════════════════════════════════
local DEBUG = true
local scriptRunning = true
local connections = {}       -- store all connections for cleanup

-- ═══════════════════════════════════════════════════════════════════════════════
-- SERVICES
-- ═══════════════════════════════════════════════════════════════════════════════
local Players = game:GetService("Players")
local UserInputService = game:GetService("UserInputService")
local VIM = game:GetService("VirtualInputManager")

local player = Players.LocalPlayer
local character = player.Character or player.CharacterAdded:Wait()

-- ═══════════════════════════════════════════════════════════════════════════════
-- DEBUG LOGGING
-- ═══════════════════════════════════════════════════════════════════════════════
local logBuffer = {}
local LOG_MAX_LINES = 300
local logSF = nil       -- assigned by GUI builder (ScrollingFrame for auto-scroll)
local logLines = {}      -- per-line GUI TextButtons
local debugLabel = nil   -- assigned by GUI builder (single-line status label)

--- Log a debug message to executor console, Roblox output, and optional GUI panel.
local function debugLog(msg)
    if not DEBUG then return end
    local prefix = "[Script]"
    local s = prefix .. " " .. tostring(msg)
    pcall(function() rconsoleprint(s .. "\n") end)
    pcall(function() rconsolewarn(s .. "\n") end)
    print(s)
    warn(s)
    if debugLabel then
        debugLabel.Text = tostring(msg)
        debugLabel.Visible = true
    end
    local t = os.date("*t")
    local line = string.format("[%02d:%02d:%02d] %s", t.hour, t.min, t.sec, tostring(msg))
    table.insert(logBuffer, line)
    if #logBuffer > LOG_MAX_LINES then
        table.remove(logBuffer, 1)
        if logLines[1] then
            logLines[1]:Destroy()
            table.remove(logLines, 1)
        end
    end
    if logSF then
        local btn = Instance.new("TextButton")
        btn.Size = UDim2.new(1, -6, 0, 14)
        btn.BackgroundTransparency = 1
        btn.Text = line
        btn.TextColor3 = Color3.fromRGB(180, 220, 180)
        btn.TextSize = 10
        btn.Font = Enum.Font.RobotoMono
        btn.TextWrapped = false
        btn.TextXAlignment = Enum.TextXAlignment.Left
        btn.AutoButtonColor = false
        btn.AutomaticSize = Enum.AutomaticSize.Y
        btn.Parent = logSF
        table.insert(logLines, btn)
        btn.Activated:Connect(function()
            pcall(function() setclipboard(line) end)
            btn.TextColor3 = Color3.fromRGB(0, 255, 100)
            task.delay(0.8, function()
                if btn and btn.Parent then btn.TextColor3 = Color3.fromRGB(180, 220, 180) end
            end)
        end)
        task.defer(function()
            if logSF then logSF.CanvasPosition = Vector2.new(0, math.huge) end
        end)
    end
end

-- ═══════════════════════════════════════════════════════════════════════════════
-- STATUS DISPLAY
-- ═══════════════════════════════════════════════════════════════════════════════
local statusLabels = {}  -- map feature name → TextLabel (populated by GUI builder)

--- Update a feature's status label in the GUI.
--- @param feature string Feature name (e.g., "cashier", "mood")
--- @param text string Status text
--- @param color? Color3 Optional text color
local function setStatus(feature, text, color)
    local label = statusLabels[feature]
    if not label then return end
    label.Text = tostring(text)
    if color then label.TextColor3 = color end
end

-- ═══════════════════════════════════════════════════════════════════════════════
-- EXECUTOR COMPATIBILITY
-- ═══════════════════════════════════════════════════════════════════════════════

--- Protect a ScreenGui from game scripts that might destroy it (Synapse).
local function protectGui(gui)
    pcall(function()
        if syn and syn.protect_gui then syn.protect_gui(gui) end
    end)
end

--- Safe wrapper for getconnections (returns {} if unavailable).
local function safeGetConnections(signal)
    if getconnections then return getconnections(signal) end
    return {}
end

-- ═══════════════════════════════════════════════════════════════════════════════
-- BUTTON CLICKING (multi-method, cross-executor)
-- ═══════════════════════════════════════════════════════════════════════════════

--- Click a GUI button using the best available method.
--- Tries: getconnections → firesignal → mousemoveabs+mouse1click → VIM.
--- @param btn GuiObject The button to click
local function clickButton(btn)
    if not btn or not btn:IsA("GuiObject") then return end

    -- Method 1: getconnections
    local fired = false
    local events = {"Activated", "MouseButton1Click", "MouseButton1Down", "MouseButton1Up"}
    for _, eventName in pairs(events) do
        local event = btn[eventName]
        if event then
            for _, conn in pairs(safeGetConnections(event)) do
                pcall(function()
                    if conn.Fire then task.spawn(conn.Fire, conn) end
                    if conn.Function then task.spawn(conn.Function) end
                    fired = true
                end)
            end
        end
    end

    -- Method 1b: firesignal
    if not fired and firesignal and btn.Activated then
        pcall(function() task.spawn(firesignal, btn.Activated) end)
        fired = true
    end

    -- Method 2: mousemoveabs + mouse1click (MacSploit)
    if not fired and mousemoveabs and mouse1click then
        pcall(function()
            local pos = btn.AbsolutePosition
            local size = btn.AbsoluteSize
            mousemoveabs(pos.X + size.X / 2, pos.Y + size.Y / 2)
            task.wait(0.08)
            mouse1click()
        end)
        return
    end

    -- Method 3: VirtualInputManager
    if not fired then
        pcall(function()
            local pos = btn.AbsolutePosition
            local size = btn.AbsoluteSize
            local x = pos.X + size.X / 2
            local y = pos.Y + size.Y / 2
            VIM:SendMouseMoveEvent(x, y, game)
            task.wait(0.08)
            VIM:SendMouseButtonEvent(x, y, 0, true, game, 1)
            task.wait(0.05)
            VIM:SendMouseButtonEvent(x, y, 0, false, game, 1)
        end)
    end
end

-- ═══════════════════════════════════════════════════════════════════════════════
-- VIM INTERACTION
-- ═══════════════════════════════════════════════════════════════════════════════

--- Press and release a key via VirtualInputManager.
--- @param keyCode EnumItem Enum.KeyCode value
local function pressKey(keyCode)
    VIM:SendKeyEvent(true, keyCode, false, game)
    task.wait(0.08)
    VIM:SendKeyEvent(false, keyCode, false, game)
    task.wait(0.05)
end

--- Press the E key (most common interact key).
local function pressE()
    pressKey(Enum.KeyCode.E)
end

--- Click a world BasePart by pointing camera at it and clicking.
--- @param part BasePart The part to click
--- @return boolean success
local function clickWorldPart(part)
    if not part or not part:IsA("BasePart") then return false end
    local camera = workspace.CurrentCamera
    camera.CFrame = CFrame.lookAt(camera.CFrame.Position, part.Position)
    task.wait(0.05)
    local screenPos, onScreen = camera:WorldToScreenPoint(part.Position)
    if not onScreen then return false end
    VIM:SendMouseMoveEvent(screenPos.X, screenPos.Y, game)
    task.wait(0.05)
    VIM:SendMouseButtonEvent(screenPos.X, screenPos.Y, 0, true, game, 1)
    task.wait(0.05)
    VIM:SendMouseButtonEvent(screenPos.X, screenPos.Y, 0, false, game, 1)
    return true
end

--- Scroll mouse wheel at a screen position via VIM.
--- @param x number Screen X
--- @param y number Screen Y
--- @param direction string "up" or "down"
--- @param scrolls? number Number of scroll events (default 3)
local function scrollAt(x, y, direction, scrolls)
    for i = 1, (scrolls or 3) do
        VIM:SendMouseWheelEvent(x, y, direction == "down" and -1 or 1, game)
        task.wait(0.15)
    end
end

-- ═══════════════════════════════════════════════════════════════════════════════
-- SERVER DESYNC
-- ═══════════════════════════════════════════════════════════════════════════════
local desyncRunning = false
local desyncHold = false
local resyncEnabled = true

--- Toggle server desync (anchor/unanchor HRP).
local function toggleDesync()
    desyncRunning = not desyncRunning
    local char = player.Character
    local hrp = char and char:FindFirstChild("HumanoidRootPart")
    if not hrp then return end
    if desyncRunning then
        hrp.Anchored = true
        debugLog("[DESYNC] Anchored — server position frozen")
    else
        hrp.Anchored = false
        debugLog("[DESYNC] Unanchored — resynced with server")
    end
end

--- Temporarily unanchor HRP so the server registers current position.
local function desyncPause()
    if not desyncRunning or not resyncEnabled then return end
    local char = player.Character
    local hrp = char and char:FindFirstChild("HumanoidRootPart")
    if hrp then
        hrp.Anchored = false
        task.wait(0.15)
    end
end

--- Re-anchor HRP after an interaction (no-op if desyncHold is true).
local function desyncResume()
    if not desyncRunning or not resyncEnabled or desyncHold then return end
    local char = player.Character
    local hrp = char and char:FindFirstChild("HumanoidRootPart")
    if hrp and hrp.Parent then
        task.wait(0.1)
        hrp.Anchored = true
    end
end

--- Force a full resync: unanchor briefly, then re-anchor.
local function desyncResync()
    if not desyncRunning then return end
    local char = player.Character
    local hrp = char and char:FindFirstChild("HumanoidRootPart")
    if not hrp then return end
    hrp.Anchored = false
    task.wait(0.15)
    if desyncRunning and hrp and hrp.Parent then hrp.Anchored = true end
end

--- Auto re-anchor on respawn.
local function setupDesyncRespawn()
    table.insert(connections, player.CharacterAdded:Connect(function(newChar)
        task.wait(0.5)
        local hrp = newChar:FindFirstChild("HumanoidRootPart")
        if hrp and desyncRunning then hrp.Anchored = true end
    end))
end

-- ═══════════════════════════════════════════════════════════════════════════════
-- SAFE TELEPORT
-- ═══════════════════════════════════════════════════════════════════════════════
local safeTpEnabled = true

--- Move HRP to a target CFrame in small steps at walking speed.
--- @param hrp BasePart HumanoidRootPart
--- @param targetCFrame CFrame Destination
--- @param speed? number Studs per second (default 6)
local function safeTeleport(hrp, targetCFrame, speed)
    if not hrp or not hrp.Parent then return end
    desyncPause()

    local wasAnchored = hrp.Anchored
    hrp.Anchored = true

    if not safeTpEnabled then
        hrp.CFrame = targetCFrame
        hrp.Anchored = wasAnchored
        desyncResume()
        return
    end

    speed = speed or 6
    local stepSize = 0.8
    local startPos = hrp.Position
    local targetPos = targetCFrame.Position
    local dx = targetPos.X - startPos.X
    local dz = targetPos.Z - startPos.Z
    local dist2D = math.sqrt(dx * dx + dz * dz)

    if dist2D < 1 then
        hrp.CFrame = targetCFrame
        hrp.Anchored = wasAnchored
        desyncResume()
        return
    end

    local dirX = dx / dist2D
    local dirZ = dz / dist2D
    local steps = math.ceil(dist2D / stepSize)
    local waitPerStep = stepSize / speed
    local maxY = math.max(startPos.Y, targetPos.Y) + 3
    local minY = math.min(startPos.Y, targetPos.Y) - 1

    for i = 1, steps do
        if not scriptRunning then hrp.Anchored = wasAnchored; return end
        if not hrp or not hrp.Parent then return end
        local t = math.min(i * stepSize, dist2D)
        local frac = t / dist2D
        local x = startPos.X + dirX * t
        local z = startPos.Z + dirZ * t
        local y = startPos.Y + (targetPos.Y - startPos.Y) * frac
        y = math.clamp(y, minY, maxY)
        hrp.CFrame = CFrame.new(x, y, z) * (targetCFrame - targetCFrame.Position)
        task.wait(waitPerStep)
    end

    hrp.CFrame = targetCFrame
    hrp.Anchored = wasAnchored
    desyncResume()
end

-- ═══════════════════════════════════════════════════════════════════════════════
-- UI SEARCH
-- ═══════════════════════════════════════════════════════════════════════════════

--- Find a GUI element by its text content (searches descendants).
--- If a TextLabel is found inside a button, returns the parent button.
--- @param parent Instance Root to search from
--- @param text string Text to find (case-insensitive substring)
--- @return GuiObject|nil
local function findUIByText(parent, text)
    if not parent then return nil end
    local lowerText = text:lower()
    for _, child in ipairs(parent:GetDescendants()) do
        if child:IsA("TextLabel") or child:IsA("TextButton") then
            if child.Text and child.Text:lower():find(lowerText, 1, true) then
                if child:IsA("TextLabel") and child.Parent
                    and (child.Parent:IsA("TextButton") or child.Parent:IsA("ImageButton")) then
                    return child.Parent
                end
                if child:IsA("TextButton") then return child end
            end
        end
    end
    return nil
end

--- Wait for a child to appear with timeout.
--- @param parent Instance
--- @param name string
--- @param timeout? number Seconds (default 10)
--- @return Instance|nil
local function waitForChild(parent, name, timeout)
    timeout = timeout or 10
    local start = tick()
    local child = parent:FindFirstChild(name)
    while not child and (tick() - start) < timeout do
        task.wait(0.1)
        child = parent:FindFirstChild(name)
    end
    return child
end

-- ═══════════════════════════════════════════════════════════════════════════════
-- INTERACT UI HELPERS (_interactUI)
-- ═══════════════════════════════════════════════════════════════════════════════

--- Get all visible interact buttons from _interactUI.Center.
--- @return table Array of {btn = GuiObject, text = string}
local function getInteractButtons()
    local pgui = player:FindFirstChild("PlayerGui")
    local iui = pgui and pgui:FindFirstChild("_interactUI")
    local ctr = iui and iui:FindFirstChild("Center")
    if not ctr then return {} end
    local result = {}
    local seen = {}
    for _, desc in ipairs(ctr:GetDescendants()) do
        if (desc:IsA("ImageButton") or desc:IsA("TextButton")) and not seen[desc] then
            seen[desc] = true
            local vis = true
            local node = desc
            while node and node ~= ctr do
                if node:IsA("GuiObject") and node.Visible == false then vis = false; break end
                node = node.Parent
            end
            if vis then
                for _, child in ipairs(desc:GetChildren()) do
                    if child:IsA("TextLabel") and child.Text ~= "" then
                        table.insert(result, {btn = desc, text = child.Text})
                        break
                    end
                end
            end
        end
    end
    return result
end

--- Check if any interact button text matches a search term.
--- @param term string Case-insensitive substring to find
--- @return GuiObject|nil btn, string|nil matchedText
local function menuHasButton(term)
    local lowerTerm = term:lower()
    for _, entry in ipairs(getInteractButtons()) do
        if entry.text:lower():find(lowerTerm, 1, true) then
            return entry.btn, entry.text
        end
    end
    return nil
end

--- Click the first interact button matching any term from a list.
--- @param terms table Array of search terms (case-insensitive)
--- @return string|nil matchedText
local function clickMenuButton(terms)
    for _, term in ipairs(terms) do
        local btn, text = menuHasButton(term)
        if btn then
            clickButton(btn)
            return text
        end
    end
    return nil
end

--- Log all currently visible interact buttons.
--- @param label string Prefix for log lines
--- @return table buttons Array of {btn, text}
local function logMenuState(label)
    local buttons = getInteractButtons()
    if #buttons == 0 then
        debugLog(label .. ": (no buttons)")
    else
        for _, entry in ipairs(buttons) do
            debugLog(label .. ": '" .. entry.text .. "'")
        end
    end
    return buttons
end

--- Wait for the interact menu to change (different buttons than before).
--- @param prevButtons table Previous getInteractButtons() result
--- @param timeout? number Seconds (default 3)
--- @return boolean changed
local function waitForMenuChange(prevButtons, timeout)
    timeout = timeout or 3
    local start = tick()
    while (tick() - start) < timeout do
        task.wait(0.3)
        local current = getInteractButtons()
        if #current ~= #prevButtons then return true end
        for i, entry in ipairs(current) do
            if not prevButtons[i] or prevButtons[i].text ~= entry.text then return true end
        end
    end
    return false
end

--- Scroll the interact menu using VIM mouse wheel.
--- @param direction string "up" or "down"
--- @param scrolls? number Number of scroll events (default 3)
local function scrollInteractMenu(direction, scrolls)
    local pgui = player:FindFirstChild("PlayerGui")
    local iui = pgui and pgui:FindFirstChild("_interactUI")
    local ctr = iui and iui:FindFirstChild("Center")
    if not ctr then return end
    local pos = ctr.AbsolutePosition
    local sz = ctr.AbsoluteSize
    scrollAt(pos.X + sz.X / 2, pos.Y + sz.Y / 2, direction, scrolls)
end

--- Close any open interact menu (click back/close button or press Backspace).
local function closeInteractMenu()
    local pgui = player:FindFirstChild("PlayerGui")
    local iui = pgui and pgui:FindFirstChild("_interactUI")
    local ctr = iui and iui:FindFirstChild("Center")
    if ctr then
        for _, btn in ipairs(ctr:GetChildren()) do
            if btn.Name == "RoundButton" or btn.Name == "CloseButton" then
                clickButton(btn)
                task.wait(0.3)
                return
            end
            for _, child in ipairs(btn:GetChildren()) do
                if child.Name == "BackIcon" or child.Name == "CloseIcon" then
                    clickButton(btn)
                    task.wait(0.3)
                    return
                end
            end
        end
    end
    -- Fallback: press Backspace
    pressKey(Enum.KeyCode.Backspace)
    task.wait(0.5)
end

--- Find a _ListFrame ScreenGui by action name (e.g., "Plant" → "_ListFrame (I_Plant)").
--- @param actionName string The action name to search for
--- @return ScreenGui|nil
local function findListFrame(actionName)
    local pgui = player:FindFirstChild("PlayerGui")
    if not pgui then return nil end
    for _, sg in ipairs(pgui:GetChildren()) do
        if sg:IsA("ScreenGui") and sg.Name:find("_ListFrame") and sg.Name:find(actionName) then
            return sg
        end
    end
    return nil
end

--- Click an item in a _ListFrame selection menu.
--- Structure: ScreenGui.Frame.ItemList.ScrollFrame.<ItemName>_Button.Take
--- @param listFrame ScreenGui The _ListFrame ScreenGui
--- @param itemName string Name of the item (e.g., "Small Mushroom")
--- @return boolean success
local function clickListFrameItem(listFrame, itemName)
    local frame = listFrame:FindFirstChild("Frame")
    local itemList = frame and frame:FindFirstChild("ItemList")
    local scrollFrame = itemList and itemList:FindFirstChild("ScrollFrame")
    if not scrollFrame then return false end
    local btnFrame = scrollFrame:FindFirstChild(itemName .. "_Button")
    if not btnFrame then
        -- Fallback: case-insensitive search
        local lower = itemName:lower()
        for _, child in ipairs(scrollFrame:GetChildren()) do
            if child.Name:lower():find(lower) then
                btnFrame = child
                break
            end
        end
    end
    if not btnFrame then return false end
    local takeBtn = btnFrame:FindFirstChild("Take")
    if not takeBtn then return false end
    clickButton(takeBtn)
    return true
end

-- ═══════════════════════════════════════════════════════════════════════════════
-- ANTI-AFK
-- ═══════════════════════════════════════════════════════════════════════════════
local antiAfkConnection = nil

--- Toggle anti-AFK (uses VirtualUser.CaptureFocus on Idled).
--- @return boolean isRunning
local function toggleAntiAfk()
    if antiAfkConnection then
        antiAfkConnection:Disconnect()
        antiAfkConnection = nil
        debugLog("[AFK] Anti-AFK disabled")
        return false
    else
        local VirtualUser = game:GetService("VirtualUser")
        antiAfkConnection = player.Idled:Connect(function()
            VirtualUser:CaptureFocus()
        end)
        debugLog("[AFK] Anti-AFK enabled")
        return true
    end
end

-- ═══════════════════════════════════════════════════════════════════════════════
-- POPUP AUTO-CLOSE
-- ═══════════════════════════════════════════════════════════════════════════════

--- Start a background loop that auto-closes popups matching keyword names.
--- @param parentName string Name of the ScreenGui/container to scan (e.g., "MainGUI")
--- @param keywords? table Array of lowercase keywords to match frame names against
local function startPopupCloser(parentName, keywords)
    keywords = keywords or {
        "reward", "starterpack", "storeframe", "supportframe",
        "buyblockbux", "buymoney", "buyevent", "paycheck",
        "event", "popup", "update", "daily", "welcome"
    }
    task.spawn(function()
        while scriptRunning do
            task.wait(2)
            local pgui = player:FindFirstChild("PlayerGui")
            local container = pgui and pgui:FindFirstChild(parentName)
            if container then
                for _, child in ipairs(container:GetChildren()) do
                    if child:IsA("Frame") and child.Visible then
                        local name = child.Name:lower()
                        local isPopup = false
                        for _, kw in ipairs(keywords) do
                            if name:find(kw) then isPopup = true; break end
                        end
                        if isPopup then
                            local closeBtn = child:FindFirstChild("Close") or child:FindFirstChild("CloseButton")
                            if not closeBtn then
                                for _, desc in ipairs(child:GetDescendants()) do
                                    if desc:IsA("TextButton") then
                                        local txt = desc.Text:lower()
                                        if txt == "x" or txt == "close" or txt == "claim" or txt == "ok" then
                                            closeBtn = desc; break
                                        end
                                    elseif desc:IsA("ImageButton") then
                                        local n = desc.Name:lower()
                                        if n == "close" or n == "x" or n == "closebutton" then
                                            closeBtn = desc; break
                                        end
                                    end
                                end
                            end
                            if closeBtn then pcall(function() clickButton(closeBtn) end) end
                        end
                    end
                end
            end
        end
    end)
end

-- ═══════════════════════════════════════════════════════════════════════════════
-- STAT/MOOD BAR READING
-- ═══════════════════════════════════════════════════════════════════════════════

--- Read a fill-based stat bar's percentage (0-100).
--- Many games use ImageLabel/Frame with Size.X.Scale as fill amount.
--- @param fillInstance GuiObject The fill element (usually ImageLabel or Frame)
--- @return number percentage 0-100
local function readBarPercentage(fillInstance)
    if not fillInstance or not fillInstance.Parent then return 0 end
    return math.floor(fillInstance.Size.X.Scale * 100)
end

-- ═══════════════════════════════════════════════════════════════════════════════
-- HELD ITEM DETECTION
-- ═══════════════════════════════════════════════════════════════════════════════

--- Check if the player is holding a Tool.
--- @return boolean
local function isHoldingTool()
    local charModel = workspace:FindFirstChild(player.Name)
    if charModel then
        for _, child in ipairs(charModel:GetChildren()) do
            if child:IsA("Tool") then return true end
        end
    end
    local char = player.Character
    if char then
        for _, child in ipairs(char:GetChildren()) do
            if child:IsA("Tool") then return true end
        end
    end
    return false
end

--- Discard held item by pressing Backspace.
local function discardHeldItem()
    if isHoldingTool() then
        pressKey(Enum.KeyCode.Backspace)
        task.wait(0.5)
    end
end

-- ═══════════════════════════════════════════════════════════════════════════════
-- PLAYER PLOT HELPERS
-- ═══════════════════════════════════════════════════════════════════════════════

--- Find the player's plot folder.
--- Common pattern: workspace.Plots.Plot_<PlayerName>
--- @return Folder|nil
local function getPlayerPlot()
    local plotsFolder = workspace:FindFirstChild("Plots")
    return plotsFolder and plotsFolder:FindFirstChild("Plot_" .. player.Name)
end

--- Check if the player is near their plot (within distance of any plot part).
--- @param maxDist? number Maximum distance in studs (default 100)
--- @return boolean
local function isOnPlot(maxDist)
    maxDist = maxDist or 100
    local char = player.Character
    local hrp = char and char:FindFirstChild("HumanoidRootPart")
    if not hrp then return false end
    local myPlot = getPlayerPlot()
    if not myPlot then return false end
    local ground = myPlot:FindFirstChild("Ground")
    if ground then
        local gPart = ground:FindFirstChildWhichIsA("BasePart")
        if gPart and (hrp.Position - gPart.Position).Magnitude < maxDist then
            return true
        end
    end
    for _, desc in ipairs(myPlot:GetDescendants()) do
        if desc:IsA("BasePart") then
            if (hrp.Position - desc.Position).Magnitude < maxDist then return true end
        end
    end
    return false
end

--- Search a parent instance for objects matching keyword names.
--- @param parent Instance Root to search
--- @param keywords table Array of lowercase keyword strings
--- @param classFilter? string Optional IsA class filter (e.g., "BasePart")
--- @return table Array of matching instances
local function findByKeywords(parent, keywords, classFilter)
    local results = {}
    for _, desc in ipairs(parent:GetDescendants()) do
        if not classFilter or desc:IsA(classFilter) then
            local name = desc.Name:lower()
            for _, kw in ipairs(keywords) do
                if name:find(kw) then
                    table.insert(results, desc)
                    break
                end
            end
        end
    end
    return results
end

-- ═══════════════════════════════════════════════════════════════════════════════
-- GUI BUILDER
-- ═══════════════════════════════════════════════════════════════════════════════

--- Create a standard dump/debug GUI with all mandatory elements:
--- draggable title bar, resize handle, copy button, ScrollingFrame, close button.
--- @param title string Window title
--- @param content string Text content to display
--- @param opts? table Optional: {displayOrder=number, width=0.6, height=0.7}
--- @return ScreenGui
local function createDumpGui(title, content, opts)
    opts = opts or {}
    local sg = Instance.new("ScreenGui")
    sg.Name = title:gsub("%s+", "") .. "Output"
    sg.ResetOnSpawn = false
    sg.DisplayOrder = opts.displayOrder or 9999
    sg.IgnoreGuiInset = true

    local f = Instance.new("Frame")
    f.Size = UDim2.new(opts.width or 0.6, 0, opts.height or 0.7, 0)
    f.Position = UDim2.new(0.2, 0, 0.15, 0)
    f.BackgroundColor3 = Color3.fromRGB(20, 20, 25)
    f.BorderSizePixel = 0
    f.Parent = sg
    Instance.new("UICorner", f).CornerRadius = UDim.new(0, 16)

    -- Title bar (draggable)
    local titleBar = Instance.new("Frame")
    titleBar.Size = UDim2.new(1, 0, 0, 36)
    titleBar.BackgroundColor3 = Color3.fromRGB(30, 35, 45)
    titleBar.BorderSizePixel = 0
    titleBar.Parent = f
    Instance.new("UICorner", titleBar).CornerRadius = UDim.new(0, 16)

    local lbl = Instance.new("TextLabel")
    lbl.Size = UDim2.new(1, -20, 1, 0)
    lbl.Position = UDim2.new(0, 10, 0, 0)
    lbl.BackgroundTransparency = 1
    lbl.Text = title
    lbl.TextColor3 = Color3.fromRGB(0, 255, 150)
    lbl.TextSize = 16
    lbl.Font = Enum.Font.GothamBold
    lbl.TextXAlignment = Enum.TextXAlignment.Left
    lbl.Parent = titleBar

    -- Drag logic
    local dragging, dragStart, startPos
    titleBar.InputBegan:Connect(function(input)
        if input.UserInputType == Enum.UserInputType.MouseButton1 then
            dragging = true; dragStart = input.Position; startPos = f.Position
        end
    end)
    titleBar.InputChanged:Connect(function(input)
        if dragging and input.UserInputType == Enum.UserInputType.MouseMovement then
            local delta = input.Position - dragStart
            f.Position = UDim2.new(startPos.X.Scale, startPos.X.Offset + delta.X,
                startPos.Y.Scale, startPos.Y.Offset + delta.Y)
        end
    end)
    game:GetService("UserInputService").InputEnded:Connect(function(input)
        if input.UserInputType == Enum.UserInputType.MouseButton1 then dragging = false end
    end)

    -- Copy button
    local copyBtn = Instance.new("TextButton")
    copyBtn.Size = UDim2.new(0, 180, 0, 32)
    copyBtn.Position = UDim2.new(0.5, -90, 0, 42)
    copyBtn.Text = "Copy to Clipboard"
    copyBtn.BackgroundColor3 = Color3.fromRGB(0, 160, 80)
    copyBtn.TextColor3 = Color3.fromRGB(255, 255, 255)
    copyBtn.TextSize = 14
    copyBtn.Font = Enum.Font.GothamBold
    copyBtn.Parent = f
    Instance.new("UICorner", copyBtn).CornerRadius = UDim.new(0, 8)
    copyBtn.MouseButton1Click:Connect(function()
        pcall(function() setclipboard(content) end)
        copyBtn.Text = "Copied!"
        task.delay(1.5, function() if copyBtn.Parent then copyBtn.Text = "Copy to Clipboard" end end)
    end)

    -- Scroll frame
    local sf = Instance.new("ScrollingFrame")
    sf.Size = UDim2.new(1, -30, 1, -130)
    sf.Position = UDim2.new(0, 15, 0, 80)
    sf.BackgroundColor3 = Color3.fromRGB(25, 28, 35)
    sf.BorderSizePixel = 0
    sf.ScrollBarThickness = 8
    sf.AutomaticCanvasSize = Enum.AutomaticSize.Y
    sf.Parent = f
    Instance.new("UICorner", sf).CornerRadius = UDim.new(0, 8)

    local tb = Instance.new("TextLabel")
    tb.Size = UDim2.new(1, -16, 0, 0)
    tb.Position = UDim2.new(0, 8, 0, 4)
    tb.AutomaticSize = Enum.AutomaticSize.Y
    tb.BackgroundTransparency = 1
    tb.TextColor3 = Color3.fromRGB(220, 220, 220)
    tb.TextSize = 12
    tb.Font = Enum.Font.RobotoMono
    tb.TextWrapped = false
    tb.Text = content
    tb.TextXAlignment = Enum.TextXAlignment.Left
    tb.TextYAlignment = Enum.TextYAlignment.Top
    tb.Parent = sf

    -- Resize handle
    local resizeHandle = Instance.new("TextButton")
    resizeHandle.Size = UDim2.new(0, 18, 0, 18)
    resizeHandle.Position = UDim2.new(1, -18, 1, -18)
    resizeHandle.Text = "◢"
    resizeHandle.TextColor3 = Color3.fromRGB(150, 150, 150)
    resizeHandle.TextSize = 14
    resizeHandle.BackgroundTransparency = 1
    resizeHandle.ZIndex = 10
    resizeHandle.Parent = f
    local resizing, resizeStart, startSize
    resizeHandle.InputBegan:Connect(function(input)
        if input.UserInputType == Enum.UserInputType.MouseButton1 then
            resizing = true; resizeStart = input.Position; startSize = f.AbsoluteSize
        end
    end)
    game:GetService("UserInputService").InputChanged:Connect(function(input)
        if resizing and input.UserInputType == Enum.UserInputType.MouseMovement then
            local delta = input.Position - resizeStart
            local newW = math.max(300, startSize.X + delta.X)
            local newH = math.max(200, startSize.Y + delta.Y)
            f.Size = UDim2.new(0, newW, 0, newH)
        end
    end)
    game:GetService("UserInputService").InputEnded:Connect(function(input)
        if input.UserInputType == Enum.UserInputType.MouseButton1 then resizing = false end
    end)

    -- Close button
    local close = Instance.new("TextButton")
    close.Size = UDim2.new(0, 120, 0, 36)
    close.Position = UDim2.new(0.5, -60, 1, -48)
    close.Text = "Close"
    close.BackgroundColor3 = Color3.fromRGB(200, 60, 60)
    close.TextColor3 = Color3.fromRGB(255, 255, 255)
    close.TextSize = 14
    close.Font = Enum.Font.GothamBold
    close.Parent = f
    Instance.new("UICorner", close).CornerRadius = UDim.new(0, 8)
    close.MouseButton1Click:Connect(function() sg:Destroy() end)

    -- Parent to PlayerGui or CoreGui
    local pgui = player:FindFirstChild("PlayerGui")
    if pgui then sg.Parent = pgui else sg.Parent = game:GetService("CoreGui") end
    protectGui(sg)

    return sg
end

-- ═══════════════════════════════════════════════════════════════════════════════
-- DUMP HELPERS
-- ═══════════════════════════════════════════════════════════════════════════════

--- Dump an instance tree to a buffer table (for dump scripts).
--- @param buf table Buffer to append lines to
--- @param inst Instance Root instance
--- @param depth? number Current depth (default 0)
--- @param maxDepth? number Max depth (default 8)
local function dumpTree(buf, inst, depth, maxDepth)
    depth = depth or 0
    if depth > (maxDepth or 8) then return end
    local indent = string.rep("  ", depth)
    local extra = ""
    if inst:IsA("BasePart") then
        extra = string.format(" @ (%.1f, %.1f, %.1f) Size=(%.1f,%.1f,%.1f)",
            inst.Position.X, inst.Position.Y, inst.Position.Z,
            inst.Size.X, inst.Size.Y, inst.Size.Z)
    end
    if inst:IsA("ValueBase") then
        extra = string.format(" = %s", tostring(inst.Value))
    end
    if inst:IsA("TextLabel") or inst:IsA("TextButton") then
        extra = string.format(" Text='%s' Vis=%s", (inst.Text or ""):sub(1, 80), tostring(inst.Visible))
    end
    if inst:IsA("ImageButton") or inst:IsA("ImageLabel") then
        extra = string.format(" Image='%s' Vis=%s", (inst.Image or ""):sub(1, 40), tostring(inst.Visible))
        for _, child in ipairs(inst:GetChildren()) do
            if child:IsA("TextLabel") then
                extra = extra .. string.format(" ChildText='%s'", child.Text:sub(1, 60))
            end
        end
    end
    table.insert(buf, indent .. inst.Name .. " [" .. inst.ClassName .. "]" .. extra)
    for _, child in ipairs(inst:GetChildren()) do
        dumpTree(buf, child, depth + 1, maxDepth)
    end
end

--- Check if a GUI element is visible (walks parent chain).
--- @param desc Instance The element to check
--- @param root Instance Stop walking at this ancestor
--- @return boolean
local function isGuiVisible(desc, root)
    local node = desc
    while node and node ~= root do
        if node:IsA("GuiObject") and node.Visible == false then return false end
        if node:IsA("ScreenGui") and node.Enabled == false then return false end
        node = node.Parent
    end
    return true
end

-- ═══════════════════════════════════════════════════════════════════════════════
-- SCRIPT LIFECYCLE
-- ═══════════════════════════════════════════════════════════════════════════════

--- Clean up all connections and destroy GUI.
--- @param gui? ScreenGui Optional GUI to destroy
local function unloadScript(gui)
    scriptRunning = false
    if antiAfkConnection then
        antiAfkConnection:Disconnect()
        antiAfkConnection = nil
    end
    -- Unanchor HRP if desync was active
    if desyncRunning then
        desyncRunning = false
        local char = player.Character
        local hrp = char and char:FindFirstChild("HumanoidRootPart")
        if hrp then hrp.Anchored = false end
    end
    for _, conn in ipairs(connections) do
        if conn then conn:Disconnect() end
    end
    table.clear(connections)
    if gui then gui:Destroy() end
end

-- ═══════════════════════════════════════════════════════════════════════════════
-- EXPORTS (for scripts that concatenate this file)
-- ═══════════════════════════════════════════════════════════════════════════════
-- All functions are local but available in the same concatenation scope.
-- If you need to access them from outside, assign to _G:
--
--   _G.RUtils = {
--       debugLog = debugLog,
--       clickButton = clickButton,
--       pressE = pressE,
--       pressKey = pressKey,
--       safeTeleport = safeTeleport,
--       clickWorldPart = clickWorldPart,
--       getInteractButtons = getInteractButtons,
--       menuHasButton = menuHasButton,
--       clickMenuButton = clickMenuButton,
--       waitForMenuChange = waitForMenuChange,
--       scrollInteractMenu = scrollInteractMenu,
--       closeInteractMenu = closeInteractMenu,
--       findListFrame = findListFrame,
--       clickListFrameItem = clickListFrameItem,
--       findUIByText = findUIByText,
--       waitForChild = waitForChild,
--       setStatus = setStatus,
--       desyncPause = desyncPause,
--       desyncResume = desyncResume,
--       toggleDesync = toggleDesync,
--       toggleAntiAfk = toggleAntiAfk,
--       startPopupCloser = startPopupCloser,
--       createDumpGui = createDumpGui,
--       dumpTree = dumpTree,
--       isGuiVisible = isGuiVisible,
--       protectGui = protectGui,
--       readBarPercentage = readBarPercentage,
--       isHoldingTool = isHoldingTool,
--       discardHeldItem = discardHeldItem,
--       getPlayerPlot = getPlayerPlot,
--       isOnPlot = isOnPlot,
--       findByKeywords = findByKeywords,
--       scrollAt = scrollAt,
--       unloadScript = unloadScript,
--   }