Built in values. These can be found in the global table.
| 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. |
- _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:
- _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:
-
(function | nil)
Compiled function, or nil if compilation failed.
-
(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:
-
(function | nil)
Compiled function, or nil if compilation failed.
-
(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:
-
(function | nil)
The loaded script file as a function, or nil if it cannot be loaded.
-
(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:
-
(function | nil)
Compiled function, or nil if compilation failed.
-
(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=table<1>)
The next key after the one provided.
-
(%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:
- _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:
-
(boolean)
true if execution succeeded without error, false otherwise.
-
(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:
- _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:
-
(boolean)
true if execution succeeded without error, false otherwise.
-
(Any...)
If execution failed, the error message. Otherwise, all returned values from the function.