Tier 3 revive cover: extend #7 to item-based defensive abilities

[hummat]

Context

#7 (v0.10.0) added defensive combat ability activation before revive interactions via revive_ability.lua hooking BtBotInteractAction.enter. Current whitelist (combat_ability_identity.lua:51) covers 7 combat-ability templates across Veteran/Zealot/Psyker/Ogryn/Arbites.

A 2026-04-11 audit confirmed the combat-ability whitelist is complete — all 15 combat ability templates were walked against class docs + decompiled buff proc_funcs, and the 8 excluded templates are all legitimately offensive (stances, charges, dashes).

However, Tier 3 item-based abilities are not covered, and several are among the strongest defensive revive tools in the game.

Missing coverage

Item-based abilities flow through item_fallback.lua (wield/use/unwield state machine), not combat_ability_action. revive_ability.try_pre_revive resolves ability identity via unit_data_extension:read_component("combat_ability_action") only, so the entire Tier 3 class is invisible to the pre-revive path.

Ability	Template slot	Defensive value for revive
Psyker Telekine Shield	slot_combat_ability item	Physical wall blocks ranged + melee — literal projectile cover over downed ally
Zealot Relic of the Emperor Ascendant	slot_combat_ability item	AoE toughness restore + DR aura to allies in radius
Arbites Nuncio-Aquila drone (with adamant_drone_buff_talent)	slot_combat_ability item	+30% revive speed and −30% TDR for allies in zone — literally designed for this

All three are validated Tier 3 abilities already handled by item_fallback.lua for general activation.

Approach

1. Semantic tagging: extend combat_ability_identity.lua with an item-based defensive whitelist (parallel to REVIVE_DEFENSIVE_BY_SEMANTIC_KEY) keyed on item slot identity, or add a is_revive_defensive_item resolver.
2. Resolution path: revive_ability.try_pre_revive currently short-circuits on combat_ability_action.template_name == nil (Tier 3 path). Add a parallel branch that reads the equipped slot_combat_ability item and matches against the item whitelist.
3. Activation: delegate to ItemFallback.begin(unit, profile) rather than action_input_extension:bot_queue_action_input. The existing item_fallback state machine handles wield → use → unwield.
4. Cooldown/charge gate: reuse existing _is_combat_template_enabled + per-item availability checks already present in item_fallback.
5. EventLog: emit revive_ability event with tier = 3 + item_slot fields for correlation with text-log revive_candidate lines.

Open questions

• Does BtBotInteractAction.enter fire early enough to start a wield sequence before the revive interaction commits? Needs trace validation — Tier 3 wield-use-unwield typically takes ~1.5–2s, which may overshoot the revive start window.
• Arbites Nuncio-Aquila drone is placement-based (ground zone) — does the bot need to be standing at the revive target before placing, or can it place en route? Check adamant_whistle.lua / drone placement logic.
• Should Psyker Telekine Shield position preference bias toward the downed ally's line of sight to nearest enemy group, rather than default bot facing?

Relevant files

• scripts/mods/BetterBots/revive_ability.lua (hook site + resolution)
• scripts/mods/BetterBots/combat_ability_identity.lua (whitelist expansion)
• scripts/mods/BetterBots/item_fallback.lua (Tier 3 state machine)
• ../Darktide-Source-Code/scripts/extension_systems/interaction/interactions/revive_interaction.lua (revive timing reference)
• docs/bot/input-system.md (Tier 3 wield-use-unwield pattern)

Acceptance criteria

• Bot Psyker equipped with Telekine Shield places shield before starting a revive interaction when enemies are within X m of the downed ally
• Bot Zealot equipped with Relic activates it before starting a revive, covering the revive window with ally toughness aura
• Bot Arbites with Nuncio-Aquila drone + adamant_drone_buff_talent places the drone at the revive location to benefit from +30% revive speed
• JSONL event log emits revive_ability events with tier: 3 for item-based activations
• Existing combat-ability path (Tier 1/2) remains unchanged — no regression in Revive-with-ability: activate defensive abilities during revive #7 coverage
• New unit tests in tests/revive_ability_spec.lua cover the item-based resolution branch

Not in scope

• Extending to other non-revive rescue interactions (pull_up, remove_net, rescue) — already covered by RESCUE_INTERACTION_TYPES, no additional work needed
• Ogryn Stimm Field (Hive Scum DLC broker_* — blocked, DLC not owned)
• Dynamic item selection (bot carries multiple defensive items) — out of scope, bots have a single slot_combat_ability

Related

