{"id":"biotoxin495/purchase-loading-overlay","name":"purchase-loading-overlay","scope":"biotoxin495","platform":"roblox","description":"Animated Roblox purchase loading overlay","version":"1.0.0","latest":"1.0.0","versions":["1.0.0"],"license":"MIT","licenseRating":"safe","licenseCaveats":[],"licenseVerified":true,"dependencies":{},"integrity":"9ecfde3e07cec79ed91a0269829f33baee02f464548105680deb1d283571f3c4","likes":0,"downloads":0,"install":"forest install biotoxin495/purchase-loading-overlay","url":"https://forest.dev/p/roblox/biotoxin495/purchase-loading-overlay","files":"https://api.forest.dev/ai/package/roblox/biotoxin495/purchase-loading-overlay/files","readme":"# PurchaseLoadingOverlay — Animated purchase loading UI for Roblox\n\n**PurchaseLoadingOverlay** is a lightweight client-side Luau module that shows a full-screen loading presentation while a purchase or other asynchronous operation is in progress.\n\nThe module creates its UI at runtime, dims the screen, and animates a rotating loading image. It only handles presentation; your game remains responsible for starting and resolving purchases.\n\n## Quick example\n\n```lua\nlocal ReplicatedStorage = game:GetService(\"ReplicatedStorage\")\nlocal PurchaseLoadingOverlay = require(\n\tReplicatedStorage.Packages.PurchaseLoadingOverlay\n)\n\nlocal overlay = PurchaseLoadingOverlay.new()\n\noverlay:Show()\n\n-- Start or await your purchase flow here.\ntask.wait(2) -- Replace with your awaited purchase operation.\n\noverlay:Hide()\noverlay:Destroy()\n```\n\nWhen no `Parent` is supplied, the generated `ScreenGui` is placed in the local player's `PlayerGui`.\n\n## 🚀 Features\n\n- Fade in a full-screen background while a loading image expands into view\n- Rotate the loading image continuously while the overlay is shown\n- Customize the background, image, layout, display order, and animation timing\n- Respect Roblox reduced-motion settings\n- Observe shown, hidden, and open-state changes\n- Reuse the generated UI across multiple show/hide cycles\n- No external runtime dependencies\n\n## 🛠️ Installation\n\n### ModuleScript\n\nPlace `init.luau` in a client-accessible ModuleScript, for example:\n\n```text\nReplicatedStorage\n└── Packages\n    └── PurchaseLoadingOverlay\n        └── init.luau\n```\n\nRequire and construct it from a `LocalScript`:\n\n```lua\nlocal ReplicatedStorage = game:GetService(\"ReplicatedStorage\")\nlocal PurchaseLoadingOverlay = require(\n\tReplicatedStorage:WaitForChild(\"Packages\"):WaitForChild(\"PurchaseLoadingOverlay\")\n)\n\nlocal overlay = PurchaseLoadingOverlay.new()\n```\n\n### Wally\n\nAdd the package to your project's `wally.toml`:\n\n```toml\n[dependencies]\nPurchaseLoadingOverlay = \"biotoxin495/purchase-loading-overlay@1.0.0\"\n```\n\nConstruct the controller on the client.\n\n## Basic usage\n\n`Show()` opens the overlay and starts the spinner. Call `Hide()` after the operation finishes:\n\n```lua\noverlay:Show()\n\nlocal success, result = pcall(function()\n\treturn performPurchase()\nend)\n\noverlay:Hide()\n\nif success then\n\tprint(\"Purchase flow finished\", result)\nend\n```\n\nThe package does not call `MarketplaceService` or decide whether a transaction succeeded. Connect it to whichever purchase or asynchronous flow your game uses.\n\nTo skip the closing animation, call `overlay:Hide(true)`. Call `overlay:Destroy()` when the controller is no longer needed.\n\n---\n\n# API reference\n\n## `PurchaseLoadingOverlay.new(config?) -> PurchaseLoadingOverlay`\n\nCreates the controller and its generated `ScreenGui`. The UI is parented to `config.Parent` when provided, or to the local player's `PlayerGui` by default. Create the controller on the client.\n\n### Configuration\n\nAll fields are optional.\n\n| Option | Type | Default | Description |\n| --- | --- | --- | --- |\n| `Name` | `string` | `\"PurchaseLoadingOverlay\"` | Generated `ScreenGui` name. |\n| `Parent` | `Instance?` | Local `PlayerGui` | Parent of the generated UI. |\n| `DisplayOrder` | `number` | `100` | Generated `ScreenGui.DisplayOrder`. |\n| `BackgroundColor` | `Color3` | Black | Background color. |\n| `VisibleTransparency` | `number` | `0.5` | Background transparency while shown. |\n| `HiddenTransparency` | `number` | `1` | Background transparency while hidden. |\n| `LoadingImage` | `string` | `\"rbxassetid://15734250582\"` | Loading image asset. |\n| `RotationDuration` | `number` | `1.5` | Seconds per full image rotation. |\n| `TransitionDuration` | `number` | `0.25` | Open and close tween duration. |\n| `RespectReducedMotion` | `boolean` | `true` | Skips movement and rotation when reduced motion is enabled. |\n| `OpenAnchorPoint` | `Vector2` | `(0.5, 0.5)` | Loading image anchor point while shown. |\n| `OpenPosition` | `UDim2` | Screen center | Loading image position while shown. |\n| `OpenSize` | `UDim2` | `UDim2.new(0.6, 0, 0.2, 0)` | Loading image size while shown. |\n| `ClosedAnchorPoint` | `Vector2` | `(0.5, 1)` | Loading image anchor point while hidden. |\n| `ClosedPosition` | `UDim2` | Top center | Loading image position while hidden. |\n| `ClosedSize` | `UDim2` | Zero size | Loading image size while hidden. |\n\nExample configuration:\n\n```lua\nlocal overlay = PurchaseLoadingOverlay.new({\n\tParent = game.Players.LocalPlayer.PlayerGui,\n\tDisplayOrder = 100,\n\tLoadingImage = \"rbxassetid://15734250582\",\n\tTransitionDuration = 0.25,\n\tRespectReducedMotion = true,\n})\n```\n\n## `overlay:Show()`\n\nShows the background, opens the loading image, and starts its rotation. Repeated calls while already shown are ignored.\n\n## `overlay:Hide(immediate?)`\n\nStops the rotation and animates the overlay closed. Pass `true` to skip the closing tween:\n\n```lua\noverlay:Hide(true)\n```\n\n## `overlay:IsShown() -> boolean`\n\nReturns whether the overlay is currently shown.\n\n## `overlay:CheckIfOpen() -> boolean`\n\nCompatibility alias for `IsShown()`.\n\n## `overlay:GetOpenChangedSignal() -> RBXScriptSignal`\n\nReturns the same signal exposed as `overlay.OpenChanged`.\n\n## `overlay:Destroy()`\n\nCancels active tweens and tasks, destroys internal events, and removes the generated `ScreenGui`. A destroyed controller cannot be reused.\n\n## Signals\n\n```lua\noverlay.Shown:Connect(function()\n\tprint(\"Purchase loading started\")\nend)\n\noverlay.Hidden:Connect(function()\n\tprint(\"Purchase loading finished\")\nend)\n\noverlay.OpenChanged:Connect(function(isOpen)\n\tprint(\"Open state:\", isOpen)\nend)\n```\n\n`OpenChanged` fires when a show or hide transition starts. `Hidden` fires after the closing transition finishes.\n\n## Notes\n\n- The default UI is a black full-screen background with transparency `0.5` while shown.\n- The loading image defaults to `rbxassetid://15734250582` and rotates once every `1.5` seconds.\n- The image expands from zero size at the top-center to `UDim2.new(0.6, 0, 0.2, 0)` at the center of the screen.\n- Every generated Instance belongs to the controller. `Show()` and `Hide()` reuse the UI; `Destroy()` removes it.\n- The package does not start purchase prompts, listen to remotes, or make transaction decisions.\n\n## Project structure\n\n```text\nPurchaseLoadingOverlay/\n├── init.luau\n├── README.md\n├── wally.toml\n├── sourcemap.json\n└── LICENSE\n```\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n\n---\n\nmade with ❤️ by biotoxin495\n","readmeTruncated":false}