Hooks

List of hooks available to SF scripts

List

calcview( player, origin, angles, fov ) Called on a HUD when you are linked to it.
canexitvehicle( ply, vehicle ) Called when a player is attempting to leave an engine vehicle (e.g. a chair).
chatboxclosed() Called on a HUD when you are linked to it and the chatbox has been closed.
chatboxopened( mode ) Called on a HUD when you are linked to it and the chatbox has been opened.
chattextchanged( text ) Called on a HUD when you are linked to it and the text in the chatbox input has changed.
checkfiledownload( ply, fileName ) Called when a file is requested by a client from an asynchronous include.
checktricorderoverride( ply, tricorder ) Called when a player is attempting to use their tricorder/scanner on the Starfall entity with this hook.
dtvarchanged( type, index, oldValue, newValue ) Called when a DTVar value is changed (if change detection was enabled by net.listenForDTVarChanges() or net.listenForAllDTVarChanges()).
entityremoved( ent ) Called when an entity is removed.
entitytakedamage( ent, inflictor, attacker, amount, pos ) Called when an entity takes damage through the server's damage system.
hudlink( player ) Called when a player links to your HUD (clientside only).
hudshoulddraw( element ) Called on a HUD when you are linked to it.
hudunlink( player ) Called when a player unlinks from your HUD (clientside only).
input( input, value ) Called when an input on a wired SF chip is written to
inputmouseapply( x, y, viewAngles ) Called when mouse input is applied to the local player's view.
keypress( ply, key ) Called when a player presses an input button.
keyrelease( ply, key ) Called when a player releases an input button.
net( length, player ) Called when a network message is received.
networkentitycreated( entity ) Called when a networked entity has been created.
notifyshouldtransmit( entity, shouldTransmit ) Called when an entity enters or leaves the local player's PVS.
oncontextmenuclose() Called when the GMod context menu is closed (-menu_context keybind).
oncontextmenuopen() Called when the GMod context menu is opened (+menu_context keybind).
onentitycreated( ent ) Called when an entity is created.
onentityscanstarted( ply, scanner, target ) Called when the local player starts scanning an entity with a scanning weapon.
onentityscanstopped( ply, scanner ) Called when the local player stops scanning an entity with a scanning weapon.
onremove( reason ) Called when the chip is being removed or updated with new code.
onscreensizechanged( oldWidth, oldHeight ) Called when the game's screen resolution has changed.
permissiongranted( permission, player ) Runs when a permission has been granted to this instance.
permissionrevoked( permission, player ) Runs when a permission has been revoked from this instance.
playerattempteduse( ply, ent ) Called when a player attempts to use an entity.
playerauthed( ply, steamID, uniqueID ) Called when a player's Steam ID has been confirmed.
playerbindpress( ply, bind, pressed ) Called when a player runs a command.
playerbuttondown( ply, key ) Called when a player presses down any button.
playerbuttonup( ply, key ) Called when a player releases any button.
playerdeath( victim, inflictor, attacker ) Called when a player dies.
playerdisconnected( ply ) Called when a player disconnects.
playerenteredvehicle( ply, vehicle, seatIndex ) Called when a player enters an engine vehicle (e.g. a chair).
playerinitialspawn( ply ) Called when a player spawns for the first time.
playerleavevehicle( ply, vehicle ) Called when a player leaves an engine vehicle (e.g. a chair), after any exit animation is completed.
playerspawn( ply ) Called when a player spawns.
playeruse( ply, ent ) Called when a player successfully uses an entity after passing prop protection checks.
postduplicationpaste( createdEntities ) Called when the duplication the chip is a part of has been fully restored.
postentitypaste( data, createdEntities ) Called when the chip has been restored.
preentitycopy( data ) Called when the chip is being copied.
readcell( address ) Called when a high speed device reads from a wired SF chip
render() Called when a frame is requested to be drawn.
renderoverlay( overlayData ) Called on HUDs and emitters when they need to render their overlay (i.e. when the local player is looking at the chip).
starfall_used( activator, repeaterEntity ) Called when a player presses use on the screen entity this instance is running on.
think() Called once per game tick on the server and once per frame on the client.
tick() Called once per game tick on both the client and the server.
tricorderoverride( ply, tricorder ) Called when a player successfully uses their tricorder/scanner on the Starfall entity with this hook.
writecell( address, data ) Called when a high speed device writes to a wired SF chip