• Revive-with-ability: activate defensive abilities during revive #7 — Original revive-with-ability implementation (Tier 1/2 combat abilities, shipped v0.10.0)
• docs/classes/psyker.md (Telekine Shield template details)
• docs/classes/zealot.md (Relic item-based ability notes)
• docs/classes/arbites.md (Nuncio-Aquila + adamant_drone_buff_talent revive speed)

[hummat]

Decision: scope-exit. Tier 3 revive cover is not viable with the engine's current interact architecture.

Investigated per Sprint 1 plan: measure the window between BtBotInteractAction.enter and revive commit to see whether a Tier 3 wield→use→unwield (~1.5–2s) fits. The answer is zero usable window, not a tight one.

Why the enter hook site can't accommodate Tier 3

1. The revive interaction fires within ~1 frame of BtBotInteractAction.enter.

bot_behavior_tree.lua gates the do_revive node on can_revive, which only returns true when both ally_destination_reached and can_interact_with_ally are true (bt_bot_conditions.lua:194-208). So by the time enter fires, the bot is already at the target, adjacent and aligned. The first run tick calls bot_unit_input:interact() (bt_bot_interact_action.lua:76), which sets input.interact_pressed = true on the next get() (bot_unit_input.lua:62-72). InteractorExtension._check_current_state sees the press on its next tick and calls interaction:start() → the interaction begins (interactor_extension.lua:276-301). End-to-end: 1–2 frames (~16–32ms @60fps).

2. Entering PlayerCharacterStateInteracting actively destroys any in-flight ability or weapon action.

This is the fatal one. player_character_state_interacting.lua:39 calls Interrupt.ability_and_action(t, unit, "interacting", nil) on state entry — which wipes any queued combat ability and any ongoing weapon action (interrupt.lua:46-49). Line 88 then force-wields DEFAULT_ITEM_SLOT_TO_WIELD = "slot_unarmed" (the revive template sets no wield_slot). A Tier 3 sequence started at enter would be interrupted before the wield action completes.

Tier 1/2 combat abilities escape this because their templates set their own wield_slot and activation doesn't route through weapon_action; the existing revive_ability.try_pre_revive queues combat_ability_action and the ability extension fires it before character-state transition. Tier 3 has no such escape — it IS a weapon action sequence.

Why an earlier hook point (approach phase) isn't a rescue either

Proposal: hook bt_bot_follow_action.enter or the perception.target_ally_need_type == "knocked_down" transition, fire Tier 3 during approach so it completes before arrival.

Failure modes:

• Interrupt still applies on arrival. If the bot arrives before the USE action commits, PlayerCharacterStateInteracting.on_enter still calls Interrupt.ability_and_action. Sequence lost.
• Navigation timing is non-deterministic. Path length, obstacles, movement speed, other BT transitions (disable, suppress, combat). No safe way to time the sequence against arrival.
• Combat disruption during approach. Wielding slot_combat_ability mid-approach means the bot stops shooting while moving through the same corridor that downed the ally. Likely gets hit, possibly knocked down itself.
• Arbites drone needs placement AT the revive location. The adamant_drone_buff_talent only buffs allies inside the drone's zone. Placed en route, the downed ally isn't in the zone — zero benefit. Placing at target requires arrival first — back to problem Validate Tier 2 abilities in-game #1.
• Per-class placement logic doesn't exist. Psyker Telekine Shield needs LOS orientation. Zealot Relic is self-centered AoE, so location matters less but still wants to be at the target. Arbites drone wants precise ground placement. Each needs bespoke positioning code.

What a viable Tier 3 revive cover would require

Not a hook patch — an architecture change:

