Return Fire -> Defensive firestance

gamedata/alldefs_post.lua

@@ -751,6 +751,28 @@ local function unitDef_Post(name, uDef)
 		end
 	end
 
+	-- Defend firestate: aircraft, long-range, starburst, and drone carrier units engage threats at any range in defend mode
+	-- regardless of calculated threat distance (see luarules/gadgets/unit_defend_firestate.lua).
+	--DEFEND FIRESTATE REWORK: Remove modoption guard; always set defend_never_hesitate for qualifying units
+	if modOptions.experimental_defend_firestate then
+		local DEFEND_NEVER_HESITATE_RANGE = 2000
+
+		if not customparams.defend_never_hesitate and next(weapondefs) then
+			for _, weaponDef in pairs(weapondefs) do
+				if not weaponDef.customparams.bogus then
+					if uDef.canfly
+						or weaponDef.weapontype == "StarburstLauncher"
+						or (weaponDef.range and weaponDef.range > DEFEND_NEVER_HESITATE_RANGE)
+						or (weaponDef.customparams.carried_unit and weaponDef.customparams.carried_unit ~= "")
+					then
+						customparams.defend_never_hesitate = true
+						break
+					end
+				end
+			end
+		end
+	end
+
 	-- Suppress engine default piece explosion effects (handled by gfx_death_fire_smoke_gl4 widget)
 	if not uDef.sfxtypes then
 		uDef.sfxtypes = {}

language/en/interface.json

@@ -265,7 +265,14 @@
 			"Fire at will": "Fire at will",
 			"Hold fire": "Hold fire",
 			"Return fire": "Return fire",
-			"firestate_tooltip": "Set under what conditions a unit should start firing at enemies (without explicit attack order)",
+			"Defend": "Defend",
+			"Fire at all": "Fire At All",
+			"firestate_hold_fire_descr": "Don't acquire targets without orders",
+			"firestate_return_fire_descr": "Return fire when attacked",
+			"firestate_defend_descr": "Fire upon enemies when they individually become a threat",
+			"firestate_fire_at_will_descr": "Fire upon enemies within range",
+			"firestate_fire_at_all_descr": "Fire upon anything belonging to the enemy within range",
+			"firestate_tooltip": "Set under what conditions a unit should start firing at enemies (without explicit attack order).",
 			"Hold pos": "Hold pos",
 			"Maneuver": "Maneuver",
 			"Roam": "Roam",
@@ -1683,7 +1690,7 @@
 				"unitidlebuildericons": "Unit idle builder icons",
 				"unitidlebuildericons_descr": "Shows a sleep icon above builder units that are idle.",
 				"unitfirestateicons": "Unit firing state icons",
-				"unitfirestateicons_descr": "Shows an icon above units that are either set on Hold Fire or Return Fire.",
+				"unitfirestateicons_descr": "Shows an icon above units that are either set on Hold fire or Defend.",
 				"resurrectionhalos": "Resurrected unit halos",
 				"resurrectionhalos_descr": "Adds halos above resurrected units.",
 				"nametags_rank": "Commander name tag rank icon",

luarules/gadgets.lua

@@ -1712,30 +1712,27 @@ end
 function gadgetHandler:AllowWeaponTarget(attackerID, targetID, attackerWeaponNum, attackerWeaponDefID, defPriority)
 	-- Calls with no input priority are pure pass/fail tests.
 	-- These are common, and BAR never disallows any of them.
-	if not defPriority then
-		return true -- The second return value is never used.
-	end
+	-- if not defPriority then
+	-- 	return true -- The second return value is never used.
+	-- end
 
 	local allowed = true
 	local result = 1.0
 
 	if targetID == -1 and attackerWeaponNum == -1 then
-		-- The `targetPriority` return value is actually the autotarget search radius,
+		-- The `defPriority` return value here is actually the autotarget search radius,
 		-- and applies to the unit's targeting search for its command AI, not weapons.
 		for _, g in ipairs(self.UnitAutoTargetRangeList) do
 			defPriority = g:UnitAutoTargetRange(attackerID, defPriority)
 		end
+
 		allowed, result = defPriority > 0, defPriority
 	else
 		-- The actual callin. BAR only uses AllowWeaponTarget for the target priority.
 		for _, g in ipairs(self.AllowWeaponTargetList) do
-			local targetPriority = g:AllowWeaponTarget(attackerID, targetID, attackerWeaponNum, attackerWeaponDefID, defPriority)
-			if targetPriority then
-				result = targetPriority
-			end
+			allowed, result = g:AllowWeaponTarget(attackerID, targetID, attackerWeaponNum, attackerWeaponDefID, defPriority)
 		end
 	end
-
 	return allowed, result
 end
 

luarules/gadgets/unit_aa_targeting_priority.lua

