Naev

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

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


Functions

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

Parameters:

  • h number Identifier of the hook to remove.

Usage:

    hook.rm( h ) -- Hook is removed
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
( funcname, where, arg )

Parameters:

  • funcname string Name of function to run when hook is triggered.
  • where string Where to hook the function. (optional)
  • arg Argument to pass to hook.

Returns:

    number Hook identifier.

Usage:

  • hook.land( "my_function" ) -- Land calls my_function
  • hook.land( "my_function", "equipment" ) -- Calls my_function at equipment screen
load (funcname, arg)
Hooks the function to the player loading the game (starts landed). ( funcname, arg )

Parameters:

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

Returns:

    number Hook identifier.

Usage:

    hook.load( "my_function" ) -- Load calls my_function
takeoff (funcname, arg)
Hooks the function to the player taking off. ( funcname, arg )

Parameters:

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

Returns:

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

Parameters:

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

Returns:

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

Parameters:

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

Returns:

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

Parameters:

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

Returns:

    number Hook identifier.
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. ( funcname, arg )

Parameters:

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

Returns:

    number Hook identifier.
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. ( funcname, arg )

Parameters:

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

Returns:

    number Hook identifier.
board (funcname, arg)
Hooks the function to the player boarding any ship.

The hook receives a single parameter which is the ship being boarded. ( funcname, arg )

Parameters:

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

Returns:

    number Hook identifier.
timer (ms, funcname, arg)
Hooks a timer.

The hook receives only the optional argument. ( ms, funcname, arg )

Parameters:

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

Returns:

    number Hook identifier.
date (resolution, funcname, arg)
Hooks a date change with custom resolution.

The hook receives only the optional argument. ( resolution, funcname, arg )

Parameters:

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

Returns:

    number Hook identifier.

Usage:

    hook.date( time.create( 0, 0, 1000 ), "some_func", nil ) -- Hooks with a 1000 second resolution
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. ( funcname, arg )

Parameters:

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

Returns:

    number Hook identifier.
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. ( funcname, arg )

Parameters:

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

Returns:

    number Hook identifier.
gather (funcname, arg)
Hooks the function to the player gatehring any sort of commodity in space.

The hook receives the name of the commodity and the quantity being gathered. ( funcname, arg )

Parameters:

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

Returns:

    number Hook identifier.
outfit_buy (funcname, arg)
Hooks the function to the player buying any sort of outfit.

The hook receives the name of the outfit and the quantity being bought. ( funcname, arg )

Parameters:

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

Returns:

    number Hook identifier.
outfit_sell (funcname, arg)
Hooks the function to the player selling any sort of outfit.

The hook receives the name of the outfit and the quantity being sold. ( funcname, arg )

Parameters:

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

Returns:

    number Hook identifier.
ship_buy (funcname, arg)
Hooks the function to the player buying any sort of ship.

The hook receives the name of the ship type bought. ( funcname, arg )

Parameters:

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

Returns:

    number Hook identifier.
ship_sell (funcname, arg)
Hooks the function to the player selling any sort of ship.

The hook receives the name of the ship type sold and the player-given name of the ship. ( funcname, arg )

Parameters:

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

Returns:

    number Hook identifier.
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 ) ( funcname, arg )

Parameters:

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

Returns:

    number Hook identifier.
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). ( funcname, arg )

Parameters:

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

Returns:

    number Hook identifier.
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 ) ( funcname, arg )

Parameters:

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

Returns:

    number Hook identifier.
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 ) ( funcname, arg )

Parameters:

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

Returns:

    number Hook identifier.
pay (funcname, arg)
Hooks the function to when the player receives or loses money.

The amount paid (or taken from the player) is passed as a parameter:
function f( amount, args ) ( funcname, arg )

Parameters:

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

Returns:

    number Hook identifier.
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(). ( funcname, arg )

Parameters:

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

Returns:

    number Hook identifier.
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

( pilot, type, funcname, arg )

Parameters:

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

Returns:

    number Hook identifier.
generated by LDoc 1.4.6 Last updated 2020-11-30 07:37:22