Globals

scripts/vscripts/alyxlib/globals.lua

Global variables

Name	Value
AlyxLibAddons	table

Functions

RegisterAlyxLibAddon

Registers an addon with AlyxLib.

RegisterAlyxLibAddon(name, version, workshopID, shortName, minAlyxLibVersion, maxAlyxLibVersion)

Parameters

• name
string
  Full display name of the addon, e.g. "My New Addon"
• version
string
  SemVer version string of the addon, e.g. "v1.2.3"
• workshopID (optional)
  string
  The ID of the addon on the Steam workshop
• shortName (optional)
  string
  Short unique name of the addon without spaces, e.g. "myaddon". Defaults to name without spaces and converted to lowercase
• minAlyxLibVersion (optional)
  string
  Minimum AlyxLib version that this addon works with, defaults to "v1.0.0"
• maxAlyxLibVersion (optional)
  string
  Maximum AlyxLib version that this addon works with, defaults to ALYXLIB_VERSION

Returns - integer The index of the addon for use in other AlyxLib functions

RegisterAlyxLibDiagnostic

Registers a diagnostic function for an addon to help users describe issues back to the developer.

The diagnostic function should return two values:

• true if the addon is working as expected, false otherwise

• An array of strings or a string containing diagnostic messages

Common AlyxLib and game information will be printed alongside the diagnostic messages for users to copy.

RegisterAlyxLibDiagnostic(addonIndex, func)

Parameters

• addonIndex
integer
  The index of the addon for use in other AlyxLib functions
• func
function
  Diagnostic function to check if the addon is working, and any diagnostic messages

CompareVersions

Compares two semantic version strings and returns an integer indicating their relative order.

It compares the versions based on their major, minor, and patch components. If a version is incomplete, the missing components are assumed to be 0.

• -1 if v1 is older than v2.

• 1 if v1 is newer than v2.

• 0 if both versions are equal.

CompareVersions(v1, v2)

Parameters

• v1
string
  The first version string to compare. May include leading "v" and whitespace, and may have missing minor or patch components
• v2
string
  The second version string to compare. Similar format and rules to v1

Returns - -1|0|1

GetScriptFile

Gets the file name of the current script without folders or extension. E.g. util.util

GetScriptFile(sep, level)

Parameters

• sep (optional)
  string
  Separator character (default: .)
• level (optional)
  integer, function
  Function level, View documents

Returns - string File name

GetEnabledAddons

Gets the list of enabled addons from the default_enabled_addons_list convar.

GetEnabledAddons()

Returns - string[] List of enabled addons

IsAddonEnabled

Checks if the addon with the given workshopID is enabled.

IsAddonEnabled(workshopID)

Parameters

• workshopID
string
  The workshop ID of the addon

Returns - boolean true if the addon is enabled, false otherwise

IsEntity

Checks if the given handle value is an entity, regardless of if it's still alive.

A common usage is replacing the often used entity check:

Example

if entity ~= nil and IsValidEntity(entity) then

With:

Example

if IsEntity(entity, true) then

IsEntity(value, checkValidity)

Parameters

• value
EntityHandle, any
  The value to check
• checkValidity (optional)
  boolean
  Optionally check validity with IsValidEntity

Returns - boolean

AddOutput

Adds an output to a given entity.

AddOutput(entity, output, target, input, parameter, delay, activator, caller, fireOnce)

Parameters

• entity
EntityHandle, string
  The entity to add the output to
• output
string
  The output name to add
• target
EntityHandle, string
  The entity the output should target, either handle or targetname
• input
string
  The input name on target
• parameter (optional)
  string
  The parameter override for input (default: "")
• delay (optional)
  number
  Delay for the output in seconds (default: 0)
• activator (optional)
  EntityHandle
  Activator for the output (default: nil)
• caller (optional)
  EntityHandle
  Caller for the output (default: nil)
• fireOnce (optional)
  boolean
  If the output should only fire once (default: false)

module_exists

Checks if the module/script exists.

module_exists(name)

Parameters

• name (optional)
  string
  Name of the module

Returns - boolean true if the module exists, false otherwise

ifrequire

Loads the given module, returns any value returned by the given module(true when module returns nothing).

Then runs the given callback function.

