Home

Module hook

Lua bindings to manipulate hooks. Hooks allow you to trigger functions to certain actions like when the player jumps or a pilot dies. They can have arguments passed to them which will then get passed to the called hook function. Example usage would be:
 function penter( arg )
 -- Function to run when player enters a system
 end
 
 hookid = hook.enter( "penter", 5 )
 

Functions

hook.board (funcname, arg) Hooks the function to the player boarding any ship.
hook.boarding (funcname, arg) Hooks the function to the player boarding any ship.
hook.comm_buy (funcname, arg) Hooks the function to the player buying any sort of commodity.
hook.comm_sell (funcname, arg) Hooks the function to the player selling any sort of commodity.
hook.date (resolution, funcname, arg) Hooks a date change with custom resolution.
hook.discover (funcname, arg) Hooks the function to when the player discovers an asset, jump point or the likes.
hook.enter (funcname, arg) Hooks the function to the player entering a system (triggers when taking off too).
hook.hail (funcname, arg) Hooks the function to the player hailing any ship (not a planet).
hook.input (funcname, arg) Hooks the function to the player pressing any input.
hook.jumpin (funcname, arg) Hooks the function to the player jumping (after changing systems).
hook.jumpout (funcname, arg) Hooks the function to the player jumping (before changing systems).
hook.land (funcname, where, arg) Hooks the function to the player landing.
hook.load (funcname, arg) Hooks the function to the player loading the game (starts landed).
hook.mouse (funcname, arg) Hooks the function to the player clicking the mouse.
hook.pilot (pilot, type, funcname, arg) Hooks the function to a specific pilot.
hook.rm (h) Removes a hook previously created.
hook.safe (funcname, arg) Hook run at the end of each frame.
hook.standing (funcname, arg) Hooks the function to any faction standing change.
hook.takeoff (funcname, arg) Hooks the function to the player taking off.
hook.timer (ms, funcname, arg) Hooks a timer.


Functions

hook.board (funcname, arg)
Hooks the function to the player boarding any ship. The hook receives a single parameter which is the ship being boarded.

Parameters

  • funcname: Name of function to run when hook is triggered.
  • arg: Argument to pass to hook.

Return value:

Hook identifier.
hook.boarding (funcname, arg)
Hooks the function to the player boarding any ship. The hook receives a single parameter which is the ship doing the boarding.

Parameters

  • funcname: Name of function to run when hook is triggered.
  • arg: Argument to pass to hook.

Return value:

Hook identifier.
hook.comm_buy (funcname, arg)
Hooks the function to the player buying any sort of commodity. The hook receives the name of the commodity and the quantity being bought.

Parameters

  • funcname: Name of function to run when hook is triggered.
  • arg: Argument to pass to hook.

Return value:

Hook identifier.
hook.comm_sell (funcname, arg)
Hooks the function to the player selling any sort of commodity. The hook receives the name of the commodity and the quantity being bought.

Parameters

  • funcname: Name of function to run when hook is triggered.
  • arg: Argument to pass to hook.

Return value:

Hook identifier.
hook.date (resolution, funcname, arg)
Hooks a date change with custom resolution. The hook receives only the optional argument.

Parameters

  • resolution: Resolution of the timer (should be a time structure).
  • funcname: Name of function to run when hook is triggered.
  • arg: Argument to pass to hook.

Usage:

hook.date( time.create( 0, 0, 1000 ), "some_func", nil ) -- Hooks with a 1000 STU resolution

Return value:

Hook identifier.
hook.discover (funcname, arg)
Hooks the function to when the player discovers an asset, jump point or the likes. The parameters passed to the function are the type which can be one of:
- "asset"
- "jump"
and the actual asset or jump point discovered with the following format:
function f( type, discovery )

Parameters

  • funcname: Name of function to run when hook is triggered.
  • arg: Argument to pass to hook.

Return value:

Hook identifier.
hook.enter (funcname, arg)
Hooks the function to the player entering a system (triggers when taking off too).

Parameters

  • funcname: Name of function to run when hook is triggered.
  • arg: Argument to pass to hook.

Return value:

Hook identifier.
hook.hail (funcname, arg)
Hooks the function to the player hailing any ship (not a planet). The hook receives a single parameter which is the ship being hailed.

Parameters

  • funcname: Name of function to run when hook is triggered.
  • arg: Argument to pass to hook.

Return value:

Hook identifier.
hook.input (funcname, arg)
Hooks the function to the player pressing any input. It returns the name of the key being pressed like "accel" and whether or not it's a press.

Functions should be in format:
function f( inputname, inputpress, args )

Parameters

  • funcname: Name of function to run when hook is triggered.
  • arg: Argument to pass to hook.

Return value:

Hook identifier.
hook.jumpin (funcname, arg)
Hooks the function to the player jumping (after changing systems).

Parameters

  • funcname: Name of function to run when hook is triggered.
  • arg: Argument to pass to hook.

Return value:

