Skip to content

ax.util

Source: gamemode/framework/util/util_core.lua

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

Documented functions: 28

Functions

ax.util:ApproachAngle(fraction, startAng, finishAng, opts)

Approaches an Angle from start to finish.

Parameters

Name Type Description
fraction number Fraction between 0 and 1
startAng Angle Start angle
finishAng Angle Finish angle
opts table\|nil Options: smooth, linear, transition

Returns

  • Angle: Approached angle

ax.util:ApproachFraction(fraction, smooth, linear)

Adjusts a fraction based on smoothness and linear toggle.

Parameters

Name Type Description
fraction number Fraction between 0 and 1
smooth number Smoothness (0-100)
linear boolean\|nil If true, prefers linear movement

Returns

  • number: Adjusted fraction

ax.util:ApproachNumber(fraction, start, finish, opts)

Approaches a number from start to finish based on a fraction and options.

Parameters

Name Type Description
fraction number Fraction between 0 and 1
start number Start value
finish number Finish value
opts table\|nil Options: smooth, linear, transition

Returns

  • number: Approached number

ax.util:ApproachVector(fraction, startVec, finishVec, opts)

Approaches a Vector from start to finish.

Parameters

Name Type Description
fraction number Fraction between 0 and 1
startVec Vector Start vector
finishVec Vector Finish vector
opts table\|nil Options: smooth, linear, transition

Returns

  • Vector: Approached vector

ax.util:ClampRound(n, min, max, decimals)

Clamp and round a number.

Parameters

Name Type Description
n number Input number
min number\|nil Minimum allowed value
max number\|nil Maximum allowed value
decimals number\|nil Number of decimal places to keep

Returns

  • number: The clamped and rounded value

Usage

local v = ax.util:ClampRound(3.14159, 0, 10, 2) -- 3.14

ax.util:DrawBlur(r, x, y, width, height, color)

Draws a blur inside a rectangle (client-only).

Parameters

Name Type Description
r number Roundness of rectangle corners
x number X screen coordinate
y number Y screen coordinate
width number Width in pixels
height number Height in pixels
color Color Color of the blur overlay (alpha used)

Usage

ax.util:DrawBlur(16,10,10,200,100,Color(255,255,255,180))

ax.util:DrawCircle(x, y, radius, segments, startAngle, endAngle)

Draw a smooth arc using polygons

Realm: client

Parameters

Name Type Description
x number Center X position
y number Center Y position
radius number Radius of the circle
segments number Number of segments for smoothness (default: 64)
startAngle number Starting angle in degrees (default: 0)
endAngle number Ending angle in degrees (default: 360)

ax.util:DrawGradient(r, name, x, y, w, h, color)

Draw a gradient material tinted with a color.

Parameters

Name Type Description
name string Gradient short name or material path
x number X coordinate
y number Y coordinate
w number Width
h number Height
color Color\|nil Optional tint color (defaults to white)

Usage

ax.util:DrawGradient(0, "left", 0, 0, 200, 400, Color(0,0,0,200))

ax.util:DrawSlice(x, y, radius, startAngle, endAngle, color)

Draw a circular slice (pie chart style progress indicator)

Realm: client

Parameters

Name Type Description
x number Center X position
y number Center Y position
radius number Radius of the slice
startAngle number Starting angle in degrees (0 is top)
endAngle number Ending angle in degrees
color table Color table with r, g, b, a

ax.util:FindInCrosshair(client, target, range)

Finds a target in the player's crosshair, with an optional range.

Realm: shared

Parameters

Name Type Description
client player Player to find the target for
target entity Target entity to check
range number Range to check for the target

Returns

  • bool: Whether or not the target is in the player's crosshair

Usage

-- returns true if Entity(2) is in Entity(1)'s crosshair
print(ax.util:FindInCrosshair(Entity(1), Entity(2)))
> true

-- returns true if Entity(2) is in Entity(1)'s crosshair within 0.5 range
print(ax.util:FindInCrosshair(Entity(1), Entity(2), 0.5))
> true

-- returns false if Entity(2) is not in Entity(1)'s crosshair within 0.1 range
print(ax.util:FindInCrosshair(Entity(1), Entity(2), 0.1))
> false

ax.util:GetGradient(name)

Get a cached gradient material by name.

Parameters

Name Type Description
name string Short name or material path

Returns

  • IMaterial: Material instance

Usage

local mat = ax.util:GetGradient("left")

ax.util:GetGradientPath(name)

Resolve a gradient material path by a short name. Accepts common names: "left", "right", "top", "bottom" or direct material paths.

Parameters

Name Type Description
name string Short name or material path

Returns

  • string: Material path

Usage

local path = ax.util:GetGradientPath("left")

ax.util:GetMaterial(path, parameters)

Returns a material from the cache or creates a new one.

Parameters

