@rb-pulse/core 1.2.24

package/index.ts

@@ -0,0 +1,399 @@
+/**
+ * @pulse/core — Component, signal, and event API for Pulse framework scripts.
+ *
+ * Write game scripts in TypeScript; compile to Lua via `rb build`.
+ * Every API maps 1-to-1 to the Pulse Lua runtime.
+ *
+ * @example
+ * ```typescript
+ * import { defineComponent, signal, on } from '@pulse/core'
+ * import { toggle, slider } from '@pulse/ui'
+ *
+ * export const KillAura = defineComponent(() => {
+ *   const enabled = signal(false)
+ *   const range   = signal(50)
+ *
+ *   on.heartbeat({ when: enabled, every: 0.1 }, dt => {
+ *     // runs every 0.1 s while enabled === true
+ *   })
+ *
+ *   return [
+ *     toggle('Kill Aura').bind(enabled),
+ *     slider('Range', { min: 1, max: 500 }).bind(range),
+ *   ]
+ * })
+ * ```
+ */
+
+// ── Signal ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Reactive state cell returned by `signal()`.
+ *
+ * Call it to read the current value; use `.set()` to write.
+ * Changes automatically propagate to UI widgets, event guards, and watchers.
+ *
+ * Compiles to: `Signal(initialValue)` in Lua.
+ */
+export interface Signal<T> {
+  /** Read the current value. Compiles to: `signalName()` */
+  (): T
+  /**
+   * Write a new value. Triggers UI, handler, and watcher updates.
+   * Compiles to: `signalName.set(value)`
+   */
+  set(value: T): void
+  /**
+   * Toggle the signal value (boolean signals only).
+   * Equivalent to `signal.set(!signal())`.
+   * Compiles to: `signalName.toggle()`
+   *
+   * @example
+   * const enabled = signal(false)
+   * button('Toggle').onClick(() => enabled.toggle())
+   */
+  toggle(this: Signal<boolean>): void
+  /**
+   * Subscribe to value changes. The callback fires immediately with the
+   * current value, then on every subsequent change.
+   * Returns an unsubscribe function.
+   * Compiles to: `signalName.watch(fn)`
+   *
+   * @example
+   * const unsubscribe = enabled.watch(v => {
+   *   print('enabled changed to', v)
+   * })
+   * // later: unsubscribe()
+   */
+  watch(fn: (value: T) => void): () => void
+  /**
+   * Mirror this signal's value into another signal on every change.
+   * Useful for propagating values across component boundaries.
+   * Compiles to: `signalName.mirror(target)`
+   */
+  mirror(target: Signal<T>): void
+}
+
+/**
+ * Derived signal — recomputes when any signal read inside `fn` changes.
+ * Read-only; no `.set()`.
+ *
+ * Compiles to: `Computed(fn)` in Lua.
+ */
+export interface Computed<T> {
+  (): T
+}
+
+// ── Event options ──────────────────────────────────────────────────────────────
+
+/**
+ * Options for periodic event handlers (`on.heartbeat`, `on.renderStepped`, `on.stepped`).
+ * Both fields are optional — omit entirely to run every frame with no guard.
+ */
+export interface HandlerOpts {
+  /**
+   * Gate: skip the callback while this signal is `false`.
+   * The event connection stays alive but the callback is skipped.
+   * Compiles to: `when = signalName` in the event binding.
+   */
+  when?: Signal<boolean>
+  /**
+   * Throttle: minimum seconds between callback invocations.
+   * Uses an internal accumulator — does not create extra connections.
+   * Accepts a number or a reactive `Signal<number>` for live adjustment.
+   * Compiles to: `every = value` in the event binding.
+   *
+   * @default 0  (every frame)
+   */
+  every?: number | Signal<number>
+}
+
+// ── Widget base ────────────────────────────────────────────────────────────────
+
+/** Base interface shared by all widget definitions returned from `defineComponent`. */
+export interface WidgetDef {
+  /**
+   * Bind this widget to a signal so their values stay in sync.
+   * The widget writes the signal on user interaction; the signal
+   * drives the widget when set programmatically.
+   */
+  bind(signal: Signal<any>): this
+}
+
+// ── Component ──────────────────────────────────────────────────────────────────
+
+/** Setup function type for `defineComponent`. */
+export type ComponentSetup = () => WidgetDef[]
+
+/**
+ * Opaque component handle returned by `defineComponent`.
+ * Pass it to `groupbox({ mount: MyComponent })` to embed its widgets.
+ */
+export interface Component<S extends ComponentSetup> {
+  readonly _type:    'component'
+  readonly _widgets: ReturnType<S>
+}
+
+// ── Core API ───────────────────────────────────────────────────────────────────
+
+/**
+ * Define a Pulse component — the primary building block.
+ *
+ * The setup function runs once on initialisation.
+ * Declare signals, register event handlers with `on.*`, then return an array
+ * of widget definitions to mount into the component's groupbox.
+ * All `on.*` subscriptions are auto-disconnected when the component is destroyed.
+ *
+ * Compiles to a self-contained Lua IIFE with Signal/bind wiring.
+ *
+ * @param setup  Called once at init. Returns UI widget array.
+ *
+ * @example
+ * export const SpeedHack = defineComponent(() => {
+ *   const enabled = signal(false)
+ *   const speed   = signal(16)
+ *
+ *   on.heartbeat({ when: enabled }, () => {
+ *     // manipulate character walkspeed
+ *   })
+ *
+ *   on.respawn(() => {
+ *     if (enabled()) applySpeed(speed())
+ *   })
+ *
+ *   return [
+ *     toggle('Speed hack').bind(enabled),
+ *     slider('Speed', { min: 1, max: 250, suffix: ' studs/s' }).bind(speed),
+ *   ]
+ * })
+ */
+export declare function defineComponent<S extends ComponentSetup>(setup: S): Component<S>
+
+/**
+ * Create a reactive state cell with an initial value.
+ *
+ * Compiles to: `Signal(initialValue)` in Lua.
+ *
+ * @param initialValue  The starting value.
+ *
+ * @example
+ * const enabled = signal(false)   // Signal<boolean>
+ * const range   = signal(50)      // Signal<number>
+ * const mode    = signal('Auto')  // Signal<string>
+ *
+ * enabled()           // read → false
+ * enabled.set(true)   // write
+ * enabled.toggle()    // flip boolean
+ * enabled.watch(v => print(v))  // subscribe
+ */
+export declare function signal<T>(initialValue: T): Signal<T>
+
+/**
+ * Create a derived signal that recomputes automatically when its dependencies change.
+ *
+ * Compiles to: `Computed(fn)` in Lua.
+ *
+ * @param fn  Pure function reading one or more signals. Must not have side effects.
+ *
+ * @example
+ * const fov   = signal(90)
+ * const label = computed(() => `FOV: ${fov()}`)
+ *
+ * // Use in a toggle tooltip or paragraph widget
+ * paragraph('Current FOV', label())
+ */
+export declare function computed<T>(fn: () => T): Computed<T>
+
+// ── Event namespace ────────────────────────────────────────────────────────────
+
+/**
+ * Event subscription namespace.
+ * All connections are automatically cleaned up when the component is destroyed.
+ *
+ * @example
+ * on.heartbeat({ when: enabled, every: 0.1 }, dt => { ... })
+ * on.heartbeat(dt => updateDisplay(dt))           // no opts overload
+ * on.signal(range, v => applyRange(v))            // signal watcher
+ * on.inputBegan(input => handleKey(input))
+ * on.respawn(() => reapplyEffects())
+ * on.after(0.5, () => init())                     // delayed one-shot
+ */
+export declare const on: {
+  /**
+   * RunService.Heartbeat — fires every frame.
+   *
+   * Compiles to: `on Heartbeat { when = ..., every = ... }` in .rblua.
+   *
+   * @param opts     Optional `when` guard and `every` throttle.
+   * @param fn       Callback invoked each (throttled) tick. Receives delta-time.
+   *
+   * @example
+   * // Throttled, gated
+   * on.heartbeat({ when: enabled, every: 0.1 }, dt => {
+   *   doWork()
+   * })
+   *
+   * // Every frame, no guard
+   * on.heartbeat(dt => updateDisplay(dt))
+   */
+  heartbeat(opts: HandlerOpts, fn: (dt: number) => void): void
+  heartbeat(fn: (dt: number) => void): void
+
+  /**
+   * RunService.RenderStepped — fires before every frame render (client only).
+   * Prefer `heartbeat` for game logic; use this for camera / visual work.
+   *
+   * @example
+   * on.renderStepped({ when: espEnabled }, dt => drawBoxes(dt))
+   * on.renderStepped(dt => updateCamera(dt))
+   */
+  renderStepped(opts: HandlerOpts, fn: (dt: number) => void): void
+  renderStepped(fn: (dt: number) => void): void
+
+  /**
+   * RunService.Stepped — fires at the physics step rate.
+   *
+   * @example
+   * on.stepped({ when: enabled }, (t, dt) => applyVelocity(dt))
+   */
+  stepped(opts: HandlerOpts, fn: (time: number, dt: number) => void): void
+  stepped(fn: (time: number, dt: number) => void): void
+
+  /**
+   * UserInputService.InputBegan.
+   *
+   * @example
+   * on.inputBegan((input, gpe) => {
+   *   if (gpe) return
+   *   if (input.KeyCode === Enum.KeyCode.X) enabled.toggle()
+   * })
+   */
+  inputBegan(fn: (input: InputObject, gameProcessed: boolean) => void): void
+
+  /**
+   * UserInputService.InputEnded.
+   *
+   * @example
+   * on.inputEnded(input => {
+   *   if (input.UserInputType === Enum.UserInputType.MouseButton1) release()
+   * })
+   */
+  inputEnded(fn: (input: InputObject, gameProcessed: boolean) => void): void
+
+  /**
+   * Fires when the player's character respawns.
+   * Use this to re-apply effects that attach to the character.
+   *
+   * @example
+   * on.respawn(() => {
+   *   if (enabled()) applySpeed(speed())
+   * })
+   */
+  respawn(fn: () => void): void
+
+  /**
+   * Player.CharacterAdded — fires when a new character model is added.
+   *
+   * @example
+   * on.characterAdded(char => {
+   *   const hrp = char.WaitForChild('HumanoidRootPart') as BasePart
+   * })
+   */
+  characterAdded(fn: (character: Model) => void): void
+
+  /**
+   * Player.CharacterRemoving — fires just before the character is removed.
+   *
+   * @example
+   * on.characterRemoving(() => cleanup())
+   */
+  characterRemoving(fn: (character: Model) => void): void
+
+  /**
+   * Subscribe to changes on a signal — fires immediately with the current value,
+   * then on every subsequent change. Part of component lifecycle (auto-disconnected).
+   *
+   * Compiles to: `on signalName { }` signal handler in .rblua.
+   *
+   * @param sig  The signal to watch.
+   * @param fn   Called with the new value on every change.
+   *
+   * @example
+   * on.signal(enabled, v => {
+   *   if (v) activateESP() else deactivateESP()
+   * })
+   *
+   * on.signal(range, v => updateAimRadius(v))
+   */
+  signal<T>(sig: Signal<T>, fn: (val: T) => void): void
+
+  /**
+   * Run a one-shot callback after a delay.
+   * Runs inside the component's init phase — useful for deferred setup.
+   * Compiles to: `task.delay(seconds, fn)` wrapped in component lifecycle.
+   *
+   * @param seconds  Delay in seconds (0.5 is typical for post-mount init).
+   * @param fn       Callback to run once.
+   *
+   * @example
+   * on.after(0.5, () => {
+   *   // safe to read UI state here — everything is mounted
+   *   Pulse.UI.paragraph('Info', 'Loaded!')
+   * })
+   */
+  after(seconds: number, fn: () => void): void
+}
+
+// ── Roblox type stubs ──────────────────────────────────────────────────────────
+// Minimal stubs so editors don't error. Install @pulse/roblox for full types.
+
+/** @see @pulse/roblox */
+export interface InputObject {
+  KeyCode:       { Value: number; Name: string }
+  UserInputType: { Value: number; Name: string }
+  Position:      Vector3
+  Delta:         Vector3
+}
+
+/** @see @pulse/roblox */
+export interface Model {
+  WaitForChild(name: string, timeout?: number): Instance
+  FindFirstChild(name: string): Instance | undefined
+  FindFirstChildOfClass(className: string): Instance | undefined
+  GetChildren(): Instance[]
+}
+
+/** @see @pulse/roblox */
+export interface Instance {
+  Name:      string
+  Parent:    Instance | undefined
+  Destroy(): void
+}
+
+/** @see @pulse/roblox */
+export interface BasePart extends Instance {
+  Position:     Vector3
+  CFrame:       CFrame
+  Size:         Vector3
+  Anchored:     boolean
+  CanCollide:   boolean
+  Transparency: number
+}
+
+/** @see @pulse/roblox */
+export interface Vector3 {
+  X: number; Y: number; Z: number
+  Magnitude: number
+  Unit: Vector3
+  add(other: Vector3): Vector3
+  sub(other: Vector3): Vector3
+  mul(scalar: number): Vector3
+}
+
+/** @see @pulse/roblox */
+export interface CFrame {
+  Position:   Vector3
+  LookVector: Vector3
+  RightVector: Vector3
+  UpVector:   Vector3
+}

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@rb-pulse/core",
+  "version": "1.2.24",
+  "description": "Pulse framework — component, signal, and event TypeScript API",
+  "main": "./index.ts",
+  "types": "./index.ts",
+  "files": [
+    "index.ts",
+    "*.d.ts"
+  ],
+  "keywords": [
+    "roblox",
+    "pulse",
+    "lua",
+    "typescript-to-lua"
+  ],
+  "license": "MIT"
+}