Lua Hook and Item Callback Discussion

[AzmodiusX]

Preamble

This is my initial document for potential hooks to be added. I realized that just adding piece-meal hooks without a plan might not result in the best outcome. Plus, I'd not like to work too much on hooks that people won't find value in.
This also covers some item functions.
If it says "approved" or "rejected", I'm not implying that's final or official. Just what I approved or rejected, and the reasoning.
This is for discussion and I want feedback.
I'll update this as needed.

Approved Hooks

Damage

Hook	Type	Description
on_creature_receive_damage	Notification	Generic - fires for all damage regardless of source
on_creature_try_receive_damage	Gating	Generic - return false to block any damage

Parameters (all share): target (Creature), source (Creature, may be nil), bodypart, damage_instance.
If damage_instance doesn't give enough context, an additional "type" for the source of the damage can be added as a param (ranged, melee, environment, spell, etc.)

Items

Hook	Type	Description
on_item_pickup	Notification	Fires when a character picks up an item
on_item_drop	Notification	Fires when a character drops an item
on_item_wield	Notification	Fires when a character wields an item
on_item_unwield	Notification	Fires when a character unwields an item
on_item_wear	Notification	Fires when a character wears/equips an item
on_item_takeoff	Notification	Fires when a character removes a worn item
on_item_broken	Notification	Fires when a worn or wielded item is destroyed
on_character_consume	Notification	Generic consumption - covers medication, drugs, food, water, and any other comestibles consumables;

Parameters: char (Character), item (Item).

Mutations

Hook	Type	Description
on_mutation_gain	Notification	Fires after a character gains a mutation
on_mutation_loss	Notification	Fires after a character loses a mutation
on_try_mutation_gain	Gating	Return false to block gaining a mutation
on_try_mutation_loss	Gating	Return false to block losing a mutation

Parameters: char (Character), trait (trait_id).

Note: Currently possible to react to mutations via JSON effect-on-condition, but it's awkward. These hooks provide a cleaner Lua-native path. Concern: thresholds, prerequisites, and cancels parameters in the mutation system may complicate utilization of the gating variants - modders blocking a mutation gain/loss could leave the character in an inconsistent state if the mutation was part of a chain or cancel pair.

Bionics

Hook	Type	Description
on_bionic_installed	Notification	Fires after a bionic is successfully installed
on_bionic_removed	Notification	Fires after a bionic is successfully uninstalled

Parameters: char (Character), bionic_id, installer (Character), autodoc (bool).

Note: Bionic installation and removal might be a bit much to veto at the moment.

Crafting

Hook	Type	Description
on_craft_start	Notification	Fires when a character begins crafting
on_craft_complete	Notification	Fires when a craft finishes successfully
on_craft_fail	Notification	Fires when a craft fails
on_character_try_craft	Gating	Return false to block crafting from starting
on_disassemble_start	Notification	Fires when a character begins disassembly
on_disassemble_complete	Notification	Fires when a disassemble finishes successfully
on_disassemble_fail	Notification	Fires when a disassemble fails
on_character_try_disassemble	Gating	Return false to block disassembly from starting

Parameters: char (Character), recipe. on_craft_start and on_craft_complete also include batch_size (int).

Construction

Hook	Type	Description
on_construct	Notification	Fires when a construction completes
on_construct_fail	Notification	Fires when a construction fails (if applicable)
on_try_construct	Gating	Return false to block a construction from starting

Parameters: TBD - likely char (Character), construction id, pos (Tripoint).

Deferred / Unsure

• Additional damage source-specific variants (environmental, field, trap-sourced, etc.) - handled by the generic hooks for now
• Skill hooks (on_skill_level_up, on_skill_practice, on_skill_rust, gating variants) - skill leveling and rust seems to be intended to be offloaded to external mods for player customization
• on_character_process_turn - per-turn hook; on_effect combined with marking entities via on_spawn/on_load hooks may be a more performant alternative already available
• Overmap hooks (on_overmap_special_placed, on_overmap_revealed) - complex system with significant existing JSON support that may be sufficient; needs further investigation
• Avatar action hooks (generic pre-action dispatch) - custom menus and hotkey support for Lua is already being worked on, which would cover the primary use cases

Rejected

• on_terrain_changed, on_furniture_changed - performance concern due to frequent calls during mapgen; construction hooks cover the main modding use case
• on_trap_triggered - traps already have decent modding support through JSON
• Mission related hooks - missions already have high modding capacity within json.
• Character creation - all potential fields can be acquired through on_game_started and utilizing gapi.get_avatar()

To Consider

• Vehicle - part installed/removed, vehicle moved, refueled, damaged
• NPC - recruitment, dismissal, attitude change (beyond dialogue hooks in PR feat(lua): Dialogue Hooks #7899)
• Activity - on_activity_start, on_activity_finish, on_activity_cancel; parameterized by activity_id; subsumes sleep/rest and reading/studying as specific activity types
• Teleportation - creature teleported (pre/post), teleport-into-wall; currently only event_bus entries, no Lua hooks
• Addiction - addiction gained, addiction lost; event_bus has gains_addiction/loses_addiction but no Lua hooks
• Healing - character healed (natural regen, item-based, NPC-aided); event_bus has character_heals_damage but no Lua hook
• Martial arts - martial art learned, style activated/deactivated; event_bus has learns_martial_art but no Lua hook
• Trading - NPC trade started, trade completed, price adjustment; no hooks at all in npctrade.cpp

Per-item callback functions

The existing dynamic item action system (iuse functions) handles item-specific use logic. Rather than global hooks, some item behaviors are better served by per-item callback functions defined in Lua:

• iwieldable functions - per-item callbacks for wield/unwield events
• iwearable functions - per-item callbacks for wear/takeoff events
• iequippable functions - per-item callbacks for durability change, repair, and break events
• istate functions - per-item callbacks for state changes like tick, pickup, and drop. Suggesting removal of tick from iuse functions.
• imelee functions - per-item callbacks for melee combat events (hit, block, etc.)
• iranged functions - per-item callbacks for ranged combat events (fire, reload, etc.)

Per-bionic callback functions

• bionic_activate functions - per-bionic callback on activation
• bionic_deactivate functions - per-bionic callback on deactivation
• bionic_on_installed functions - per-bionic callback when installed
• bionic_on_removed functions - per-bionic callback when removed

Per-mutation callback functions

• mutation_activate functions - per-mutation callback on activation
• mutation_deactivate functions - per-mutation callback on deactivation
• mutation_on_gain functions - per-mutation callback when gained
• mutation_on_loss functions - per-mutation callback when lost

These per-entity callbacks would allow individual items, bionics, and mutations to define their own Lua behavior, complementing the global hooks above.