feat(lua): add trap related lua hooks

[ChrisLR]

Purpose of change (The Why)

Currently traps are very hard coded, would be nice to see what would be done with proper mod supported traps.

Describe the solution (The How)

Added itrap can_trigger on_trigger on_trigger_aftermath hooks by copying off iranged.
Also adds a lua trapfunc so behavior can be driven entirely by lua.

Describe alternatives you've considered

Testing

Tested with: The Beer Trap

Add in a mod's items.json

{
    "type": "trap",
    "id": "tr_beertrap",
    "trigger_weight": "200 g",
    "name": "beer trap",
    "color": "blue",
    "symbol": "^",
    "visibility": 2,
    "avoidance": 7,
    "difficulty": 0,
    "action": "lua",
    "//": "trigger_items isn't needed for this action, since trap behavior is tied to the target freeing themselves.",
    "remove_on_trigger": true,
    "drops": [ "beertrap" ],
    "vehicle_data": {
      "damage": 300,
      "sound_volume": 8,
      "sound": "SNAP!",
      "sound_type": "trap",
      "sound_variant": "bear_trap",
      "remove_trap": true,
      "spawn_items": [ "beertrap" ]
    }
  },
  {
    "id": "beertrap",
    "type": "GENERIC",
    "category": "deployables",
    "name": { "str": "beer trap" },
    "description": "This is a spring-loaded pair of steel jaws connected to a sensitive pressure plate.  Use it to set it on the ground, creating a trap that will ensnare and damage anything that steps on it.  If you are carrying a shovel, you will have the option of burying it.",
    "weight": "14000 g",
    "volume": "1500 ml",
    "price": "60 USD",
    "price_postapoc": "10 USD",
    "to_hit": -2,
    "bashing": 9,
    "cutting": 1,
    "material": "steel",
    "symbol": ";",
    "color": "light_gray",
    "use_action": {
      "type": "place_trap",
      "allow_underwater": true,
      "bury_question": "Bury the beertrap?",
      "bury": { "trap": "beertrap", "moves": 275, "practice": 7, "done_message": "You don't bury the beertrap." },
      "trap": "tr_beertrap",
      "moves": 200,
      "practice": 4,
      "done_message": "You set the beertrap."
    }
  }

Then register in the lua mod's preload

game.itrap_functions["tr_beertrap"] = {
    can_trigger = function(...) return mod.can_trigger_func(...) end,
    on_trigger = function(...) mod.on_trigger_func(...) end,
    on_trigger_aftermath = function(...) return mod.on_trigger_aftermath_func(...) end,
}

and implement the functions in main.lua

mod.can_trigger_func = function(params)
  local target = params.target
  if target and (target:is_npc() or target:is_avatar()) then
    return true
  end
  return false
end

mod.on_trigger_func = function(params)
  local beer_item_id = ItypeId.new("belgian_ale")
  local can_item_id = ItypeId.new("can_drink")
  local beer_can = gapi.create_item(can_item_id, 1)
  beer_can:add_item_with_id(beer_item_id, 1)
  beer_can:set_charges(0)
  local target = params.target
  target:add_item(beer_can)
  target:wield(beer_can)
end

mod.on_trigger_aftermath_func = function(params)
  gapi.add_msg("After Trigger")
end

FYI, its likely an existing bug to be forced to set the charges to zero, an error pops up after reloading if we don't.

Additional context

Checklist

Mandatory

• I linked any relevant issues using github keyword syntax like closes #1234 in Summary of the PR so it can be closed automatically.

Optional

• This PR used AI assistance.
  • I added an Assisted-by: trailer to every AI-assisted commit in the Linux kernel format.
• This PR ports someone else's contribution (e.g from DDA or other fork).
  • I have added port scope to the PR title.
  • I have attributed original authors in the commit messages adding Co-Authored-By in the commit message.
  • I have linked the URL of original PR(s) in the description.
• This is a C++ PR that modifies JSON loading or behavior.
  • I have documented the changes in the appropriate location in the docs/ folder.
  • If documentation for this feature does not exist, please write it or at least note its lack in PR description.
  • New localizable fields need to be added to the lang/bn_extract_json_strings.sh script if it does not support them yet.
  • If applicable, add checks on game load that would validate the loaded data.
  • If it modifies format of save files, please add migration from the old format.
• This is a PR that modifies build process or code organization.
  • Please document the changes in the appropriate location in the docs/ folder.
  • If documentation for this feature or process does not exist, please write it.
  • If the change alters versions of software required to build or work with the game, please document it.
• This is a PR that removes JSON entities.
  • The removed JSON entities have new entries in data/json/obsoletion/ folder or use some other migration process for existing saves.
• This PR adds/removes a mod.
  • I have added mods scope to the PR title.
  • The mod_name in data/mods/<mod_name> matches id in modinfo.json.
• This PR modifies lua scripts or the lua API.
  • I have added lua scope to the PR title.
  • I have added type annotations to functions so that it's safe and easy to maintain.

Build Artifacts

PR build for commit a7b23af (Clear lua_itrap_actors in lua_state_deleter) on 2026-07-02 00:20:42

• ✅ Linux tiles — download
• ✅ Windows tiles — download
• ✅ macOS tiles — download
• ✅ Android tiles — download

[scarf005]

related: #7722

[autofix-ci]

Autofix has formatted code style violation in this PR.

I edit commits locally (e.g: git, github desktop) and want to keep autofix

1. Run git pull. this will merge the automated commit into your local copy of the PR branch.
2. Continue working.

I do not want the automated commit

1. Format your code locally, then commit it.
2. Run git push --force to force push your branch. This will overwrite the automated commit on remote with your local one.
3. Continue working.

If you don't do this, your following commits will be based on the old commit, and cause MERGE CONFLICT.

[ChrisLR]

Renamed this, wasn't sure if another function would be better.

[WishDuck]

Seems to cause a segfault when I load every few times ( dont fully quit log below )?
The trap does not appear to stay existant in between save loads ( appears to be specific to lua traps )

crash.log

[ChrisLR]

should be fixed now

[WishDuck]

Compiled and load tested
Traps appear to work
No crash on quitting anymore it seems
Saveload appears to work
Green checkymarky