Library builtin

Built in values. These can be found in the global table.

Functions

Angle( p, y, r ) Creates a new angle object.
CRC( string ) Returns a CRC32 value of the given string.
Color( r, g, b, a ) Provides a new colour object.
GetTypeDef( name ) Returns a table which you can add new methods for the given type to.
HSVToColor( h, s, v, a ) Returns a colour object from the given HSV values
IsValid( object ) Returns true if the passed in value is not nil, has an "isValid" method and that method returns true.
Material( path, option ) Returns a new IMaterial from the given path.
Matrix( data ) Creates a new VMatrix.
Mesh( materialHint ) Creates a new IMesh object to hold static mesh data.
Quaternion( real, i, j, k ) Creates a quaternion from the given components.
Vector( x, y, z ) Creates a new vector object.
Vector2( x, y ) Creates a new 2D vector.
assert( condition, msg ) Throws an error if the condition parameter is not truthy.
compileString( code, name, env ) Compiles the given string and returns it as a function, or nil and a string if there is a syntax error.
cpuAverage( addTimeSeconds ) Gets the average CPU time for the current instance, used for the average CPU time quota.
cpuGlobalTime( currentInstanceAverageTimeSeconds ) Returns the global CPU time usage across all chips on the server in seconds.
cpuMax() Gets the CPU time hard quota.
cpuTime() Gets the amount of time spent running this frame/tick.
doAll() Runs every file you included.
dofile( file ) Runs an --@include'd file and returns the result.
error( message, level ) Throws an error, halting execution.
getLibraries() Gets a list of all libraries
getScripts() Returns every included script file in a table of filepath -> function pairs.
getfenv() Gets the current function environment.
getmetatable( table ) Retrieves the metatable of the given table, or the value of the __metatable field on its metatable if the metatable is locked.
hint( message, type, duration ) Shows a gamemode hint to the chip owner.
ipairs( table ) Provides a sequential iterator for tables.
load( code, name, env ) Compiles the given string and returns it as a function, or nil and a string if there is a syntax error.
loadfile( file ) Returns a function representing the given file which can be invoked with arguments.
loadstring( code, name, env ) Compiles the given string and returns it as a function, or nil and a string if there is a syntax error.
localToWorld( localPos, localAng, originPos, originAng ) Converts a local space vector into a world space vector.
next( table, key ) Provides the next key-value pair in the given table.
pairs( table ) Provides an iterator that visits every key-value pair in the table once, with no guarantee for the order in which they are visited.
pcall( func, ... ) Runs the given function and catches any errors.
print( ... ) Prints a message to the player's chat.
printColor( ... ) Prints a message to the chip owner's chat in colour.
printConsole( ... ) Prints a message to your console.
rawequal( v1, v2 ) Determines if two values are equal without using either value's __eq metamethod.
rawget( table, key ) Retrives a value from the given table without inspecting __index.
rawset( table, key, value ) Sets a value on the given table without triggering __newindex.
require( file ) Runs an --@include'd script and caches the result.
requireAll() Requires every file you included that has not already been run.
select( index, vararg ) Selects values from a vararg.
setName( name ) Changes the name of the chip.
setfenv( func, table ) Sets the function environment for the given function.
setmetatable( table, metatable ) Sets a metatable on the given table, providing its metatable is not locked.
showOverlay( show ) Sets whether to show the overlay with the chip name, CPU time etc.
tonumber( object ) Converts the given value into its number representation.
tostring( object ) Converts the given value into its string representation.
type( value ) Provides the name of the type of the given object.
unpack( table, index, endIndex ) Unpacks the values in the given table into individual return values.
worldToLocal( position, angle, newSystemOrigin, newSystemAngles ) Converts a world space vector into a local space vector.
xpcall( func, callback, ... ) Runs the given function and calls the given callback function on error.

Fields

CLIENT Constant that denotes whether the code is executed on the client.
SERVER Constant that denotes whether the code is executed on the server.
NOTIFY_GENERIC NOTIFY_GENERIC for hint()
NOTIFY_ERROR NOTIFY_ERROR for hint()
NOTIFY_HINT NOTIFY_HINT for hint()


Functions

_G.Angle( p, y, r )
Creates a new angle object. Omitting the components will default them to 0.

Environment:

Shared

Parameters:

  • (number | Angle?) p: Initial value of the pitch component, or an angle to copy.
  • (number?) y: Initial value of the yaw component.
  • (number?) r: Initial value of the roll component.

