Utility
Common operations and helper functions for the Lilia framework.
Overview
lia.util.findPlayersInBox(mins, maxs)
Purpose
Finds all players within an axis-aligned bounding box.
When Called
Use when you need the players contained inside specific world bounds (e.g. triggers or zones).
Parameters
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.requestEntityInformation(client, entity, argTypes, callback)
Purpose
Prompts the user for entity information and forwards the result.
When Called
Use when a client must supply additional data for an entity action.
Parameters
Player client Player who will be prompted for the information.
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(client, ent, argTypes, function(info) print(info) end)
lia.util.getBySteamID(steamID)
Purpose
Locates a connected player by SteamID or SteamID64 and requires an active character.
When Called
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)
Purpose
Returns all players inside a spherical radius from a point.
When Called
Use to gather players near a position for proximity-based effects or checks.
Parameters
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)
Purpose
Resolves a player from various identifiers and optionally informs the caller on failure.
When Called
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)
Purpose
Collects all spawned item entities created by a specific player.
When Called
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)
Purpose
Collects spawned item entities from a player filtered by item class.
When Called
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)
Purpose
Finds entities created by or associated with a player, optionally by class.
When Called
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)
Purpose
Performs case-insensitive equality and substring comparison between two strings.
When Called
Use for loose name matching where exact case is not important.
Parameters
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()
Purpose
Returns all connected staff members.
When Called
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)
Purpose
Resolves a player from a SteamID64 wrapper around `findPlayerBySteamID`.
When Called
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)
Purpose
Searches connected players for a matching SteamID.
When Called
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)
Purpose
Checks whether a bounding hull can fit at a position without collisions.
When Called
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)
Purpose
Finds all players within a given radius.
When Called
Use for proximity-based logic such as AoE effects or notifications.
Parameters
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)
Purpose
Formats a string using named placeholders or positional arguments.
When Called
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)
Purpose
Retrieves and caches a material by path and parameters.
When Called
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)
Purpose
Resolves a faction table by name or unique ID and notifies the caller on failure.
When Called
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)
Purpose
Generates a random full name from provided or default name lists.
When Called
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.setPositionCallback(firstNames, lastNames)
Purpose
Generates a random full name from provided or default name lists.
When Called
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)
Purpose
Sends a localized table UI payload to a client.
When Called
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)
Purpose
Finds nearby empty positions around an entity using grid sampling.
When Called
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)
Purpose
Animates a panel appearing from a scaled, transparent state to its target size and opacity.
When Called
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.drawGradient(x, y, w, h, direction, colorShadow, radius, flags)
Purpose
Draws a directional gradient rectangle.
When Called
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)
Purpose
Wraps text to a maximum width using a specified font.
When Called
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)
Purpose
Draws a blurred background behind a panel.
When Called
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)
Purpose
Draws a blurred background with a dark overlay in a panel's bounds.
When Called
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)
Purpose
Draws a blur effect over a specific rectangle on the screen.
When Called
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.createTableUI(title, columns, data, options, charID)
Purpose
Builds and displays a table UI on the client.
When Called
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.drawEntText(ent, text, posY, alphaOverride)
Purpose
Draws floating text above an entity that eases in based on distance.
When Called
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)
Purpose
Draws text at the player's look position with distance-based easing.
When Called
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")
lia.util.setFeaturePosition(pos, typeId)
Purpose
Sets a feature position using the position tool callback system.
When Called
Called by the position tool when a player sets a position (left-click or Shift+R).
Parameters
Vector pos The world position to set.
string typeId The type ID of the position callback (e.g., "faction_spawn_adder", "sit_room").
Example Usage
lia.util.setFeaturePosition(Vector(0, 0, 0), "faction_spawn_adder")
lia.util.drawLookText(text, posY, Screen, Screen, alphaOverride, maxDist)
Purpose
Draws text at the player's look position with distance-based easing.
When Called
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")
lia.util.setFeaturePosition(pos, typeId)
Purpose
Sets a feature position using the position tool callback system.
When Called
Called by the position tool when a player sets a position (left-click or Shift+R).
Parameters
Vector pos The world position to set.
string typeId The type ID of the position callback (e.g., "faction_spawn_adder", "sit_room").
Example Usage
lia.util.setFeaturePosition(Vector(0, 0, 0), "faction_spawn_adder")
lia.util.removeFeaturePosition(pos, typeId)
Purpose
Removes a feature position using the position tool callback system.
When Called
Called by the position tool when a player removes a position (right-click).
Parameters
Vector pos The world position to remove.
string typeId The type ID of the position callback (e.g., "faction_spawn_adder", "sit_room").
Example Usage
lia.util.removeFeaturePosition(Vector(0, 0, 0), "faction_spawn_adder")
lia.util.drawESPStyledText(text, x, y, espColor, font, fadeAlpha)
Purpose
Draws styled ESP text with background, blur, and theme support.
When Called
Use when you need to draw text with ESP styling, including background panels and blur effects.
Parameters
string text The text to display.
number x X position on screen.
number y Y position on screen.
Color espColor Color for the accent/bottom bar.
string font Font to use for the text.
number, optional fadeAlpha Alpha multiplier for fading (default: 1).
Returns
number Height of the drawn element.
Example Usage
local height = lia.util.drawESPStyledText("Player Name", 200, 100, Color(255, 0, 0), "liaMediumFont", 0.8)