1. A new "pre-revive staging" BT state that fires Tier 3 before transitioning to BtBotInteractAction, gated on distance-to-target (e.g. activate at 3–5m so the sequence completes just as the bot arrives).
2. A way to suppress PlayerCharacterStateInteracting.on_enter's interrupt for a grace window, or to delay the interact press until the ability sequence reports complete.
3. Per-class placement logic for Arbites drone (ground-target the revive location, not the bot's current position).
4. Combat-pressure gate (don't wield item during approach if taking ranged fire).
5. Full validation across three classes, three grenade-like activation patterns, and at least the three relevant rescue interaction types.

Conservative estimate: 1–2 week workstream with significant in-game test time. Not a small patch. Not a P2 issue — this is P3 or "future — architecture-scoped".

Recommendation

• Do not extend revive_ability.lua with Tier 3 resolution on the enter hook. It cannot work.
• Reclassify this issue as blocked-by-architecture or close as won't-fix. Leave the defensive value documented so a future engine change (or a rethink of the approach-phase hook) can revisit.
• Sprint 1 capacity freed: continue to Per-breed weakspot aim map: Mauler spine, Crusher back-of-head, Bulwark side #92 and Navmesh validation for charge/dash abilities #13.

Files read for verification

• bot_behavior_tree.lua:5-17 — revive node wiring
• bt_bot_conditions.lua:194-208 — can_revive requires destination reached + can_interact
• bt_bot_interact_action.lua:9-85 — enter/run flow, interact press timing
• bot_unit_input.lua:62-72, 123-129 — interact press emission
• interactor_extension.lua:272-301 — button-press → interaction:start → state transition
• interaction_templates.lua:315-334 — revive duration = 3
• player_character_state_interacting.lua:33-88 — Interrupt.ability_and_action + force-wield on entry
• interrupt.lua:46-49 — confirms interrupt kills ability + weapon action

[hummat]

Update: independent second opinion + milestone change

Ran a parallel investigation with a different model (via the Codex rescue path) to sanity-check my scope-exit call. Core finding survived — the BtBotInteractAction.enter hook cannot work — but the independent review surfaced an architecture I dismissed too quickly.

What the second opinion agreed on

• BtBotInteractAction.enter is unusable. PlayerCharacterStateInteracting.on_enter:39 calls Interrupt.ability_and_action("interacting", ...) which kills any in-flight ability or weapon action via interrupt.lua:46-49. The state also force-wields slot_unarmed (line 88) since the revive template has no wield_slot.
• Tier 1/2 combat abilities route through ability_extension and complete before the state transition; Tier 3 item sequences are weapon actions and don't escape the interrupt.
• The enter → revive-start window is 1–2 fixed-frame cycles.

What the second opinion surfaced that I missed

revive_ability.on_refresh_destination is already wired (revive_ability.lua:402-427) and fires during navigation to the downed ally, well before _has_reached_ally_aid_destination() flips true. Combined with gating bt_bot_conditions.can_revive to suppress interact-node entry while a Tier 3 sequence is mid-flight, this avoids the interrupt entirely — the bot stays in bt_bot_follow_action until the item sequence completes, then transitions to BtBotInteractAction.

Supporting precedent: item_fallback.lua:56-62 already ships LOCK_WEAPON_SWITCH_DURING_ITEM_SEQUENCE to gate the mod's weapon switcher by item-sequence state. The same gating pattern applies to can_revive.

Per-profile timing fits:

• force_field_instant: unwield_delay = 0.5, total ~2.5s (item_fallback.lua:92-101)
• drone_instant: unwield_delay = 1.1, total ~1.2s (item_fallback.lua:112-121)
• channel (zealot_relic): unwield_delay = 5.6, plus explicit slot locking — incompatible regardless of hook point; excluded from any proposed scope.

Risks the second opinion did not address

• Combat disruption during approach. Wielding slot_combat_ability while moving through the same corridor that downed the ally may itself get the bot hit or knocked down.
• Arbites drone placement. adamant_drone_buff_talent's revive-speed buff requires the drone's zone to overlap the downed ally. Placing the drone en route means the zone center is wherever the bot was during approach, not at the target.
• Navigation-arrival vs. sequence-completion race. The gate handles this in principle, but in practice the bot may arrive and idle next to a downed ally for 1–2 seconds while the sequence finishes, which is visibly weird.
• Per-class placement logic is bespoke. Shield needs LOS-to-enemy orientation, drone needs target-proximity ground placement, relic is self-centered (and excluded anyway).

Revised recommendation

Not "won't fix" — the architecture is real. But still not a Sprint 1 fit, and too large for Sprint 5 alongside #56/#96/#97/#101.

Move to Post-1.0. Captures the intent: implementation is viable, it just needs a proper workstream. Concrete plan if/when revisited:

1. Extend revive_ability.on_refresh_destination to start Tier 3 sequence when perception.target_ally_need_type == "knocked_down" and distance-to-target is within a placement-appropriate band.
2. Hook bt_bot_conditions.can_revive (via mod:hook) to return false while _fallback_state_by_unit[unit].item_stage indicates an in-flight Tier 3 sequence, with a timeout to abandon on stuck state.
3. Per-profile placement targeting: shield-at-ally-LOS, drone-at-target-ground-position. Relic excluded by its 5.6s unwield + slot lock.
4. Combat-pressure gate: skip Tier 3 activation if bot is under ranged fire during approach (existing _is_suppressed check extended to "hitting" signal).
5. Full validation surface: three classes × three item profiles × three rescue interaction types × ally-down scenarios under combat load.

Labels: keeping enhancement, P2: later, tier/class/area markers for future scoping. Milestone moves to Post-1.0.