Skip to content

nut.util

Utility module.

This module contains numerous useful utility functions used within other modules and classes.

General Utility Functions

Provides various helpers for file inclusion, server data handling, player properties, and math-based utilities.

nut.util.include (fileName, state)
nut.util.include

Includes a Lua file depending on filename prefix or forced state.

Parameters:

string fileName The file name to include

string state optional One of 'server', 'shared', or 'client'

nut.util.includeDir (directory, fromLua, recursive)
nut.util.includeDir

Includes all Lua files in a directory with optional recursion.

Parameters:

string directory Directory to search for files

boolean fromLua optional. default: false Whether to include relative from /lua

boolean recursive optional. default: false Whether to include subdirectories

nut.util.getAddress ()
nut.util.getAddress

Deprecated. Returns the server's IP address. Use game.GetIPAddress() instead.

Returns:

string IP address and port

nut.util.getAdmins (isSuper)
nut.util.getAdmins

Returns a table of admin or superadmin players.

Parameters:

boolean isSuper optional. default: false True to return only superadmins

Returns:

tab Table of Player objects

nut.util.isSteamID (value)
nut.util.isSteamID

Returns true if a string is a 32-bit SteamID.

Parameters:

string value The string to test

Returns:

bool True if valid SteamID

nut.util.findPlayer (identifier, allowPatterns)
nut.util.findPlayer

Finds a player by name or SteamID.

Parameters:

string identifier Player name or SteamID

boolean allowPatterns optional. default: false Whether to allow pattern search

Returns:

client Matching player

Or

nil If no match found

nut.util.gridVector (vec, gridSize)
nut.util.gridVector

Snaps a vector to the nearest point on a grid.

Parameters:

Vector vec The vector to round

number gridSize Grid spacing

Returns:

vector Snapped vector

nut.util.getAllChar ()
nut.util.getAllChar

Gets all active character IDs from connected players.

Returns:

tab Table of character IDs

nut.util.getMaterial (materialPath)
nut.util.getMaterial

Returns a single cached copy of a material or creates it if it doesn't exist.

Parameters:

string materialPath Path to the material

Returns:

Material The loaded or cached material

Blur Drawing Utilities

Provides functions to draw blurred backgrounds behind panels or at specific coordinates, with support for performance-friendly fallback.

nut.util.drawBlur (panel, amount, passes)
nut.util.drawBlur

Draws a blurred material over the screen, to blur things. Automatically uses a cheaper fallback if the nut_cheapblur convar is enabled.

Parameters:

Panel panel The panel to apply blur behind

number amount optional. default: 5 The intensity of the blur

number passes optional. default: 0.2 How many blur layers to draw

nut.util.drawBlurAt (x, y, w, h, amount, passes)
nut.util.drawBlurAt

Draws a blurred background at a given screen rectangle. Automatically uses a cheaper fallback if the nut_cheapblur convar is enabled.

Parameters:

integer x X-coordinate

integer y Y-coordinate

integer w Width of the blur region

integer h Height of the blur region

number amount optional. default: 5 The intensity of the blur

number passes optional. default: 0.2 How many blur layers to draw

Drawing Utilities

Provides helper functions for text rendering and resolution tracking in NutScript.

nut.util.drawText (text, x, y, color, alignX, alignY, font, alpha)
nut.util.drawText

Draw a text with a shadow.

Parameters:

string text The string to draw

integer x X-position

integer y Y-position

Color color Text color (defaults to white)

integer alignX optional. default: 0 Horizontal alignment (0 = left, 1 = center, 2 = right)

integer alignY optional. default: 0 Vertical alignment (0 = top, 1 = center, 2 = bottom)

string font optional. default: "nutGenericFont" Font to use

number alpha optional Override alpha value

Returns:

number Width of the drawn text

nut.util.wrapText (text, width, font)
nut.util.wrapText

Wraps text so it does not pass a certain width.

Parameters:

string text The string to wrap

number width Maximum line width in pixels

string font optional. default: "nutChatFont" Font used to measure width

Returns:

table Array of wrapped lines

number Maximum line width

Notification Utilities

Handles localized and plain chat notifications sent from the server or generated locally.

nut.util.notify (message)
nut.util.notify

Displays a plain chat message.

Parameters:

string message The message to display

nut.util.notifyLocalized (message, ...)
nut.util.notifyLocalized

Creates a translated notification.

Parameters:

string message The localization key

vararg ... Optional arguments to insert into the message

nut.util.notify (message, recipient)
nut.util.notify

Sends a plain text notification to a player or broadcasts it.

Parameters:

string message The message to display

vararg recipient optional A single player, table of players, or nil to broadcast

nut.util.notifyLocalized (message, recipient, ...)
nut.util.notifyLocalized

Sends a localized message to a player or broadcasts it. Accepts optional arguments for translation.

Parameters:

string message The localization key

vararg recipient optional A single player, table of players, or nil to broadcast

vararg ... Optional translation arguments

Queued Sound Utility

Plays a sequence of sounds from an entity with optional delay and timing control.

nut.util.emitQueuedSounds (entity, sounds, delay, spacing, volume, pitch)
nut.util.emitQueuedSounds

Plays a sequence of sounds from an entity with optional spacing, volume, and pitch. Accepts tables of sounds with optional time offsets.

Parameters:

Entity entity The entity emitting the sounds

table sounds Array of sounds or sound tables {soundPath, postDelay, preDelay}

number delay optional. default: 0 Initial delay before the first sound

number spacing optional. default: 0.1 Spacing between sounds

number volume optional Sound volume

number pitch optional Sound pitch

Returns:

number Total time taken to emit all sounds

String Comparison Utility

Provides a helper to check for strict or loose matching between two strings.

nut.util.stringMatches (a, b)
nut.util.stringMatches

Returns whether two strings match strictly or loosely. Performs case-insensitive comparison and substring searching.

Parameters:

string a The first string

string b The second string

Returns:

bool True if the strings match

Time Utilities

Provides utilities for parsing, formatting, and comparing time values.

nut.util.getUTCTime ()
nut.util.getUTCTime

Gets the current time in the UTC time-zone.

Returns:

int UTC time offset in seconds

nut.util.getStringTime (text)
nut.util.getStringTime

Gets the amount of seconds from a given formatted string. Example: 5y2d7w = 5 years, 2 days, and 7 weeks. If just given a minute, it is assumed minutes.

Parameters:

string text The time string to parse

Returns:

int The number of seconds represented

nut.util.dateToNumber (str)
nut.util.dateToNumber

Parses a timestamp string into a date table. Uses the current timestamp if none is provided.

Parameters:

string str optional Timestamp in format "%Y-%m-%d %H:%M:%S"

Returns:

table Table with year, month, day, hour, min, sec keys

Ragdoll utilities

Provides a function to locate an empty viable space around an entity. Used, for instance, when a player ragdoll is removed and the player entity's position must be appropriately placed.

nut.util.findEmptySpace (entity, filter, spacing, size, height, tolerance)
nut.util.findEmptySpace

Attempts to find empty positions around an entity. Checks a grid and returns sorted viable positions.

Parameters:

Entity entity The entity to start from

vararg filter optional Filter to exclude from traces

number spacing optional. default: 32 Distance between grid points

number size optional. default: 3 Grid radius to search

number height optional. default: 36 Height of bounding box

number tolerance optional. default: 5 Z tolerance for ground check

Returns:

table Array of viable positions