pulse-rb 1.2.24

package/pulse/helpers/remote.lua

@@ -0,0 +1,128 @@
+-- ── Pulse.Remote ─────────────────────────────────────────────────────────────
+-- Lazy-resolved, path-cached RemoteEvent / RemoteFunction wrapper.
+-- Paths are slash-separated from ReplicatedStorage: "Remotes/Building".
+--
+-- Usage:
+--   -- Direct fire / invoke
+--   Pulse.Remote.fire("Remotes/Building", "Place", cf)
+--   local result = Pulse.Remote.invoke("Remotes/GetStats")
+--
+--   -- Pre-bound function (preferred in a game's remotes.lua)
+--   func.Remote_Build = Pulse.Remote.bind("Remotes/Building")
+--   func.Remote_Build("Place", cf)
+--
+--   -- Client-event listener
+--   Pulse.Remote.connect("Remotes/Notify", function(msg) ... end)
+--
+--   -- Warm the cache before first use (avoids WaitForChild latency in hot loops)
+--   Pulse.Remote.prefetch("Remotes/Building", "Remotes/Storage")
+
+Pulse.Remote = (function()
+    local R       = {}
+    local _RS     = game:GetService("ReplicatedStorage")
+    local _PENDING = {}          -- sentinel: resolution in progress
+    local _cache  = {}           -- path → Instance | false | _PENDING
+
+    local function _split(path)
+        local parts = {}
+        for part in path:gmatch("[^/]+") do parts[#parts + 1] = part end
+        return parts
+    end
+
+    -- Walk a slash-separated path under ReplicatedStorage via WaitForChild.
+    -- Yields on the first call; O(1) cache hit on every subsequent call.
+    -- Returns the resolved Instance, or nil if any segment is missing.
+    local function _resolve(path)
+        -- Another coroutine may be resolving the same path; wait for it.
+        while _cache[path] == _PENDING do task.wait(0.05) end
+
+        local cached = _cache[path]
+        if cached ~= nil then return cached ~= false and cached or nil end
+
+        _cache[path] = _PENDING
+        local node = _RS
+        for _, part in ipairs(_split(path)) do
+            local ok, child = pcall(function()
+                return node:WaitForChild(part, 10)
+            end)
+            if not ok or not child then
+                Pulse.Log.warn("Remote", "path not found",
+                    { path = path, segment = part })
+                _cache[path] = false
+                return nil
+            end
+            node = child
+        end
+        _cache[path] = node
+        return node
+    end
+
+    -- FireServer a RemoteEvent at `path`.
+    function R.fire(path, ...)
+        local remote = _resolve(path)
+        if not remote then return end
+        local args = { ... }
+        local ok, err = pcall(function()
+            remote:FireServer(table.unpack(args))
+        end)
+        if not ok then
+            Pulse.Log.warn("Remote", "fire failed",
+                { path = path, err = tostring(err) })
+        end
+    end
+
+    -- InvokeServer a RemoteFunction at `path`. Returns the result or nil.
+    function R.invoke(path, ...)
+        local remote = _resolve(path)
+        if not remote then return nil end
+        local args = { ... }
+        local ok, result = pcall(function()
+            return remote:InvokeServer(table.unpack(args))
+        end)
+        if not ok then
+            Pulse.Log.warn("Remote", "invoke failed",
+                { path = path, err = tostring(result) })
+            return nil
+        end
+        return result
+    end
+
+    -- Connect `fn` to a RemoteEvent's OnClientEvent. Returns the connection.
+    function R.connect(path, fn)
+        local remote = _resolve(path)
+        if not remote then return nil end
+        return remote.OnClientEvent:Connect(fn)
+    end
+
+    -- Returns a pre-bound fire function: fn(...) → fires path with those args.
+    -- Use this in a game's remotes.lua to define named wrappers without boilerplate.
+    function R.bind(path)
+        return function(...) R.fire(path, ...) end
+    end
+
+    -- Returns a pre-bound invoke function: fn(...) → returns invoke result.
+    function R.bindi(path)
+        return function(...) return R.invoke(path, ...) end
+    end
+
+    -- Returns a wrapper object with :fire, :invoke, :connect, :get.
+    -- Useful when you need multiple operations on the same remote in one place.
+    function R.wrap(path)
+        local self = {}
+        function self:fire(...)    R.fire(path, ...)          end
+        function self:invoke(...)  return R.invoke(path, ...) end
+        function self:connect(fn)  return R.connect(path, fn) end
+        function self:get()        return _resolve(path)      end
+        return self
+    end
+
+    -- Resolve paths eagerly in background threads so first-use has zero latency.
+    -- Call Pulse.Remote.prefetch(...) inside a task.spawn in init {}.
+    function R.prefetch(...)
+        for _, path in ipairs({...}) do
+            task.spawn(function() _resolve(path) end)
+        end
+    end
+
+    return R
+end)()

package/pulse/helpers/restore.lua

@@ -0,0 +1,59 @@
+-- ── Pulse.Restore ────────────────────────────────────────────────────────────
+-- Save and restore Instance property values.
+-- Replaces _originalSizes tables, OriginalProtectionValues, etc.
+-- Usage:
+--   local r = Pulse.Restore.new()
+--   r:save(part, "Size")           -- remember current part.Size
+--   r:save(boolValue, "Value")     -- remember current .Value
+--   r:all()                         -- restore everything to saved state
+--   r:one(part, "Size")            -- restore just one entry
+--   r:has(part, "Size")            → bool
+
+Pulse.Restore = (function()
+    local R = {}
+
+    function R.new()
+        local self = { _data = {} }
+
+        local function key(obj, prop)
+            return tostring(obj) .. "\0" .. prop
+        end
+
+        -- Save obj[prop] if not already saved (first-save wins).
+        function self:save(obj, prop)
+            local k = key(obj, prop)
+            if self._data[k] then return end
+            local ok, val = pcall(function() return obj[prop] end)
+            if ok then self._data[k] = { obj = obj, prop = prop, val = val } end
+        end
+
+        -- Restore one saved entry.
+        function self:one(obj, prop)
+            local k   = key(obj, prop)
+            local rec = self._data[k]
+            if rec then
+                pcall(function() rec.obj[rec.prop] = rec.val end)
+                self._data[k] = nil
+            end
+        end
+
+        -- Restore all saved entries and clear the table.
+        function self:all()
+            for _, rec in pairs(self._data) do
+                pcall(function() rec.obj[rec.prop] = rec.val end)
+            end
+            self._data = {}
+        end
+
+        -- Forget saved values without restoring.
+        function self:clear() self._data = {} end
+
+        function self:has(obj, prop)
+            return self._data[key(obj, prop)] ~= nil
+        end
+
+        return self
+    end
+
+    return R
+end)()

package/pulse/helpers/store.lua

@@ -0,0 +1,39 @@
+-- ── Pulse.Store ───────────────────────────────────────────────────────────────
+-- Key-value reactive store — cross-component shared state via named signals.
+-- Usage:
+--   Pulse.Store.define("key", defaultValue)
+--   Pulse.Store.get("key")             → current value
+--   Pulse.Store.set("key", value)      → writes + fires watchers
+--   Pulse.Store.watch("key", fn)       → fn(newValue) on change
+--   Pulse.Store.signal("key")          → raw Signal object
+
+Pulse.Store = (function()
+    local S       = {}
+    local _entries = {}
+
+    function S.define(key, default)
+        if _entries[key] then return end
+        _entries[key] = Signal(default)
+    end
+
+    function S.get(key)
+        local e = _entries[key]
+        return e and e() or nil
+    end
+
+    function S.set(key, value)
+        local e = _entries[key]
+        if e then e(value) end
+    end
+
+    function S.watch(key, fn)
+        local e = _entries[key]
+        if e then e:onChange(fn) end
+    end
+
+    function S.signal(key)
+        return _entries[key]
+    end
+
+    return S
+end)()

package/pulse/helpers/team.lua

@@ -0,0 +1,83 @@
+-- ── Pulse.Team ────────────────────────────────────────────────────────────────
+-- Configurable faction/enemy resolver factory.
+-- Decouples "who is an enemy" logic from features that act on enemies.
+-- Each resolver is an independent object — create one per use-case.
+--
+-- Usage:
+--   local r = Pulse.Team.resolver({
+--       isSelf    = function(e) return e == _LocalPlayer end,
+--       isValid   = function(e) return e.Character ~= nil end,
+--       isHostile = function(e) return func.IsOnWarriorsTeam() ~= func.IsWarrior(e) end,
+--       exclude   = { func.IsParamountShifterFriendly },
+--   })
+--
+--   r:isEnemy(player)          → bool
+--   r:isAlly(player)           → bool (valid, not self, not enemy)
+--   r:filter(playerList)       → list of enemies only
+--   r:partition(playerList)    → allies, enemies  (two return values)
+--
+-- opts fields:
+--   isSelf(entity)     → bool  — entity is the local player / our own unit; always skipped
+--   isValid(entity)    → bool  — entity is in a valid state (alive, has character, etc.)
+--                                Returning false means "skip" but NOT enemy — used for
+--                                pre-filtering dead/respawning players.
+--   isHostile(entity)  → bool  — REQUIRED core check: is this entity on the opposing side?
+--   exclude            = { fn, fn, ... }
+--                                Additional veto functions.  Any fn(entity) returning true
+--                                means "treat as not-enemy" (friendly exceptions, etc.).
+
+Pulse.Team = {}
+
+function Pulse.Team.resolver(opts)
+    opts = opts or {}
+    local R = {}
+
+    -- Internal: run all checks in order. Returns "enemy", "skip", or "ally".
+    local function _classify(entity)
+        if not entity then return "skip" end
+        if opts.isSelf  and opts.isSelf(entity)          then return "skip" end
+        if opts.isValid and not opts.isValid(entity)      then return "skip" end
+        if opts.exclude then
+            for _, fn in ipairs(opts.exclude) do
+                if fn(entity) then return "ally" end
+            end
+        end
+        if not opts.isHostile                             then return "ally" end
+        return opts.isHostile(entity) and "enemy" or "ally"
+    end
+
+    -- True if entity should be targeted as an enemy.
+    function R:isEnemy(entity)
+        return _classify(entity) == "enemy"
+    end
+
+    -- True if entity is valid, not self, and not an enemy.
+    function R:isAlly(entity)
+        return _classify(entity) == "ally"
+    end
+
+    -- Returns a new list containing only enemies from `list`.
+    function R:filter(list)
+        local out = {}
+        for _, e in ipairs(list) do
+            if _classify(e) == "enemy" then out[#out + 1] = e end
+        end
+        return out
+    end
+
+    -- Splits `list` into two lists: allies, enemies.
+    function R:partition(list)
+        local allies, enemies = {}, {}
+        for _, e in ipairs(list) do
+            local c = _classify(e)
+            if c == "enemy" then
+                enemies[#enemies + 1] = e
+            elseif c == "ally" then
+                allies[#allies + 1] = e
+            end
+        end
+        return allies, enemies
+    end
+
+    return R
+end

package/pulse/helpers/testmode.lua

@@ -0,0 +1,80 @@
+-- Pulse.TestMode — dev-build test harness.
+-- Active only when _PULSE_DEV = true.  In prod every call is a no-op.
+--
+-- Usage (in rb/pulse/dev/devconfig.lua):
+--   Pulse.TestMode.configure({ target = "ShifterPartsCutter" })
+--   Pulse.TestMode.configure({ target = { "Aimbot", "ShifterCutter" } })
+--   Pulse.TestMode.configure({ all = true })  -- all features on (normal dev mode)
+--
+-- The defaults runner in compiler.py reads isActive()/isTarget(id) to force
+-- non-target toggles to false before the UI is shown.
+
+do
+    local _active  = (_PULSE_DEV == true)
+    local _enabled = false
+    local _targets = {}   -- set: lowercased target names
+
+    Pulse.TestMode = {}
+
+    -- Configure test mode.  Call from devlog.lua before the defaults runner fires.
+    -- opts.target = "Name" | { "Name1", "Name2" }  — only these features enabled
+    -- opts.all    = true                            — all features on (disable test filter)
+    function Pulse.TestMode.configure(opts)
+        if not _active then return end
+        _targets = {}
+        _enabled = false
+
+        if opts.all then
+            -- explicit "all on" — not in filtered test mode
+            Pulse.Monitor.set("test", "all-on")
+            return
+        end
+
+        local raw = opts.target
+        if raw == nil then return end
+
+        local list = type(raw) == "table" and raw or { raw }
+        for _, name in ipairs(list) do
+            if type(name) == "string" and name ~= "" then
+                _targets[name:lower()] = true
+            end
+        end
+
+        if next(_targets) then
+            _enabled = true
+            local names = {}
+            for n in pairs(_targets) do names[#names + 1] = n end
+            table.sort(names)
+            Pulse.Monitor.set("test", "only:" .. table.concat(names, ","))
+            Pulse.Log.info("testmode", "test mode active", { targets = names })
+        else
+            Pulse.Monitor.set("test", "all-on")
+        end
+    end
+
+    -- Returns true when test mode is filtering features (some are forced off).
+    function Pulse.TestMode.isActive()
+        return _active and _enabled
+    end
+
+    -- Returns true if widgetId belongs to a test target.
+    -- Uses case-insensitive substring match:
+    --   target "ShifterCutter" matches "ShifterCutterEnable", "ShifterCutterKey", etc.
+    function Pulse.TestMode.isTarget(widgetId)
+        if not _active or not _enabled then return true end
+        if next(_targets) == nil then return true end
+        local lower = widgetId:lower()
+        for name in pairs(_targets) do
+            if lower:find(name, 1, true) then return true end
+        end
+        return false
+    end
+
+    -- Returns a sorted list of target names (used by the defaults runner notify).
+    function Pulse.TestMode.getTargets()
+        local t = {}
+        for name in pairs(_targets) do t[#t + 1] = name end
+        table.sort(t)
+        return t
+    end
+end

package/pulse/helpers/trace.lua

@@ -0,0 +1,111 @@
+-- Pulse.Trace — inter-function call tracing for dev builds.
+-- Active only when _PULSE_DEV = true.  In prod every call is a no-op.
+--
+-- Usage (in rb/pulse/dev/devconfig.lua):
+--   Pulse.Trace.instrument(func, "globals")   -- wrap all func.* functions
+--   Pulse.Trace.wrap(someFunc, "tag", "name") -- wrap a single function
+--   Pulse.Trace.disable()                     -- stop tracing without unwrapping
+--   Pulse.Trace.enable()                      -- re-enable
+--
+-- Output example:
+--   → IsWarrior  Player1
+--   ← IsWarrior  true
+--   → GetCachedTitans  (none)
+--   ← GetCachedTitans  {n=3}
+
+do
+    local _active = (_PULSE_DEV == true)
+    local _on     = true
+
+    -- ── Value serializer ─────────────────────────────────────────────────────
+    -- Converts a single Lua/Roblox value to a short readable string.
+    local function _val(v)
+        local t = type(v)
+        if t == "nil"     then return "nil" end
+        if t == "boolean" then return tostring(v) end
+        if t == "number"  then
+            -- trim unnecessary decimals
+            local s = string.format("%.4g", v)
+            return s
+        end
+        if t == "string" then
+            local s = v:sub(1, 28)
+            return '"' .. s .. (v:len() > 28 and '…"' or '"')
+        end
+        if t == "table" then
+            local n = 0; for _ in pairs(v) do n = n + 1 end
+            return "{n=" .. n .. "}"
+        end
+        -- Roblox Instance, Vector3, CFrame, etc.
+        local ok, s = pcall(tostring, v)
+        if ok then return s:sub(1, 36) end
+        return "<?>"
+    end
+
+    -- Serializes variadic args to a single display string.
+    local function _args(...)
+        local n = select("#", ...)
+        if n == 0 then return "(none)" end
+        local parts = {}
+        for i = 1, math.min(n, 4) do
+            parts[i] = _val(select(i, ...))
+        end
+        if n > 4 then parts[#parts + 1] = "+" .. (n - 4) .. " more" end
+        return table.concat(parts, "  ")
+    end
+
+    -- Serializes return values (same logic).
+    local function _rets(pack)
+        local n = pack.n
+        if n == 0 then return "(none)" end
+        local parts = {}
+        for i = 1, math.min(n, 4) do
+            parts[i] = _val(pack[i])
+        end
+        if n > 4 then parts[#parts + 1] = "+" .. (n - 4) .. " more" end
+        return table.concat(parts, "  ")
+    end
+
+    -- ── Public API ────────────────────────────────────────────────────────────
+
+    Pulse.Trace = {}
+
+    function Pulse.Trace.enable()  _on = true  end
+    function Pulse.Trace.disable() _on = false end
+
+    -- Wrap a single function.  The returned function is safe — it never swallows
+    -- errors; it re-throws after logging so callers behave identically.
+    function Pulse.Trace.wrap(fn, tag, name)
+        if not _active then return fn end
+        local _name = tostring(name or "?")
+        return function(...)
+            if not _on then return fn(...) end
+            Pulse.Log.trace(tag, "→ " .. _name, { in_ = _args(...) })
+            local results = table.pack(pcall(fn, ...))
+            local ok = table.remove(results, 1)
+            results.n = results.n - 1
+            if ok then
+                Pulse.Log.trace(tag, "← " .. _name, { out = _rets(results) })
+                return table.unpack(results, 1, results.n)
+            else
+                local err = tostring(results[1])
+                Pulse.Log.error(tag, "✕ " .. _name .. " threw", { err = err })
+                error(results[1], 2)
+            end
+        end
+    end
+
+    -- Wrap every function-valued field in tbl in-place.
+    -- Useful for tracing all func.* helpers at once from devlog.lua.
+    function Pulse.Trace.instrument(tbl, tag)
+        if not _active then return end
+        local count = 0
+        for k, v in pairs(tbl) do
+            if type(v) == "function" then
+                tbl[k] = Pulse.Trace.wrap(v, tag, k)
+                count = count + 1
+            end
+        end
+        Pulse.Log.debug(tag, "instrumented", { functions = count })
+    end
+end

package/pulse/helpers/track.lua

@@ -0,0 +1,85 @@
+-- ── Pulse.Track ──────────────────────────────────────────────────────────────
+-- Entity lifecycle tracking — apply effects and auto-cleanup when they leave.
+-- Usage:
+--   local tracker = Pulse.Track.new("Aimbot")   -- name is optional but helps logs
+--
+--   tracker:apply(titan, function(t)
+--       Pulse.Draw.removeHighlight(t:FindFirstChild("Hitboxes"), "ESP")
+--   end)
+--
+--   on Heartbeat every 1.0 when titanEnabled {
+--       tracker:cleanup(func.IsTitanDead)
+--       for _, t in ipairs(func.GetCachedTitans()) do
+--           if not tracker:has(t) then applyESP(t) end
+--       end
+--   }
+--
+--   on titanEnabled { if not v then tracker:clear() end }
+
+Pulse.Track = (function()
+    local T = {}
+
+    function T.new(name)
+        local _tag  = "track" .. (name and (":" .. name) or "")
+        local self  = { _e = {}, _c = {} }
+
+        -- Mark entity as tracked; cleanupFn(entity) is called when removed.
+        function self:apply(entity, cleanupFn)
+            self._e[entity] = true
+            if cleanupFn then self._c[entity] = cleanupFn end
+            Pulse.Log.trace(_tag, "apply", { name = pcall(function() return entity.Name end) and entity.Name or "?" })
+        end
+
+        -- Remove one entity and call its cleanup function.
+        function self:remove(entity)
+            if not self._e[entity] then return end
+            local fn = self._c[entity]
+            if fn then pcall(fn, entity) end
+            local eName = "?"
+            pcall(function() eName = entity.Name end)
+            Pulse.Log.trace(_tag, "remove", { name = eName })
+            self._e[entity] = nil; self._c[entity] = nil
+        end
+
+        -- Remove all entities where predicate(entity) returns true.
+        function self:cleanup(predicate)
+            local toRemove = {}
+            for entity in pairs(self._e) do
+                local ok, result = pcall(predicate, entity)
+                if ok and result then toRemove[#toRemove + 1] = entity end
+            end
+            if #toRemove > 0 then
+                Pulse.Log.debug(_tag, "cleanup", { removed = #toRemove, remaining = self:count() - #toRemove })
+            end
+            for _, entity in ipairs(toRemove) do self:remove(entity) end
+        end
+
+        -- Remove every tracked entity and call all cleanup functions.
+        function self:clear()
+            local n = self:count()
+            if n > 0 then
+                Pulse.Log.debug(_tag, "clear", { count = n })
+            end
+            for entity in pairs(self._e) do
+                local fn = self._c[entity]
+                if fn then pcall(fn, entity) end
+            end
+            self._e = {}; self._c = {}
+        end
+
+        function self:has(entity) return self._e[entity] == true end
+
+        function self:count()
+            local n = 0; for _ in pairs(self._e) do n = n + 1 end; return n
+        end
+
+        -- Call fn(entity) for every tracked entity (errors are swallowed).
+        function self:each(fn)
+            for entity in pairs(self._e) do pcall(fn, entity) end
+        end
+
+        return self
+    end
+
+    return T
+end)()

package/pulse/helpers/vec.lua

@@ -0,0 +1,52 @@
+-- ── Pulse.Vec ────────────────────────────────────────────────────────────────
+-- NaN-safe Vector3 utilities.
+-- Replaces `tostring(dir.X) == "nan"` guards and zero-distance crashes.
+-- Usage:
+--   local dir = Pulse.Vec.dir(fromPos, toPos)        -- safe unit direction
+--   local dir = Pulse.Vec.flatDir(fromPos, toPos)    -- XZ-plane only
+--   local ok  = Pulse.Vec.isValid(someVec)           -- no NaN/inf
+
+Pulse.Vec = (function()
+    local V  = {}
+    local _n = math.huge  -- used for inf check
+
+    local function isNaN(n) return n ~= n end
+
+    -- Unit direction from `from` to `to`. Returns fallback if positions overlap.
+    function V.dir(from, to, fallback)
+        local d = to - from
+        if d.Magnitude < 1e-6 then
+            return fallback or Vector3.new(0, 0, 1)
+        end
+        return d.Unit
+    end
+
+    -- XZ-plane unit direction (Y ignored). Falls back to camera look if coincident.
+    function V.flatDir(from, to, fallback)
+        local dx = to.X - from.X
+        local dz = to.Z - from.Z
+        local mag = math.sqrt(dx * dx + dz * dz)
+        if mag < 1e-6 then
+            if fallback then return fallback end
+            local cam = workspace.CurrentCamera
+            if cam then
+                local lv = cam.CFrame.LookVector
+                if math.sqrt(lv.X * lv.X + lv.Z * lv.Z) > 1e-6 then
+                    return Vector3.new(lv.X, 0, lv.Z).Unit
+                end
+            end
+            return Vector3.new(0, 0, 1)
+        end
+        return Vector3.new(dx / mag, 0, dz / mag)
+    end
+
+    -- True if vec has no NaN or infinite components.
+    function V.isValid(vec)
+        if typeof(vec) ~= "Vector3" then return false end
+        return not (isNaN(vec.X) or isNaN(vec.Y) or isNaN(vec.Z)
+                 or vec.X == _n  or vec.Y == _n  or vec.Z == _n
+                 or vec.X == -_n or vec.Y == -_n or vec.Z == -_n)
+    end
+
+    return V
+end)()