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.
info (funcname[, where], arg) Hooks the function to the info menu.
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_spob (funcname, arg) Hooks the function to the player hailing any spob.
hail (funcname, arg) Hooks the function to the player hailing any ship (not a spob).
board (funcname, arg) Hooks the function to the player boarding any ship.
timer (s, funcname, arg) Hooks a timer.
timerClear () Clear all timers added by hook.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.
comm_jettison (funcname, arg) Hooks the function to the player jettisoning 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.
outfit_sell (funcname, arg) Hooks the function to the player equipping or deequipping any 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.
ship_swap (funcname, arg) Hooks the function to the player swapping their 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 spob, jump point or the likes.
asteroid_scan (funcname, Argument) Hooks the function to when the player scans an asteroid.
pay (funcname, arg) Hooks the function to when the player receives or loses money through player.pay() (the Lua function only).
safe (funcname, arg) Hook run once at the end of the next frame regardless of anything that can happen.
update (funcname, arg) Hook run at the end of each frame when the update routine is run (game is not paused, etc.).
renderbg (funcname, arg) Hook that runs during rendering the background (just above the static background stuff).
renderfg (funcname, arg) Hook that runs during rendering the foreground (just below the gui stuff).
rendertop (funcname, arg) Hook that runs during rendering aove everything.
mission_done (funcname, arg) Hook that runs when a mission is complete.
event_done (funcname, arg) Hook that runs when a event is complete.
custom (hookname, funcname) Hook run once at the end of the next frame regardless when manually triggered.
pilot (pilot, type, funcname, arg) Hooks the function to a specific pilot.


Functions

rm (h)
Removes a hook previously created.

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

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
info (funcname[, where], arg)
Hooks the function to the info menu.

Can also be used to hook the various subparts of the info menu. Possible targets for where are:
- "main"
- "ship"
- "weapons"
- "cargo"
- "mission"
- "standing"
- "shiplog"

Parameters:

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

Returns:

    number Hook identifier.

Usage:

  • hook.info( "my_function" ) -- Info calls my_function

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

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.

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).

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).

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).

Parameters:

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

Returns:

    number Hook identifier.
hail_spob (funcname, arg)
Hooks the function to the player hailing any spob.

The hook receives a single parameter which is the spob being hailed.

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 spob).

The hook receives a single parameter which is the ship being hailed.

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.

Parameters:

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

Returns:

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

The hook receives only the optional argument.

Parameters:

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

Returns:

    number Hook identifier.
timerClear ()
Clear all timers added by hook.timer. This only affects timers created by the mission or event calling this function.
date (resolution, funcname, arg)
Hooks a date change with custom resolution.

The hook receives only the optional argument.

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.new( 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 commodity bought and the quantity being bought.

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 commodity sold and the quantity being sold.

Parameters:

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

Returns:

    number Hook identifier.
comm_jettison (funcname, arg)
Hooks the function to the player jettisoning any sort of commodity.

The hook receives the commodity and the quantity jettisoned.

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 commodity and the quantity being gathered.

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.

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.

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 equipping or deequipping any outfit.

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.

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.

Parameters:

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

Returns:

    number Hook identifier.
ship_swap (funcname, arg)
Hooks the function to the player swapping their ship.

The hook receives the name of the ship swapped to and the name of the ship swapped from (if applicable).

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 )

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), and whether it is a down (true) or up (false) event.

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, system, secondary, primary_fct, args )

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 spob, jump point or the likes.

The parameters passed to the function are the type which can be one of:
- "spob"
- "jump"
and the actual spob or jump point discovered with the following format:
function f( type, discovery )

Parameters:

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

Returns:

    number Hook identifier.
asteroid_scan (funcname, Argument)
Hooks the function to when the player scans an asteroid.

The parameter passed to the function is the asteroid scanned.

Parameters:

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

Returns:

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

The amount paid (or taken from the player) and reason (which is nil by default) is passed as a parameter:
function f( amount, reason, args )

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 once at the end of the next frame regardless of anything that can happen.

This hook is a good way to do possibly breaking stuff like for example player.teleport().

Parameters:

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

Returns:

    number Hook identifier.
update (funcname, arg)
Hook run at the end of each frame when the update routine is run (game is not paused, etc.).

It is closely related to hook.safe(), but you have to manually remove it or it continues forever.

The current delta-tick (time passed in game) and real delta-tick (independent of game status) are passed as parameters:
function f( dt, real_dt, args )

Parameters:

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

Returns:

    number Hook identifier.
renderbg (funcname, arg)
Hook that runs during rendering the background (just above the static background stuff). Meant to be only for rendering things.

Parameters:

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

Returns:

    number Hook identifier.
renderfg (funcname, arg)
Hook that runs during rendering the foreground (just below the gui stuff). Meant to be only for rendering things.

Parameters:

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

Returns:

    number Hook identifier.
rendertop (funcname, arg)
Hook that runs during rendering aove everything. Meant to be as an alternative to doing post-processing shader effects.

Parameters:

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

Returns:

    number Hook identifier.
mission_done (funcname, arg)
Hook that runs when a mission is complete. The entire mission information table is passed similar to player.evtDoneList().

Parameters:

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

Returns:

    number Hook identifier.
event_done (funcname, arg)
Hook that runs when a event is complete. The entire event information table is passed similar to player.evtDoneList().

Parameters:

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

Returns:

    number Hook identifier.
custom (hookname, funcname)
Hook run once at the end of the next frame regardless when manually triggered. Can be triggered manually with `naev.trigger`.

Parameters:

  • hookname string Name to give the hook. This should not overlap with standard names.
  • funcname string Name of function to run when hook is triggered.

Returns:

    number Hook identifier.
pilot (pilot, type, funcname, arg)
Hooks the function to a specific pilot.

These hooks only live in the current system and get reset every time the player enters a new system.

You can hook to different actions. Currently hook system only supports:

  • "creation" : triggered when a pilot is created.
  • "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 by the player (start of boarding).
  • "boardall" : triggered when a pilot is boarded by any pilot (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.
  • "discovered" : triggered when the pilot is in stealth and discovered by another pilot (not necessarily the player).
  • "idle" : triggered when the pilot becomes idle in manual control.
  • "lockon" : triggered when the pilot locked on a missile on its target.
  • "stealth" : triggered when the pilot either enters or leaves stealth.
  • "scanned" : triggered when the pilot is scanned by another pilot.
  • "scan" : triggered when the pilot scans another pilot.

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 spob or jump point the pilot is landing at or jumped from, respectively:

function land_hook( pilot, spob, arg )
end

function jump_hook( pilot, jump_point, arg )
end

The stealth hook passes whether or not the ship is stealthing or destealthing as a boolean:

function stealth_hook( pilot, status, arg )
end

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.5.0 Last updated 2024-11-21 07:14:26