Return value:

    (Angle) A new angle object with the given initial components.
_G.CRC( string )
Returns a CRC32 value of the given string.

Environment:

Shared

Parameters:

  • string: The string to compute the CRC32 value for.

Return value:

    (string) The CRC32 value as a string.
_G.Color( r, g, b, a )
Provides a new colour object. All values should be between 0 and 255.

Environment:

Shared

Parameters:

  • r: Initial red value.
  • g: Initial green value.
  • b: Initial blue value.
  • a: (Optional) Initial alpha value, defaults to 255.

Return value:

    (Color) A new colour object with r, g, b, a fields.
_G.GetTypeDef( name )
Returns a table which you can add new methods for the given type to.

Deprecated: Use starfall.getTypeDef() instead.

Environment:

Shared

Parameters:

  • name: The name of the type you want to extend, e.g "Entity".

Return value:

    (table) If the type exists, then a table which you can add methods to. Otherwise nil.
_G.HSVToColor( h, s, v, a )
Returns a colour object from the given HSV values

Deprecated: Use Color.fromHSV() instead.

Environment:

Shared

Parameters:

  • h: Hue, 0 - 1
  • s: Saturation, 0 - 1
  • v: Value, 0 - 1
  • a: (Optional) Alpha value, defaults to 255.

Return value:

    (Color) A new Color object with values converted into RGB from HSV.
_G.IsValid( object )
Returns true if the passed in value is not nil, has an "isValid" method and that method returns true.

Environment:

Shared

Parameters:

  • object: The object to check for validity.

Return value:

    (boolean) True if the object is "valid", false otherwise.
_G.Material( path, option )
Returns a new IMaterial from the given path. Note that materials with a shader that is not UnlitGeneric will not render correctly in 2D contexts like screens and HUDs. For such materials, use render.getTextureID( path ) to get an unlit version.

Environment:

Client

Parameters:

  • path: The path to the material (excluding materials/).
  • option: If a PNG file, then any combination (separated by spaces) of: - vertexlitgeneric - unlitgeneric - nocull - alphatest - mips - noclamp - smooth

Usage:

    -- Load a PNG material, setting the "noclamp" and "smooth" parameters. 
    local WaveMaterial = Material( "vgui/wave.png", "noclamp smooth" )

Return value:

    (IMaterial | nil) New IMaterial, or nil if the given path is invalid.
_G.Matrix( data )
Creates a new VMatrix.

Environment:

Shared

Parameters:

  • (table> | VMatrix?) data: A 4x4 table of values to initialise the matrix with, or a VMatrix to copy.

Usage:

    local Values = { 
    	{ 1, 0, 0, 4 }, 
    	{ 0, 2, 0, 5 }, 
    	{ 0, 0, 3, 6 }, 
    	{ 0, 0, 0, 1 } 
    } 
    local NewMatrix = Matrix( Values ) 
    local Copy = Matrix( NewMatrix )

Return value:

    (VMatrix) A new VMatrix object with the given initial values, or otherwise the identity matrix.
_G.Mesh( materialHint )
Creates a new IMesh object to hold static mesh data.

Environment:

Client

Parameters:

  • materialHint: (Optional) An IMaterial that the mesh will be used with. Provides a hint for the mesh's internal format.

Return value:

    (IMesh) New IMesh.
_G.Quaternion( real, i, j, k )
Creates a quaternion from the given components.

Environment:

Shared

Parameters:

  • real: The real part.
  • i: The i component.
  • j: The j component.
  • k: The k component.

Return value:

    (Quaternion) A quaternion with the given components.
_G.Vector( x, y, z )
Creates a new vector object. Omitting the components will default them to 0.

Environment:

Shared

Parameters:

  • (number | Vector?) x: Initial value of the x component, or a vector to copy.
  • (number?) y: Initial value of the y component.
  • (number?) z: Initial value of the z component.

Return value:

    (Vector) A new vector object with the given initial components.
_G.Vector2( x, y )
Creates a new 2D vector.

Environment:

Server

Parameters:

  • (Vector2 | Vector | number?) x: The x coordinate to initialise the vector with if a number, or the vector to copy values from.
  • (number?) y: The y coordinate to initialise the vector with (ignored if X is a vector).

Return value:

    (Vector2) A new 2D vector with the given initial components, or (0, 0) if no components are given.
_G.assert( condition, msg )
Throws an error if the condition parameter is not truthy. Returns the condition parameter otherwise.

