Skip to main content

EZUtil

Documentation

EZUtil is a collection of small, game-agnostic Roblox utilities: tables, math, dates, instances, players, UI layout, projectiles, particles and VFX. It has no game config, Knit services or hardcoded game paths, so you can drop it into any project.

Installation​

Add the package to your Wally manifest:

[dependencies]
EZUtil = "breezy1214/ezutil@0.1.0"

EZUtil depends on Janitor and Promise; Wally installs both for you.

Usage​

local EZUtil = require(ReplicatedStorage.Packages.EZUtil)

print(EZUtil.MathUtil.shortenNumber(1200)) -- 1.2K
print(EZUtil.DateUtil.formatDuration(3725)) -- 1h 2m 5s

-- Or require a single module directly
local TableUtil = require(ReplicatedStorage.Packages.EZUtil.TableUtil)

Each 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.

Modules​

AimIndicator​

A single neon disc that marks where an ability will land.

  • create(size, color?, parent?): replaces any existing indicator with a new disc, parented to parent (defaults to workspace).
  • update(position): moves the indicator onto a ground position.
  • destroy(): removes the indicator.

CharacterRigUtil​

Helpers for character rigs, humanoids and skinned meshes.

  • waitForHumanoid(character, timeout): returns the character's Humanoid, waiting up to timeout seconds.
  • waitForAnimator(humanoid, timeout): returns the humanoid's Animator, waiting up to timeout seconds.
  • findBodyPart(character, name): finds a body part by name, resolving accessory handles to their MeshPart.
  • waitForBodyPart(character, name, timeout): polls findBodyPart until it succeeds, times out, or the character is removed.
  • getFeetY(rootPart, humanoid): the world Y of the character's feet.
  • standRootOn(character, rootPart, humanoid, groundCFrame): pivots the character so its feet rest on groundCFrame.
  • isGroundedState(state): whether a HumanoidStateType counts as grounded.
  • findSkinnedMesh(character): the MeshPart whose Bones pose a skinned character, or nil for a jointed rig.
  • collectCharacterBones(character): every Bone under the character, parents before children.

DateUtil​

Timestamps, periods and human-readable durations.

  • SECONDS_PER_DAY, SECONDS_PER_WEEK: constants.
  • dateTimeComponentsToTimestamp(components): converts UTC date components to a unix timestamp in seconds.
  • unix(): the current UTC unix timestamp in seconds.
  • getPeriod(timestamp, duration, offset?): the index of the fixed-length period containing timestamp.
  • getPeriodEnd(period, duration, offset?): the timestamp at which a period ends.
  • formatDuration(seconds): formats seconds as 1h 2m 5s.
  • timeAgoUnix(timestamp, endTimestamp?): seconds elapsed since timestamp.
  • formatUnix(timestamp, format, locale?): formats a timestamp with a DateTime format string.
  • unixToClockFormat(timestamp, format?, locale?): formats a timestamp as mm:ss by default.
  • timeAgo(timestamp, endTimestamp?): a readable "time ago" string, such as 1 minute 20 seconds ago.
  • totalTime(timestamp, endTimestamp?, separator?, depth?): a readable total duration with an optional unit limit.

FixedRewardSequence​

  • build(weights): builds a deterministic, evenly spread reward sequence whose frequencies match weights, starting at the rarest reward.

GroundUtil​

  • projectDown(position, depth, raycastParams, resultOffset?): raycasts straight down and returns the hit position plus an optional offset.
  • raycast(origin, direction, filterList?, filterType?, collisionGroup?): a one-call raycast that builds its RaycastParams for you.

InstanceUtil​

  • FindFirstAncestorWithTag(instance, tag): the nearest ancestor with a CollectionService tag.
  • GetDescendantsWithTag(instance, tag): every descendant with a tag.
  • ExpectChild(parent, name): returns a child, or errors with its full path if it is missing.
  • findFirstChildWithTag(instance, tagName): the first direct child with a tag.
  • weldParts(part0, part1): welds two parts with a WeldConstraint.
  • weldAttachments(attach1, attach2): joins two attachments with a RigidConstraint.
  • lookAt(object, target, rotateOnYAxis?): tweens a part to face a target and returns a Promise that resolves when the tween ends.

JanitorUtil​

  • safeDestroy(janitor?): destroys a Janitor unless it is nil or already cleaning, and warns instead of throwing on failure.

LayoutUtil​

Keeps ScrollingFrame canvases and items sized correctly.

  • resolveUDim(size, referenceSize): converts a UDim to pixels against a reference size.
  • FixScrollingCanvas(layout, scrollingFrame, padding?): keeps CanvasSize fitted to the layout's content and padding. Returns a cleanup function.
  • FixAuthoredListHeights(scrollingFrame, layout, items): locks list items and padding to their authored heights relative to the viewport. Returns a cleanup function.
  • FixLayout(layout, scrollingFrame, itemAspectRatio?, padding?): applies aspect-ratio constraints to items and keeps the vertical canvas fitted. Returns a cleanup function.

