{"id":"breezy1214/ezutil","name":"ezutil","scope":"breezy1214","platform":"roblox","description":"Reusable, game-agnostic Roblox utilities: tables, math, dates, instances, players, layout, projectiles, particles and more.","version":"0.1.3","latest":"0.1.3","versions":["0.1.0","0.1.1","0.1.2","0.1.3"],"license":"MIT","licenseRating":"safe","licenseCaveats":[],"licenseVerified":true,"dependencies":{"howmanysmall/janitor":{"version":"^1.18.3","alias":"Janitor"},"evaera/promise":{"version":"^4.0.0","alias":"Promise"}},"integrity":"8db66e92cb1a4d6754682fc26bed655e98521b38594b85a652f0ea7aa54b70a0","likes":0,"downloads":0,"install":"forest install breezy1214/ezutil","url":"https://forest.dev/p/roblox/breezy1214/ezutil","files":"https://api.forest.dev/ai/package/roblox/breezy1214/ezutil/files","readme":"# EZUtil\r\n\r\n[Documentation](https://breezy1214.github.io/EZUtil/)\r\n\r\nEZUtil is a collection of small, game-agnostic Roblox utilities: tables, math, dates, colors, instances, players, UI layout and drag and drop, sounds, highlights, projectiles, particles and VFX. It has no game config, Knit services or hardcoded game paths, so you can drop it into any project.\r\n\r\n## Installation\r\n\r\nAdd the package to your [Wally](https://wally.run) manifest:\r\n\r\n```toml\r\n[dependencies]\r\nEZUtil = \"breezy1214/ezutil@0.1.0\"\r\n```\r\n\r\nEZUtil depends on [Janitor](https://github.com/howmanysmall/Janitor) and [Promise](https://github.com/evaera/roblox-lua-promise); Wally installs both for you.\r\n\r\n## Usage\r\n\r\n```lua\r\nlocal EZUtil = require(ReplicatedStorage.Packages.EZUtil)\r\n\r\nprint(EZUtil.MathUtil.shortenNumber(1200)) -- 1.2K\r\nprint(EZUtil.DateUtil.formatDuration(3725)) -- 1h 2m 5s\r\nprint(EZUtil.DateUtil.formatClock(65)) -- 1:05\r\n\r\n-- Or require a single module directly\r\nlocal TableUtil = require(ReplicatedStorage.Packages.EZUtil.TableUtil)\r\n```\r\n\r\nEach module is required lazily, the first time its field is read, so a client-only module never runs on the server (and the reverse). The package root is fully typed, so `EZUtil.` autocompletes every module and its functions.\r\n\r\n## Modules\r\n\r\n### AimIndicator\r\n\r\nA single neon disc that marks where an ability will land.\r\n\r\n- `create(size, color?, parent?)`: replaces any existing indicator with a new disc, parented to `parent` (defaults to `workspace`).\r\n- `update(position)`: moves the indicator onto a ground position.\r\n- `destroy()`: removes the indicator.\r\n\r\n### CharacterRigUtil\r\n\r\nHelpers for character rigs, humanoids and skinned meshes.\r\n\r\n- `waitForHumanoid(character, timeout)`: returns the character's Humanoid, waiting up to `timeout` seconds.\r\n- `waitForAnimator(humanoid, timeout)`: returns the humanoid's Animator, waiting up to `timeout` seconds.\r\n- `findBodyPart(character, name)`: finds a body part by name, resolving accessory handles to their MeshPart.\r\n- `waitForBodyPart(character, name, timeout)`: polls `findBodyPart` until it succeeds, times out, or the character is removed.\r\n- `getFeetY(rootPart, humanoid)`: the world Y of the character's feet.\r\n- `standRootOn(character, rootPart, humanoid, groundCFrame)`: pivots the character so its feet rest on `groundCFrame`.\r\n- `isGroundedState(state)`: whether a HumanoidStateType counts as grounded.\r\n- `findSkinnedMesh(character)`: the MeshPart whose Bones pose a skinned character, or nil for a jointed rig.\r\n- `collectCharacterBones(character)`: every Bone under the character, parents before children.\r\n\r\n### ColorUtil\r\n\r\nConverts Color3 values to and from `{ R, G, B }` tables of 0-255 integers, safe to save or send over remotes.\r\n\r\n- `serialize(color)`: a new `{ R, G, B }` table from a Color3 or a serialized color.\r\n- `deserialize(value, fallback?)`: a Color3, or `fallback` when `value` is not a valid serialized color.\r\n- `isSerialized(value)`, `toColor3(value)`: validation and conversion.\r\n- `equals(left, right)`: compares any mix of Color3 and serialized colors by their 8-bit channels.\r\n- `findInPalette(value, palette)`: the index of the first matching palette color.\r\n- `toKey(color)`, `fromKey(key)`: a `\"R,G,B\"` dictionary key and back.\r\n\r\n```lua\r\nlocal saved = ColorUtil.serialize(Color3.fromRGB(217, 169, 135)) -- { R = 217, G = 169, B = 135 }\r\nlocal color = ColorUtil.deserialize(profile.Data.Color, Color3.new(1, 1, 1))\r\n```\r\n\r\n### DateUtil\r\n\r\nTimestamps, periods and human-readable durations.\r\n\r\n- `SECONDS_PER_DAY`, `SECONDS_PER_WEEK`: constants.\r\n- `dateTimeComponentsToTimestamp(components)`: converts UTC date components to a unix timestamp in seconds.\r\n- `unix()`: the current UTC unix timestamp in seconds.\r\n- `getPeriod(timestamp, duration, offset?)`: the index of the fixed-length period containing `timestamp`.\r\n- `getPeriodEnd(period, duration, offset?)`: the timestamp at which a period ends.\r\n- `formatDuration(seconds)`: formats seconds as `1h 2m 5s`.\r\n- `formatClock(seconds, options?)`: formats seconds as `m:ss`, or `h:mm:ss` from an hour up. Options: `hours` (`\"auto\"`, `\"always\"` or `\"never\"`), `round` (`\"ceil\"` by default, or `\"floor\"`) and `padMinutes`.\r\n- `timeAgoUnix(timestamp, endTimestamp?)`: seconds elapsed since `timestamp`.\r\n- `formatUnix(timestamp, format, locale?)`: formats a timestamp with a DateTime format string.\r\n- `unixToClockFormat(timestamp, format?, locale?)`: formats a timestamp as `mm:ss` by default.\r\n- `timeAgo(timestamp, endTimestamp?)`: a readable \"time ago\" string, such as `1 minute 20 seconds ago`.\r\n- `totalTime(timestamp, endTimestamp?, separator?, depth?)`: a readable total duration with an optional unit limit.\r\n\r\n### DragDrop\r\n\r\nA client-side UI drag-and-drop controller. Each controller owns its sources and drop targets, runs one drag at a time, and reports everything through callbacks.\r\n\r\n- `new(options?)`: creates a controller. Options cover the move threshold (8 px), touch hold time (0.25 s), target slop, a ghost factory with its parent, DisplayOrder and sizing, the snap-back time, a safe zone, click and hover sounds, and the `onDragStart`, `onMove`, `onTargetChanged`, `onClearing`, `onDrop` and `onCancel` callbacks.\r\n- `controller:addSource(id, gui, options)`: adds a `UIDragDetector` to `gui`. Options: `payload` (a getter), `enabled`, `onTap`, `canClear` and `targetId`. Returns a handle with `refresh` and `Destroy`.\r\n- `controller:addTarget(id, gui, options?)`: registers a drop target with an optional `accept(payload, targetId)` predicate and slop. Returns a remove function.\r\n- `controller:removeTarget(id)`, `controller:refresh()`, `controller:cancel()`, `controller:isDragging()`, `controller:getActive()`, `controller:Destroy()`.\r\n\r\nA press turns into a drag after it moves past the threshold. On touch, a press inside an overflowing ScrollingFrame scrolls it instead, unless it is held still first. A press that never moves calls `onTap`, because the detector swallows the button's `Activated`. A cancelled drag tweens its ghost back to the source.\r\n\r\n```lua\r\nlocal drag = DragDrop.new({\r\n\tghost = function(itemId: string): GuiObject\r\n\t\treturn makeIcon(itemId)\r\n\tend,\r\n\tonDrop = function(itemId: string, _fromSlot, toSlot)\r\n\t\tif toSlot then\r\n\t\t\tequip(itemId, toSlot)\r\n\t\telse\r\n\t\t\tunequip(itemId)\r\n\t\tend\r\n\tend,\r\n})\r\n\r\nfor index, slot in slotFrames do\r\n\tdrag:addTarget(index, slot)\r\n\tdrag:addSource(index, slot, {\r\n\t\tpayload = function()\r\n\t\t\treturn hotbar[index]\r\n\t\tend,\r\n\t\ttargetId = index,\r\n\t\tcanClear = true,\r\n\t\tonTap = function()\r\n\t\t\tselect(index)\r\n\t\tend,\r\n\t})\r\nend\r\n```\r\n\r\n### FixedRewardSequence\r\n\r\n- `build(weights)`: builds a deterministic, evenly spread reward sequence whose frequencies match `weights`, starting at the rarest reward.\r\n\r\n### GroundUtil\r\n\r\n- `projectDown(position, depth, raycastParams, resultOffset?)`: raycasts straight down and returns the hit position plus an optional offset.\r\n- `raycast(origin, direction, filterList?, filterType?, collisionGroup?)`: a one-call raycast that builds its RaycastParams for you.\r\n- `isPointInPart(part, point)`: whether a point is inside a part's rotated box.\r\n- `getSnappedCFrame(model, pivot, raycastParams?, depth?)`: `pivot` lowered so the model rests on the floor below it. The raycast excludes the model by default.\r\n- `snapToFloorPivot(model, pivot, raycastParams?, depth?)`: pivots the model onto that floor and returns the CFrame.\r\n\r\n### HighlightUtil\r\n\r\n- `new(options?)`: creates a highlighter with its own cache. Options: `ignore(object)` to skip objects such as a baseplate, and `parent`.\r\n- `highlighter:add(object, config?)`, `highlighter:addPulse(object, config?)`: adds one Highlight per model or part. A pulse animates the fill transparency.\r\n- `highlighter:remove(object)`, `highlighter:addBulk(objects, config?)`, `highlighter:removeBulk(objects)`, `highlighter:get(object)`, `highlighter:clear()`, `highlighter:Destroy()`.\r\n\r\n```lua\r\nlocal highlighter = HighlightUtil.new({\r\n\tignore = function(object)\r\n\t\treturn object.Name == \"Baseplate\"\r\n\tend,\r\n})\r\nhighlighter:addPulse(door, { fillColor = Color3.fromRGB(0, 170, 255) })\r\n```\r\n\r\n### InstanceUtil\r\n\r\n- `FindFirstAncestorWithTag(instance, tag)`: the nearest ancestor with a CollectionService tag.\r\n- `GetDescendantsWithTag(instance, tag)`: every descendant with a tag.\r\n- `ExpectChild(parent, name)`: returns a child, or errors with its full path if it is missing.\r\n- `findFirstChildWithTag(instance, tagName)`: the first direct child with a tag.\r\n- `weldParts(part0, part1)`: welds two parts with a WeldConstraint.\r\n- `weldAttachments(attach1, attach2)`: joins two attachments with a RigidConstraint.\r\n- `lookAt(object, target, rotateOnYAxis?)`: tweens a part to face a target and returns a Promise that resolves when the tween ends.\r\n\r\n### JanitorUtil\r\n\r\n- `safeDestroy(janitor?)`: destroys a Janitor unless it is nil or already cleaning, and warns instead of throwing on failure.\r\n\r\n### LayoutUtil\r\n\r\nKeeps ScrollingFrame canvases and items sized correctly.\r\n\r\n- `resolveUDim(size, referenceSize)`: converts a UDim to pixels against a reference size.\r\n- `getInheritedScale(instance)`: the product of every UIScale on the instance and its ancestors, up to its LayerCollector.\r\n- `FixScrollingCanvas(layout, scrollingFrame, padding?)`: keeps CanvasSize fitted to the layout's content and padding. Returns a cleanup function.\r\n- `FixAuthoredListHeights(scrollingFrame, layout, items)`: locks list items and padding to their authored heights relative to the viewport. Returns a cleanup function.\r\n- `FixLayout(layout, scrollingFrame, itemAspectRatio?, padding?)`: applies aspect-ratio constraints to items and keeps the vertical canvas fitted. Returns a cleanup function.\r\n\r\n### MathUtil\r\n\r\n- `lerp(start, stop, alpha)`: linear interpolation.\r\n- `round(number)`: rounds to the nearest integer.\r\n- `roundNumber(num, numPlaces)`: rounds to the nearest value with a number of decimal places.\r\n- `formatInt(number, decimals?)`: adds thousands separators, such as `1,000.01`.\r\n- `shortenNumber(number, minimumTiers?)`: abbreviates large numbers, such as `1.2K` or `3M`.\r\n- `random(min, max?, float?)`: a random integer or float. `min` defaults to 1 when only one number is given.\r\n- `randomRange(min, max)`: a random float in a range.\r\n- `randomString(length?)`: a random alphanumeric string, 18 characters by default.\r\n- `randomObj(tableOrInstance)`: a random array element or child.\r\n- `randomInDisc(radius)`: a uniformly random flat offset inside a disc.\r\n- `getRandomInPart(part)`: a random CFrame on a part's XZ plane.\r\n- `getVector3(object)`: extracts a position from a Vector3, CFrame, Attachment, BasePart, value object or Camera.\r\n- `getDistance(origin, target)`: the distance between any two values `getVector3` supports.\r\n- `getPartBottomSurface(part)`: the CFrame at the centre of a part's bottom face.\r\n- `isNumberSecure(value)`: true only for non-negative numbers.\r\n\r\n### ParticleUtil\r\n\r\n- `waitForTemplate(name, folder)`, `waitForPart(name, folder)`, `waitForModel(name, folder)`: wait up to 5 seconds for a typed asset in `folder`, and warn if it is missing or the wrong class.\r\n- `burst(template, cframe)`: clones an attachment, emits each emitter's `EmitCount` attribute after its optional `EmitDelay`, then cleans up.\r\n- `setEnabled(root, enabled)`: toggles every ParticleEmitter under `root`.\r\n- `release(root)`: stops emitters and lights, then destroys `root` after its particles finish.\r\n\r\n### PlayerUtil\r\n\r\n- `ensureAnimator(character)`: returns the character's Animator, creating one if needed.\r\n- `loadAnimation(janitor, character, animationId)`: loads an Action4 track that the Janitor stops and destroys.\r\n- `getHumanoid(object)`: the Humanoid of a Player, character Model or Humanoid.\r\n- `isAlive(object)`, `hasHumanoid(object)`: humanoid health and presence checks.\r\n- `getCharacterHeight(character)`: the character's bounding-box height.\r\n- `getPositiontAtFeet(character)`: the world position at the character's feet.\r\n- `getCharacterInformation(player)`: returns the character, Humanoid and HumanoidRootPart.\r\n- `getPlayerFromInstance(part)` (alias `getPlayerFromPart`): the Player whose character contains a part.\r\n- `getGroupRank(player, groupId)`: a cached group rank lookup.\r\n- `isCreator(player)`, `getUserLevel(player)`, `userLevel`: checks for the game creator, group staff and Premium.\r\n- `disableOtherUi(value, exception?)`: client only. Hides or restores every ScreenGui except `exception` and Topbar GUIs.\r\n\r\n### ProfileUtil\r\n\r\n- `scope(label, callback)`: runs a non-yielding callback inside a named MicroProfiler scope and returns its results.\r\n\r\n### ProjectileUtil\r\n\r\nBallistic projectiles and aim previews.\r\n\r\n- `calculateLaunchVelocity(origin, target, duration, gravity?)`: the launch velocity needed to hit `target` in `duration` seconds.\r\n- `getPositionAtTime(origin, velocity, time, gravity?)`, `getVelocityAtTime(velocity, time, gravity?)`: the arc's position and velocity at a time.\r\n- `launch(config)`: animates an anchored part along the arc, with optional raycast hits and bounces. Returns a controller with `Cancel` and `IsActive`.\r\n- `createAimBeam(config)`: draws the arc with a single curved Beam. Returns an object with `Update` and `Destroy`.\r\n\r\n### SearchUtil\r\n\r\n- `getPartCount(instance)`, `getDescendantParts(instance)`: count or collect descendant BaseParts.\r\n- `getFirstPart(instance)`: the first BasePart child.\r\n- `getAncestor(child, nameOrPredicate)`: the first ancestor, or the instance itself, that matches.\r\n- `find(node, keyOrPredicate, maxDepth?)`: a breadth-limited search through Instance children or nested tables.\r\n- `exists(node, names)`: whether every named child or key exists.\r\n\r\n### SoundUtil\r\n\r\nPlays sounds with priorities, fades and cross-fades. It never changes a Sound it did not create: a sound played in place gets its overridden properties back when it finishes.\r\n\r\n- `new(options?)`: creates a sound player. Every option is optional. `sounds` is a root whose descendant Sounds are found by name, or a lookup function. `volume(sound)` returns a volume multiplier for a playing sound. `duckFactor` (0.1) applies to sounds below the highest playing priority. `playAtParent` (`workspace.Terrain`) holds `playAt` emitters.\r\n- `player:play(sound)`, `player:playAt(sound, position)`: play a Sound, a name, or a config, in place or as a clone from a point in the world. Both return a Promise that resolves with the Sound when it finishes.\r\n- `player:stop(sound, preserve?)`, `player:pauseSound(sound)`, `player:resumeSound(sound)`.\r\n- `player:fade(sound, targetVolume, duration)`, `player:crossFade(fadeOut, fadeIn, duration)`: Promise-based volume fades.\r\n- `player:getSoundInstance(name)`, `player:refreshVolumes()`, `player:Destroy()`.\r\n\r\n```lua\r\nlocal sounds = SoundUtil.new({\r\n\tsounds = SoundService,\r\n\tvolume = function(sound)\r\n\t\treturn if sound.SoundGroup == musicGroup and not settings.Music then 0 else 1\r\n\tend,\r\n})\r\n\r\nsounds:play(script.Hit)\r\nsounds:play({ name = \"BossMusic\", looped = true, priority = 1 })\r\nsounds:crossFade(\"BossMusic\", \"MainMusic\", 2)\r\n```\r\n\r\n### SystemUtil\r\n\r\n- `timeout(delay, callback)`: runs `callback` after `delay` seconds.\r\n- `interval(interval, callback)`: runs `callback(elapsed, dt)` every `interval` seconds until it returns `false`. Returns the connection.\r\n- `inTable(table, value)`: whether a value is in a table.\r\n- `disconnect(connectionOrList)`: disconnects one connection or a list of them.\r\n- `getProductInfo(productId, infoType?)`: a cached, pcall-wrapped `MarketplaceService:GetProductInfo`.\r\n- `isMobile()`, `isConsole()`: input-based platform checks.\r\n\r\n### TableDiffUtil\r\n\r\n- `shallowEqual(left, right)`: whether two tables have the same keys and values.\r\n\r\n### TableUtil\r\n\r\n- `flip`, `map`, `filter`, `mapIndex`: transform tables, or an Instance's children.\r\n- `extend`, `assign`: merge tables, with an optional deep merge.\r\n- `split`, `join`, `trimWhitespace`, `trimLeadingWhitespace`, `trimTrailingWhitespace`: string ","readmeTruncated":true,"readmeFull":"https://api.forest.dev/v1/package/breezy1214/roblox/ezutil/0.1.3/readme"}