Library starfall

Starfall library. Used for introspection of the running instance.

Functions

Error( message, level ) Constructs a new Error object with the given message, capturing the traceback starting at the given level.
getAuthor( starfallEntity ) Provides the author of the given entity's instance.
getLibraries() Gets a list of all library names.
getMainFileName() Provides the name of the main file used to load the running script.
getName( starfallEntity ) Provides the current name of the given entity's instance.
getScripts() Returns every included script file in a table of filepath -> function pairs.
getSuperTypeOf( typeName ) Returns the name of the type the given type inherits from, if any.
getTypeDef( name ) Returns a table which you can add new methods for the given type to, if the type is extendable.
isInstanceOf( object, type ) Returns whether the given object is an instance of the given type.
isSpawnedFromDuplicator() Returns whether the current instance's entity spawned from a duplicator.
setName( name ) Changes the name of the running chip.
showOverlay( show ) Sets whether to show the overlay with the chip name, CPU time etc.


Functions

starfall.Error( message, level )
Constructs a new Error object with the given message, capturing the traceback starting at the given level. This is akin to a call to error(), but instead of throwing, the message and traceback are captured. If the returned error object is thrown with error() and left uncaught, its message and traceback will be shown in the editor, rather than the traceback from the point at which it was thrown.

Environment:

Shared

Parameters:

  • (Any) message: The message to store on the error (usually a string, but can be any value).
  • (number?) level: The stack level at which to start capturing the traceback (default = 1).

Usage:

    local function OnError( Err ) 
    	-- Capture the error as-is (level 0 won't add the source to the message), and its traceback. 
    	return starfall.Error( Err, 0 ) 
    end 
    -- Assume that ExampleFunction is some external function whose errors should be captured. 
    local Success, Err = xpcall( ExampleFunction, OnError ) 
    if not Success then 
    	-- Err is an Error type, with a recorded message and traceback. 
    	print( "Example operation failed:", Err:getMessage() ) 
    	print( Err:getTraceback() ) 
    	-- It can be thrown again to preserve the original traceback. 
    	error( Err ) 
    end

Return value:

    (Error) An Error object with the given message, capturing the traceback at the given level.
starfall.getAuthor( starfallEntity )
Provides the author of the given entity's instance.

Environment:

Shared

Parameters:

  • (Entity?) starfallEntity: (Optional) The entity to get the author of. If not provided, the entity executing this function will be used.

Return value:

    (string) The entity's Starfall author.
starfall.getLibraries()
Gets a list of all library names.

Environment:

Shared

Return value:

    (table) A table containing the names of all available libraries.
starfall.getMainFileName()
Provides the name of the main file used to load the running script.

Environment:

Shared

Return value:

    (string) The main file's name.
starfall.getName( starfallEntity )
Provides the current name of the given entity's instance.

Environment:

Shared

Parameters:

  • (Entity?) starfallEntity: (Optional) The entity to get the name of. If not provided, the entity executing this function will be used.

Return value:

    (string) The entity's Starfall name.
starfall.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(). Note that this does not contain scripts that were included asynchronously and have not yet been downloaded.

Environment:

Shared

Usage:

    -- This snippet loads all script files. 
    local Scripts = starfall.getScripts() 
    for FilePath, CompiledScript in pairs( Scripts ) do 
    	-- If you want to only load those from a certain folder, check FilePath starts with the folder path. 
    	-- Calling the CompiledScript function loads the script file. 
    	CompiledScript() 
    end

Return value:

    (table) Table of filepath -> function pairs.
starfall.getSuperTypeOf( typeName )
Returns the name of the type the given type inherits from, if any.

Environment:

Shared

Parameters:

  • (string) typeName: The name of the type to get the super type of.
starfall.getTypeDef( name )
Returns a table which you can add new methods for the given type to, if the type is extendable. The type's own methods are accessible through this table, but cannot be overwritten. Note that native types (Angle, Color, Vector) cannot be extended.

Environment:

Shared

Parameters:

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

Usage:

    -- Get the "Player" type. 
    local Player = starfall.getTypeDef( "Player" ) 
     
    -- Add a new method to check if the player's an ally. 
    function Player:isFactionAlly() 
    	return faction.isAlly( self ) 
    end 
     
    -- The new method's ready and can be used on any player object now! 
    print( ents.owner():isFactionAlly() ) -- True if you're in a faction.

Return value:

    (table | nil) If the type exists, then a table which you can add methods to. Otherwise nil.
starfall.isInstanceOf( object, type )
Returns whether the given object is an instance of the given type. That is, if the given object either is the given type, or inherits from it.

Environment:

Shared

Parameters:

  • (Any) object: The object to check.
  • (string) type: The name of the type to check for.

Return value:

    (boolean) True if the given object is, or inherits from the given type.
starfall.isSpawnedFromDuplicator()
Returns whether the current instance's entity spawned from a duplicator.

Environment:

Server

Return value:

    (boolean) True if the current instance's entity was spawned from a duplicator.
starfall.setName( name )
Changes the name of the running chip.

Environment:

Shared

Parameters:

  • (string) name: The name to use.
starfall.showOverlay( show )
Sets whether to show the overlay with the chip name, CPU time etc.

Environment:

Client

Parameters:

  • (boolean) show: Whether to show the overlay.

Valid XHTML 1.0!