@@ -97,7 +97,8 @@ if gadgetHandler:IsSyncedCode() then
 	function gadget:AllowWeaponTarget(unitID, targetID, attackerWeaponNum, attackerWeaponDefID, defPriority)
 		local mult = airPriorityMultiplier[spGetUnitDefID(targetID)]
 		if mult then
-			return defPriority * mult
+			return true, (defPriority or 1.0) * mult
 		end
+		return true
 	end
 end

luarules/gadgets/unit_defend_firestate.lua

@@ -0,0 +1,249 @@
+--DEFEND FIRESTATE REWORK: Remove guard; defend targeting is always required
+if not Spring.GetModOptions().experimental_defend_firestate then
+	return
+end
+
+local gadget = gadget ---@type Gadget
+
+function gadget:GetInfo()
+	return {
+		name = "Firestate Defend",
+		desc = "Limits defend firestate to nearby targets",
+		author = "SethDGamre",
+		date = "2026.06.28",
+		license = "GNU GPL, v2 or later",
+		layer = 0,
+		enabled = true
+	}
+end
+
+if not gadgetHandler:IsSyncedCode() then
+	return false
+end
+
+--increase safety margin buffer so a pawn can walk through a minefield that's exposed
+
+local Firestates = VFS.Include("modules/firestates.lua")
+local WeaponThreat = VFS.Include("modules/weaponthreat.lua")
+local CMD_FIRE_STATE = CMD.FIRE_STATE
+local ALWAYS_SHOOT = WeaponThreat.ALWAYS_SHOOT
+local NO_THREAT = WeaponThreat.NO_THREAT
+local HP_CHECK_INTERVAL_FRAMES = Game.gameSpeed * 3
+local MIN_RADAR_DEFPRIORITY = 10000000 -- this is the floor of what a radar covered unit will generate for defpriorirty. If below this, it's certainly in LOS. For performance
+local UNIT_DEF_ID = 1
+local IS_DEFEND = 2
+local NEVER_HESITATE = 3
+local WEAPON_DEF_IDS = 4
+local LAST_HEALTH = 5
+local HP_CHECK_FRAME = 6
+local RADAR_AGGRO = 7
+local CLOAKED = 8
+local ALWAYS_HARMLESS = 9
+local defThreatRanges = {}
+local neverHesitateAttackers = {}
+local alwaysHarmlessUnitDefs = {}
+local weaponWatchRefCount = {}
+local watchedWeaponsByUnitDef = {}
+local metaData = {}
+local gameFrame = 0
+
+local spGetUnitDefID = Spring.GetUnitDefID
+local spGetUnitRulesParam = Spring.GetUnitRulesParam
+local spGetUnitIsCloaked = Spring.GetUnitIsCloaked
+local spGetAllUnits = Spring.GetAllUnits
+local spGetUnitHealth = Spring.GetUnitHealth
+local spGetUnitSeparation = Spring.GetUnitSeparation
+
+local function addWeaponWatches(weaponDefIDs)
+	for index = 1, #weaponDefIDs do
+		local weaponDefID = weaponDefIDs[index]
+		local refCount = (weaponWatchRefCount[weaponDefID] or 0) + 1
+		weaponWatchRefCount[weaponDefID] = refCount
+		if refCount == 1 then
+			Script.SetWatchAllowTarget(weaponDefID, true)
+		end
+	end
+end
+
+local function removeWeaponWatches(weaponDefIDs)
+	for index = 1, #weaponDefIDs do
+		local weaponDefID = weaponDefIDs[index]
+		local refCount = (weaponWatchRefCount[weaponDefID] or 0) - 1
+		if refCount <= 0 then
+			weaponWatchRefCount[weaponDefID] = nil
+			Script.SetWatchAllowTarget(weaponDefID, false)
+		else
+			weaponWatchRefCount[weaponDefID] = refCount
+		end
+	end
+end
+
+local function setDefendWatch(unitID, isDefend)
+	local meta = metaData[unitID]
+	if not meta then
+		return
+	end
+
+	if isDefend then
+		if meta[IS_DEFEND] then
+			meta[LAST_HEALTH] = spGetUnitHealth(unitID)
+			return
+		end
+
+		local unitDefID = meta[UNIT_DEF_ID]
+		local weaponDefIDs = watchedWeaponsByUnitDef[unitDefID]
+		meta[IS_DEFEND] = true
+		meta[NEVER_HESITATE] = neverHesitateAttackers[unitDefID] or false
+		meta[WEAPON_DEF_IDS] = weaponDefIDs
+		meta[LAST_HEALTH] = spGetUnitHealth(unitID)
+
+		if weaponDefIDs then
+			addWeaponWatches(weaponDefIDs)
+		end
+	elseif meta[IS_DEFEND] then
+		if meta[WEAPON_DEF_IDS] then
+			removeWeaponWatches(meta[WEAPON_DEF_IDS])
+		end
+		meta[IS_DEFEND] = nil
+		meta[WEAPON_DEF_IDS] = nil
+		meta[RADAR_AGGRO] = nil
+		meta[HP_CHECK_FRAME] = nil
+	end
+end
+
+local function checkDefendUnitHealth(attackerID, meta)
+	local nextCheckFrame = meta[HP_CHECK_FRAME]
+	if nextCheckFrame and gameFrame < nextCheckFrame then
+		return
+	end
+
+	local currentHealth = spGetUnitHealth(attackerID)
+	if not currentHealth then
+		return
+	end
+
+	local lastHealth = meta[LAST_HEALTH]
+	if lastHealth and currentHealth < lastHealth then
+		meta[RADAR_AGGRO] = true
+	elseif lastHealth and currentHealth > lastHealth then
+		meta[RADAR_AGGRO] = nil
+	end
+
+	meta[LAST_HEALTH] = currentHealth
+	meta[HP_CHECK_FRAME] = gameFrame + HP_CHECK_INTERVAL_FRAMES
+end
+
+local function updateDefendWatchFromRulesParam(unitID)
+	local state = spGetUnitRulesParam(unitID, Firestates.RULES_PARAM)
+	setDefendWatch(unitID, state == Firestates.DEFEND)
+end
+
+local function createUnitMeta(unitDefID)
+	local meta = { [UNIT_DEF_ID] = unitDefID }
+	if alwaysHarmlessUnitDefs[unitDefID] then
+		meta[ALWAYS_HARMLESS] = true
+	end
+	return meta
+end
+
+function gadget:UnitCommand(unitID, unitDefID, unitTeamID, cmdID, cmdParams, cmdOptions, cmdTag, playerID, fromSynced, fromLua)
+	if cmdID == CMD_FIRE_STATE then
+		updateDefendWatchFromRulesParam(unitID)
+	end
+end
+
+function gadget:UnitCreated(unitID, unitDefID, unitTeam)
+	metaData[unitID] = createUnitMeta(unitDefID)
+end
+
+function gadget:UnitFinished(unitID, unitDefID, unitTeam)
+	updateDefendWatchFromRulesParam(unitID)
+end
+
+function gadget:UnitCloaked(unitID, unitDefID, unitTeam)
+	local meta = metaData[unitID]
+	if meta then
+		meta[CLOAKED] = true
+	end
+end
+
+function gadget:UnitDecloaked(unitID, unitDefID, unitTeam)
+	local meta = metaData[unitID]
+	if meta then
+		meta[CLOAKED] = nil
+	end
+end
+
+function gadget:UnitDestroyed(unitID, unitDefID, unitTeam)
+	local meta = metaData[unitID]
+	if meta and meta[WEAPON_DEF_IDS] then
+		removeWeaponWatches(meta[WEAPON_DEF_IDS])
+	end
+	metaData[unitID] = nil
+end
+
+function gadget:GameFrame(frame)
+	gameFrame = frame
+end
+
+function gadget:AllowWeaponTarget(attackerID, targetID, attackerWeaponNum, attackerWeaponDefID, defPriority)
+	local targetMeta = metaData[targetID]
+	if not targetMeta then
+		return false
+	end
+
+	local attackerMeta = metaData[attackerID]
+	local isDefend = attackerMeta and attackerMeta[IS_DEFEND]
+
+	if targetMeta[ALWAYS_HARMLESS] then
+		return not isDefend
+	end
+
+	if not isDefend then
+		return true
+	end
+
+	local rangesForWeapon = defThreatRanges[attackerWeaponDefID]
+	if not rangesForWeapon then
+		return true
+	end
+
+	local threatRange = rangesForWeapon[targetMeta[UNIT_DEF_ID]]
+	if not threatRange or threatRange == NO_THREAT then
+		return false
+	end
+
+	if attackerMeta[CLOAKED] then
+		return false
+	end
+
+	if attackerMeta[NEVER_HESITATE] then
+		return true
+	end
+
+	if (defPriority or 0) > MIN_RADAR_DEFPRIORITY then
+		checkDefendUnitHealth(attackerID, attackerMeta)
+		return attackerMeta[RADAR_AGGRO] or false
+	end
+
+	if threatRange == ALWAYS_SHOOT then
+		return true
+	end
+
+	local separation = spGetUnitSeparation(attackerID, targetID)
+	return not separation or separation <= threatRange
+end
+
+function gadget:Initialize()
+	defThreatRanges, watchedWeaponsByUnitDef, neverHesitateAttackers, alwaysHarmlessUnitDefs = WeaponThreat.buildDefendData()
+
+	for _, unitID in ipairs(spGetAllUnits()) do
+		local unitDefID = spGetUnitDefID(unitID)
+		local meta = createUnitMeta(unitDefID)
+		metaData[unitID] = meta
+		updateDefendWatchFromRulesParam(unitID)
+		if spGetUnitIsCloaked(unitID) then
+			meta[CLOAKED] = true
+		end
+	end
+end