Environment:

Shared

Parameters:

  • condition: Condition that evaluates to true on success, and false-y on failure.
  • msg: Error value to throw if the condition value is false-y.

Return value:

    (%1) The condition value provided, if it is not false-y.
_G.compileString( code, name, env )
Compiles the given string and returns it as a function, or nil and a string if there is a syntax error.

Deprecated: Use load.

Environment:

Shared

Parameters:

  • (string) code: Lua code string to compile.
  • (string?) name: (Optional) Name to assign to the chunk.
  • (table?) env: (Optional) Environment to assign to the chunk.

Return values:

  1. (function | nil) Compiled function, or nil if compilation failed.
  2. (string) An error string if there's a syntax error.
_G.cpuAverage( addTimeSeconds )
Gets the average CPU time for the current instance, used for the average CPU time quota. This value represents a moving average over previous frames/ticks and is not updated in real time.

Environment:

Shared

Parameters:

  • (number?) addTimeSeconds: If provided, the returned time will assume this many additional seconds will be used up this tick/frame (e.g. pass cpuTime() to predict the average including this frame/tick).

Return value:

    (number) Current average CPU time in seconds.
_G.cpuGlobalTime( currentInstanceAverageTimeSeconds )
Returns the global CPU time usage across all chips on the server in seconds. This is used to calculate the global CPU quota.

Environment:

Server

Parameters:

  • (number?) currentInstanceAverageTimeSeconds: If provided, the returned time will assume the current instance has this many seconds as its average CPU time.
_G.cpuMax()
Gets the CPU time hard quota. If cpuGlobalTime(), cpuAverage() or cpuTime() exceed this value, the instance may be halted.

Environment:

Shared

Return value:

    (number) Quota in seconds.
_G.cpuTime()
Gets the amount of time spent running this frame/tick. This value is updated in real time.

Environment:

Shared

Return value:

    (number) Current execution CPU time in seconds since the last frame/tick.
_G.doAll()
Runs every file you included. Be careful with files that only belong on the server/client, it won't discriminate. Note that this does not load asynchronously included scripts that have not yet been downloaded. Those must be loaded with dofile().

Environment:

Shared

Return value:

    (table) A table of file name => returned value for every script executed.
_G.dofile( file )
Runs an --@include'd file and returns the result. If the file was included asynchronously this will first download the file and yield until it's available. Thus for asynchronous includes, this must be called within a coroutine, the main file, or a file that is loaded by the main file.

Environment:

Shared

Parameters:

  • file: The filename to execute, must have been included.

Return value:

    The return value of the executed file, not cached.
_G.error( message, level )
Throws an error, halting execution. If the current line is not executing within pcall/xpcall, this will terminate the running instance.

Environment:

Shared

Parameters:

  • message: The error message/object. This can be any value, but is normally a string.
  • (number) level: The level at which the error should originate from, where 1 is the current level, 2 is the caller and so on.
_G.getLibraries()
Gets a list of all libraries

Deprecated: Use starfall.getLibraries() instead.

Environment:

Shared

Return value:

    (table) A table containing the names of all available libraries.
_G.getScripts()
Returns every included script file in a table of filepath -> function pairs. Call a function to run the file in the same way as dofile().

Deprecated: Use starfall.getScripts() instead.

Environment:

Shared

Return value:

    (table) Table of filepath -> function pairs.
_G.getfenv()
Gets the current function environment.

Environment:

Shared

Return value:

    (table) Environment table of the current function.
_G.getmetatable( table )
Retrieves the metatable of the given table, or the value of the __metatable field on its metatable if the metatable is locked.

Environment:

Shared

Parameters:

  • table: Table to get the metatable of.

Return value:

    (table | nil) The metatable assigned to the given table if not locked, the __metatable field on the table's metatable if locked, or nil if the table has no metatable.
_G.hint( message, type, duration )
Shows a gamemode hint to the chip owner.

Environment:

Shared

Parameters:

  • message: The string message to display.
  • type: The type of message, one of NOTIFY_GENERIC, NOTIFY_ERROR or NOTIFY_HINT.
  • duration: How long to show the message for.
_G.ipairs( table )
Provides a sequential iterator for tables.

Environment:

Shared

Parameters:

  • table: Table to iterate in order starting at index 1.
_G.load( code, name, env )
Compiles the given string and returns it as a function, or nil and a string if there is a syntax error. This function can also accept a mode parameter to be compatible with Lua 5.2+, but only "t" or "bt" are accepted ("bt" is treated as "t" as bytecode loading is not permitted).

