Skip to content

ax.util

Source: gamemode/framework/util/util_find.lua

Utility helpers used across the Parallax framework (printing, file handling, text utilities, etc.).

Section: find_utilities

Documented functions: 6

Functions

ax.util:FindCharacter(identifier, allowUnloaded)

Finds a character by numeric ID or by name (partial, case-insensitive).

Searches in two passes:

  1. Active characters — iterates connected players and tests each one's current character (client:GetCharacter()). Numeric identifiers are matched by exact character ID; string identifiers are matched by name using FindString (partial, case-insensitive, exact matches take priority via the matchesByName helper).
  2. All instances — if no active character matched, falls back to ax.character.instances (all loaded characters regardless of whether a player is using them). Numeric lookup uses direct table indexing; string lookup uses the same name-matching helper.

Returns nil when nothing is found.

Realm: shared

Parameters

Name Type Description
identifier number\|string A numeric character ID or a name string (full or partial).

Returns

  • ax.character.meta|nil: The matched character object, or nil.

Usage

ax.util:FindCharacter(42)        -- by ID
ax.util:FindCharacter("John")           -- partial name match
ax.util:FindCharacter("john doe")       -- case-insensitive

ax.util:FindPlayer(identifier)

Finds a connected player by a variety of identifier types.

Lookup is attempted in this priority order:

  1. If identifier is already a valid Player entity, it is returned as-is.
  2. If identifier is a number, Entity(identifier) is returned.
  3. If identifier is a string, the following are tried in order:

a. SteamID format (e.g. "STEAM_0:1:12345") → player.GetBySteamID

b. SteamID64 format (e.g. "76561198...") → player.GetBySteamID64

c. Partial name/SteamID/SteamID64 substring match against all players (case-insensitive, first match wins).

  1. If identifier is a table (array), each element is tried recursively and the first successful match is returned.

Returns NULL (not nil) on no match — callers should test with IsValid.

Realm: shared

Parameters

Name Type Description
identifier number\|string\|Player\|table An entity index, SteamID, SteamID64, name substring, a Player entity, or a table of any of these.

Returns

  • Player|NULL: The matched player entity, or NULL if not found.

Usage

ax.util:FindPlayer("76561198000000000")
ax.util:FindPlayer("John")      -- partial name match
ax.util:FindPlayer(1)           -- entity index

ax.util:FindString(str, find, caseSensitive, startPos, usePatterns)

Tests whether find appears as a substring inside str.

By default the search is case-insensitive (both strings are lowercased via utf8.lower or string.lower before comparison) and pattern characters in find are treated as plain text. All optional parameters allow overriding these defaults when needed.

Prints an error and returns false when either str or find is nil.

Realm: shared

Parameters

Name Type Description
str string The string to search in.
find string The substring (or pattern) to search for.
caseSensitive boolean\|nil When true, the strings are compared without lowercasing. Default: false (case-insensitive).
startPos number\|nil The character position to start searching from. Default: 0 (from the beginning).
usePatterns boolean\|nil When true, find is treated as a Lua pattern. Default: false (plain-text search via string.find plain flag).

Returns

  • boolean: True if find appears in str, false otherwise.

Usage

ax.util:FindString("Hello World", "world")            -- true
ax.util:FindString("Hello World", "World", true)            -- true (exact case)
ax.util:FindString("Hello World", "World", false)           -- true (case-insensitive)
ax.util:FindString("Hello World", "xyz")                    -- false

ax.util:FindText(txt, find)

Tests whether any word in a text block contains a substring.

Splits txt by both spaces and newlines and passes each word individually to FindString. Returns true as soon as any word matches. Returns false immediately when either argument is nil. This is more permissive than a whole-string search — it matches even when the query appears in only one word of a multi-word text.

Realm: shared

Parameters

Name Type Description
txt string The text block to split and search.
find string The substring to look for in each word.

Returns

  • boolean: True if any word in txt contains find (case-insensitive).

Usage

ax.util:FindText("the quick brown fox", "quick")   -- true
ax.util:FindText("hello\nworld", "world")                 -- true
ax.util:FindText("hello world", "xyz")                    -- false

ax.util:NormalizeSearchString(value)

Utility helpers used across the Parallax framework (printing, file handling, text utilities, etc.).

User and character finder utilities.

Normalises a value into a lowercase, trimmed string for search comparisons.

Converts value to a string via tostring, trims leading/trailing whitespace, and lowercases the result using utf8.lower when available (falling back to string.lower). Returns "" when the result is empty or when value is nil. Used as a pre-processing step by SearchMatches to ensure consistent case-insensitive matching.

Realm: shared

Parameters

Name Type Description
value any The value to normalise (coerced to string).

Returns

  • string: The trimmed, lowercased string, or "" if empty/nil.

Usage

ax.util:NormalizeSearchString("  Hello  ")  -- "hello"
ax.util:NormalizeSearchString(nil)                 -- ""

ax.util:SearchMatches(query, ...)

Tests whether a search query is contained in any of the provided candidates.

Both the query and each candidate are normalised with NormalizeSearchString before comparison. An empty query always returns true — this matches the convention of "show everything when the search box is blank". The check is substring-based (not exact match), so "cit" will match "citizen".

Realm: shared

Parameters

Name Type Description
query string The search text to look for.
... any Candidate values to test against (each coerced to string).

Returns

  • boolean: True if the query is empty, or if any candidate contains the query as a substring (case-insensitive).

Usage

ax.util:SearchMatches("pol", "Citizen", "Police Officer") -- true
ax.util:SearchMatches("", "anything")                            -- true
ax.util:SearchMatches("xyz", "Citizen", "Police")               -- false