MathUtil​

  • lerp(start, stop, alpha): linear interpolation.
  • round(number): rounds to the nearest integer.
  • roundNumber(num, numPlaces): rounds to the nearest value with a number of decimal places.
  • formatInt(number, decimals?): adds thousands separators, such as 1,000.01.
  • shortenNumber(number, minimumTiers?): abbreviates large numbers, such as 1.2K or 3M.
  • random(min, max?, float?): a random integer or float. min defaults to 1 when only one number is given.
  • randomRange(min, max): a random float in a range.
  • randomString(length?): a random alphanumeric string, 18 characters by default.
  • randomObj(tableOrInstance): a random array element or child.
  • randomInDisc(radius): a uniformly random flat offset inside a disc.
  • getRandomInPart(part): a random CFrame on a part's XZ plane.
  • getVector3(object): extracts a position from a Vector3, CFrame, Attachment, BasePart, value object or Camera.
  • getDistance(origin, target): the distance between any two values getVector3 supports.
  • getPartBottomSurface(part): the CFrame at the centre of a part's bottom face.
  • isNumberSecure(value): true only for non-negative numbers.

ParticleUtil​

  • 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.
  • burst(template, cframe): clones an attachment, emits each emitter's EmitCount attribute after its optional EmitDelay, then cleans up.
  • setEnabled(root, enabled): toggles every ParticleEmitter under root.
  • release(root): stops emitters and lights, then destroys root after its particles finish.

PlayerUtil​

  • ensureAnimator(character): returns the character's Animator, creating one if needed.
  • loadAnimation(janitor, character, animationId): loads an Action4 track that the Janitor stops and destroys.
  • getHumanoid(object): the Humanoid of a Player, character Model or Humanoid.
  • isAlive(object), hasHumanoid(object): humanoid health and presence checks.
  • getCharacterHeight(character): the character's bounding-box height.
  • getPositiontAtFeet(character): the world position at the character's feet.
  • getCharacterInformation(player): returns the character, Humanoid and HumanoidRootPart.
  • getPlayerFromInstance(part) (alias getPlayerFromPart): the Player whose character contains a part.
  • getGroupRank(player, groupId): a cached group rank lookup.
  • isCreator(player), getUserLevel(player), userLevel: checks for the game creator, group staff and Premium.
  • disableOtherUi(value, exception?): client only. Hides or restores every ScreenGui except exception and Topbar GUIs.

ProfileUtil​

  • scope(label, callback): runs a non-yielding callback inside a named MicroProfiler scope and returns its results.

ProjectileUtil​

Ballistic projectiles and aim previews.

  • calculateLaunchVelocity(origin, target, duration, gravity?): the launch velocity needed to hit target in duration seconds.
  • getPositionAtTime(origin, velocity, time, gravity?), getVelocityAtTime(velocity, time, gravity?): the arc's position and velocity at a time.
  • launch(config): animates an anchored part along the arc, with optional raycast hits and bounces. Returns a controller with Cancel and IsActive.
  • createAimBeam(config): draws the arc with a single curved Beam. Returns an object with Update and Destroy.

SearchUtil​

  • getPartCount(instance), getDescendantParts(instance): count or collect descendant BaseParts.
  • getFirstPart(instance): the first BasePart child.
  • getAncestor(child, nameOrPredicate): the first ancestor, or the instance itself, that matches.
  • find(node, keyOrPredicate, maxDepth?): a breadth-limited search through Instance children or nested tables.
  • exists(node, names): whether every named child or key exists.

SystemUtil​

  • timeout(delay, callback): runs callback after delay seconds.
  • interval(interval, callback): runs callback(elapsed, dt) every interval seconds until it returns false. Returns the connection.
  • inTable(table, value): whether a value is in a table.
  • disconnect(connectionOrList): disconnects one connection or a list of them.
  • getProductInfo(productId, infoType?): a cached, pcall-wrapped MarketplaceService:GetProductInfo.
  • isMobile(), isConsole(): input-based platform checks.

TableDiffUtil​

  • shallowEqual(left, right): whether two tables have the same keys and values.

TableUtil​

  • flip, map, filter, mapIndex: transform tables, or an Instance's children.
  • extend, assign: merge tables, with an optional deep merge.
  • split, join, trimWhitespace, trimLeadingWhitespace, trimTrailingWhitespace: string helpers.
  • treePath(tree, path, delimiter?): reads a dotted path through a table or Instance tree.
  • insertIf(target, value, condition): appends a value only if the condition passes.
  • instanceChildrenToTable(instance): maps child names to children.
  • makeConfigFromValues(folder): converts a Folder or Configuration of value objects into a nested table.
  • tableLength, indexOf, tableRandom, tableRandomIndex, tableRemove: counting, lookup, random picks and in-place removal.

VfxUtil​

Plays VFX templates whose emitters are configured with EmitCount, EmitDelay and EmitDuration attributes.

  • uprightAt(template, position): a CFrame at position that keeps the template's rotation.
  • play(template, cframe, parent?): plays a one-shot clone, parented to parent (defaults to workspace), and cleans it up when finished.
  • attach(template, part): welds a continuously emitting clone to part and returns a stop function.

License​

MIT