Name Type Description
path string Material path
parameters string\|nil Parameters string passed to Material()

Returns

  • IMaterial: The created or cached material

Usage

local mat = ax.util:GetMaterial("sprites/glow", "nocull")

ax.util:GetProjectName()

Get the current project/gamemode name (falls back to "parallax").

Returns

  • string: The active gamemode folder name or "parallax"

Usage

local name = ax.util:GetProjectName()

ax.util:GetServerAddress()

Get the server's network address. Returns the raw address string as returned by game.GetIPAddress(), plus the parsed ip and port when available.

Realm: shared

Returns

  • string|nil: full The full "ip:port" string or nil when unavailable
  • string|nil: ip The IP portion (may be "0.0.0.0" or similar)
  • number|nil: port The port number (0 when not present)

Usage

local full, ip, port = ax.util:GetServerAddress()

ax.util:IsValidPlayer(client)

Returns true if the entity is a valid player.

Parameters

Name Type Description
client Entity Candidate entity

Returns

  • boolean: True if entity is a valid player

Usage

if ax.util:IsValidPlayer(client) then -- do something end

ax.util:NameToUniqueID(name)

Convert a human-readable name to a sanitized unique id.

Parameters

Name Type Description
name string Human-readable name

Returns

  • string: A sanitized lowercase unique id

Usage

local id = ax.util:NameToUniqueID("My Module") -- "my_module"
local id2 = ax.util:NameToUniqueID("MyModule") -- "my_module"

ax.util:PadNumber(num, digits)

Pads a number with leading zeroes until it reaches the desired digit length.

Parameters

Name Type Description
num number The number to pad.
digits number The total amount of digits the result should have.

Returns

  • string: The padded number as a string.

ax.util:SafeCall(fn, ...)

Safely call a function and capture errors, returning success and results.

Parameters

Name Type Description
fn function Function to call
... any Arguments to pass to fn

Returns

  • boolean: ok True if function executed without error
  • any: ... Results returned by fn when ok is true

Usage

local ok, result = ax.util:SafeCall(function() return 1+1 end)

ax.util:SafeCall(fn, ...)

Safe function call wrapper (returns ok and result).

Parameters

Name Type Description
fn function Function to call

Returns

  • boolean: ok True if function executed without error
  • any: The return value of the function when ok

Usage

local ok, res = ax.util:SafeCall(function() return 123 end)

ax.util:SafeParseTable(tInput, bToJson)

Utility helpers used across the Parallax framework (printing, file handling, text utilities, etc.). Safely parse a JSON string into a table, or return table input unchanged.

Parameters

Name Type Description
tInput string\|table JSON string or already-parsed table
bToJson boolean\|nil Unused parameter for future use

Returns

  • table|nil: The parsed table or nil on failure

Usage

local tbl = ax.util:SafeParseTable(jsonString)

ax.util:SanitizeKey(key)

Sanitize a key to be safe for use in file names.

Parameters

Name Type Description
key string Input key

Returns

  • string: A filesystem-safe string

Usage

local safe = ax.util:SanitizeKey("Player:Test") -- "Player_Test"

ax.util:Scale(value)

Scale a value using the user's UI scale preference.

Realm: client

Parameters

Name Type Description
value number The base value to scale

Returns

  • number: The scaled value

Usage

local scaledSize = ax.util:Scale(16) -- 16 * uiScale option

ax.util:ScreenScale(value)

Scale a ScreenScale value using the user's UI scale preference.

Realm: client

Parameters

Name Type Description
value number The base value to pass to ScreenScale

Returns

  • number: The ScreenScale'd and UI-scaled value

Usage

local scaledPadding = ax.util:ScreenScale(16)

ax.util:ScreenScaleH(value)

Scale a ScreenScaleH value using the user's UI scale preference.

Realm: client

Parameters

Name Type Description
value number The base value to pass to ScreenScaleH

Returns

  • number: The ScreenScaleH'd and UI-scaled value

Usage

local scaledHeight = ax.util:ScreenScaleH(32)

ax.util:TokenizeString(str)

Tokenize a string into arguments, respecting quoted strings.

Parameters

Name Type Description
str string Input command string

Returns

  • table: Array of token strings

Usage

local args = ax.util:TokenizeString('say "hello world"')

ax.util:UniqueIDToCamel(id)

Convert a unique id to camel case.

Parameters

Name Type Description
id string Unique id to convert

Returns

  • string: Camel-cased string

Usage

local camel = ax.util:UniqueIDToCamel("my_module") -- "MyModule"

ax.util:UniqueIDToName(id)

Convert a unique id (underscored) back to a human-friendly name.

Parameters

Name Type Description
id string Unique id to convert

Returns

  • string: Human-friendly name

Usage

local name = ax.util:UniqueIDToName("my_module") -- "My Module"