pulse-rb 1.2.24

package/pulse/helpers/cache.lua

@@ -0,0 +1,68 @@
+-- ── Pulse.Cache ──────────────────────────────────────────────────────────────
+-- Timed key-value cache and fetch-wrapper.
+-- Usage:
+--   local c = Pulse.Cache.new(2)            -- 2-second TTL per key
+--   c:set("titans", titanList)
+--   local list = c:get("titans")            -- nil after 2 s
+--
+--   local getTitans = Pulse.Cache.wrap(2, function()
+--       return workspace.Titans.Alive:GetChildren()
+--   end)
+
+Pulse.Cache = (function()
+    local C = {}
+
+    -- Create a new timed key-value cache.
+    -- ttl: seconds until entries expire; pass nil for entries that never expire.
+    function C.new(ttl)
+        local self = { _d = {}, _t = {}, _ttl = ttl }
+
+        function self:get(key)
+            if self._ttl then
+                local ts = self._t[key]
+                if ts and (tick() - ts) > self._ttl then
+                    self._d[key] = nil; self._t[key] = nil; return nil
+                end
+            end
+            return self._d[key]
+        end
+
+        function self:set(key, value)
+            self._d[key] = value
+            if self._ttl then self._t[key] = tick() end
+        end
+
+        function self:has(key)  return self:get(key) ~= nil end
+        function self:del(key)  self._d[key] = nil; self._t[key] = nil end
+        function self:clear()   self._d = {}; self._t = {} end
+
+        function self:keys()
+            local result = {}
+            for k in pairs(self._d) do
+                if self:has(k) then result[#result + 1] = k end
+            end
+            return result
+        end
+
+        return self
+    end
+
+    -- Wrap a fetcher so its return value is cached for `ttl` seconds.
+    -- Passes through all arguments to fetcher on cache miss.
+    function C.wrap(ttl, fetcher)
+        local _v, _t = nil, 0
+        return function(...)
+            local now = tick()
+            if _v ~= nil and (now - _t) < ttl then return _v end
+            local ok, result = pcall(fetcher, ...)
+            if ok and result ~= nil then
+                _v = result; _t = now
+            else
+                _v = nil; _t = 0
+            end
+            return _v or {}
+        end
+    end
+
+    return C
+end)()

package/pulse/helpers/cleaner.lua

@@ -0,0 +1,110 @@
+-- ── Pulse.Cleaner ─────────────────────────────────────────────────────────────
+-- Scheduled object-removal scheduler with optional filtering and a named registry.
+-- Pulse.Loop is referenced lazily (inside start()), so load order doesn't matter.
+--
+-- Usage — one-shot cleaner:
+--   local c = Pulse.Cleaner.new({
+--       collect  = function() return workspace.Map.Decor:GetChildren() end,
+--       interval = 1.0,
+--   })
+--   c:start()   c:stop()   c:running()
+--
+-- Usage — named registry (cross-component access):
+--   Pulse.Cleaner.register("mapDecor", { collect = ..., interval = 1 })
+--   Pulse.Cleaner.get("mapDecor"):start()
+--   Pulse.Cleaner.stopAll()
+
+Pulse.Cleaner = (function()
+    local C = {}
+    local _registry = {}
+
+    -- Create a new cleaner.
+    -- opts:
+    --   collect   — function() → {Instance,...}   required
+    --   filter    — function(inst) → bool          optional; return false to skip removal
+    --   interval  — seconds between sweeps         default 1.0
+    --   onSweep   — function(removedCount)         optional callback after each sweep
+    function C.new(opts)
+        opts = opts or {}
+        local self = {
+            totalRemoved = 0,
+            _interval    = opts.interval or 1.0,
+            _collect     = opts.collect  or function() return {} end,
+            _filter      = opts.filter,
+            _onSweep     = opts.onSweep,
+            _loop        = nil,
+        }
+
+        function self:_sweep()
+            local ok, list = pcall(self._collect)
+            if not ok or type(list) ~= "table" or #list == 0 then return end
+            local removed = 0
+            for _, obj in ipairs(list) do
+                local skip = false
+                if self._filter then
+                    local fok, keep = pcall(self._filter, obj)
+                    skip = fok and not keep
+                end
+                if not skip then
+                    if pcall(function() obj:Destroy() end) then
+                        removed = removed + 1
+                    end
+                end
+            end
+            self.totalRemoved = self.totalRemoved + removed
+            if removed > 0 and self._onSweep then
+                pcall(self._onSweep, removed)
+            end
+        end
+
+        function self:start()
+            self:stop()
+            self._loop = Pulse.Loop.new(self._interval, function()
+                self:_sweep()
+            end)
+            self._loop:start()
+        end
+
+        function self:stop()
+            if self._loop then
+                self._loop:stop()
+                self._loop = nil
+            end
+        end
+
+        function self:running()
+            return self._loop ~= nil and self._loop:running()
+        end
+
+        function self:setInterval(n)
+            self._interval = n
+            if self._loop then self._loop:setInterval(n) end
+        end
+
+        function self:reset()
+            self.totalRemoved = 0
+        end
+
+        return self
+    end
+
+    -- Named registry — register once, access from any component.
+    function C.register(name, opts)
+        local c = C.new(opts)
+        _registry[name] = c
+        return c
+    end
+
+    function C.get(name)    return _registry[name] end
+    function C.startAll()   for _, c in pairs(_registry) do c:start() end end
+    function C.stopAll()    for _, c in pairs(_registry) do c:stop()  end end
+
+    function C.registeredNames()
+        local names = {}
+        for k in pairs(_registry) do names[#names + 1] = k end
+        table.sort(names)
+        return names
+    end
+
+    return C
+end)()

package/pulse/helpers/conn.lua

@@ -0,0 +1,33 @@
+-- ── Pulse.Conn ────────────────────────────────────────────────────────────────
+-- Named connection manager — one live connection per name, auto-disconnects on rebind.
+-- Replaces the manual func.BindConnection / func.Disconnect pattern.
+-- Usage:
+--   Pulse.Conn.bind("ESP",        RunService.Heartbeat:Connect(fn))
+--   Pulse.Conn.disconnect("ESP")
+--   Pulse.Conn.disconnectAll()
+
+Pulse.Conn = (function()
+    local C = {}
+    local _named = {}
+
+    function C.bind(name, connection)
+        if _named[name] then pcall(function() _named[name]:Disconnect() end) end
+        _named[name] = connection
+    end
+
+    function C.disconnect(name)
+        if _named[name] then
+            pcall(function() _named[name]:Disconnect() end)
+            _named[name] = nil
+        end
+    end
+
+    function C.disconnectAll()
+        for _, conn in pairs(_named) do
+            pcall(function() conn:Disconnect() end)
+        end
+        _named = {}
+    end
+
+    return C
+end)()

package/pulse/helpers/cooldown.lua

@@ -0,0 +1,47 @@
+-- ── Pulse.Cooldown ───────────────────────────────────────────────────────────
+-- Per-entity (or global) cooldown tracking.
+-- Replaces manual `lastFireTimes = {}` tables scattered across components.
+-- Usage:
+--   local cd = Pulse.Cooldown.new(1.0)          -- single shared cooldown
+--   if cd:ready() then cd:use(); fireRemote() end
+--
+--   local pcd = Pulse.Cooldown.perEntity(0.5)   -- one timer per entity
+--   if pcd:ready(player) then pcd:use(player); applyEffect(player) end
+--   pcd:purge(isDead)                            -- drop entries for dead entities
+
+Pulse.Cooldown = (function()
+    local C = {}
+
+    -- A single shared cooldown (one timestamp).
+    function C.new(duration)
+        local self = { _last = 0, _dur = duration }
+        function self:ready()   return (tick() - self._last) >= self._dur end
+        function self:use()     self._last = tick() end
+        function self:reset()   self._last = 0 end
+        function self:set(d)    self._dur = d end
+        return self
+    end
+
+    -- One cooldown timer per entity (keyed by any value).
+    function C.perEntity(duration)
+        local self = { _times = {}, _dur = duration }
+        function self:ready(key)
+            local t = self._times[key]
+            return not t or (tick() - t) >= self._dur
+        end
+        function self:use(key)    self._times[key] = tick() end
+        function self:reset(key)
+            if key then self._times[key] = nil else self._times = {} end
+        end
+        function self:set(d)      self._dur = d end
+        -- Remove entries where isDeadFn(entity) returns true.
+        function self:purge(isDeadFn)
+            for key in pairs(self._times) do
+                if isDeadFn(key) then self._times[key] = nil end
+            end
+        end
+        return self
+    end
+
+    return C
+end)()

package/pulse/helpers/draw.lua

@@ -0,0 +1,122 @@
+-- ── Pulse.Draw ───────────────────────────────────────────────────────────────
+-- Highlight / Drawing / SelectionBox creation helpers.
+-- Usage:
+--   local hl = Pulse.Draw.highlight(part, "HitboxESP", { fill = Color3.new(1,0,0), fillAlpha = 0.5 })
+--   Pulse.Draw.removeHighlight(part, "HitboxESP")
+--   local ring = Pulse.Draw.circle({ radius = 300, color = Color3.new(1,1,1) })
+--   Pulse.Draw.remove(ring)
+
+Pulse.Draw = (function()
+    local D = {}
+
+    -- Create or replace a named Highlight on an instance.
+    -- opts: fill, outline, fillAlpha (0–1), outlineAlpha (0–1), adornee, alwaysOnTop
+    function D.highlight(target, name, opts)
+        if not target then return nil end
+        opts = opts or {}
+        local old = target:FindFirstChild(name)
+        if old then old:Destroy() end
+        local h = Instance.new("Highlight")
+        h.Name                = name
+        h.FillColor           = opts.fill        or Color3.fromRGB(255, 0,   0)
+        h.OutlineColor        = opts.outline      or Color3.fromRGB(255, 255, 255)
+        h.FillTransparency    = opts.fillAlpha    ~= nil and opts.fillAlpha    or 0.5
+        h.OutlineTransparency = opts.outlineAlpha ~= nil and opts.outlineAlpha or 0
+        h.Adornee             = opts.adornee      or target
+        if opts.alwaysOnTop then
+            h.DepthMode = Enum.HighlightDepthMode.AlwaysOnTop
+        end
+        h.Parent = target
+        return h
+    end
+
+    -- Destroy a named Highlight on target (no-op if missing).
+    function D.removeHighlight(target, name)
+        if not target then return end
+        local h = target:FindFirstChild(name)
+        if h then h:Destroy() end
+    end
+
+    -- Create a Drawing circle (FOV ring, radar dot, etc.).
+    -- opts: color, thickness, alpha, filled, radius, visible, sides, position
+    function D.circle(opts)
+        opts = opts or {}
+        local c = Drawing.new("Circle")
+        c.Color        = opts.color     or Color3.fromRGB(255, 255, 255)
+        c.Thickness    = opts.thickness or 2
+        c.Transparency = opts.alpha     ~= nil and opts.alpha    or 0.8
+        c.Filled       = opts.filled    ~= nil and opts.filled   or false
+        c.Radius       = opts.radius    or 100
+        c.NumSides     = opts.sides     or 64
+        c.Visible      = opts.visible   == nil and true  or opts.visible
+        c.Position     = opts.position  or Vector2.new(0, 0)
+        return c
+    end
+
+    -- Safely remove any Drawing object.
+    function D.remove(drawing)
+        if drawing then pcall(function() drawing:Remove() end) end
+    end
+
+    -- Create or replace a SelectionBox on target.
+    -- opts: color, thickness
+    function D.selectionBox(target, name, opts)
+        if not target then return nil end
+        opts = opts or {}
+        local old = target:FindFirstChild(name)
+        if old then old:Destroy() end
+        local sb = Instance.new("SelectionBox")
+        sb.Name          = name
+        sb.Color3        = opts.color     or Color3.fromRGB(255, 0, 0)
+        sb.LineThickness = opts.thickness or 0.05
+        sb.Adornee       = target
+        sb.Parent        = target
+        return sb
+    end
+
+    -- Create or replace a BillboardGui label on a part (name tag, distance, etc.).
+    -- opts: text, color, size (UDim2), offset (Vector3), alwaysOnTop, fontSize
+    function D.billboard(target, name, opts)
+        if not target then return nil end
+        opts = opts or {}
+        local old = target:FindFirstChild(name)
+        if old then old:Destroy() end
+        local bg = Instance.new("BillboardGui")
+        bg.Name         = name
+        bg.Size         = opts.size   or UDim2.new(0, 120, 0, 28)
+        bg.StudsOffset  = opts.offset or Vector3.new(0, 3, 0)
+        bg.AlwaysOnTop  = opts.alwaysOnTop ~= false
+        bg.Adornee      = target
+        bg.Parent       = target
+        local lbl = Instance.new("TextLabel")
+        lbl.Size                  = UDim2.new(1, 0, 1, 0)
+        lbl.BackgroundTransparency = 1
+        lbl.Text                  = opts.text  or ""
+        lbl.TextColor3            = opts.color or Color3.fromRGB(255, 255, 255)
+        lbl.TextScaled            = true
+        lbl.Font                  = Enum.Font.GothamBold
+        lbl.Parent                = bg
+        return bg
+    end
+
+    -- Destroy a named BillboardGui on target (no-op if missing).
+    function D.removeBillboard(target, name)
+        if not target then return end
+        local b = target:FindFirstChild(name)
+        if b then b:Destroy() end
+    end
+
+    -- Destroy every child named `name` found anywhere under `parent`.
+    -- Useful for batch cleanup after e.g. a Highlights pass.
+    function D.removeAll(name, parent)
+        parent = parent or workspace
+        local list = parent:GetDescendants()
+        for i = 1, #list do
+            if list[i].Name == name then
+                pcall(function() list[i]:Destroy() end)
+            end
+        end
+    end
+
+    return D
+end)()

package/pulse/helpers/hitbox.lua

@@ -0,0 +1,63 @@
+-- ── Pulse.Hitbox ──────────────────────────────────────────────────────────────
+-- Uniform size-expansion manager for BaseParts (hitbox stretching).
+-- Game-agnostic: works on any BasePart regardless of game/character structure.
+-- Saves original sizes on first apply and restores them cleanly.
+--
+-- Usage:
+--   local hm = Pulse.Hitbox.new("enemyHitbox")
+--   hm:apply(part, 30)       -- expand to 30×30×30, saving original
+--   hm:apply(part, 30)       -- idempotent: original already saved
+--   hm:restore(part)         -- restore this part to saved size
+--   hm:restoreAll()          -- restore all managed parts
+--   hm:isExpanded(part)      -- true if part is currently expanded
+--
+-- For visual indicators use Pulse.Draw.selectionBox / Pulse.Draw.highlight separately.
+
+Pulse.Hitbox = {}
+
+function Pulse.Hitbox.new(tag)
+    local self    = {}
+    local _orig   = {}   -- part → Vector3 original Size
+    local _tag    = tag or "hitbox"
+
+    -- Expand part to a uniform size³ cube, saving the original on first call.
+    function self:apply(part, size)
+        if not part or not part:IsA("BasePart") then return end
+        if not _orig[part] then
+            _orig[part] = part.Size
+        end
+        part.Size = Vector3.new(size, size, size)
+    end
+
+    -- Restore a single part to its saved size.  No-op if not managed.
+    function self:restore(part)
+        if not part then return end
+        local orig = _orig[part]
+        if orig then
+            if part.Parent then pcall(function() part.Size = orig end) end
+            _orig[part] = nil
+        end
+    end
+
+    -- Restore all managed parts and clear state.
+    function self:restoreAll()
+        local n = 0
+        for part, orig in pairs(_orig) do
+            if part and part.Parent then
+                pcall(function() part.Size = orig end)
+            end
+            n = n + 1
+        end
+        _orig = {}
+        if n > 0 and Pulse.Log then
+            Pulse.Log.debug(_tag, "restoreAll", { count = n })
+        end
+    end
+
+    -- Returns true if this part is currently expanded by this manager.
+    function self:isExpanded(part)
+        return _orig[part] ~= nil
+    end
+
+    return self
+end

package/pulse/helpers/input.lua

@@ -0,0 +1,24 @@
+-- ── Pulse.Input ──────────────────────────────────────────────────────────────
+-- Key-press simulation using VirtualInputManager + UserInputService.
+-- Usage:
+--   Pulse.Input.simulateKey(Enum.KeyCode.T)
+
+Pulse.Input = (function()
+    local I = {}
+
+    function I.simulateKey(keyCode)
+        pcall(function()
+            _VIM:SendKeyEvent(true,  keyCode, false, game)
+            task.wait(0.1)
+            _VIM:SendKeyEvent(false, keyCode, false, game)
+        end)
+        pcall(function()
+            local ev = { KeyCode = keyCode, UserInputType = Enum.UserInputType.Keyboard }
+            _PulseUIS.InputBegan:Fire(ev, false)
+            task.wait(0.05)
+            _PulseUIS.InputEnded:Fire(ev, false)
+        end)
+    end
+
+    return I
+end)()