calcview( player, origin, angles, fov )
Called on a HUD when you are linked to it. Return a table with origin, angles and fov fields to change your camera view.

Environment:

Client

Parameters:

  • player: The local player.
  • origin: The default location of the camera.
  • angles: The default angles of the camera.
  • fov: The default field of view of the camera.

Return value:

    (CamData) A table describing the view to render from.
canexitvehicle( ply, vehicle )
Called when a player is attempting to leave an engine vehicle (e.g. a chair). This hook is executed only if the player has granted the CONTROL_VEHICLE_INPUT permission and the vehicle belongs to the instance owner.

Environment:

Server

Parameters:

  • (Player) ply: The player that is attempting to leave the vehicle.
  • (Vehicle) vehicle: The vehicle the player is currently sat in.

Return value:

    (boolean) False to block the exit.
chatboxclosed()
Called on a HUD when you are linked to it and the chatbox has been closed. This requires the READ_CHATBOX_STATE permission.

Environment:

Client
chatboxopened( mode )
Called on a HUD when you are linked to it and the chatbox has been opened. This requires the READ_CHATBOX_STATE permission.

Environment:

Client

Parameters:

  • mode: The mode the chatbox was opened with.
chattextchanged( text )
Called on a HUD when you are linked to it and the text in the chatbox input has changed. This requires the READ_CHATBOX_STATE permission.

Environment:

Client

Parameters:

  • text: The contents of the chatbox input.
checkfiledownload( ply, fileName )
Called when a file is requested by a client from an asynchronous include. Return false to deny the download. If no hook callback returns a value, the download will be allowed.

Environment:

Server

Parameters:

  • (Player) ply: The player attempting to download the file.
  • (string) fileName: The name of the file being downloaded (as a full path).

Usage:

    -- Only allow downloads for the chip owner. This will cause require()/dofile() to throw an error for other players. 
    hook.add( "checkfiledownload", "Deny non-owner", function( Ply, FileName ) 
    	print( Ply:nick(), "attempted to download file:", FileName ) 
    	return Ply == ents.owner() 
    end )

Return value:

    (boolean) True to allow the download, false to deny.
checktricorderoverride( ply, tricorder )
Called when a player is attempting to use their tricorder/scanner on the Starfall entity with this hook.

Environment:

Server

Parameters:

  • ply: The player attempting to use their tricorder/scanner.
  • tricorder: The tricorder/scanner being used to override.

Return value:

    True if they should be allowed to use it, false otherwise.
dtvarchanged( type, index, oldValue, newValue )
Called when a DTVar value is changed (if change detection was enabled by net.listenForDTVarChanges() or net.listenForAllDTVarChanges()).

Environment:

Client

Parameters:

  • (string) type: The type of DTVar that has changed.
  • (number) index: The index under the given type of the DTVar that has changed.
  • (Any) oldValue: The previous value for the DTVar.
  • (Any) newValue: The new value for the DTVar.
entityremoved( ent )
Called when an entity is removed.

Environment:

Shared

Parameters:

  • ent: The entity removed.
entitytakedamage( ent, inflictor, attacker, amount, pos )
Called when an entity takes damage through the server's damage system. NOTE: This hook is sampled over time, and will not report every damage event. To track exact damage amounts, periodically poll the health of a given entity.

Environment:

Server

Parameters:

  • (Entity) ent: The entity that took damage.
  • (Entity) inflictor: The weapon that caused the damage.
  • (Entity) attacker: The owner of the weapon that caused the damage.
  • (number) amount: The amount of damage taken.
  • (Vector) pos: The position at which the damage occurred (in world space).
hudlink( player )
Called when a player links to your HUD (clientside only).

Environment:

Client

Parameters:

  • player: The player linking.
hudshoulddraw( element )
Called on a HUD when you are linked to it. Return a value to deny the given HUD element from drawing. See: https://wiki.facepunch.com/gmod/HUD_Element_List In addition to the above, the following extra elements are defined: * LuaHudHealth * LuaHudAmmo * LuaHudDeathNotice

Environment:

Client

Parameters:

  • element: The string name of the HUD element requesting permission to draw.
hudunlink( player )
Called when a player unlinks from your HUD (clientside only).

Environment:

Client

Parameters:

  • player: The player being unlinked.
input( input, value )
Called when an input on a wired SF chip is written to

Environment:

Server

Parameters:

  • input: The input name
  • value: The value of the input
