pulse-rb 1.2.24

package/pulse/helpers/log.lua

@@ -0,0 +1,228 @@
+-- ── Pulse.Log + Pulse.Monitor ─────────────────────────────────────────────────
+-- Structured dev logging with levels, tag filtering, throttling, and assertions.
+-- Active only when _PULSE_DEV = true (injected by compiler in --dev builds).
+-- In prod every call is a single boolean check — zero overhead.
+--
+-- Usage:
+--   Pulse.Log.info("Aimbot", "locked", { name = t.Name, dist = d })
+--   Pulse.Log.warn("globals", "folder missing")
+--   Pulse.Log.error("Cutter", "pcall failed", { err = tostring(e) })
+--   Pulse.Log.assert(x ~= nil, "Cutter", "x must not be nil here")
+--   Pulse.Log.throttle("NapeSize", 5, "debug", "scanning " .. n .. " titans")
+--   Pulse.Log.configure({ level="debug", file="dev.log", tags={"Aimbot"} })
+--
+-- Monitors (live key-value dashboard):
+--   Pulse.Monitor.set("titans", 3)
+--   Pulse.Monitor.getAll()  →  { titans=3, shifters=1, ... }
+
+do
+    -- ── Shared state ─────────────────────────────────────────────────────────
+
+    local _active   = (_PULSE_DEV == true)
+    local _minN     = 2       -- 0=trace 1=debug 2=info 3=warn 4=error
+    local _tagWL    = nil     -- nil=all; table=whitelist
+    local _tagBL    = nil     -- blacklist (only when _tagWL is nil)
+    local _disabledTags = {}  -- per-tag disable (runtime toggle)
+    local _console  = true
+    local _file     = nil
+    local _buf      = {}      -- ring buffer of structured entries
+    local _bufMax   = 600
+    local _seq      = 0       -- monotonic entry ID for GUI polling
+    local _timers   = {}      -- throttle: key → last tick
+    local _knownTags = {}     -- set of all tags ever seen
+    local _subs     = {}      -- subscribers: fn(entry) — used by Pulse.Narrate etc.
+
+    local _N   = { trace=0, debug=1, info=2, warn=3, error=4 }
+    local _LBL = { [0]="TRC", [1]="DBG", [2]="INF", [3]="WRN", [4]="ERR" }
+    local _HS  = game:GetService("HttpService")
+
+    -- ── Helpers ───────────────────────────────────────────────────────────────
+
+    local function _ts()
+        local ok, s = pcall(os.date, "%H:%M:%S")
+        return (ok and type(s) == "string") and s
+            or string.format("%d", math.floor(tick() % 86400))
+    end
+
+    local function _fmtData(data)
+        if data == nil then return "" end
+        if type(data) ~= "table" then return "  " .. tostring(data) end
+        local ok, s = pcall(function() return _HS:JSONEncode(data) end)
+        return ok and ("  " .. s) or ""
+    end
+
+    local function _tagAllowed(tag)
+        if _disabledTags[tag] then return false end
+        if _tagWL then return _tagWL[tag] == true end
+        if _tagBL then return _tagBL[tag] ~= true end
+        return true
+    end
+
+    local function _emit(tag, n, msg, data)
+        if not _active          then return end
+        if n < _minN            then return end
+        if not _tagAllowed(tag) then return end
+
+        _knownTags[tag] = true
+        local ts   = _ts()
+        local line = string.format("[%s] %s [%s] %s%s", ts, _LBL[n], tag, tostring(msg), _fmtData(data))
+
+        _seq = _seq + 1
+        local entry = { id=_seq, ts=ts, n=n, lbl=_LBL[n], tag=tag, msg=tostring(msg), data=data, line=line }
+        _buf[#_buf + 1] = entry
+        if #_buf > _bufMax then table.remove(_buf, 1) end
+
+        if _console then
+            if n >= 3 then warn(line) else print(line) end
+        end
+        for _, fn in ipairs(_subs) do pcall(fn, entry) end
+        if _file then
+            pcall(function()
+                if type(rawget(_G, "appendfile")) == "function" then
+                    appendfile(_file, line .. "\n")
+                end
+            end)
+        end
+    end
+
+    -- ── Public API ────────────────────────────────────────────────────────────
+
+    Pulse.Log = {}
+
+    -- Configure (call from rb/pulse/dev/devconfig.lua).
+    -- opts: level, console, file, tags (whitelist array), except (blacklist array)
+    function Pulse.Log.configure(opts)
+        if not _active then return end
+        if opts.level   ~= nil then _minN    = _N[opts.level] or _minN end
+        if opts.console ~= nil then _console = opts.console end
+        if opts.file    ~= nil then _file    = opts.file
+            -- Start fresh log file for this session.
+            if _file then
+                pcall(function()
+                    if type(rawget(_G, "writefile")) == "function" then
+                        writefile(_file, string.format("=== Pulse Dev  %s ===\n", _ts()))
+                    end
+                end)
+            end
+        end
+        if opts.tags ~= nil then
+            _tagWL = {}; _tagBL = nil
+            for _, t in ipairs(opts.tags) do _tagWL[t] = true end
+        elseif opts.except ~= nil then
+            _tagBL = {}; _tagWL = nil
+            for _, t in ipairs(opts.except) do _tagBL[t] = true end
+        end
+    end
+
+    -- Per-tag enable/disable at runtime (used by debug UI toggles).
+    function Pulse.Log.setTagEnabled(tag, enabled)
+        _disabledTags[tag] = not enabled
+    end
+
+    -- Returns a copy of all tags ever seen (for the debug UI tag list).
+    function Pulse.Log.getKnownTags()
+        local t = {}
+        for tag in pairs(_knownTags) do t[#t+1] = tag end
+        table.sort(t)
+        return t
+    end
+
+    -- Poll for entries newer than `afterId` (0 = all).  Used by the debug GUI.
+    function Pulse.Log.getNewEntries(afterId)
+        local result = {}
+        for _, e in ipairs(_buf) do
+            if e.id > afterId then result[#result+1] = e end
+        end
+        return result
+    end
+
+    -- Log levels.
+    function Pulse.Log.trace(tag, msg, data) _emit(tag, 0, msg, data) end
+    function Pulse.Log.debug(tag, msg, data) _emit(tag, 1, msg, data) end
+    function Pulse.Log.info (tag, msg, data) _emit(tag, 2, msg, data) end
+    function Pulse.Log.warn (tag, msg, data) _emit(tag, 3, msg, data) end
+    function Pulse.Log.error(tag, msg, data) _emit(tag, 4, msg, data) end
+
+    -- Assertion — logs ERROR if condition is false; never throws.
+    function Pulse.Log.assert(cond, tag, msg, data)
+        if not cond then _emit(tag, 4, "ASSERT: " .. tostring(msg), data) end
+    end
+
+    -- Throttled log — safe for Heartbeat loops; at most once per `interval` s.
+    function Pulse.Log.throttle(tag, interval, level, msg, data)
+        if not _active then return end
+        local key = tag .. "|" .. tostring(msg)
+        local now = tick()
+        if _timers[key] and (now - _timers[key]) < interval then return end
+        _timers[key] = now
+        _emit(tag, _N[level] or 2, msg, data)
+    end
+
+    -- Dump a table as a debug entry.
+    function Pulse.Log.snapshot(tag, label, tbl)
+        _emit(tag, 1, "snapshot: " .. tostring(label), tbl)
+    end
+
+    -- Subscribe to all emitted entries (used by Pulse.Narrate for auto-narration).
+    function Pulse.Log.subscribe(fn)
+        _subs[#_subs + 1] = fn
+    end
+
+    -- Watch a Signal for value changes — logs every time it fires.
+    -- Essential for "feature randomly stops working": you'll see exactly when
+    -- and to what value the signal was set.
+    -- Usage: Pulse.Log.watchSignal(Components.Aimbot.enabled, "aimbot", "enabled")
+    function Pulse.Log.watchSignal(signal, tag, name)
+        if not _active then return end
+        signal:onChange(function(v)
+            _emit(tag, 2, "signal change: " .. tostring(name or "?") .. " → " .. tostring(v))
+        end)
+    end
+
+    -- Compat / utility.
+    function Pulse.Log.enable()  _active = true  end
+    function Pulse.Log.disable() _active = false end
+    function Pulse.Log.clear()   _buf = {}; _timers = {}; _seq = 0 end
+    function Pulse.Log.dump()    local t={}; for _,e in ipairs(_buf) do t[#t+1]=e.line end; return table.concat(t,"\n") end
+    function Pulse.Log.save(path)
+        path = path or "pulse_log.txt"
+        if type(rawget(_G, "writefile")) == "function" then
+            pcall(writefile, path, Pulse.Log.dump())
+            return true
+        end
+        return false
+    end
+
+    if _active then
+        print("[Pulse.Log] dev mode  — configure via Pulse.Log.configure({...})")
+    end
+end
+
+-- ── Pulse.Monitor ─────────────────────────────────────────────────────────────
+-- Lightweight live key-value store for the debug UI monitor bar.
+-- Pulse.Monitor.set("titans", 3) anywhere; debug GUI reads it every frame.
+
+do
+    local _vals = {}
+    local _subs = {}
+
+    Pulse.Monitor = {}
+
+    function Pulse.Monitor.set(key, value)
+        _vals[key] = value
+        for _, fn in ipairs(_subs) do pcall(fn, key, value) end
+    end
+
+    -- Increment a named counter — use in loop bodies to prove execution.
+    -- Put Pulse.Monitor.tick("aimbot") inside a Heartbeat loop and watch
+    -- the monitor bar: if the count stops increasing, the loop stopped.
+    function Pulse.Monitor.tick(key)
+        local v = (_vals[key] or 0) + 1
+        _vals[key] = v
+        for _, fn in ipairs(_subs) do pcall(fn, key, v) end
+    end
+
+    function Pulse.Monitor.get(key)       return _vals[key] end
+    function Pulse.Monitor.getAll()       local t={}; for k,v in pairs(_vals) do t[k]=v end; return t end
+    function Pulse.Monitor.subscribe(fn)  _subs[#_subs+1] = fn end
+end

package/pulse/helpers/loop.lua

@@ -0,0 +1,58 @@
+-- ── Pulse.Loop ───────────────────────────────────────────────────────────────
+-- A managed task loop with lifecycle logging and spam-safe error handling.
+-- Usage:
+--   local loop = Pulse.Loop.new(1.0, function() ... end, "Aimbot")
+--
+--   loop:start()         -- begin (restarts if already running)
+--   loop:stop()          -- cancel (safe even if not running)
+--   loop:running()       → bool
+--   loop:setInterval(n)  -- change interval while running
+
+Pulse.Loop = (function()
+    local L = {}
+
+    -- interval: seconds between ticks
+    -- fn: body; return false to self-stop
+    -- tag: log tag for this loop (optional, defaults to "loop")
+    function L.new(interval, fn, tag)
+        local _tag  = tag or "loop"
+        local self  = { _id = nil, _interval = interval, _fn = fn }
+
+        function self:start()
+            self:stop()     -- stop previous run if any (silent — _id already nil after stop)
+            local id = {}
+            self._id = id
+            Pulse.Log.trace(_tag, "loop started", { interval = self._interval })
+            task.spawn(function()
+                while self._id == id do
+                    local ok, result = pcall(self._fn)
+                    if not ok then
+                        -- Throttle to once every 5 s per unique error so loops can't spam.
+                        Pulse.Log.throttle(_tag, 5, "warn", "loop error", { err = tostring(result) })
+                    elseif result == false then
+                        Pulse.Log.trace(_tag, "loop self-stopped")
+                        break
+                    end
+                    if self._id == id then
+                        task.wait(self._interval)
+                    end
+                end
+                if self._id == id then self._id = nil end
+            end)
+        end
+
+        function self:stop()
+            if self._id ~= nil then
+                Pulse.Log.trace(_tag, "loop stopped")
+            end
+            self._id = nil
+        end
+
+        function self:running()      return self._id ~= nil end
+        function self:setInterval(n) self._interval = n end
+
+        return self
+    end
+
+    return L
+end)()

package/pulse/helpers/memory.lua

@@ -0,0 +1,48 @@
+-- ── Pulse.Memory ─────────────────────────────────────────────────────────────
+-- Executor capability checks and safe module resolution.
+-- Usage:
+--   if Pulse.Memory.supports("writefile") then Pulse.Log.save() end
+--   local mem = Pulse.Memory.requireFrom("ODMG", "Client", "Memory")
+
+Pulse.Memory = (function()
+    local M = {}
+
+    -- True if the named global function exists (e.g. "writefile", "readfile").
+    function M.supports(fnName)
+        return type(rawget(_G, fnName)) == "function"
+    end
+
+    -- Test whether a table field is actually writable on this executor.
+    -- Returns true / false.
+    function M.testWritable(tbl, key)
+        if not tbl then return false end
+        local orig
+        if not pcall(function() orig = tbl[key] end) then return false end
+        local test = type(orig) == "number" and (orig + 9999.1) or 9999.1
+        if not pcall(function() tbl[key] = test end) then return false end
+        local readback
+        if not pcall(function() readback = tbl[key] end) then
+            pcall(function() tbl[key] = orig end); return false
+        end
+        pcall(function() tbl[key] = orig end)
+        return readback == test
+    end
+
+    -- Traverse child names from Player.Character and require() the final Instance.
+    -- Returns the module value or nil if any step fails.
+    function M.requireFrom(...)
+        local node = _LocalPlayer.Character
+        if not node then return nil end
+        for _, name in ipairs({...}) do
+            if not node then return nil end
+            local ok, child = pcall(function() return node:FindFirstChild(name) end)
+            if not ok or not child then return nil end
+            node = child
+        end
+        if typeof(node) ~= "Instance" then return nil end
+        local ok, result = pcall(require, node)
+        return ok and result or nil
+    end
+
+    return M
+end)()

package/pulse/helpers/narrate.lua

@@ -0,0 +1,160 @@
+-- Pulse.Narrate — on-screen toast + sound narration for dev builds.
+-- Active only when _PULSE_DEV = true.  In prod every call is a no-op.
+--
+-- Usage:
+--   Pulse.Narrate.say("locking titan", "warn")  -- explicit toast
+--   Pulse.Narrate.configure({ autoLevel = "warn", sound = true, volume = 0.5 })
+--   -- After configure(), Pulse.Log entries at or above autoLevel are auto-narrated.
+
+do
+    local _active    = (_PULSE_DEV == true)
+    local _sound     = true
+    local _volume    = 0.5
+    local _autoN     = 3        -- auto-narrate warn (3) and error (4) by default
+    local _N         = { trace=0, debug=1, info=2, warn=3, error=4 }
+
+    -- Level colors matching the log palette
+    local _colors = {
+        [0] = Color3.fromRGB(72,  72,  90),
+        [1] = Color3.fromRGB(70,  175, 155),
+        [2] = Color3.fromRGB(170, 195, 220),
+        [3] = Color3.fromRGB(215, 165, 45),
+        [4] = Color3.fromRGB(215, 65,  65),
+    }
+
+    -- ── Lazy GUI (created on first call) ─────────────────────────────────────
+    local _gui   = nil
+    local _frame = nil
+    local _label = nil
+    local _TS    = nil
+    pcall(function() _TS = game:GetService("TweenService") end)
+
+    local function _ensureGui()
+        if _gui then return end
+        local parent
+        pcall(function() parent = game:GetService("CoreGui") end)
+        if not parent then
+            pcall(function() parent = game:GetService("Players").LocalPlayer.PlayerGui end)
+        end
+        if not parent then return end
+
+        _gui = Instance.new("ScreenGui")
+        _gui.Name           = "PulseNarrate"
+        _gui.ResetOnSpawn   = false
+        _gui.IgnoreGuiInset = true
+        _gui.DisplayOrder   = 1001
+        pcall(function() _gui.Parent = parent end)
+
+        _frame = Instance.new("Frame")
+        _frame.Name                 = "Toast"
+        _frame.Size                 = UDim2.new(0, 520, 0, 52)
+        _frame.Position             = UDim2.new(0.5, -260, 0, 110)
+        _frame.BackgroundColor3     = Color3.fromRGB(10, 10, 18)
+        _frame.BackgroundTransparency = 0.15
+        _frame.BorderSizePixel      = 0
+        _frame.Visible              = false
+        _frame.Parent               = _gui
+        Instance.new("UICorner", _frame).CornerRadius = UDim.new(0, 8)
+        local stroke = Instance.new("UIStroke", _frame)
+        stroke.Color = Color3.fromRGB(60, 60, 90)
+        stroke.Thickness = 1
+
+        _label = Instance.new("TextLabel")
+        _label.Size                = UDim2.new(1, -20, 1, 0)
+        _label.Position            = UDim2.new(0, 10, 0, 0)
+        _label.BackgroundTransparency = 1
+        _label.Font                = Enum.Font.GothamBold
+        _label.TextSize            = 15
+        _label.TextColor3          = Color3.fromRGB(200, 200, 220)
+        _label.TextXAlignment      = Enum.TextXAlignment.Center
+        _label.TextYAlignment      = Enum.TextYAlignment.Center
+        _label.TextWrapped         = true
+        _label.RichText            = true
+        _label.Text                = ""
+        _label.Parent              = _frame
+    end
+
+    -- ── Sound ─────────────────────────────────────────────────────────────────
+    local _snd = nil
+    local _pitches = { [0]=0.5, [1]=0.7, [2]=1.0, [3]=1.35, [4]=1.7 }
+
+    local function _playSound(n)
+        if not _sound then return end
+        pcall(function()
+            if not _snd then
+                _snd = Instance.new("Sound")
+                _snd.SoundId = "rbxasset://sounds/electronicpingshort.wav"
+                _snd.Parent  = game:GetService("SoundService")
+            end
+            _snd.Volume        = _volume
+            _snd.PlaybackSpeed = _pitches[n] or 1.0
+            _snd:Play()
+        end)
+    end
+
+    -- ── Toast display ─────────────────────────────────────────────────────────
+    local _toastActive = false
+
+    local function _showToast(msg, n)
+        _ensureGui()
+        if not (_frame and _frame.Parent) then return end
+        local color = _colors[n] or _colors[2]
+
+        _label.Text           = tostring(msg)
+        _label.TextColor3     = color
+        _label.TextTransparency = 0
+        _frame.BackgroundTransparency = 0.15
+        _frame.Visible        = true
+        _toastActive          = true
+
+        -- Fade out after 2.8 s
+        task.delay(2.3, function()
+            if not (_frame and _frame.Parent) then return end
+            if _TS then
+                local ti = TweenInfo.new(0.5, Enum.EasingStyle.Quad, Enum.EasingDirection.In)
+                _TS:Create(_frame, ti, { BackgroundTransparency = 1 }):Play()
+                _TS:Create(_label, ti, { TextTransparency = 1 }):Play()
+                task.wait(0.55)
+            end
+            if _frame and _frame.Parent then
+                _frame.Visible = false
+                _toastActive   = false
+                if _label then _label.TextTransparency = 0 end
+            end
+        end)
+    end
+
+    -- ── Public API ────────────────────────────────────────────────────────────
+
+    Pulse.Narrate = {}
+
+    function Pulse.Narrate.configure(opts)
+        if not _active then return end
+        if opts.sound     ~= nil then _sound   = opts.sound  end
+        if opts.volume    ~= nil then _volume  = opts.volume end
+        if opts.autoLevel ~= nil then
+            _autoN = _N[opts.autoLevel] or _autoN
+        end
+    end
+
+    -- Explicitly announce a message.
+    -- levelName: "trace" | "debug" | "info" | "warn" | "error"  (default "info")
+    function Pulse.Narrate.say(msg, levelName)
+        if not _active then return end
+        local n = _N[levelName] or 2
+        local prefix = levelName and ("[" .. levelName:upper():sub(1,3) .. "] ") or ""
+        _showToast(prefix .. tostring(msg), n)
+        _playSound(n)
+    end
+
+    -- Subscribe to Pulse.Log so entries at/above autoLevel get auto-narrated.
+    -- This runs immediately after narrate.lua is loaded (Pulse.Log is already defined).
+    if _active and Pulse.Log and Pulse.Log.subscribe then
+        Pulse.Log.subscribe(function(e)
+            if e.n >= _autoN then
+                _showToast(e.tag .. ": " .. e.msg, e.n)
+                _playSound(e.n)
+            end
+        end)
+    end
+end

package/pulse/helpers/notify.lua

@@ -0,0 +1,51 @@
+-- ── Pulse.Notify ─────────────────────────────────────────────────────────────
+-- In-game notification helpers.
+--
+-- Instant toast:
+--   Pulse.Notify("Aimbot locked on target")
+--   Pulse.Notify("Speed boost active", 5)    -- 5-second toast
+--
+-- Auto-notify when a boolean signal changes:
+--   Pulse.Notify.onToggle(self.enabled, "Aimbot")
+--   -- fires "Aimbot on" when signal → true, "Aimbot off" when → false
+--
+--   Pulse.Notify.onToggle(self.enabled, "AutoFarm", {
+--       on       = "AutoFarm started",   -- custom on message
+--       off      = "AutoFarm stopped",   -- custom off message
+--       duration = 5,                    -- toast duration in seconds (default 3)
+--       notify_on  = true,               -- set false to skip the ON notification
+--       notify_off = true,               -- set false to skip the OFF notification
+--   })
+--
+-- Returns the unsubscribe function so you can stop watching:
+--   local stop = Pulse.Notify.onToggle(sig, "Name")
+--   stop()   -- disconnect
+
+do
+    Pulse.Notify = {}
+
+    -- Make Pulse.Notify(...) callable as a direct shorthand for _PulseNotify.
+    setmetatable(Pulse.Notify, {
+        __call = function(_, msg, duration)
+            pcall(_PulseNotify, tostring(msg), duration or 3)
+        end,
+    })
+
+    -- Watch a boolean signal and fire a toast each time it changes.
+    -- Returns the unsubscribe function (useful inside component:watch).
+    function Pulse.Notify.onToggle(signal, name, opts)
+        opts = opts or {}
+        local dur = opts.duration or 3
+        return signal:onChange(function(v)
+            if v then
+                if opts.notify_on ~= false then
+                    pcall(_PulseNotify, opts.on or (name .. " on"), dur)
+                end
+            else
+                if opts.notify_off ~= false then
+                    pcall(_PulseNotify, opts.off or (name .. " off"), dur)
+                end
+            end
+        end)
+    end
+end

package/pulse/helpers/perf.lua

@@ -0,0 +1,48 @@
+-- ── Pulse.Perf ───────────────────────────────────────────────────────────────
+-- Lightweight frame-time sampler with rolling average and optional warn threshold.
+-- Usage:
+--   Pulse.Perf.tick()               -- call once per frame to sample
+--   Pulse.Perf.avg()                -- average frame time in seconds
+--   Pulse.Perf.fps()                -- estimated FPS (1 / avg)
+--   Pulse.Perf.enabled              -- false when auto-disabled on error
+--   Pulse.Perf.setThreshold(ms)     -- warn when avg > ms  (default 50 ms)
+
+Pulse.Perf = (function()
+    local P = {}
+    P.enabled   = true
+    P._buf      = {}
+    P._max      = 60
+    P._last     = 0
+    P._avg      = 0
+    P._thresh   = 0.05     -- 50 ms
+    P._lastWarn = 0
+    P._warnCD   = 5
+
+    function P.tick()
+        if not P.enabled then return end
+        local ok = pcall(function()
+            local now = tick()
+            if P._last > 0 then
+                local ft = now - P._last
+                P._buf[#P._buf + 1] = ft
+                if #P._buf > P._max then table.remove(P._buf, 1) end
+                local total = 0
+                for i = 1, #P._buf do total = total + P._buf[i] end
+                P._avg = total / #P._buf
+                if P._thresh > 0 and P._avg > P._thresh
+                   and now - P._lastWarn > P._warnCD then
+                    warn("[Pulse.Perf] avg frame time: " .. math.floor(P._avg * 1000) .. " ms")
+                    P._lastWarn = now
+                end
+            end
+            P._last = now
+        end)
+        if not ok then P.enabled = false end
+    end
+
+    function P.avg()              return P._avg                               end
+    function P.fps()              return P._avg > 0 and (1 / P._avg) or 0    end
+    function P.setThreshold(ms)   P._thresh = ms / 1000                       end
+
+    return P
+end)()