Hook identifier.
hook.jumpout (funcname, arg)
Hooks the function to the player jumping (before changing systems).

Parameters

  • funcname: Name of function to run when hook is triggered.
  • arg: Argument to pass to hook.

Return value:

Hook identifier.
hook.land (funcname, where, arg)
Hooks the function to the player landing. Can also be used to hook the various subparts of the landing menu. Possible targets for where are:
- "land" - when landed (default with no parameter )
- "outfits" - when visited outfitter
- "shipyard" - when visited shipyard
- "bar" - when visited bar
- "mission" - when visited mission computer
- "commodity" - when visited commodity exchange
- "equipment" - when visiting equipment place

Parameters

  • funcname: Name of function to run when hook is triggered.
  • where: Optional argument to specify where to hook the function.
  • arg: Argument to pass to hook.

Usage

  • hook.land( "my_function" ) -- Land calls my_function
  • hook.land( "my_function", "equipment" ) -- Calls my_function at equipment screen

Return value:

Hook identifier.
hook.load (funcname, arg)
Hooks the function to the player loading the game (starts landed).

Parameters

  • funcname: Name of function to run when hook is triggered.
  • arg: Argument to pass to hook.

Usage:

hook.load( "my_function" ) -- Load calls my_function

Return value:

Hook identifier.
hook.mouse (funcname, arg)
Hooks the function to the player clicking the mouse. The parameter passed to the function is the button pressed (1==left,2==middle,3==right).

Parameters

  • funcname: Name of function to run when hook is triggered.
  • arg: Argument to pass to hook.

Return value:

Hook identifier.
hook.pilot (pilot, type, funcname, arg)
Hooks the function to a specific pilot. You can hook to different actions. Currently hook system only supports:
  • "death" : triggered when pilot dies (before marked as dead).
  • "exploded" : triggered when pilot has died and the final explosion has begun.
  • "boarding" : triggered when a pilot boards another ship (start of boarding).
  • "board" : triggered when a pilot is boarded (start of boarding).
  • "disable" : triggered when pilot is disabled (with disable set).
  • "undisable" : triggered when pilot recovers from being disabled.
  • "jump" : triggered when pilot jumps to hyperspace (before he actually jumps out).
  • "hail" : triggered when pilot is hailed.
  • "land" : triggered when pilot is landing (right when starting land descent).
  • "attacked" : triggered when the pilot is attacked.
  • "idle" : triggered when the pilot becomes idle in manual control.
  • "lockon" : triggered when the pilot locked on a missile on it's target.

If you pass nil as pilot, it will set it as a global hook that will jump for all pilots.

DO NOT DO UNSAFE THINGS IN PILOT HOOKS. THIS MEANS STUFF LIKE player.teleport(). IF YOU HAVE DOUBTS USE A "safe" HOOK.

These hooks all pass the pilot triggering the hook as a parameter, so they should have the structure of:

function my_hook( pilot, arg )
end

The combat hooks also pass the pilot acting on it, so for example the pilot that disabled, attacked or killed the selected pilot. They have the following format:

function combat_hook( pilot, attacker, arg )
end

Please note that in the case of disable or death hook the attacker may be nil indicating that it was killed by other means like for example the shockwave of a dying ship or nebula volatility.

The land and jump hooks also pass the asset or jump point the pilot is landing at or jumped from, respectively:

function land_hook( pilot, planet, arg )
end

function jump_hook( pilot, jump_point, arg )
end


Parameters

  • pilot: Pilot identifier to hook (or nil for all).
  • type: One of the supported hook types.
  • funcname: Name of function to run when hook is triggered.
  • arg: Argument to pass to hook.

Return value:

Hook identifier.
hook.rm (h)
Removes a hook previously created.

Parameters

  • h: Identifier of the hook to remove.

Usage:

hook.rm( h ) -- Hook is removed
hook.safe (funcname, arg)
Hook run at the end of each frame. This hook is a good way to do possibly breaking stuff like for example player.teleport().

Parameters

  • funcname: Name of function to run when hook is triggered.
  • arg: Argument to pass to hook.

Return value:

Hook identifier.
hook.standing (funcname, arg)
Hooks the function to any faction standing change. The parameters passed to the function are faction whose standing is being changed and the amount changed:
function f( faction, change, args )

Parameters

  • funcname: Name of function to run when hook is triggered.
  • arg: Argument to pass to hook.

Return value:

Hook identifier.
hook.takeoff (funcname, arg)
Hooks the function to the player taking off.

Parameters

  • funcname: Name of function to run when hook is triggered.
  • arg: Argument to pass to hook.

Return value:

Hook identifier.
hook.timer (ms, funcname, arg)
Hooks a timer. The hook receives only the optional argument.

Parameters

  • ms: Milliseconds to delay.
  • funcname: Name of function to run when hook is triggered.
  • arg: Argument to pass to hook.

Return value:

Hook identifier.

Valid XHTML 1.0!