inputmouseapply( x, y, viewAngles )
Called when mouse input is applied to the local player's view.

Environment:

Client

Parameters:

  • x: The amount of mouse movement along the x-axis this frame.
  • y: The amount of mouse movement along the y-axis this frame.
  • viewAngles: The view angles of the local player.
keypress( ply, key )
Called when a player presses an input button.

Environment:

Shared

Parameters:

  • ply: The player pressing the button.
  • key: The IN_ button.
keyrelease( ply, key )
Called when a player releases an input button.

Environment:

Shared

Parameters:

  • ply: The player releasing the button.
  • key: The IN_ button.
net( length, player )
Called when a network message is received. Note that network messages are stateful, and thus once read, data cannot be retrieved again. Having multiple callbacks for this hook will not work unless each is reading a separate part of the incoming message.

Environment:

Shared

Parameters:

  • (number) length: The length of the network message in bits.
  • (Player) player: The player that sent the network message (only on the server side).
networkentitycreated( entity )
Called when a networked entity has been created.

Environment:

Client

Parameters:

  • entity: The entity that has been created.
notifyshouldtransmit( entity, shouldTransmit )
Called when an entity enters or leaves the local player's PVS.

Environment:

Client

Parameters:

  • entity: The entity whose transmission state has changed.
  • shouldTransmit: Whether the entity is transmitting or not.
oncontextmenuclose()
Called when the GMod context menu is closed (-menu_context keybind).

Environment:

Client
oncontextmenuopen()
Called when the GMod context menu is opened (+menu_context keybind).

Environment:

Client
onentitycreated( ent )
Called when an entity is created.

Environment:

Shared

Parameters:

  • ent: The entity created.
onentityscanstarted( ply, scanner, target )
Called when the local player starts scanning an entity with a scanning weapon. Note that this may be called multiple times with different entities as the player switches targets before "onentityscanstopped" is called. To detect scanning on players other than the instance owner, a linked HUD is required.

Environment:

Client

Parameters:

  • (Player) ply: The player that is initiating the scan.
  • (Weapon) scanner: The scanner weapon being used to scan the entity.
  • (Entity) target: The target entity that is being scanned.
onentityscanstopped( ply, scanner )
Called when the local player stops scanning an entity with a scanning weapon. Note that this is called only when the player no longer has an active scanning target. If the player changes target, only "onentityscanstarted" will be called. To detect scanning on players other than the instance owner, a linked HUD is required.

Environment:

Client

Parameters:

  • (Player) ply: The player that was scanning.
  • (Weapon) scanner: The scanner weapon that was being used to scan an entity.
onremove( reason )
Called when the chip is being removed or updated with new code.

Environment:

Shared

Parameters:

  • reason: The reason for the instance shutdown (one of "UPDATING", "RESTARTING", "TERMINATING" or "REMOVING").
onscreensizechanged( oldWidth, oldHeight )
Called when the game's screen resolution has changed. Calling render.getScreenRes() will return the new size.

Environment:

Client

Parameters:

  • oldWidth: The old screen width in pixels.
  • oldHeight: The old screen height in pixels.
permissiongranted( permission, player )
Runs when a permission has been granted to this instance.

Environment:

Shared

Parameters:

  • (string) permission: The permission that has been granted.
  • (Player) player: The player that granted the permission. This is always ents.player() on the client.
permissionrevoked( permission, player )
Runs when a permission has been revoked from this instance.

Environment:

Shared

Parameters:

  • (string) permission: The permission that has been revoked.
  • (Player) player: The player that revoked the permission. This is always ents.player() on the client.
playerattempteduse( ply, ent )
Called when a player attempts to use an entity. This is called before prop protection checks, so the player may not be allowed to use the entity. Use the "playeruse" hook for successful use events.

Environment:

Server

Parameters:

  • (Player) ply: The player that pressed their use key.
  • (Entity) ent: The entity that the player is attempting to use.
playerauthed( ply, steamID, uniqueID )
Called when a player's Steam ID has been confirmed.

Environment:

Server

Parameters:

  • ply: The player that has been authed.
  • steamID: Their Steam ID.
  • uniqueID: Don't use it, it's not really unique thanks to Garry.