Environment:

Shared

Parameters:

  • (string) code: Lua code string to compile.
  • (string?) name: (Optional) Name to assign to the chunk.
  • (table?) env: (Optional) Environment to assign to the chunk.

Return values:

  1. (function | nil) Compiled function, or nil if compilation failed.
  2. (string) An error string if there's a syntax error.
_G.loadfile( file )
Returns a function representing the given file which can be invoked with arguments. If the file was included asynchronously this will first download the file and yield until it's available. Thus for asynchronous includes, this must be called within a coroutine, the main file, or a file that is loaded by the main file.

Environment:

Shared

Parameters:

  • (string) file: The filename to load.

Return values:

  1. (function | nil) The loaded script file as a function, or nil if it cannot be loaded.
  2. (string) If the file could not be loaded, the reason why.
_G.loadstring( code, name, env )
Compiles the given string and returns it as a function, or nil and a string if there is a syntax error.

Deprecated: Use load.

Environment:

Shared

Parameters:

  • (string) code: Lua code string to compile.
  • (string?) name: (Optional) Name to assign to the chunk.
  • (table?) env: (Optional) Environment to assign to the chunk.

Return values:

  1. (function | nil) Compiled function, or nil if compilation failed.
  2. (string) An error string if there's a syntax error.
_G.localToWorld( localPos, localAng, originPos, originAng )
Converts a local space vector into a world space vector.

Environment:

Shared

Parameters:

  • localPos: Local position.
  • localAng: Local angle.
  • originPos: Co-ordinate system origin.
  • originAng: Angles the system translates from.
_G.next( table, key )
Provides the next key-value pair in the given table. Note that the meaning of next has no guaranteed order.

Environment:

Shared

Parameters:

  • table: Table to get the next key-value pair of.
  • key: (Optional) The key to start at.

Return values:

  1. (%1=table<1>) The next key after the one provided.
  2. (%1=table<2>) The value at the next key.
_G.pairs( table )
Provides an iterator that visits every key-value pair in the table once, with no guarantee for the order in which they are visited.

Environment:

Shared

Parameters:

  • table: Table to iterate.
_G.pcall( func, ... )
Runs the given function and catches any errors. Returns true, return values on success, false, error on fail.

Environment:

Shared

Parameters:

  • func: Function to run.
  • ...: Arguments to pass to Func when calling.

Usage:

    local function MyAwesomeFunc( ... ) 
    	print( "Thanks for", ... ) 
    end 
    local Success, Err = pcall( MyAwesomeFunc, "cake", "cookies", "milk" )

Return values:

  1. (boolean) true if execution succeeded without error, false otherwise.
  2. (Any...) If execution failed, the error message. Otherwise, all returned values from the function.
_G.print( ... )
Prints a message to the player's chat. Limited to 254 characters on the server.

Environment:

Shared

Parameters:

  • ...:
_G.printColor( ... )
Prints a message to the chip owner's chat in colour.

Environment:

Shared

Parameters:

  • ...:

Usage:

    printColor( Color( 255, 0, 0 ), "This text is in red! ", 
    	Color( 255, 255, 255 ), "This text is in white!" )
_G.printConsole( ... )
Prints a message to your console. Limited to 254 characters on the server.

Environment:

Shared

Parameters:

  • ...:
_G.rawequal( v1, v2 )
Determines if two values are equal without using either value's __eq metamethod.

Environment:

Shared

Parameters:

  • v1: First value to compare.
  • v2: Second value to compare.

Return value:

    (boolean) True if both values are equal, ignoring __eq. False otherwise.
_G.rawget( table, key )
Retrives a value from the given table without inspecting __index. This does not work on library tables or locked types.

Environment:

Shared

Parameters:

  • table: The table to get the value from.
  • key: The key to get from the table.

Return value:

    (%1=table<2>) The value stored on the table, ignoring the __index metamethod.
_G.rawset( table, key, value )
Sets a value on the given table without triggering __newindex. This does not work on library tables or locked types.

Environment:

Shared

Parameters:

  • table: the table to set the value on.
  • key: The key to write to.
  • value: The value to write.
_G.require( file )
Runs an --@include'd script and caches the result. If the file was included asynchronously this will first download the file and yield until it's available. Thus for asynchronous includes, this must be called within a coroutine, the main file, or a file that is loaded by the main file.