If the module fails to load then the callback is not executed and no error is thrown, but a warning is displayed in the console.

ifrequire(modname, callback)

Parameters

• modname
string
  Name of the module/script
• callback
function?
  Callback function

Returns - unknown|nil The value returned by the module, or nil if the module fails to load

IncludeScript

Executes a script file. Included in the current scope by default.

IncludeScript(scriptFileName, scope)

Parameters

• scriptFileName
string
  Name of the script
• scope (optional)
  ScriptScope
  Scope to include the script in

Returns - boolean true if the script was successfully included, false otherwise

IsVREnabled

Checks if the game was started in VR mode.

IsVREnabled()

Returns - boolean true if the game was started in VR mode, false otherwise

prints

Prints all arguments with spaces between instead of tabs.

prints(...)

Parameters

• ...

printn

Prints all arguments on a new line instead of tabs.

printn(...)

Parameters

• ...

devprint

Prints all arguments if convar "developer" is greater than 0.

devprint(...)

Parameters

• ...

devprints

Prints all arguments on a new line instead of tabs if convar "developer" is greater than 0.

devprints(...)

Parameters

• ...

devprintn

Prints all arguments with spaces between instead of tabs if convar "developer" is greater than 0.

devprintn(...)

Parameters

• ...

devprint2

Prints all arguments if convar "developer" is greater than 1.

devprint2(...)

Parameters

• ...

devprints2

Prints all arguments on a new line instead of tabs if convar "developer" is greater than 1.

devprints2(...)

Parameters

• ...

devprintn2

Prints all arguments with spaces between instead of tabs if convar "developer" is greater than 1.

devprintn2(...)

Parameters

• ...

warn

Prints a warning in the console, along with a vscript print if inside tools mode.

warn(...)

Parameters

• ...

devwarn

Prints a warning in the console, along with a vscript print if inside tools mode. But only if convar "developer" is greater than 0.

devwarn(...)

Parameters

• ...

Expose

Add a function to the calling entity's script scope with alternate casing.

Makes a function easier to call from Hammer through I/O.

E.g.

Example

local function TriggerRelay(io)
    DoEntFire("my_relay", "Trigger", "", 0, io.activator, io.caller)
end
Expose(TriggerRelay)

-- Or with alternate name
Expose(TriggerRelay, "RelayInput")

Expose(func, name, scope)

Parameters

• func
function
  The function to expose
• name (optional)
  string
  Optionally the name of the function for faster processing
• scope (optional)
  table
  Optionally the explicit scope to put the exposed function in

IsVector

Checks if a value is a Vector.

IsVector(value)

Parameters

• value
any
  Value to check

Returns - boolean true if the value is a Vector, false otherwise

IsQAngle

Checks if a value is a QAngle.

IsQAngle(value)

Parameters

• value
any
  Value to check

Returns - boolean true if the value is a QAngle, false otherwise

DeepCopyTable

Copy all keys from tbl and any nested tables into a brand new table and return it. This is a good way to get a unique reference with matching data.

Any functions and userdata will be copied by reference, except for: Vector, QAngle

DeepCopyTable(tbl)

Parameters

• tbl
table
  Table to copy

Returns - table A copy of tbl

TableRemove

Searches for value in tbl and sets the associated key to nil, returning the key if found.

If your table is an array you should use ArrayRemove instead.

TableRemove(tbl, value)

Parameters

• tbl
table
  Table to search
• value
any
  Value to search for

Returns - any The key of value if found, nil otherwise

TableRandom

Returns a random key/value pair from a unordered table.

TableRandom(tbl)

Parameters

• tbl
table
  Table to get a random pair from

Returns

• any
key
  Random key selected

• any
value
  Value linked to the random key

TableKeys

Returns all keys of a table as a new ordered array.

TableKeys(tbl)

Parameters

• tbl
table<K,any>
  Table to get keys from

Returns - K[] List of keys

TableValues

Returns all values in a table as a new ordered array.

TableValues(tbl)

Parameters

• tbl
table<any,V>
  Table to get values from

Returns - V[] List of values

TableSize

Returns the size of a table by counting all keys.

TableSize(tbl)

Parameters

• tbl
table
  The table to count

Returns - number The size of the table

TablePluck

Collects all values for a specific key from a list of tables.