playerbindpress( ply, bind, pressed )
Called when a player runs a command. Return true to block the command (only works for the chip's owner).

Environment:

Client

Parameters:

  • ply: The player using the command (the local player).
  • bind: The command run, e.g "+attack"
  • pressed: Boolean value whether the bind was activated or deactivated.
playerbuttondown( ply, key )
Called when a player presses down any button.

Environment:

Shared

Parameters:

  • ply: The player pressing the button.
  • key: The KEY_ or MOUSE_ button.
playerbuttonup( ply, key )
Called when a player releases any button.

Environment:

Shared

Parameters:

  • ply: The player releasing the button.
  • key: The KEY_ or MOUSE_ button.
playerdeath( victim, inflictor, attacker )
Called when a player dies.

Environment:

Server

Parameters:

  • victim: The player that died.
  • inflictor: The entity that caused the death.
  • attacker: The player that killed them.
playerdisconnected( ply )
Called when a player disconnects.

Environment:

Server

Parameters:

  • ply: The player that left.
playerenteredvehicle( ply, vehicle, seatIndex )
Called when a player enters an engine vehicle (e.g. a chair).

Environment:

Server

Parameters:

  • (Player) ply: The player that entered the vehicle.
  • (Vehicle) vehicle: The vehicle that was entered.
  • (number) seatIndex: The index of the seat that was entered (starting from 0).
playerinitialspawn( ply )
Called when a player spawns for the first time.

Environment:

Server

Parameters:

  • ply: The player that has spawned for the first time.
playerleavevehicle( ply, vehicle )
Called when a player leaves an engine vehicle (e.g. a chair), after any exit animation is completed.

Environment:

Server

Parameters:

  • (Player) ply: The player that left the vehicle.
  • (Vehicle) vehicle: The vehicle that was left.
playerspawn( ply )
Called when a player spawns.

Environment:

Server

Parameters:

  • ply: The player that has spawned.
playeruse( ply, ent )
Called when a player successfully uses an entity after passing prop protection checks.

Environment:

Server

Parameters:

  • (Player) ply: The player that pressed their use key.
  • (Entity) ent: The entity that is being used.
postduplicationpaste( createdEntities )
Called when the duplication the chip is a part of has been fully restored.

Environment:

Server

Parameters:

  • createdEntities: A table keyed by entity index (at the point of saving), where each entity corresponds to an entity in the dupe.
postentitypaste( data, createdEntities )
Called when the chip has been restored. Note that other entities in the duplication may not have been fully restored yet. To wait until everything has been restored, use the "postduplicationpaste" hook.

Environment:

Server

Parameters:

  • data: The table of data you saved with PreEntityCopy.
  • createdEntities: A table keyed by entity index (at the point of saving), where each entity corresponds to an entity in the dupe.
preentitycopy( data )
Called when the chip is being copied. Note: don't try to store anything other than basic numbers, booleans and strings. To store an entity, store its entity index, then use the created entities lookup in PostEntityPaste using the saved index.

Environment:

Server

Parameters:

  • data: Add values to this table to be saved.
readcell( address )
Called when a high speed device reads from a wired SF chip

Environment:

Server

Parameters:

  • address: The address requested

Return value:

    The value read
render()
Called when a frame is requested to be drawn. You may want to unhook from this if you don't need to render anything for a bit

Environment:

Client
renderoverlay( overlayData )
Called on HUDs and emitters when they need to render their overlay (i.e. when the local player is looking at the chip). Adding a hook for this event will hide the default overlay. If you just want to disable the overlay from drawing, use starfall.showOverlay( false ).

Environment:

Client

Parameters:

  • (RenderOverlayData) overlayData: Metadata used to render the default overlay.
starfall_used( activator, repeaterEntity )
Called when a player presses use on the screen entity this instance is running on.

Environment:

Shared

Parameters:

  • activator: The player that pressed use on the screen.
  • repeaterEntity: The repater screen entity that use was pressed on, if it was not pressed on the original screen.
think()
Called once per game tick on the server and once per frame on the client.

Environment:

Shared
tick()
Called once per game tick on both the client and the server.

Environment:

Shared
tricorderoverride( ply, tricorder )
Called when a player successfully uses their tricorder/scanner on the Starfall entity with this hook.

Environment:

Server

Parameters:

  • ply: The player that was successful in using their tricorder/scanner on your entity.
  • tricorder: The tricorder/scanner being used to override.
writecell( address, data )
Called when a high speed device writes to a wired SF chip

Environment:

Server

Parameters:

  • address: The address written to
  • data: The data being written

Valid XHTML 1.0!