summerengine/summer/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

3. Commit at fire time

# projectile_weapon.gd
 
func _spawn_projectile(dir: Vector3, target: Node3D) -> void:
    var dmg: float = base_damage * GameManager.player_damage_mult
    # Commit expected damage. No crit factor — we don't gamble on RNG. If crit
    # over-kills the target, the next-frame release refunds the difference.
    var commit_amount: float = dmg
    if target != null and target.has_method("commit_pending"):
        target.commit_pending(commit_amount)
    var proj: Node3D = _projectile_scene.instantiate()
    # ... add_child, position, etc ...
    proj.setup(dir * PROJECTILE_SPEED, dmg, ..., target, commit_amount)

4. Release at bullet death (catch-all)

The bullet must release the commitment exactly once when it leaves the tree, regardless of how. Hit, pierce-out, range-expire, or any other free path. Use tree_exiting so the release is guaranteed without each free-site having to remember.

# bullet.gd
 
var _committed_target: Node = null
var _committed_amount: float = 0.0
var _committed_released: bool = false
 
 
func setup(..., commit_target: Node = null, commit_amount: float = 0.0) -> void:
    # ... other setup ...
    _committed_target = commit_target
    _committed_amount = commit_amount
 
 
func _ready() -> void:
    # ... other wiring ...
    tree_exiting.connect(_release_committed)
 
 
## Idempotent so multiple call paths can't double-release.
func _release_committed() -> void:
    if _committed_released:
        return
    _committed_released = true
    if _committed_amount <= 0.0:
        return
    if _committed_target != null and is_instance_valid(_committed_target) \
            and _committed_target.has_method("release_pending"):
        _committed_target.release_pending(_committed_amount)

Bonus — spread fan across multiple enemies

When the weapon fires N projectiles per shot (extra-projectiles upgrade, multishot), pick a fresh target per projectile instead of fanning all N at the primary target. Combined with the saturation filter this drains follow-on shots toward fresh enemies.

# projectile_weapon.gd, multishot path
 
for i in total_projectiles:
    var per_shot_target := Targeting.pick(global_position, mode, range)
    if per_shot_target == null:
        per_shot_target = primary_target  # fall back if nothing else in range
    _spawn_projectile(dir.rotated(Vector3.UP, fan_angle), per_shot_target)

Bonus — bump projectile speed

The over-commit window is attack_speed * bullet_travel_time. Faster bullets shrink it for free. 22 m/s up to 35 m/s halves the window without affecting balance much. Cheap fix to bundle with the pattern.

What this does NOT solve

• Pierce > 1 weapons. The committed amount is reserved on the first target only. Subsequent pierces are bonus damage to whoever happens to be in line. That is fine — pierce already feels random by design.
• AOE / nova / orbital weapons. They hit everyone in radius regardless of "target," so single-target pending-damage doesn't apply. Skip them.
• Slow-but-massive weapons. A single shot that one-shots multiple enemies in sequence (rocket launcher, railgun) doesn't benefit much. The window where the over-commit happens is too short to matter.

Why this beats alternatives

Pending-damage is local to the targeting query, requires no per-bullet ticking, and keeps each weapon archetype's identity intact.

Verification

Test scenario: spawn a single weak enemy directly in front of the player at point-blank range. Equip the auto-fire weapon and the highest-attack-speed item. Watch the bullet fan when the enemy dies.

Before: 5-15 bullets continue past the corpse over the next ~0.5s. After: 1-2 bullets continue (the ones that were already past the half-flight point), the rest of the fire pool redirects to whatever target Targeting picks next, or stops if there's none in range.

Use summer_get_diagnostics to confirm no new errors.

summer_inspect_node will not show you pending_damage mid-fight. It reads the edited scene in the editor — the response even tags itself provenance: editor_scene — so it reports the saved node, not the live instance. Runtime values need a runtime read: with the game running, read the enemy with summer_inspect_runtime_node or summer_game_probe (engine builds with the runtime-control ops; see the agent-playtesting skill).

On any build, the RunVerification op, sent through summer_batch, also works. It spins up a hidden, disposable game instance that runs a GDScript probe and exits; it never touches the editor:

summer_batch(ops=[{
  "op": "RunVerification",
  "max_seconds": 20,
  "probe_source": "extends SummerProbeBase\nfunc _ready():\n\tawait super._ready()\n\t# spawn one enemy, fire at it, then:\n\treport('pending_damage', enemy.pending_damage)\n\tfinish()"
}])

Probe API: report(), save_frame(), press(), key(), finish(). Returns {ok, results, frames, out_dir}.

Do not reach for SimulateInput here. It is only reachable from the in-editor chat bridge; an MCP or CLI caller gets {ok: false, failure_reason: "unsupported_transport"} back. Drive input from inside the probe with press() / key() instead.

<!-- shell-commands: generated from the operation catalog by npm run generate:registry; do not edit by hand -->

From a shell

No Summer MCP tools in this session? Run each one as a command; when summer --version is missing or below 4.0, use npx -y summer-engine@latest in place of summer. Fields are flags in kebab-case (--scene-path res://main.tscn) or one --input '<json>', and summer ops describe <op> prints the exact input. The summer-cli skill has the rest.

<!-- /shell-commands -->