Module Hooks

Entry points crawl uses for calling into lua.

Crawl contacts clua through hooks. Hooks can be interacted with either by altering a hook table, defining certian functions, or the interface functions described here.

Note: This is not a real module. All names described here are in the global clua namespace.

Functions

add_autopickup_func (func) Add an autopickup function.
auto_experience () Automatically distribute or accept potion of experience distributions.
c_answer_prompt () Answer a prompt.
c_assign_invletter (the) What letter should this item get?
c_trap_is_safe (trapname) Is this trap safe?
ch_mon_is_safe (monster, is_safe, moving, dist) Is this monster safe?
ch_start_running (kind) Pre runrest hook.
ch_stop_running (kind) Post runrest hook.
ch_target_monster (x, y) Do we want to target this monster?
ch_target_monster_expl (x, y) Do we want to target this monster for an explosion?
ch_target_shadow_step (x, y) Do we want to try to shadow step here?
choose_stat_gain () Choose a stat.
clear_autopickup_funcs () Clear the autopickup function table.
opt_boolean (optname, default) Define a boolean option.
ready () Start of turn hook.
skill_training_needed () Select skills for training.

Tables

c_persist Persistent data store.
chk_interrupt_activity Activity interrupt table.
chk_interrupt_macro Macro interrupt table.
chk_lua_option Lua option extension table Add lua processed options to options.txt.
chk_lua_save Save hooks.


Functions

add_autopickup_func (func)
Add an autopickup function. Autopickup functions are passed an items.Item and an object name, and are expected to return true for "yes pickup", false for "no do not". Any other return means "no opinion".

Parameters:

  • func autopickup function
auto_experience ()
Automatically distribute or accept potion of experience distributions.

Called when presented with the skill menu after quaffing a potion of experience. Can use the skilling functions in you to change training.

Returns:

    boolean true for accept false to prompt user
c_answer_prompt ()
Answer a prompt.

This hook can be defined to answer a yesno prompt automatically.

Returns:

    boolean|nil true for yes, false for no, nil for pass
c_assign_invletter (the)
What letter should this item get?

This hook can be re-defined to provide detailed customization. It will be ignored if it fails to return a free slot.

Parameters:

Returns:

    int free slot index to put the item in

See also:

c_trap_is_safe (trapname)
Is this trap safe?

This hook can be defined to extend trap safety checks.

Crawl will call this hook with the trap name when the player tries to move onto a tile with a trap. A failed check will result in the user being prompted if they try to move onto the trap.

Parameters:

  • trapname string

Returns:

    boolean
ch_mon_is_safe (monster, is_safe, moving, dist)
Is this monster safe?

This hook can be defined to add extra safety checks or overrides. It is called when crawl wants to consider interrupting a repeat action because there are unsafe monsters around.

Parameters:

  • monster monster.mon-info info
  • is_safe boolean what crawl currently thinks about the monster
  • moving boolean is this safe to move near
  • dist int how far away is this monster

Returns:

    boolean is it safe?
ch_start_running (kind)

Pre runrest hook.

This hook can be defined to execute lua when some form of rest or autotravel starts.

The parameter is what kind of running was just stopped, and has the following possible values:

  • "travel" for autotravel (with XG or similar)
  • "interlevel" for interlevel travel
  • "explore" for autoexplore
  • "explore_greedy" for autoexplore + item pickup
  • "run" for a plain run (Shift+Dir)
  • "" for a rest

Parameters:

  • kind string
ch_stop_running (kind)

Post runrest hook.

This hook can be defined to execute lua when some form of rest or autotravel stops.

The parameter is what kind of running was just stopped, and has the following possible values:

  • "travel" for autotravel (with XG or similar)
  • "interlevel" for interlevel travel
  • "explore" for autoexplore
  • "explore_greedy" for autoexplore + item pickup
  • "run" for a plain run (Shift+Dir)
  • "" for a rest

Parameters:

  • kind string
ch_target_monster (x, y)
Do we want to target this monster?

This hook can be re-defined to alter the auto-targeter.

Called by the targeter by each cell in sight, spiralling outward from the player, until a target is found, to set the default target Uses player centered coordinates.

Return true for yes, false for no, and nil for no opinion.

Parameters:

  • x int
  • y int

Returns:

    boolean or nil
ch_target_monster_expl (x, y)
Do we want to target this monster for an explosion?

This hook can be re-defined to alter the auto-targeter.

Called by the explosion targeter by each cell in sight, spiralling outward from the player, until a target is found, to set the default target Uses player centered coordinates.

Return true for yes, false for no, and nil for no opinion.

Parameters:

  • x int
  • y int

Returns:

    boolean or nil
ch_target_shadow_step (x, y)
Do we want to try to shadow step here?

This hook can be re-defined to alter the auto-targeter.

Called by the targeter by each cell in sight, spiralling outward from the player, until a target is found, to set the default target Uses player centered coordinates. If this function has no opinion ch_target_monster is called in fall-through.

Return true for yes, false for no, and nil for no opinion.

Parameters:

  • x int
  • y int

Returns:

    boolean or nil
choose_stat_gain ()
Choose a stat.

This hook can be defined to answer the stat choice prompt automatically.

Called on levelup to prompt for a stat choice. Returns a string with the stat choice.

Returns:

    string stat choice
clear_autopickup_funcs ()
Clear the autopickup function table.
opt_boolean (optname, default)
Define a boolean option. Convenience function for use with chk_lua_option.

Parameters:

  • optname
  • default

Usage:

    chk_lua_option["myboolopt"] = opt_boolean
ready ()
Start of turn hook.

This hook can be defined to provide start of turn checks.

Crawl calls this function at the start of each turn if there are no remaining command repeats, macros, delays, or inputs in the buffer. This is done before reading new input.

skill_training_needed ()
Select skills for training.

Called when no skills are currently selected for training. Can use the skilling functions in you to change training. Will prompt the user if this function fails to select skills for training.

Returns:

    boolean true to accept the skilling, false to prompt the user

Tables

c_persist
Persistent data store. Data placed in this table will automatically persist through saves and deaths. See persist.lua for the internal details of how this is done.
chk_interrupt_activity
Activity interrupt table. Maps activity names to interrupt functions When crawl needs to interrupt an internal delay it looks up the delay by name in this table and if a function is present, calls it with the parameters name, cause, and extra. The function returns true to interrupt, false to express no opinion, and nil for "don't interrupt". Return nil only if you really know what you're doing.
chk_interrupt_macro
Macro interrupt table. Maps macro names to interrupt handling functions. When crawl needs to interrupt a macro it calls this function with the parameters name, cause, and extra. The function returns true if the macro was interrupted
chk_lua_option
Lua option extension table Add lua processed options to options.txt. Keys are treated as option names. Value should be a function that takes parameters key, value, and mode. When processing an option defined in this way crawl will call the corresponding function with value the string that is on the other side of the equals sign and one of the following mode values describing the assignment type:

  • 0 for =
  • 1 for +=
  • -1 for -=
  • 2 for ^=

The global table Globals.options is provided as a target store for these options.

See also:

chk_lua_save
Save hooks. Push into this table, rather than indexing into it. A list of functions which get called when saving. They are expected to return strings of lua that will be executed on load. Data saved with this method is associated with the character save and will be lost on death. For permanet storage see c_persist.
generated by LDoc 1.4.6 Last updated 2018-08-21 11:24:55