Utility¶
General-purpose helpers for Lilia bodygroups, player lookup, entity ownership queries, world-space placement, string formatting, cached materials, table UI handling, and clientside drawing utilities.
Overview
lia.util.normalizeBodygroupKey(key)View Source
Purpose
Normalizes a bodygroup identifier into either a numeric bodygroup index or a trimmed bodygroup name.
Realm
Shared
Parameters
any key The bodygroup key to normalize. Numeric values and numeric strings are converted to numbers; non-empty strings are trimmed.
Returns
number|string|nil The normalized bodygroup index or name. Returns nil when the key cannot be normalized.
Example Usage
local key = lia.util.normalizeBodygroupKey(" headgear ")
local numericKey = lia.util.normalizeBodygroupKey("2")
lia.util.resolveBodygroupIndex(target, identifier)View Source
Purpose
Resolves a bodygroup identifier against an entity or player into a numeric bodygroup index.
Realm
Shared
Parameters
Entity|Player target The entity whose bodygroups should be checked.
number|string identifier The bodygroup index, numeric string, or bodygroup name to resolve.
Returns
number|nil The resolved bodygroup index. Returns nil when the target is invalid or the identifier cannot be matched.
Example Usage
local index = lia.util.resolveBodygroupIndex(client, "headgear")
if index then client:SetBodygroup(index, 1) end
lia.util.normalizeBodygroups(bodygroups)View Source
Purpose
Converts supported bodygroup table formats into a simple identifier-to-value lookup table.
Realm
Shared
Parameters
table bodygroups A bodygroup table containing array entries, keyed values, or both.
Returns
table A normalized table where each key is a bodygroup identifier and each value is a numeric bodygroup value.
Example Usage
local bodygroups = lia.util.normalizeBodygroups({{name = "headgear", value = 1}, [2] = 0})
lia.util.resolveBodygroups(target, bodygroups)View Source
Purpose
Resolves a bodygroup table into numeric bodygroup indices for a specific target entity.
Realm
Shared
Parameters
Entity|Player target The entity whose bodygroups should be resolved.
table bodygroups The bodygroup data to normalize and resolve.
Returns
table A table of resolved numeric bodygroup indices mapped to numeric bodygroup values.
Example Usage
local resolved = lia.util.resolveBodygroups(client, {headgear = 1})
lia.util.applyBodygroups(target, bodygroups)View Source
Purpose
Applies bodygroup values to a valid entity after resolving bodygroup names or identifiers.
Realm
Shared
Parameters
Entity|Player target The entity receiving the bodygroup changes.
table bodygroups The bodygroup data to apply.
Returns
table The resolved bodygroups that were applied. Returns an empty table when the target is invalid.
Example Usage
lia.util.applyBodygroups(client, {headgear = 1, [2] = 0})
lia.util.findPlayersInBox(mins, maxs)View Source
Purpose
Finds all players inside an axis-aligned world-space box.
Realm
Shared
Parameters
Returns
table A sequential table containing every valid player found 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)View Source
Purpose
Requests argument input from a client for an entity and removes the entity if the request is cancelled.
Realm
Shared
Parameters
Player client The player receiving the argument request.
Entity entity The entity associated with the request.
table argTypes The argument definitions passed to `client:requestArguments`.
function callback optional Optional callback called with the submitted information when the request succeeds.
Returns
nil This function does not return a value.
Example Usage
lia.util.requestEntityInformation(client, entity, args, function(information)
entity.information = information
end)
lia.util.getBySteamID(steamID)View Source
Purpose
Finds an online player with an active character by SteamID or SteamID64.
Realm
Shared
Parameters
string steamID The SteamID or SteamID64 to search for.
Returns
Player|nil The matching player with a loaded character, or nil when no match is found.
Example Usage
local client = lia.util.getBySteamID("STEAM_0:1:123456")
lia.util.findPlayersInSphere(origin, radius)View Source
Purpose
Finds all players within a radius of a world position.
Realm
Shared
Parameters
Returns
table A sequential table containing players within the radius.
Example Usage
local nearby = lia.util.findPlayersInSphere(entity:GetPos(), 256)
lia.util.findPlayer(client, identifier)View Source
Purpose
Resolves a player from a command-style identifier, SteamID, SteamID64, self marker, trace marker, or partial name.
Realm
Shared
Parameters
Player client optional The player performing the lookup. Used for `^`, `@`, and localized error notifications.
string identifier The player identifier to resolve.
Returns
Player|nil The matching player, or nil when no valid player is found.
Example Usage
local target = lia.util.findPlayer(client, "@")
local byName = lia.util.findPlayer(client, "samael")
lia.util.findPlayerItems(client)View Source
lia.util.findPlayerItemsByClass(client, class)View Source
Purpose
Finds spawned item entities created by a player that match a specific item ID.
Realm
Shared
Parameters
Player client The player whose created item entities should be searched.
string class The item ID stored in the entity network variable.
Returns
table A sequential table containing matching item entities.
Example Usage
local radios = lia.util.findPlayerItemsByClass(client, "handheld_radio")
lia.util.findPlayerEntities(client, class)View Source
Purpose
Finds entities created by, or assigned to, a specific player, optionally filtered by entity class.
Realm
Shared
Parameters
Player client The player whose entities should be found.
string class optional Optional entity class filter.
Returns
table A sequential table containing matching entities.
Example Usage
local doors = lia.util.findPlayerEntities(client, "prop_door_rotating")
local owned = lia.util.findPlayerEntities(client)
lia.util.stringMatches(a, b)View Source
Purpose
Performs a case-sensitive and case-insensitive substring or exact-string comparison.
Realm
Shared
Parameters
Returns
boolean True when the strings match exactly or when `b` is found within `a`; otherwise false.
Example Usage
if lia.util.stringMatches(client:Name(), "sam") then
print(client:Name())
end
lia.util.getAdmins()View Source
Purpose
Collects all online players that pass the framework staff check.
Realm
Shared
Returns
table A sequential table containing online staff players.
Example Usage
for _, staff in ipairs(lia.util.getAdmins()) do
staff:notify("Staff notice")
end
lia.util.findPlayerBySteamID64(SteamID64)View Source
Purpose
Finds an online player by converting a SteamID64 into a SteamID first.
Realm
Shared
Parameters
string SteamID64 The SteamID64 to convert and search for.
Returns
Player|nil The matching player, or nil when conversion fails or no player matches.
Example Usage
local client = lia.util.findPlayerBySteamID64("76561198000000000")
lia.util.findPlayerBySteamID(SteamID)View Source
Purpose
Finds an online player by SteamID.
Realm
Shared
Parameters
string SteamID The SteamID to search for.
Returns
Player|nil The matching player, or nil when no player matches.
Example Usage
local client = lia.util.findPlayerBySteamID("STEAM_0:1:123456")
lia.util.canFit(pos, mins, maxs, filter)View Source
Purpose
Checks whether a hull can fit at a world position without hitting player-solid geometry.
Realm
Shared
Parameters
Vector pos The position to test.
Vector mins optional Optional hull minimums. Defaults to `Vector(16, 16, 0)` and is inverted when positive.
Vector maxs optional Optional hull maximums. Defaults to `mins`.
Entity|table filter optional Optional trace filter.
Returns
boolean True when the hull does not hit anything; otherwise false.
Example Usage
if lia.util.canFit(spawnPos, nil, nil, client) then
client:SetPos(spawnPos)
end
lia.util.playerInRadius(pos, dist)View Source
Purpose
Finds valid players within a radius of a world position.
Realm
Shared
Parameters
Returns
table A sequential table containing players inside the radius.
Example Usage
local players = lia.util.playerInRadius(entity:GetPos(), 128)
lia.util.formatStringNamed(format)View Source
Purpose
Replaces `{name}` or ordered placeholder tokens in a string with table or vararg values.
Realm
Shared
Parameters
string format The format string containing `{token}` placeholders.
Returns
string The formatted string with placeholders replaced.
Example Usage
local text = lia.util.formatStringNamed("Hello, {name}", {name = client:Name()})
local ordered = lia.util.formatStringNamed("{first} {second}", "Hello", "World")
lia.util.getMaterial(materialPath, materialParameters)View Source
Purpose
Returns a cached material instance for a material path and optional material parameters.
Realm
Shared
Parameters
string materialPath The material path to load.
string materialParameters optional Optional material parameters passed to `Material` on first load.
Returns
IMaterial The cached or newly created material.
Example Usage
local blur = lia.util.getMaterial("pp/blurscreen")
lia.util.findFaction(client, name)View Source
Purpose
Finds a faction by numeric/team key, name, or unique ID, and notifies the client when no match is found.
Realm
Shared
Parameters
Player client The player to notify when the faction cannot be found.
any name The faction key, display name, or unique ID to search for.
Returns
table|nil The matching faction table, or nil when no faction matches.
Example Usage
local faction = lia.util.findFaction(client, "citizen")
lia.util.generateRandomName(firstNames, lastNames)View Source
Purpose
Generates a random full name from provided first-name and last-name lists or built-in fallback lists.
Realm
Shared
Parameters
table firstNames optional Optional list of first names.
table lastNames optional Optional list of last names.
Returns
string A generated first-name and last-name combination.
Example Usage
local name = lia.util.generateRandomName()
local custom = lia.util.generateRandomName({"Alex"}, {"Morgan"})
lia.util.setPositionCallback(name, data)View Source
Purpose
Registers or updates a named feature-position callback definition.
Realm
Shared
Parameters
string name The display name for the position callback.
table data Callback data containing `onRun`, `onSelect`, and optional `onRemove`, `HUDPaint`, `serverOnly`, and `color` fields.
Returns
nil This function does not return a value.
Example Usage
lia.util.setPositionCallback("Vendor Spawn", {
onRun = function(pos, client, typeId) end,
onSelect = function() end
})
lia.util.sendTableUI(client, title, columns, data, options, characterID)View Source
Purpose
Sends localized table UI data to a player through the large-table networking helper.
Realm
Server
Parameters
Player client The player who should receive the table UI.
string title optional Optional localization key for the table title.
table columns Column definitions, with names localized before sending.
table data Row data for the table UI.
table options optional Optional row action definitions.
number characterID optional Optional character ID associated with row actions.
Returns
nil This function does not return a value.
Example Usage
lia.util.sendTableUI(client, "players", columns, rows, options, client:getChar():getID())
lia.util.findEmptySpace(entity, filter, spacing, size, height, tolerance)View Source
Purpose
Finds nearby empty world positions around an entity using trace checks and distance sorting.
Realm
Server
Parameters
Entity entity The entity used as the search origin and default filter.
Entity|table filter optional Optional trace filter. Defaults to the entity.
number spacing optional Distance between checked grid positions. Defaults to 32.
number size optional Number of grid steps to search in each direction. Defaults to 3.
number height optional Height used for vertical trace checks. Defaults to 36.
number tolerance optional Vertical offset used to avoid immediate ground contact. Defaults to 5.
Returns
table A distance-sorted table of valid empty positions.
Example Usage
local positions = lia.util.findEmptySpace(entity, client, 32, 4)
local nearest = positions[1]
lia.util.animateAppearance(panel, targetWidth, targetHeight, duration, alphaDuration, callback, scaleFactor)View Source
Purpose
Animates a panel from a scaled, transparent state to its target size, position, and full opacity.
Realm
Client
Parameters
Panel panel The panel to animate.
number targetWidth The final panel width.
number targetHeight The final panel height.
number duration optional Approximate size and position animation duration. Defaults to 0.18.
number alphaDuration optional Approximate alpha animation duration. Defaults to `duration`.
function callback optional Optional callback called with the panel when the animation finishes.
number scaleFactor optional Initial scale multiplier. Defaults to 0.8.
Returns
nil This function does not return a value.
Example Usage
lia.util.animateAppearance(frame, 400, 300, 0.2)
lia.util.drawGradient(x, y, w, h, direction, colorShadow, radius, flags)View Source
Purpose
Draws one of the built-in VGUI gradient materials through the Lilia Derma material helper.
Realm
Client
Parameters
number x The x position to draw at.
number y The y position to draw at.
number w The gradient width.
number h The gradient height.
number direction Gradient material index: up, down, left, or right.
Color colorShadow The color used to draw the gradient.
number radius optional Optional rounded radius. Defaults to 0.
number flags optional Optional drawing flags passed to the Derma helper.
Returns
nil This function does not return a value.
Example Usage
lia.util.drawGradient(0, 0, 200, 40, 2, Color(0, 0, 0, 180))
lia.util.wrapText(text, width, font)View Source
Purpose
Wraps text into multiple lines that fit within a target pixel width for a specific font.
Realm
Client
Parameters
string text The text to wrap.
number width The maximum line width in pixels.
string font optional Font name used for measuring. Defaults to `LiliaFont.16`.
Returns
table, number The wrapped lines and the widest measured line width.
Example Usage
local lines, maxWidth = lia.util.wrapText(description, 300, "LiliaFont.16")
lia.util.drawBlur(panel, amount, passes, alpha)View Source
Purpose
Draws a screen-space blur behind a panel.
Realm
Client
Parameters
Panel panel The panel whose screen position determines the blur offset.
number amount optional Blur strength. Defaults to 5.
number passes optional Present for compatibility; the function uses a fixed internal pass count.
number alpha optional Blur draw alpha. Defaults to 255.
Returns
nil This function does not return a value.
Example Usage
frame.Paint = function(self)
lia.util.drawBlur(self, 4)
end
lia.util.drawBlackBlur(panel, amount, passes, alpha, darkAlpha)View Source
Purpose
Draws a blur behind a panel and overlays a dark rectangle over the panel area.
Realm
Client
Parameters
Panel panel The panel to draw behind and darken.
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 dark overlay. Defaults to 220.
Returns
nil This function does not return a value.
Example Usage
lia.util.drawBlackBlur(frame, 6, 5, 255, 200)
lia.util.drawBlurAt(x, y, w, h, amount, passes, alpha)View Source
Purpose
Draws a localized blur over a rectangular screen area.
Realm
Client
Parameters
number x The x position of the blur rectangle.
number y The y position of the blur rectangle.
number w The blur rectangle width.
number h The blur rectangle height.
number amount optional Blur strength. Defaults to 5.
number passes optional Starting blur-loop value. Defaults to 0.2.
number alpha optional Blur draw alpha. Defaults to 255.
Returns
nil This function does not return a value.
Example Usage
lia.util.drawBlurAt(20, 20, 300, 120, 6)
lia.util.createTableUI(title, columns, data, options, charID)View Source
Purpose
Creates a clientside table window with localized columns, row data, copy support, and optional row actions.
Realm
Client
Parameters
string title optional Optional localization key for the frame title.
table columns Column definitions used to build the table.
table data Row data displayed in the table.
table options optional Optional row action definitions that may send net messages.
number charID optional Character ID written with row action net messages.
Returns
Panel, Panel The created frame and table panel.
Example Usage
local frame, listView = lia.util.createTableUI("players", columns, rows, options, charID)
lia.util.drawEntText(ent, text, posY, alphaOverride)View Source
Purpose
Draws animated styled text above an entity when the local player is close enough to see it.
Realm
Client
Parameters
Entity ent The entity to draw text above.
string text The text to display.
number posY optional Optional screen-space vertical offset.
number alphaOverride optional Optional alpha multiplier or 0-255 alpha value.
Returns
nil This function does not return a value.
Example Usage
lia.util.drawEntText(entity, "Open", 0, 255)
lia.util.drawLookText(text, posY, alphaOverride, maxDist)View Source
Purpose
Draws animated styled text at the point the local player is looking at within a maximum distance.
Realm
Client
Parameters
string text The text to display.
number posY optional Optional screen-space vertical offset.
number alphaOverride optional Optional alpha multiplier or 0-255 alpha value.
number maxDist optional Maximum trace distance. Defaults to 380.
Returns
nil This function does not return a value.
Example Usage
lia.util.drawLookText("Interact", 0, 255, 256)
lia.util.setFeaturePosition(pos, typeId)View Source
Purpose
Defines an empty clientside placeholder for setting a feature position before the implemented definition later in the file replaces it.
Realm
Client
Parameters
Vector pos The position argument accepted by the placeholder.
string typeId The feature-position callback ID accepted by the placeholder.
Returns
nil This placeholder does not return a value.
Example Usage
lia.util.setFeaturePosition(pos, typeId)
lia.util.drawLookText(text, posY, alphaOverride, maxDist)View Source
Purpose
Draws animated styled text at the point the local player is looking at within a maximum distance.
Realm
Client
Parameters
string text The text to display.
number posY optional Optional screen-space vertical offset.
number alphaOverride optional Optional alpha multiplier or 0-255 alpha value.
number maxDist optional Maximum trace distance. Defaults to 380.
Returns
nil This function does not return a value.
Example Usage
lia.util.drawLookText("Interact", 0, 255, 256)
lia.util.setFeaturePosition(pos, typeId)View Source
Purpose
Runs a registered feature-position callback for a clientside position selection.
Realm
Client
Parameters
Returns
nil This function does not return a value.
Example Usage
lia.util.setFeaturePosition(trace.HitPos, "vendor_spawn")
lia.util.removeFeaturePosition(pos, typeId)View Source
Purpose
Removes or requests removal of a feature position using the registered callback for a type ID.
Realm
Client
Parameters
Returns
nil This function does not return a value.
Example Usage
lia.util.removeFeaturePosition(trace.HitPos, "vendor_spawn")
lia.util.drawESPStyledText(text, x, y, espColor, font, fadeAlpha)View Source
Purpose
Draws styled ESP text with a themed background, blur, accent bar, and fade alpha.
Realm
Client
Parameters
string text The ESP text to draw.
number x The horizontal screen position.
number y The vertical screen position.
Color espColor optional Optional accent color. Defaults to the active theme accent.
string font Font used to measure and draw the text.
number fadeAlpha optional Alpha multiplier from 0 to 1. Defaults to 1.
Returns
number The height of the styled text block.
Example Usage
lia.util.drawESPStyledText("Target", x, y, Color(255, 255, 255), "LiliaFont.24", 1)