Targeting, Hit Detection & Target Info

The key words MUST, MUST NOT, SHOULD, and MAY are used as in RFC 2119.

Weapon targeting and melee hit resolution share one geometry: the per-weapon hit cone, reverse-engineered from PSO:BB (check_enemy_is_targetable + ItemPMT; values tabulated at wiki.pioneer2.net/w/Weapons) and tuned in the #/combat-room web tool. Reticles, the target-info HUD, and damage all read the same cone — targeting and hits MUST NOT use different shapes.

The hit cone

Per weapon type (data: CombatManager.WEAPON_TYPE_CONFIGS, keys hit_h_dist, hit_v_dist, hit_h_angle_deg, hit_v_angle_deg):

• The cone's apex sits hit_v_dist behind the player along −facing (PSO's apex pull-back — widens point-blank coverage). The origin is the weapon position (player + ~1 m); targets are tested at their hitbox center.
• Reach from the apex is hit_h_dist + hit_v_dist + the target's own collision radius — a bigger enemy is easier to reach, exactly as in PSO.
• The horizontal half-angle is hit_h_angle_deg, tested in the XZ plane against the player's facing.
• The vertical half-angle hit_v_angle_deg bounds the slope from the apex (the angle between the flattened and the full 3D direction to the target, per the PSO:BB decompile); 90° means unbounded — PSO's launchers/cards.
• An enemy passes the cone iff the reach and both angle tests pass and it is alive.

Targetable set, primary target, reticles

• Each frame the player computes the targetable set: alive enemies passing the cone, sorted nearest-first. The nearest is the primary target.
• Reticles show on the nearest max_targets enemies (techniques MAY extend range/width/count as before; the Slicer keeps its bounce-target reticles).
• Ground items (DropBase, state available) are targetable for the HUD only: an item MUST NOT ever be hit by a swing, and target snap/aim assists MUST ignore items.
• Destructibles (boxes) ride the enemies group so they can be targeted, reticled, and smashed — but they carry no enemy_data, and when one is the primary target the info panel MUST NOT render (PSO shows no details for containers).

Hit resolution — the damaging frame

• A swing resolves its hits once, when the animation crosses the step's damaging frame (damaging_frac, a per-step fraction of the swing clip — data, per weapon type). Before that frame the swing MUST NOT damage anything; after it, later arrivals into the cone MUST NOT be hit by the same swing.
• At the damaging frame, melee hits the nearest max_targets enemies in the cone, applying the step's damage/knockback/element per the existing damage dict (hits_per_step hits each via Hurtbox.take_hit). Ranged weapon types fire their projectiles at the damaging frame instead.
• A damage interrupt before the damaging frame means the swing lands nothing — an interrupted swing does no damage (consistent with #377 commitment and the #428 lifetime invariant: exits from ATTACKING clear all pending offense).
• Replaced model: the old always-on Area3D box (active from swing start to step end) is retired for melee; the box config keys remain only for legacy consumers until they migrate.

Target-info HUD (bottom-left)

• The bottom-left HUD slot shows the primary target's info: an enemy → name + HP bar (live current_hp / max); a ground item → the item's display name.
• Precedence (PSO's split-reticle model): an enemy in the weapon cone always wins; an item is primary only when no enemy is targetable and the item is within ITEM_INFO_RANGE (2 m) inside the cone.
• Nothing to show → the panel MUST NOT render. No empty frame, no placeholder.
• The Quick Weapon Menu owns the corner: while it is open the target panel MUST NOT render (see Quick Weapon Menu — its behavior contract is unchanged; only its visual style is shared with this panel).
• The panel hides with the rest of the HUD for scene overlays / Start Menu (existing hide_for_menu behavior).

Visual style

Both the target panel and the quick weapon menu draw the PSZ panel language: a chamfered-corner plate with horizontal pinstripes and a navy border (light-blue plate for target info, navy plate for the menu), via the shared PszPanel draw helper. Style is SHOULD-level — tune freely; the visibility/priority rules above are the MUSTs.

Implemented by

• scripts/3d/combat/cone_targeting.gd (ConeTargeting) — the pure cone test (unit-tested directly).
• scripts/autoloads/combat_manager.gd — hit_h_dist / hit_v_dist / hit_h_angle_deg / damaging_frac per weapon type.
• scripts/3d/player/player.gd — _update_combat_targets (cone scan, primary + _primary_target_info), _handle_attack_state (damaging-frame trigger), _execute_attack_hit (melee cone hits / ranged projectiles).
• scripts/3d/field/field_hud.gd — _TargetInfoPanel + the restyled _QuickWeaponMenu; scripts/ui/psz_panel.gd (PszPanel).
• scripts/3d/elements/drop_base.gd — drops join the drops group for the HUD scan.

← Mechanics