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_choose_acquirement () | Acquirement scroll hook. |
| c_message (text, channel) | Receive a message from the message window. |
| 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_force_autopickup | Autopickup functions User interface via add_autopickup_func and clear_autopickup_funcs. |
| 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. |
Fields
| chk_ability_choice | Ability choice. |
| chk_spell_choice | Spell choice. |
Local Functions
| c_choose_ability () | Ability choice internal hook. |
| c_choose_spell () | Spell choice internal hook. |
| c_interrupt_activity (aname, iname, cause, extra) | Internal activity interrupt hook. |
| c_interrupt_macro (iname, cause, extra) | Internal macro interrupt hook. |
| c_process_lua_option (key, val, mode) | Internal Lua option processing hook. |
| c_save () | Save hook function. |
| ch_force_autopickup (it, name) | Internal entrypoint to autopickup functions |
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:
- the items.Item item being put into inventory
Returns:
-
int
free slot index to put the item in
See also:
- c_choose_acquirement ()
-
Acquirement scroll hook.
This hook can be defined to execute lua when an acquirement scroll is read.
The hook should call items.acquirement_items to get an array of items.Item representations of the offered items. If it returns a valid index in this array, the given item will be acquired without the usual acquirement menu.
Returns:
-
int
An index between 1 and the number of offered items.
- c_message (text, channel)
-
Receive a message from the message window.
This hook can be re-defined to receive messages from the message window. It is called for each message after player configured mute settings are applied to the message.
Parameters:
- text string The message text
- channel string The message channel name
- 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.luafor the internal details of how this is done. - chk_force_autopickup
- Autopickup functions User interface via add_autopickup_func and clear_autopickup_funcs.
- 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:
- 0 for
- 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.
Fields
- chk_ability_choice
-
Ability choice.
This variable can be set by lua before the user is shown the "Activate which ability?" prompt. If set to a valid ability letter that ability will be activated without prompting the user. Otherwise the ability prompt proceedes as normal.
This value is cleared after every ability activation.
The current table mapping letters to abilities can be accessed with the you.abil_table function.
- chk_spell_choice
-
Spell choice.
This variable can be set by lua before the user is shown the "Cast which spell?" prompt. If set to a valid spell letter that will be selected without prompting the user. Execution passes to targeting, which can be handled either through the lua system or by the user.
The current table mapping letters to spells can be accessed with the you.spell_table function.
Local Functions
- c_choose_ability ()
-
Ability choice internal hook.
Internal function supporting chkabilitychoice
Returns:
-
string or nil
The ability letter to activate or nil to prompt the user
- c_choose_spell ()
-
Spell choice internal hook.
Internal function supporting chkabilitychoice
Returns:
-
string or nil
The spell letter to activate or nil to prompt the user
- c_interrupt_activity (aname, iname, cause, extra)
-
Internal activity interrupt hook.
Entry point for chkinterruptactivity
Notice that cinterruptactivity defaults to false whereas cinterruptmacro defaults to true. This is because "false" really just means "go ahead and use the default logic to kill this activity" here, whereas false is interpreted as "no, don't stop this macro" for cinterruptmacro.
If cinterruptactivity, or one of the individual hooks wants to ensure that the activity continues, it must return nil (make sure you know what you're doing when you return nil!).
Parameters:
- aname
- iname
- cause
- extra If some joker undefined the table, bail out
- c_interrupt_macro (iname, cause, extra)
-
Internal macro interrupt hook.
Entry point for chkinterruptmacro
Parameters:
- iname
- cause
- extra If some joker undefined the table, stop all macros
- c_process_lua_option (key, val, mode)
-
Internal Lua option processing hook.
This function returns true to tell Crawl not to process the option further.
Mode is described in chk_lua_option.
Parameters:
- key
- val
- mode
- c_save ()
- Save hook function. Walks the chkluasave table.
- ch_force_autopickup (it, name)
-
Internal entrypoint to autopickup functions
Parameters:
- it items.Item
- name