TablePluck(tbl, key)

Parameters

• tbl
table[]
  List of tables
• key
any
  Key to get values from

Returns - any[] List of values found for key

TableFindKey

Returns the key of the first value that matches the predicate.

TableFindKey(tbl, predicate)

Parameters

• tbl
table
  Table to search
• predicate
function
  Predicate function

Returns - any Key of the first value that matches the predicate

ArrayRandom

Returns a random value from an array.

ArrayRandom(array, min, max)

Parameters

• array
T[]
  Array to get a value from
• min (optional)
  integer
  Optional minimum bound
• max (optional)
  integer
  Optional maximum bound

Returns

• T
one
  The random value

• integer
two
  The random index

ArrayShuffle

Shuffles a given array in-place.

ArrayShuffle(array)

Parameters

• array
any[]
  Array to shuffle

ArrayRemove

Remove an item from an array at a given position.

This is exponentially faster than table.remove for large arrays.

ArrayRemove(array, pos)

Parameters

• array
T
  The array to remove from
• pos
integer
  Position to remove at

Returns - T The same array passed in

ArrayRemoveVal

Remove a value from an array.

This is exponentially faster than table.remove for large arrays.

ArrayRemoveVal(array, value)

Parameters

• array
T
  The array to remove from
• value
any
  The value to remove

Returns - T The same array passed in

ArrayAppend

Appends array2 onto array1 as a new array.

Safe extend function alternative to vlua.extend, neither input arrays are modified.

ArrayAppend(array1, array2)

Parameters

• array1
T1[]
  Base array
• array2
T2[]
  Array which will be appended onto the base array

Returns - T1[]|T2[] The new appended array

ArrayAppends

Appends any number of arrays onto array as a new array object.

Safe extend function alternative to vlua.extend, no input arrays are modified.

ArrayAppends(array)

Parameters

• array
T[]
  Base array

Returns - T[] The new appended array

TraceLineExt

Does a raytrace along a line with extended parameters. You ignore multiple entities as well as classes and names. Because the trace has to be redone multiple times, a timeout parameter can be defined to cap the number of traces.

TraceLineExt(parameters)

Parameters

• parameters
TraceTableLineExt
  Trace parameters

Returns - boolean true if the trace was successful

TraceLineWorld

Does a raytrace along a line until it hits the world or reaches the end of the line.

TraceLineWorld(parameters)

Parameters

• parameters
TraceTableLine
  Trace parameters

Returns - TraceTableLine Trace parameters with results

TraceLineEntity

Does a raytrace along a line until it hits the specified entity or reaches the end of the line.

TraceLineEntity(parameters)

Parameters

• parameters
TraceTableLine
  Trace parameters

Returns - TraceTableLine Trace parameters with results

TraceLineSimple

Performs a simple line trace and returns the trace table.

TraceLineSimple(startpos, endpos, ignore, mask)

Parameters

• startpos
Vector
  Start position
• endpos
Vector
  End position
• ignore (optional)
  EntityHandle
  Entity to ignore
• mask (optional)
  integer
  Trace mask

Returns - TraceTableLine Trace table with results

IsWorld

Checks if an entity is the world entity.

IsWorld(entity)

Parameters

• entity
EntityHandle
  Entity to check

Returns - boolean true if the entity is the world entity, false otherwise

GetWorld

Gets the world entity.

GetWorld()

Returns - EntityHandle World entity

IsPhysicsObject

Checks if an entity is a physical entity.

IsPhysicsObject(entity)

Parameters

• entity
EntityHandle
  Entity to check

Returns - boolean true if the entity is a physical entity, false otherwise

haskey

Checks if a table has a key (this essentially the same as tbl[key] ~= nil).

haskey(tbl, key)

Parameters

• tbl
table
  Table to check
• key
any
  Key to look for

Returns - boolean true if the table has the key, false otherwise

truthy

Checks if a value is truthy or falsy.

falsy == nil|false|0|""|{}

truthy(value)

Parameters

• value
any
  The value to be checked

Returns - boolean true if the value is truthy, false otherwise

SearchEntity

Searches an entity for a key using a search pattern. E.g. "getclass" will find "GetClassname"

Works with class.lua EntityClass entities.

