Talent-aware bot behavior: Zealot Martyrdom as proof-of-concept

[hummat]

Summary

Teach bots to adapt their playstyle based on equipped keystones, starting with Zealot Martyrdom as proof-of-concept. A Martyrdom Zealot should stay at low health (where it gets up to +50% melee damage, +50% attack speed, -37.5% toughness DR) and refuse healing that would remove those stacks.

Requires Tertium 5/6 — vanilla bots have talents = {} and never have keystones.

Background: How Martyrdom Works

• Passive keystone — always active, no activation needed
• Grants stacking bonuses per missing health segment (max 5 stacks):
  • Base: +10% melee damage per stack (max +50%)
  • Optional modifier: +10% melee attack speed per stack (max +50%)
  • Optional modifier: -7.5% toughness damage taken per stack (max -37.5%)
  • Optional modifier: +0.1 ability CDR per stack per second (max +0.5/s)
• Internal buff: zealot_martyrdom_base
• Talent ID: zealot_martyrdom

Detection API

-- Option A: Check talent table (requires Tertium 5/6 to populate talents)
local talent_ext = ScriptUnit.has_extension(unit, "talent_system")
local talents = talent_ext and talent_ext:talents() or {}
local has_martyrdom = talents["zealot_martyrdom"] ~= nil

-- Option B: Check active buff stacks (works if buff is running)
local buff_ext = ScriptUnit.has_extension(unit, "buff_system")
local has_martyrdom = buff_ext and buff_ext:current_stacks("zealot_martyrdom_base") > 0

-- Stack count (for threshold scaling)
local health_ext = ScriptUnit.extension(unit, "health_system")
local max_wounds = health_ext:max_wounds()
local damage_taken = health_ext:damage_taken()
local permanent_damage = health_ext:permanent_damage_taken()
local max_health = health_ext:max_health()
local current_wounds = Health.calculate_num_segments(
    math.max(damage_taken, permanent_damage), max_health, max_wounds
)
local martyrdom_stacks = math.min(max_wounds - current_wounds, 5)

API notes:

• zealot_martyrdom_grants_ally_power_bonus is a modifier talent special rule, NOT the base keystone — don't use it for base detection
• buff_extension:has_buff_name() does not exist — use current_stacks() instead
• Health.damage_taken_percent() does not exist — use 1 - Health.current_health_percent(unit)

Gracefully degrades: vanilla bots and non-Zealots get false, no error.

Implementation Plan

1. Talent detection in build_context()

local talent_ext = ScriptUnit.has_extension(unit, "talent_system")
local talents = talent_ext and talent_ext:talents() or {}
ctx.has_martyrdom = talents["zealot_martyrdom"] ~= nil

2. Suppress healing

Bot healing uses three independent subsystems. Martyrdom bots should opt out of the first two:

System	What it does	Where tracked	Hook target	Martyrdom behavior
Health stations	Fixed level objects (medicae stations)	_update_health_stations() in bot_behavior_extension.lua sets needs_health = true	Hook _update_health_stations	Skip needs_health = true — Martyrdom bot never queues, freeing charges for others
Deployed med-crates	Medical crates placed on ground by players	BotGroup._update_pickups_and_deployables_near_player() sets pickup_component.health_deployable	Hook the bot_group function or clear health_deployable after assignment	Skip — don't interact with deployed med-crates
Pocketable pickups	Med-kits / wound cures carried in inventory	BotGroup._update_mule_pickups() sets pickup_component.mule_pickup	Hook _update_mule_pickups or filter by slot	Allow wound cures (slot_pocketable_small / syringe_corruption_pocketable), block med-kits (slot_pocketable / medical_crate_pocketable)

Wound cure exception: Wound cures heal corruption (heal_types.blessing_syringe), not green health. Martyrdom wants low green health but NOT high corruption — corruption reduces max health segments, which reduces available Martyrdom stacks. Wound cures should remain allowed.