Environment:

Shared

Parameters:

  • file: The filename to execute, must have been included.

Return value:

    The return value of the executed file, cached if it has already been required.
_G.requireAll()
Requires every file you included that has not already been run. Be careful with files that only belong on the server/client, it won't discriminate. Note that this does not load asynchronously included scripts that have not yet been downloaded. Those must be loaded with require().

Environment:

Shared

Return value:

    (table) A table of file name => returned value for every script that has been required (whether they were loaded previously or not).
_G.select( index, vararg )
Selects values from a vararg.

Environment:

Shared

Parameters:

  • index: Index to start at, or "#" to get the size of the vararg.
  • vararg: Vararg to retrieve value/size from.

Return value:

    (number | Any...) The values starting at the given index until the end of the vararg, or the size of the vararg if "#" was the index.
_G.setName( name )
Changes the name of the chip.

Deprecated: Use starfall.setName() instead.

Environment:

Shared

Parameters:

  • name: The name to use.
_G.setfenv( func, table )
Sets the function environment for the given function. Essentially changes the global scope to the table you pass in.

Environment:

Shared

Parameters:

  • func: The function to set the environment for.
  • table: The function environment table to set.

Usage:

    local FEnv = { Cake = "great!", print = print } 
    local function MyAwesomeFunc() 
    	print( Cake ) 
    end 
    setfenv( MyAwesomeFunc, FEnv ) 
    MyAwesomeFunc() --Prints "great!"
_G.setmetatable( table, metatable )
Sets a metatable on the given table, providing its metatable is not locked.

Environment:

Shared

Parameters:

  • table: Table to assign the metatable of.
  • metatable: Table to set as the metatable.

Return value:

    (table) The passed in table.
_G.showOverlay( show )
Sets whether to show the overlay with the chip name, CPU time etc.

Deprecated: Use starfall.showOverlay() instead.

Environment:

Client

Parameters:

  • show: Whether to show the overlay.
_G.tonumber( object )
Converts the given value into its number representation.

Environment:

Shared

Parameters:

  • object: Object to be converted to a number.

Return value:

    (number) The object as a number, or nil if it cannot be converted.
_G.tostring( object )
Converts the given value into its string representation.

Environment:

Shared

Parameters:

  • object: Object to be converted to a string.

Return value:

    (string) The object as a string, never nil.
_G.type( value )
Provides the name of the type of the given object.

Environment:

Shared

Parameters:

  • value: Value to retrieve the type of.

Return value:

    (string) The type name for the given object, e.g. "string", "number" etc.
_G.unpack( table, index, endIndex )
Unpacks the values in the given table into individual return values. This is the same as the table.unpack() function.

Environment:

Shared

Parameters:

  • (table) table: Table to unpack into a vararg.
  • (number?) index: The index to start unpacking from (default = 1).
  • (number?) endIndex: The index to finish unpacking at (default = #table).

Return value:

    (Any...) A value per entry in the table unpacked.
_G.worldToLocal( position, angle, newSystemOrigin, newSystemAngles )
Converts a world space vector into a local space vector.

Environment:

Shared

Parameters:

  • position: World position.
  • angle: World angle.
  • newSystemOrigin: System origin.
  • newSystemAngles: System angles.
_G.xpcall( func, callback, ... )
Runs the given function and calls the given callback function on error.

Environment:

Shared

Parameters:

  • func: Function to run.
  • callback: Function to run on error. It's passed the error and executed before the stack unwinds, allowing for accurate tracebacks. The returned value is used as the final error result.
  • ...: Optional arguments to pass to the provided function when calling.

Usage:

    local function ErrorHandler( Error ) 
    	-- Here the stack is yet to unwind, so the traceback points at the exact line the error occurred. 
    	-- The value returned here will be output as the second returned value from xpcall. 
    	return debug.traceback( Error ) 
    end 
    local function MyAwesomeFunc( ... ) 
    	print( "Thanks for", ... ) 
    end 
    local Success, Err = xpcall( MyAwesomeFunc, ErrorHandler, "cake", "cookies", "milk" ) 
    if not Success then 
    	-- Err will include an accurate traceback here due to returning debug.traceback() in the error handler. 
    	print( "Failed with error:", Err ) 
    end

Return values:

  1. (boolean) true if execution succeeded without error, false otherwise.
  2. (Any...) If execution failed, the error message. Otherwise, all returned values from the function.

Valid XHTML 1.0!