UIToolkit

A shared Wally package of cross-project reusable client UI utilities for Roblox experiences.

Installation

[dependencies]
UIToolkit = "hollower233/uitoolkit@0.3.1"

Run wally install, then require the package from the generated Packages folder.

Client usage

local UIToolkit = require(game.ReplicatedStorage.Packages.UIToolkit)

-- Zero-config, call once each on the client:
UIToolkit.client.initClickSound()
UIToolkit.client.initDeviceAdapt()

-- Generic "scan a folder of UI modules, require + two-phase Init them" scaffold:
local handle = UIToolkit.client.initUIManager(someFolder, { "SomeScreenGui", "AnotherScreenGui" })
handle.Get("SomeModuleName")
handle.SetScreenGuiEnabled("SomeScreenGui", false)

-- Zero-config, call once on the client:
UIToolkit.client.initFeedbackButton()

-- Per-button factory, call whenever you need a red dot (not part of `client`):
local dot = UIToolkit.RedDot.mount(someGuiButton)
dot.Visible = true

initClickSound()

Automatically binds a click sound to every GuiButton under the local player's PlayerGui (present and future), skipping JumpButton and any button with the noAutoSound attribute set to a truthy value. Looks for ReplicatedStorage.音效素材.通用点击音效 first, falls back to a bundled sound asset.

initDeviceAdapt()

Automatically scans PlayerGui for newly added ScreenGuis and shrinks (never enlarges) oversized panels to fit the viewport's safe area, using a UIScale instance so it never fights panel-open/close tweens that animate Size.

initUIManager(folder, screenGuiNames?)

A generic "module manager" scaffold, intended to be wrapped by a project-specific module that knows its own folder and ScreenGui dependencies:

1. Waits for each name in screenGuiNames to appear under the local player's PlayerGui.
2. Warns for any StarterGui ScreenGui left with ResetOnSpawn enabled.
3. requires every ModuleScript directly under folder.
4. Calls .Init() on every required module that has one (all modules are required first, so .Init() implementations can safely Get each other).
5. Returns a handle: Get(name) returns a required module by its instance name; SetScreenGuiEnabled(guiName, enabled) toggles a ScreenGui under the local player's PlayerGui.

This function carries no project-specific assumptions — it only knows about the folder and screenGuiNames you pass it, so it can be called more than once for different folders if needed.

initFeedbackButton()

Displays a left-aligned TopbarPlus icon and opens Roblox's feedback prompt (SocialService:PromptFeedbackSubmissionAsync()) when selected. Calling it more than once returns the existing icon without creating another one. Pulls in TopbarPlus as a transitive dependency — projects that only need initClickSound/initDeviceAdapt/initUIManager still receive it via wally install, even if they never call this function.

RedDot.mount(btn)

Idempotently attaches a red-dot Frame (named redDot) as a child of the given GuiButton and returns it, hidden (Visible = false) by default — the caller controls its visibility/count. Looks for a style template at StarterGui.红点模板.示例按钮.红点 first, falling back to a code-created default (never clones a StarterGui instance directly per project convention). Unlike the client.initXxx functions this is not a global one-time initializer — it's a per-button factory, so it is exposed as a sibling RedDot field rather than under client.

License

MIT. See LICENSE.