SearchEntity(entity, searchPattern)

Parameters

• entity
EntityHandle, EntityClass
  The entity to search
• searchPattern
string
  The name pattern to search for

Returns

• string?
key
  The full name of the first key matching searchPattern

• any?
value
  The value of the key found

LerpAngle

Linearly interpolates between two angles.

LerpAngle(t, angle_start, angle_end)

Parameters

• t
number
  The interpolation parameter, where 0 returns angle_start and 1 returns angle_end
• angle_start
number
  The starting angle in degrees
• angle_end
number
  The ending angle in degrees

Returns - number The interpolated angle

CalcClosestPointOnEntityOBBAdjusted

Calculates the closest point on an entity's OBB to a position.

This is a modified version of the original function that fixes off-center models not calculating correctly.

CalcClosestPointOnEntityOBBAdjusted(entity, position)

Parameters

• entity
EntityHandle
  The entity to calculate the closest point on
• position
Vector
  The position to calculate the closest point to

Returns - Vector The closest point on the entity's OBB to the position

DefaultTable

Assigns a default value to a table which will be returned if an invalid key is accessed.

DefaultTable(tbl, default)

Parameters

• tbl
T
  The table to which the default value will be assigned
• default
any
  The default value to be returned for invalid keys

Returns - T The table with the default value assigned

Wrap

Wraps a value within a specified range.

Wrap(value, min, max)

Parameters

• value
number
  The value to be wrapped
• min
number
  The minimum value of the range
• max
number
  The maximum value of the range

Returns - number The wrapped value within the specified range

CreateToggleBehavior

This function creates a toggle behavior function that switches between two provided functions based on a condition.

Example:

Example

local alphaToggle = CreateToggleBehavior(
    function(name)
        print(name .. "Alpha went below 50%")
    end,
    function(name)
        print(name .. "Alpha went above 50%")
    end
)

Example

thisEntity:SetThink("thinker", function()
    alphaToggle(thisEntity:GetRenderAlpha() < 128, thisEntity:GetName())
    return 0
end, 0)

CreateToggleBehavior(on, off)

Parameters

• on (optional)
  function
  Function called when the condition is true
• off (optional)
  function
  Function called when the condition is false

Returns - function The created toggle function

CalcClosestCornerOnEntityAABB

Computes the closest corner relative to a vector on the AABB of an entity.

CalcClosestCornerOnEntityAABB(entity, position)

Parameters

• entity
EntityHandle
  The entity to calculate the closest corner on
• position
Vector
  The vector to calculate the closest corner to

SetPhysVelocity

Sets the absolute world velocity of an entity.

SetPhysVelocity(velocity)

Parameters

• velocity
Vector
  The target velocity in units/second.

RandomChance

Returns one of two values based on a percentage chance.

If the random roll succeeds, returns onTrue (default: true). If it fails, returns onFalse (default: false).

RandomChance(chance, onTrue, onFalse)

Parameters

• chance
number
  The percentage chance of success (0-100)
• onTrue (optional)
  any
  Value to return if the chance succeeds (default: true)
• onFalse (optional)
  any
  Value to return if the chance fails (default: false)

Returns - boolean|any

Types

AlyxLibAddon

A registered AlyxLib addon.

Field	Type	Description
name	string	Full display name of the addon, e.g. My "New Addon"
version	string	SemVer version string of the addon, e.g. "v1.2.3"
shortName	string	Short unique name of the addon without spaces, e.g. "myaddon"
minAlyxLibVersion	string	Minimum AlyxLib version that this addon works with
maxAlyxLibVersion	string	Maximum AlyxLib version that this addon works with
workshopID?	string	The ID of the addon on the Steam workshop
diagnosticFunction?	function	Diagnostic function to check if the addon is working, and any diagnostic messages

TraceTableLineExt

Inherits from: TraceTableLine

Field	Type	Description
ignore	(EntityHandle|EntityHandle[])?	Entity or array of entities to ignore
ignoreclass	(string|string[])?	Class or array of classes to ignore
ignorename	(string|string[])?	Name or array of names to ignore
timeout	integer?	Maxmimum number of traces before returning regardless of parameters
traces	integer	Number of traces done
dontignore	EntityHandle	A single entity to always hit, ignoring if it exists in ignore