Distinguishing med-kits from wound cures: Different pickup templates and inventory slots:

• Med-kit: medical_crate_pocketable, slot slot_pocketable
• Wound cure: syringe_corruption_pocketable, slot slot_pocketable_small

3. Adjust heuristic thresholds

Current Zealot heuristics treat low health as emergency → defensive ability use. Martyrdom inverts this:

Heuristic	Current behavior	Martyrdom adjustment
zealot_dash	Activates at toughness < 30% (defensive)	Keep — toughness recovery is still valuable at low health
zealot_invisibility	Emergency at health < 25%	Raise threshold or disable health-based panic — low health is intended
zealot_relic	Team toughness support	No change — team utility unrelated to Martyrdom

The key change: don't treat low health as a crisis. A Martyrdom Zealot at 20% health with 5 stacks is at peak performance, not in danger.

4. Follow-up: cross-bot Martyrdom awareness

Current heuristics don't inspect ally health — ogryn_taunt keys off target_ally_needs_aid (a perception/disable signal, not "ally is low HP"). So there's no immediate risk of other bots panic-rescuing a low-health Martyrdom Zealot.

If future heuristics add ally-health checks (e.g. #10 rescue dash), they should exclude Martyrdom Zealots from the "allies in trouble" calculation. This is a follow-up concern, not part of the initial implementation.

5. Optional: prefer melee

All Martyrdom bonuses are melee-only. Could bias weapon selection toward melee when stacks are high, but this is a stretch goal — the existing BT melee/ranged switching works acceptably.

Future: Other Keystones

This establishes a talent-aware framework that can extend to:

Keystone	Class	Behavioral change	Detection
Martyrdom	Zealot	Don't heal, fight at low HP	talents["zealot_martyrdom"] or current_stacks("zealot_martyrdom_base") > 0
Alt Peril Explosion	Psyker	Higher peril tolerance (no knockdown)	has_special_rule("psyker_no_knock_down_overload")
Discharge Debuff	Psyker	Gate Shout behind safety window (+10% dmg taken for 8s)	has_special_rule("psyker_discharge_damage_debuff")
Chemical Dependency	Broker	Spam abilities to maintain stacking buff	has_special_rule("broker_keystone_chemical_dependency_sub_1_crit_chance")
Adrenaline Junkie	Broker	Melee-weighted, chain abilities during Frenzy	has_special_rule("broker_keystone_adrenaline_junkie_extra_killing_blow_stacks")
Carapace Armor	Ogryn	Stack management via Charge/Taunt timing	has_special_rule("ogryn_carapace_armor_explosion_on_zero_stacks")

Start with Martyrdom as the simplest (binary "don't heal" rule), then extend the framework.

Scope & Constraints

• Tertium-only: Vanilla bots have talents = {}. Graceful degradation — feature simply doesn't activate.
• No new modules needed: Talent check in build_context(), healing hooks in BetterBots.lua, heuristic adjustments in heuristics.lua.
• No mod settings needed initially: Auto-detect from talent. Could add a manual override toggle later ("Force Martyrdom playstyle" for vanilla bot users).
• Testing: Unit tests can mock talent_extension in build_context(). In-game validation requires Tertium 5/6 + Zealot with Martyrdom equipped.

Acceptance Criteria

• Martyrdom Zealot bot does not use health stations
• Martyrdom Zealot bot does not interact with deployed med-crates
• Martyrdom Zealot bot does not pick up pocketable med-kits
• Martyrdom Zealot bot DOES pick up wound cures (corruption healing)
• zealot_invisibility does not panic-activate at low health when Martyrdom is active
• Non-Martyrdom Zealots and other classes are unaffected
• Vanilla bots (no Tertium) are unaffected — no errors, no behavior change
• build_context() includes has_martyrdom field
• Unit tests cover Martyrdom detection and healing suppression logic

[hummat]

Related: Scrier's Gaze peril venting conflict

The current BetterBots peril management (overheat bridge in weapon_action.lua) makes the BT vent node fire for warp weapons at 50–99% peril. This is correct for most Psyker builds, but actively harmful for Scrier's Gaze builds that run Warp Ghost + Warp Splitting + Warp Rider.

These builds intentionally sustain high peril for stacking damage/crit/DR buffs. The Gandalf build (nomalarkey) explicitly says: "Warp Ghost enables you to nearly permanently run at high peril maximizing the buffs from Warp Splitting, One with the Warp, and Warp Rider." Venting drops peril → loses all three buff tiers.

What needs to happen

Add to the keystone detection table in the issue body:

Keystone	Class	Behavioral change	Detection
Warp Ghost / Warp Splitting	Psyker	Suppress peril venting during Scrier's Gaze (high peril is intentional)	talents["psyker_warp_ghost"] or talents["psyker_warp_split"]

This is separate from the "Alt Peril Explosion" row already listed — that's about no-knockdown tolerance, this is about vent suppression when high peril is a buff source.

Severity

Without this, a Scrier's Gaze bot with the overheat bridge active will:

1. Pop Scrier's → peril rises → crosses 50% BT vent threshold → bot vents → loses Warp Splitting/Rider buffs → damage drops
2. Repeat every cycle, making the stance significantly weaker than intended

The 97% weapon action gate is fine (prevents explosion), but the vent node firing at 50% is the problem. A talent-aware override could raise the vent threshold to ~90% when Warp Ghost is equipped, or suppress venting entirely during active Scrier's Gaze.

[hummat]

Update from #45 investigation (2026-03-15)

Key discovery: talents = {} in vanilla bot profiles is a design choice, not a hard engine constraint. When Tertium passes real backend profiles with populated talents tables, the engine processes them fully — passive bonuses, ability modifications, everything.

This means #38 has two complementary paths:

1. Write talents into profiles (Enrich bot profiles with talents and weapon blessings #63) — populate profile.talents with talent selections from hadrons-blessing builds. Gives bots passive bonuses without any runtime detection.
2. Read talents at runtime (this issue) — detect equipped talents via talent_extension:talents() to adjust heuristic thresholds (e.g. Martyrdom → suppress healing).

Path 1 is a prerequisite for path 2 when using BetterBots' built-in profiles (without Tertium). With Tertium, path 2 can read the player's real talents directly.

Talent format: { [talent_name_string] = tier_number } — flat table, simple to populate from hadrons-blessing build data.

[hummat]

Pre-work: heuristics.lua split plan

As of v0.10.0-dev (750 tests, 30 modules), file size analysis shows heuristics.lua at 1953 lines — the largest file in the mod. It holds 18 _can_activate_* functions, build_context(), and the dispatch table.

Current state (top 5 by size)

File	Lines	Status
heuristics.lua	1953	Split before #38
grenade_fallback.lua	1176	OK (cohesive state machine)
BetterBots.lua	1133	Watch (wiring hub)
bot_profiles.lua	944	OK
item_fallback.lua	910	OK

Why split before #38

Talent-aware heuristics will add per-talent branching inside each _can_activate_* function (e.g., Martyrdom low-HP aggression for Zealot). This could easily double the file size. Splitting first keeps the diff reviewable and the per-class files independent.

Proposed split

1. heuristics_context.lua — build_context() + shared helpers (enemy counting, ally state)
2. Per-class heuristic files — heuristics_veteran.lua, heuristics_zealot.lua, heuristics_psyker.lua, heuristics_ogryn.lua, heuristics_arbites.lua, heuristics_hive_scum.lua
3. heuristics.lua — thin dispatch: template name → class file → function. Keeps the public API (resolve_decision, evaluate_heuristic) unchanged.

The per-class split maps naturally to the existing function grouping and to the per-class talent trees that #38 introduces.

Not splitting

• BetterBots.lua — the single-file wiring hub is easy to grep; splitting would scatter dependency info
• grenade_fallback.lua — cohesive state machine, splitting would scatter related states