auto-fire-targeting

Auto-Fire Weapon Targeting — pending-damage pattern

A survivors-genre auto-fire weapon picks a target each fire frame. Naive nearest-enemy targeting wastes bullets when fire rate exceeds bullet flight time. This skill encodes the pending-damage pattern that fixes it.

The problem

Auto-fire weapon. Bullet speed 22 m/s. Target 10m away. Bullet takes ~0.45s to arrive. With high attack speed the player fires several bullets per second. By the time the first bullet arrives and kills the target, several more bullets are already in flight toward where the target was. They miss into empty space. The player sees bullets "fan out in a cone past the dead enemy" while other enemies stand around untouched.

This is not a re-targeting bug. The weapon's _fire() correctly re-runs find_nearest_enemy() each shot. The issue is that the target is alive at fire-time and dead at arrival-time. All shots fired in that window aim at it because none of them know about the kill in flight.

The fix — pending damage commitment

Each enemy carries a counter of damage that is in flight toward it. Targeting de-prefers (but does not exclude) enemies whose pending damage already exceeds their current HP.

1. Add the counter to the enemy base class

# enemy_base_3d.gd

var pending_damage: float = 0.0


func commit_pending(amount: float) -> void:
    pending_damage += amount


func release_pending(amount: float) -> void:
    pending_damage = maxf(0.0, pending_damage - amount)


## True if enough damage is already in flight to kill this enemy.
func is_saturated() -> bool:
    return pending_damage >= health

2. Update the targeting helper

The selector keeps the saturated set as a fallback. If every enemy is saturated, the player must still be able to fire on someone — fall through to a normal nearest pick across saturated enemies. Otherwise prefer non-saturated.

# targeting.gd

static func pick(origin: Vector3, mode: int, max_range: float, ...) -> Node3D:
    var enemies: Array = GameManager.get_enemies()
    var best: Node3D = null
    var best_score: float = -INF
    var fallback: Node3D = null
    var fallback_score: float = -INF
    for enemy in enemies:
        # ... existing range + LoS filters ...
        var score := _score(enemy, d_sq, mode)
        var saturated: bool = "is_saturated" in enemy and enemy.is_saturated()
        if saturated:
            if score > fallback_score:
                fallback_score = score
                fallback = enemy
        else:
            if score > best_score:
                best_score = score
                best = enemy
    if best != null:
        return best
    return fallback  # everyone is saturated; fire on the next-best anyway