{"id":"biotoxin495/gradientkit","name":"gradientkit","scope":"biotoxin495","platform":"roblox","description":"A standalone UIGradient creation and animation utility for Roblox UI, intended to run on the client. GradientKit can create or reuse gradients, apply built-in effects, and return disposable controllers for cleanup. It does not require a UI framework or service container.","version":"1.0.0","latest":"1.0.0","versions":["1.0.0"],"license":"MIT","licenseRating":"safe","licenseCaveats":[],"licenseVerified":true,"dependencies":{},"integrity":"da219ab87d17e22c66af64b40a93fb3c3e5a31007719c1d03b6f5f30d7cf1d48","likes":0,"downloads":0,"install":"forest install biotoxin495/gradientkit","url":"https://forest.dev/p/roblox/biotoxin495/gradientkit","files":"https://api.forest.dev/ai/package/roblox/biotoxin495/gradientkit/files","readme":"# GradientKit — A standalone UIGradient effect library\n\n**GradientKit** is a small, dependency-free Roblox module for creating, reusing, and animating `UIGradient` objects. It provides built-in effects for buttons, cards, titles, backgrounds, and other Roblox UI without requiring a UI framework or service container.\n\nGradientKit can work with gradients authored in Studio or create them automatically. Each active effect owns its tweens and connections, returns a controller for direct control, and restores the gradient's original state when it stops.\n\n## Quick example\n\n```lua\nlocal ReplicatedStorage = game:GetService(\"ReplicatedStorage\")\n\nlocal GradientKit = require(ReplicatedStorage.Packages.GradientKit)\n\nlocal controller = GradientKit.Apply(script.Parent.Button, \"Shine\", {\n\tDuration = 0.8,\n\tDelay = 2,\n})\n\n-- Stop the effect whenever the owning UI is torn down.\ncontroller:Stop()\n```\n\n`Apply` reuses the first `UIGradient` under the target or creates one when necessary.\n\n## ✨ Features\n\n* Fully standalone and dependency-free\n* Works with existing Studio-authored `UIGradient` objects\n* Creates gradients automatically when applying an effect to a `GuiObject`\n* One active GradientKit effect per `UIGradient`\n* Automatically stops the previous effect on the same gradient\n* Built-in shine, hover, rainbow, scrolling, rotation, sweep, press, and palette effects\n* Typed public APIs and exported Luau options\n* Configurable tween timing, easing, colors, offsets, and rotation\n* Interaction targets for hover and press effects\n* Restores original gradient properties when stopped by default\n* Optional cleanup of gradients created by `Apply`\n* Cleans up when a gradient is destroyed\n* Supports friendly effect aliases such as `Flow` and `Activated`\n\n## 📖 Basic usage\n\nCopy `GradientKit` into your project and require it from a client script. UI interaction and animation should normally run on the client.\n\n### Applying an effect\n\n```lua\nlocal controller = GradientKit.Apply(button, \"Shine\")\n\nif controller:IsRunning() then\n\tprint(\"The gradient effect is active\")\nend\n```\n\nThe target must be a `GuiObject`. `Apply` uses an existing child `UIGradient` when one is available; otherwise it creates a gradient named `Gradient`.\n\n### Using an existing UIGradient\n\nCreate and style the gradient yourself in Studio, then start an effect on it:\n\n```lua\nlocal button = script.Parent.Button\nlocal gradient = button.UIGradient\n\nlocal controller = GradientKit.Start(gradient, \"Hover\", {\n\tDuration = 0.35,\n})\n```\n\nFor interactive effects, `Start` uses the gradient's parent as the interaction target when that parent is a `GuiObject`. Override it when a different object should receive input:\n\n```lua\nGradientKit.Start(label.UIGradient, \"Hover\", {\n\tInteractionTarget = button,\n})\n```\n\n### Creating a gradient\n\n```lua\nlocal gradient = GradientKit.Create(frame, {\n\tName = \"BackgroundGradient\",\n\tColors = {\n\t\tColor3.fromRGB(255, 90, 150),\n\t\tColor3.fromRGB(100, 110, 255),\n\t},\n\tRotation = 45,\n})\n```\n\nUse either `Colors` for a palette or `Color` for a complete `ColorSequence`.\n\n### Targeting one of several gradients\n\nWhen a `GuiObject` contains multiple gradients, pass `GradientName` to `Apply`:\n\n```lua\nGradientKit.Apply(frame, \"Rotate\", {\n\tGradientName = \"BackgroundGradient\",\n})\n```\n\n### Included effects\n\n* `Shine` — applies a bright center band and sweeps it across the UI.\n* `Hover` — moves a gradient into view on hover and alternates its exit direction.\n* `HoverStay` — slides continuously while hovered and pauses when the pointer leaves.\n* `Rainbow` — generates an HSV rainbow palette and cycles it across the gradient.\n* `Scroll` / `Flow` — continuously moves the current gradient from one offset to another.\n* `Rotate` — continuously rotates the gradient while preserving its colors and offset.\n* `Sweep` — periodically sweeps the current gradient without imposing a color style.\n* `Pressed` / `Activated` — moves and optionally rotates the gradient while pressed.\n* `ColorCycle` — continuously cycles through a developer-defined palette of three or more colors.\n\n## Effect examples\n\n### Shine\n\n```lua\nGradientKit.Apply(button, \"Shine\", {\n\tBaseColor = Color3.fromRGB(255, 80, 160),\n\tShineColor = Color3.fromRGB(255, 235, 250),\n\tDuration = 0.8,\n\tDelay = 2,\n\tShinesPerBurst = 2,\n\tRotation = 45,\n})\n```\n\n### Hover\n\n```lua\nGradientKit.Apply(button, \"Hover\", {\n\tColors = {\n\t\tColor3.fromRGB(255, 220, 80),\n\t\tColor3.fromRGB(80, 255, 140),\n\t\tColor3.fromRGB(80, 170, 255),\n\t},\n\tDuration = 0.4,\n})\n```\n\n### HoverStay\n\n```lua\nGradientKit.Apply(button, \"HoverStay\", {\n\tColors = {\n\t\tColor3.fromRGB(255, 100, 155),\n\t\tColor3.fromRGB(95, 180, 255),\n\t},\n\tDuration = 2.5,\n})\n```\n\n### Rainbow\n\n```lua\nGradientKit.Apply(title, \"Rainbow\", {\n\tDuration = 1,\n\tSteps = 18,\n\tSaturation = 1,\n\tValue = 1,\n})\n```\n\nProviding at least three colors through `Colors` makes `Rainbow` use that palette instead of generating HSV colors.\n\n### Scroll / Flow\n\n```lua\nGradientKit.Apply(frame, \"Flow\", {\n\tStartOffset = Vector2.new(-1, 0),\n\tEndOffset = Vector2.new(1, 0),\n\tDuration = 3,\n\tRotation = 20,\n})\n```\n\n### Rotate\n\n```lua\nGradientKit.Apply(frame, \"Rotate\", {\n\tDuration = 5,\n\tClockwise = true,\n\tDegrees = 360,\n})\n```\n\nSet `Clockwise = false` for counter-clockwise rotation.\n\n### Sweep\n\n```lua\nGradientKit.Apply(card, \"Sweep\", {\n\tDuration = 0.75,\n\tDelay = 2.25,\n\tStartOffset = Vector2.new(-1, 0),\n\tEndOffset = Vector2.new(1, 0),\n})\n```\n\n### Pressed / Activated\n\n```lua\nGradientKit.Apply(button, \"Pressed\", {\n\tDuration = 0.12,\n\tRestOffset = Vector2.new(0, 0),\n\tPressedOffset = Vector2.new(0.1, 0),\n})\n```\n\nThe gradient can also rotate slightly during the press:\n\n```lua\nGradientKit.Apply(button, \"Activated\", {\n\tPressedOffset = Vector2.new(0.08, 0),\n\tRestRotation = 0,\n\tPressedRotation = 8,\n})\n```\n\n### ColorCycle\n\n```lua\nGradientKit.Apply(title, \"ColorCycle\", {\n\tColors = {\n\t\tColor3.fromRGB(255, 90, 130),\n\t\tColor3.fromRGB(255, 200, 80),\n\t\tColor3.fromRGB(90, 220, 255),\n\t\tColor3.fromRGB(165, 100, 255),\n\t},\n\tDuration = 1.2,\n})\n```\n\n`ColorCycle` requires at least three colors.\n\n## Preserving your own gradient style\n\nSome effects have built-in visual styles. `Shine` creates a base/shine color sequence and `Hover` provides a default palette. Disable those defaults when the gradient's existing colors should remain in control:\n\n```lua\nGradientKit.Start(gradient, \"Shine\", {\n\tUseDefaultStyle = false,\n})\n```\n\n`SetupDefaults` is accepted as a backward-compatible alias for `UseDefaultStyle`.\n\n`Scroll`, `Rotate`, `Sweep`, and `Pressed` preserve the existing gradient style unless colors are explicitly supplied.\n\n## Stopping effects\n\n### Stop with the controller\n\n```lua\nlocal controller = GradientKit.Apply(button, \"Shine\")\ncontroller:Stop()\n```\n\n### Stop with the gradient or controller\n\n```lua\nGradientKit.Stop(button.UIGradient)\nGradientKit.Stop(controller)\n```\n\n### Stop every active effect\n\n```lua\nlocal stoppedCount = GradientKit.StopAll()\n```\n\n`Stop` returns whether an active effect was found. `StopAll` returns the number of controllers that were stopped. Calling `Stop` with no target also stops all active effects.\n\n## ⚙️ API\n\n### `GradientKit.Create(guiObject, properties?) -> UIGradient`\n\nCreates and parents a new `UIGradient` under `guiObject`.\n\nSupported properties are `Name`, `Enabled`, `Color`, `Colors`, `Transparency`, `Offset`, and `Rotation`.\n\n### `GradientKit.Apply(guiObject, effectName, options?) -> Controller`\n\nApplies an effect directly to a `GuiObject`, reusing a matching existing gradient or creating one when necessary. `GradientName` selects a specific gradient by name.\n\n### `GradientKit.Start(gradient, effectName, options?) -> Controller`\n\nStarts an effect on a specific `UIGradient`. Starting another effect on the same gradient automatically stops the previous controller first.\n\n### `GradientKit.Stop(target?) -> boolean`\n\nStops an effect using its controller or `UIGradient`. With no target, all active effects are stopped and the return value indicates whether any were active.\n\n### `GradientKit.StopAll() -> number`\n\nStops all active effects and returns the number stopped.\n\n### `GradientKit.IsActive(gradient) -> boolean`\n\nReturns whether the gradient currently has an active GradientKit controller.\n\n### `GradientKit.GetController(gradient) -> Controller?`\n\nReturns the active controller for the gradient, if one exists.\n\n### Controller methods\n\n```lua\ncontroller:Stop() -> boolean\ncontroller:IsRunning() -> boolean\n```\n\n## Complete configuration reference\n\n### Gradient properties (`GradientKit.Create`)\n\n| Property | Type | Description |\n| --- | --- | --- |\n| `Name` | `string?` | Name assigned to the new gradient. Defaults to `\"Gradient\"`. |\n| `Enabled` | `boolean?` | Whether the gradient is enabled. |\n| `Color` | `ColorSequence?` | Complete color sequence to apply. |\n| `Colors` | `{ Color3 }?` | Colors converted into evenly spaced keypoints. |\n| `Transparency` | `NumberSequence?` | Transparency sequence to apply. |\n| `Offset` | `Vector2?` | Initial gradient offset. |\n| `Rotation` | `number?` | Initial gradient rotation. |\n\n### Effect options\n\nAll options are optional. Unsupported options are ignored by effects that do not use them.\n\n| Option | Type | Used by |\n| --- | --- | --- |\n| `Duration` | `number?` | Tween-based effects |\n| `EasingStyle` | `Enum.EasingStyle?` | Tween-based effects |\n| `EasingDirection` | `Enum.EasingDirection?` | Tween-based effects |\n| `DelayTime` | `number?` | Tween creation |\n| `Reverses` | `boolean?` | Effects allowing repeat options |\n| `RepeatCount` | `number?` | Effects allowing repeat options |\n| `InteractionTarget` | `GuiObject?` | `Hover`, `HoverStay`, `Pressed` |\n| `RestoreOnStop` | `boolean?` | All effects; defaults to restoring |\n| `DestroyOnStop` | `boolean?` | Gradients created by `Apply` |\n| `UseDefaultStyle` | `boolean?` | `Shine`, `Hover`, `HoverStay` |\n| `SetupDefaults` | `boolean?` | Backward-compatible alias |\n| `Colors` | `{ Color3 }?` | Palette and color effects |\n| `StartOffset` | `Vector2?` | Offset-based effects |\n| `EndOffset` | `Vector2?` | Offset-based effects |\n| `Rotation` | `number?` | Effects with configurable rotation |\n| `BaseColor` | `Color3?` | `Shine` |\n| `ShineColor` | `Color3?` | `Shine` |\n| `Delay` | `number?` | `Shine`, `Sweep` |\n| `ShinesPerBurst` | `number?` | `Shine` |\n| `Steps` | `number?` | Generated `Rainbow` palettes |\n| `Saturation` | `number?` | Generated `Rainbow` palettes |\n| `Value` | `number?` | Generated `Rainbow` palettes |\n| `StartRotation` | `number?` | `Rotate` |\n| `Clockwise` | `boolean?` | `Rotate` |\n| `Degrees` | `number?` | `Rotate` |\n| `RestOffset` | `Vector2?` | `Pressed` |\n| `PressedOffset` | `Vector2?` | `Pressed` |\n| `PressedRotation` | `number?` | `Pressed` |\n| `RestRotation` | `number?` | `Pressed` |\n| `GradientName` | `string?` | `Apply` |\n\n## Effect aliases\n\nGradientKit ignores spaces, underscores, hyphens, and capitalization when resolving effect names.\n\n```text\nShine / Shimmer\nHoverStay / Hover Stay / hover-stay\nRainbow / RGB\nScroll / Flow\nRotate / Spin\nPressed / Press / Activated / Activate / Click\nColorCycle / ColourCycle / Cycle / ColorShift\n```\n\n## 📝 Notes\n\n* GradientKit is intended for client-side UI.\n* `Hover`, `HoverStay`, and `Pressed` require an interaction target. `Apply` supplies the target automatically; `Start` resolves it from the gradient's parent when possible.\n* Stopping an effect restores `Enabled`, `Color`, `Transparency`, `Offset`, and `Rotation` from before the effect started unless `RestoreOnStop = false`.\n* `DestroyOnStop` only destroys gradients created by `GradientKit.Apply`; it never destroys a gradient supplied by the developer.\n* Destroying a `UIGradient` automatically removes its active controller and tracked connections.\n* Effects are self-contained and use Roblox `TweenService` plus lightweight task loops instead of a permanent global frame-by-frame scheduler.\n\n## 🛠️ Installation\n\nPlace the package somewhere accessible to your client UI code, for example:\n\n```text\nReplicatedStorage\n└── Packages\n    └── GradientKit\n```\n\nThen require it from a `LocalScript`:\n\n```lua\nlocal ReplicatedStorage = game:GetService(\"ReplicatedStorage\")\nlocal GradientKit = require(ReplicatedStorage.Packages.GradientKit)\n```\n\nGradientKit does not depend on this exact folder structure; it is only a suggested organization.\n\n\n## License\n\nThis project is released under the MIT License.\n\nSee `LICENSE` for details.\n\nmade with ❤️ by biotoxin495\n","readmeTruncated":false}