Force staff / charge weapon secondary fire via charge metadata

[hummat]

Problem

Force staffs and other charge-based weapons have a secondary fire mode (hold-to-charge AoE explosion) that bots never use. #31 fixes primary fire for these weapons, but the secondary fire requires the charge shot system in bt_bot_shoot_action.

Context

bt_bot_shoot_action already has a charge shot system (lines 62-73):

• can_charge_shot — enables charge behavior
• charge_action_input — input to queue (default "brace")
• charge_shot_delay — timing
• always_charge_before_firing, charge_against_armored_enemy, etc.

Force staff p1 secondary fire flow:

1. charge input (action_two_hold) → action_charge (hold)
2. charge_release input (action_two_hold release) → triggers explosion
3. OR trigger_explosion input (action_one_pressed + action_two_hold hold) → fires while charging

This is fundamentally different from ADS — it's a hold-and-release combat mode, not scope-in-for-accuracy.

Desired behavior

Inject charge metadata for weapons with charge-based secondary fire:

attack_meta_data = {
    can_charge_shot = true,
    charge_action_input = "charge",
    -- ... timing/condition fields
}

Weapons affected

• Force staff p1 (charge → explosion)
• Potentially other staff variants
• Any weapon where action_two_hold maps to a charged secondary rather than ADS

Why this is separate from #41

#41 is about weapon-aware ADS gestalt selection (when to scope in). This issue is about teaching bots a new fire mode (charged secondary) via existing bt_bot_shoot_action charge infrastructure.

Why this is separate from #31

#31 fixes fire/aim input name resolution for the vanilla fallback chain. This requires populating additional charge metadata fields that #31 deliberately scoped out, since the charge system is a separate code path in bt_bot_shoot_action.

References

• bt_bot_shoot_action.lua:62-73 — charge shot scratchpad fields
• forcestaff_p1_m1.lua — charge/charge_release/trigger_explosion inputs
• Player weapon ranged attack_meta_data injection (plasma gun silent fire fix) #31 — ranged attack_meta_data injection (fire input fix)
• Weapon/enemy-aware ADS vs hip-fire #41 — weapon-aware ADS (gestalt selection)

[hummat]

May already work via vanilla metadata

During in-game testing of #31, we observed charge inputs (15 occurrences) being queued by bots with force staffs. This suggests the vanilla attack_meta_data already ships with can_charge_shot = true and charge_action_input = "charge" for staffs — meaning bt_bot_shoot_action's existing charge shot system handles secondary fire without any additional work from us.

The real blocker was the broken primary fire input (shoot_pressed not being derived), which #31 fixed. With primary fire working, the vanilla charge system may already handle secondary fire correctly.

Status: Needs verification — do the charged explosions actually land properly (timing, targeting, explosion trigger)? If so, this issue can be closed. If the charge behavior is buggy (holds too long, never releases, doesn't trigger explosion), the issue scope shrinks to tuning the existing charge metadata rather than implementing it from scratch.

[hummat]

Investigation & partial fix (dev/m4-batch1)

Root cause

The original issue assumed can_charge_shot / charge metadata injection was the path. Investigation found:

1. can_charge_shot is unset on ALL vanilla weapon templates — the BT charge shot system (_should_charge) is completely unused.
2. Vanilla already maps staff "aiming" to charging via attack_meta_data: aim_action_name=action_charge, unaim_action_name=action_vent. The bot's aim system provides the charge→vent cycle naturally.
3. The real problem is a _may_fire() validation mismatch: vanilla _may_fire() validates scratchpad.fire_action_input (= shoot_pressed), but _fire() dispatches scratchpad.aim_fire_action_input when aiming_shot == true. For staves where these differ, _may_fire() passes for the wrong input and the aimed fire never reaches _fire().

Implementation (on dev/m4-batch1, uncommitted)

Two-part fix:

1. ranged_meta_data.lua: New find_aim_action_for_fire() derives the full aim chain from the weapon template's allowed_chain_actions graph — sets aim_action_input/name, aim_fire_action_input/name, and unaim_action_input/name.
2. BetterBots.lua: Hook on BtBotShootAction._may_fire() temporarily swaps fire_action_input to aim_fire_action_input for the duration of the validation call, so the validation and dispatch use the same input.

Per-family status

Staff families have different charged fire inputs:

Family	Charged input	allowed_chain_actions match	Status
forcestaff_p4_m1 (trauma)	shoot_charged	✅ Yes	PASS — 18 charged fires in tagged log
forcestaff_p3_m1 (voidstrike)	shoot_charged	Likely yes	Untested (same input as p4)
forcestaff_p2_m1 (flame/inferno)	trigger_charge_flame	❌ No	FAIL — 0 charged fires, falls back to shoot_pressed
forcestaff_p1_m1 (surge)	trigger_explosion	Unknown	Untested

Why p2 fails

find_aim_action_for_fire() walks allowed_chain_actions on the charge action to find which hold-start action chains into the aimed fire input. The p2 flame staff's charge action likely doesn't list trigger_charge_flame in its allowed_chain_actions — different template structure from p4. The derivation needs broadening.

Injection log confirms: charge=1 (only 1 template family overridden, down from 7 with the simpler approach).

Evidence

Tagged weapon logging (bot=N weapon_template=X action=Y):

• p4 session (console-2026-03-09-18.45.21): forcestaff_p4_m1 fires shoot_charged 18×, cycle is charge → shoot_charged → charge_release
• p2 session (same log, later): forcestaff_p2_m1 fires shoot_pressed 17×, old charge → vent pattern persists, zero trigger_charge_flame

Next steps

• Broaden find_aim_action_for_fire() to handle p1/p2 template structures (check decompiled forcestaff_p1_m1.lua and forcestaff_p2_m1.lua for how their charge→fire chain is structured)
• Retest all 4 families with tagged logging
• Consider whether partial coverage (p3/p4 only) is worth shipping