Utility Library
Common operations and helper functions for the Lilia framework.
Overview
The utility library provides comprehensive functionality for common operations and helper functions used throughout the Lilia framework. It contains a wide range of utilities for player management, string processing, entity handling, UI operations, and general purpose calculations. The library is divided into server-side functions for game logic and data management, and client-side functions for user interface, visual effects, and player interaction. These utilities simplify complex operations, provide consistent behavior across the framework, and offer reusable components for modules and plugins. The library handles everything from player identification and spatial queries to advanced UI animations and text processing, ensuring robust and efficient operations across both server and client environments.
lia.util.findPlayersInBox(mins, maxs)
Finds all players within an axis-aligned bounding box.
Use when you need the players contained inside specific world bounds (e.g. triggers or zones).
Parameters:
Vector mins Minimum corner of the search box.Vector maxs Maximum corner of the search box.
Returns:
table List of player entities inside the box.Example Usage:
local players = lia.util.findPlayersInBox(Vector(-128, -128, 0), Vector(128, 128, 128))
lia.util.getBySteamID(steamID)
Locates a connected player by SteamID or SteamID64 and requires an active character.
Use when commands or systems need to resolve a Steam identifier to a live player with a character loaded.
Parameters:
string steamID SteamID (e.g. "STEAM_0:1:12345") or SteamID64; empty/invalid strings are ignored.Returns:
Player|nil The matching player with a loaded character, or nil if not found/invalid input.Example Usage:
local ply = lia.util.getBySteamID("76561198000000000")
if ply then print("Found", ply:Name()) end
lia.util.findPlayersInSphere(origin, radius)
Returns all players inside a spherical radius from a point.
Use to gather players near a position for proximity-based effects or checks.
Parameters:
Vector origin Center of the search sphere.number radius Radius of the search sphere.
Returns:
table Players whose positions are within the given radius.Example Usage:
for _, ply in ipairs(lia.util.findPlayersInSphere(pos, 256)) do
ply:ChatPrint("You feel a nearby pulse.")
end
lia.util.findPlayer(client, identifier)
Resolves a player from various identifiers and optionally informs the caller on failure.
Use in admin/command handlers that accept flexible player identifiers (SteamID, SteamID64, name, "^", "@").
Parameters:
Player client optional The player requesting the lookup; used for localized error notifications.string identifier Identifier to match: SteamID, SteamID64, "^" (self), "@" (trace target), or partial name.
Returns:
Player|nil Matched player or nil when no match is found/identifier is invalid.Example Usage:
local target = lia.util.findPlayer(caller, args[1])
if not target then return end
target:kick("Example")
lia.util.findPlayerItems(client)
Collects all spawned item entities created by a specific player.
Use when cleaning up or inspecting items a player has spawned into the world.
Parameters:
Player client Player whose created item entities should be found.Returns:
table List of item entities created by the player.Example Usage:
for _, ent in ipairs(lia.util.findPlayerItems(ply)) do
ent:Remove()
end
lia.util.findPlayerItemsByClass(client, class)
Collects spawned item entities from a player filtered by item class.
Use when you need only specific item classes (by netvar "id") created by a player.
Parameters:
Player client Player whose item entities are being inspected.string class Item class/netvar id to match.
Returns:
table Item entities created by the player that match the class.Example Usage:
local ammo = lia.util.findPlayerItemsByClass(ply, "ammo_9mm")
lia.util.findPlayerEntities(client, class)
Finds entities created by or associated with a player, optionally by class.
Use to track props or scripted entities a player spawned or owns.
Parameters:
Player client Player whose entities should be matched.string class optional Optional entity class filter; nil includes all classes.
Returns:
table Entities created by or linked via entity.client to the player that match the class filter.Example Usage:
local ragdolls = lia.util.findPlayerEntities(ply, "prop_ragdoll")
lia.util.stringMatches(a, b)
Performs case-insensitive equality and substring comparison between two strings.
Use for loose name matching where exact case is not important.
Parameters:
string a First string to compare.string b Second string to compare.
Returns:
boolean True if the strings are equal (case-insensitive) or one contains the other; otherwise false.Example Usage:
if lia.util.stringMatches(ply:Name(), "john") then print("Matched player") end
lia.util.getAdmins()
Returns all connected staff members.
Use when broadcasting staff notifications or iterating over staff-only recipients.
Returns:
table Players that pass `isStaff()`.Example Usage:
for _, admin in ipairs(lia.util.getAdmins()) do
admin:notify("Server restart in 5 minutes.")
end
lia.util.findPlayerBySteamID64(SteamID64)
Resolves a player from a SteamID64 wrapper around `findPlayerBySteamID`.
Use when you have a 64-bit SteamID and need the corresponding player entity.
Parameters:
string SteamID64 SteamID64 to resolve.Returns:
Player|nil Matching player or nil when none is found/SteamID64 is invalid.Example Usage:
local ply = lia.util.findPlayerBySteamID64(steamID64)
lia.util.findPlayerBySteamID(SteamID)
Searches connected players for a matching SteamID.
Use when you need to map a SteamID string to the in-game player.
Parameters:
string SteamID SteamID in legacy format (e.g. "STEAM_0:1:12345").Returns:
Player|nil Player whose SteamID matches, or nil if none.Example Usage:
local ply = lia.util.findPlayerBySteamID("STEAM_0:1:12345")
lia.util.canFit(pos, mins, maxs, filter)
Checks whether a bounding hull can fit at a position without collisions.
Use before spawning or teleporting entities to ensure the space is clear.
Parameters:
Vector pos Position to test.Vector mins Hull minimums; defaults to Vector(16, 16, 0) mirrored if positive.
Vector maxs optional Hull maximums; defaults to mins when nil.
Entity|table filter optional Entity or filter list to ignore in the trace.
Returns:
boolean True if the hull does not hit anything solid, false otherwise.Example Usage:
if lia.util.canFit(pos, Vector(16, 16, 0)) then
ent:SetPos(pos)
end
lia.util.playerInRadius(pos, dist)
Finds all players within a given radius.
Use for proximity-based logic such as AoE effects or notifications.
Parameters:
Vector pos Center position for the search.number dist Radius to search, in units.
Returns:
table Players whose distance squared to pos is less than dist^2.Example Usage:
for _, ply in ipairs(lia.util.playerInRadius(pos, 512)) do
ply:notify("You are near the beacon.")
end
lia.util.formatStringNamed(format)
Formats a string using named placeholders or positional arguments.
Use to substitute tokens in a template string with table keys or ordered arguments.
Parameters:
string format Template containing placeholders like "{name}".Returns:
string The formatted string with placeholders replaced.Example Usage:
lia.util.formatStringNamed("Hello {who}", {who = "world"})
lia.util.formatStringNamed("{1} + {2}", 1, 2)
lia.util.getMaterial(materialPath, materialParameters)
Retrieves and caches a material by path and parameters.
Use whenever drawing materials repeatedly to avoid recreating them.
Parameters:
string materialPath Path to the material.string materialParameters optional Optional material creation parameters.
Returns:
IMaterial Cached or newly created material instance.Example Usage:
local blurMat = lia.util.getMaterial("pp/blurscreen")
lia.util.findFaction(client, name)
Resolves a faction table by name or unique ID and notifies the caller on failure.
Use in commands or UI when users input a faction identifier.
Parameters:
Player client Player to notify on invalid faction.string name Faction name or uniqueID to search for.
Returns:
table|nil Matching faction table, or nil if not found.Example Usage:
local faction = lia.util.findFaction(ply, "combine")
if faction then print(faction.name) end
lia.util.generateRandomName(firstNames, lastNames)
Generates a random full name from provided or default name lists.
Use when creating placeholder or randomized character names.
Parameters:
table firstNames optional Optional list of first names to draw from; defaults to built-in list when nil/empty.table lastNames optional Optional list of last names to draw from; defaults to built-in list when nil/empty.
Returns:
string Concatenated first and last name.Example Usage:
local name = lia.util.generateRandomName()
lia.util.sendTableUI(client, title, columns, data, options, characterID)
Sends a localized table UI payload to a client.
Use when the server needs to present tabular data/options to a specific player.
Parameters:
Player client Recipient player.string title optional Localization key for the window title; defaults to "tableListTitle".
table columns Column definitions; names are localized if present.
table data Row data to display.
table options optional Optional menu options to accompany the table.
number characterID optional Optional character identifier to send with the payload.
Example Usage:
lia.util.sendTableUI(ply, "staffList", columns, rows, options, charID)
lia.util.findEmptySpace(entity, filter, spacing, size, height, tolerance)
Finds nearby empty positions around an entity using grid sampling.
Use when spawning items or players near an entity while avoiding collisions and the void.
Parameters:
Entity entity Origin entity to search around.Entity|table filter optional Optional trace filter to ignore certain entities; defaults to the origin entity.
number spacing Grid spacing between samples; defaults to 32.
number size Number of steps in each direction from the origin; defaults to 3.
number height Hull height used for traces; defaults to 36.
number tolerance Upward offset to avoid starting inside the ground; defaults to 5.
Returns:
table Sorted list of valid origin positions, nearest to farthest from the entity.Example Usage:
local spots = lia.util.findEmptySpace(ent, nil, 24)
local pos = spots[1]
lia.util.animateAppearance(panel, targetWidth, targetHeight, duration, alphaDuration, callback, scaleFactor)
Animates a panel appearing from a scaled, transparent state to its target size and opacity.
Use when showing popups or menus that should ease into view.
Parameters:
Panel panel Panel to animate.number targetWidth Final width of the panel.
number targetHeight Final height of the panel.
number duration optional Duration for size/position easing; defaults to 0.18 seconds.
number alphaDuration optional Duration for alpha easing; defaults to duration.
function callback optional Called when the animation finishes.
number scaleFactor optional Initial size scale relative to target; defaults to 0.8.
Example Usage:
lia.util.animateAppearance(panel, 300, 200)
lia.util.clampMenuPosition(panel)
Keeps a menu panel within the screen bounds, respecting the character logo space.
Use after positioning a menu to prevent it from going off-screen.
Parameters:
Panel panel Menu panel to clamp.Example Usage:
lia.util.clampMenuPosition(menu)
lia.util.drawGradient(x, y, w, h, direction, colorShadow, radius, flags)
Draws a directional gradient rectangle.
Use in panel paints when you need simple gradient backgrounds.
Parameters:
number x X position of the gradient.number y Y position of the gradient.
number w Width of the gradient.
number h Height of the gradient.
number direction Gradient direction index (1 up, 2 down, 3 left, 4 right).
Color colorShadow Color tint for the gradient.
number radius optional Corner radius for drawing helper; defaults to 0.
number flags optional Optional draw flags passed to `drawMaterial`.
Example Usage:
lia.util.drawGradient(0, 0, w, h, 2, Color(0, 0, 0, 180))
lia.util.wrapText(text, width, font)
Wraps text to a maximum width using a specified font.
Use when drawing text that must fit inside a set horizontal space.
Parameters:
string text Text to wrap.number width Maximum width in pixels.
string font optional Font name to measure with; defaults to "LiliaFont.16".
Returns:
table, number Array of wrapped lines and the widest line width.Example Usage:
local lines = lia.util.wrapText(description, 300, "LiliaFont.17")
lia.util.drawBlur(panel, amount, passes, alpha)
Draws a blurred background behind a panel.
Use inside a panel's Paint hook to soften the content behind it.
Parameters:
Panel panel Panel whose screen area will be blurred.number amount optional Blur strength; defaults to 5.
number passes optional Unused; kept for signature compatibility.
number alpha optional Draw color alpha; defaults to 255.
Example Usage:
lia.util.drawBlur(self, 4)
lia.util.drawBlackBlur(panel, amount, passes, alpha, darkAlpha)
Draws a blurred background with a dark overlay in a panel's bounds.
Use for modal overlays where both blur and darkening are desired.
Parameters:
Panel panel Panel area to blur.number amount optional Blur strength; defaults to 6.
number passes optional Number of blur passes; defaults to 5.
number alpha optional Blur draw alpha; defaults to 255.
number darkAlpha optional Alpha for the black overlay; defaults to 220.
Example Usage:
lia.util.drawBlackBlur(self, 6, 4, 255, 200)
lia.util.drawBlurAt(x, y, w, h, amount, passes, alpha)
Draws a blur effect over a specific rectangle on the screen.
Use when you need a localized blur that is not tied to a panel.
Parameters:
number x X coordinate of the rectangle.number y Y coordinate of the rectangle.
number w Width of the rectangle.
number h Height of the rectangle.
number amount optional Blur strength; defaults to 5.
number passes optional Number of blur samples; defaults to 0.2 steps when nil.
number alpha optional Draw alpha; defaults to 255.
Example Usage:
lia.util.drawBlurAt(100, 100, 200, 150, 4)
lia.util.requestEntityInformation(entity, argTypes, callback)
Prompts the user for entity information and forwards the result.
Use when a client must supply additional data for an entity action.
Parameters:
Entity entity Entity that the information pertains to; removed if the request fails.table argTypes Argument descriptors passed to `requestArguments`.
function callback optional Invoked with the collected information on success.
Example Usage:
lia.util.requestEntityInformation(ent, argTypes, function(info) print(info) end)
lia.util.createTableUI(title, columns, data, options, charID)
Builds and displays a table UI on the client.
Use when the client needs to view tabular data with optional menu actions.
Parameters:
string title optional Localization key for the frame title; defaults to "tableListTitle".table columns Column definitions with `name`, `width`, `align`, and `sortable` fields.
table data Row data keyed by column field names.
table options optional Optional menu options with callbacks or net names.
number charID optional Character identifier forwarded with net options.
Returns:
Panel, Panel The created frame and table list view.Example Usage:
local frame, list = lia.util.createTableUI("myData", cols, rows)
lia.util.openOptionsMenu(title, options)
Displays a simple options menu with clickable entries.
Use to quickly prompt the user with a list of named actions.
Parameters:
string title optional Title text to show at the top of the menu; defaults to "options".table options Either an array of {name, callback} or a map of name -> callback.
Returns:
Panel|nil The created frame, or nil if no valid options exist.Example Usage:
lia.util.openOptionsMenu("choose", {{"Yes", onYes}, {"No", onNo}})
lia.util.drawEntText(ent, text, posY, alphaOverride)
Draws floating text above an entity that eases in based on distance.
Use in HUD painting to label world entities when nearby.
Parameters:
Entity ent Entity to draw text above.string text Text to display.
number posY optional Vertical offset in screen space; defaults to 0.
number alphaOverride optional Optional alpha multiplier (0-1 or 0-255).
Example Usage:
hook.Add("HUDPaint", "DrawEntLabels", function()
lia.util.drawEntText(ent, "Storage")
end)
lia.util.drawLookText(text, posY, Screen, Screen, alphaOverride, maxDist)
Draws text at the player's look position with distance-based easing.
Use to display contextual prompts or hints where the player is aiming.
Parameters:
string text Text to render at the hit position.number posY optional Screen-space vertical offset; defaults to 0.
unknown Screen space vertical offset; defaults to 0.
unknown Screen space vertical offset; defaults to 0.
number alphaOverride optional Optional alpha multiplier (0-1 or 0-255).
number maxDist optional Maximum trace distance; defaults to 380 units.
Example Usage:
lia.util.drawLookText("Press E to interact")