class_name WeaponShot
extends Resource


@export_group("Weapon")


# Human-readable name for reference in UI and logs.
@export var shot_name: String

# PackedScene reference to the bullet / projectile scene instantiated on fire.
@export var bullet_scene: PackedScene

# Icon used when this weapon appears as a powerup pickup on the field.
@export var pickup_icon: Texture2D


@export_subgroup("Launch")


# Damage dealt by a single projectile instance.
@export_range(1, 100, 1) var damage: int = 1

# Travel speed of projectiles in pixels per second.
@export_range(50, 2000, 10) var speed: int = 135

# Number of projectiles fired in a burst pattern.
@export_range(1, 20, 1) var projectiles: int = 2


@export_subgroup("Spawn Geometry")


# Vertical spacing between projectiles in a burst (used by WeaponFireHelper to compute the ^ pattern).
# This parameter has a dual role: spatial (computing the ^ burst geometry) and temporal
# (serving as the burst-gating threshold in ShootComponent.shoot()). When compensate_spawn_geometry
# is enabled, this parameter is overridden by geometric compensation for spatial calculations;
# temporal behavior remains unchanged and continues to use this value.
@export_range(10, 200, 0.5) var projectile_vertical_spacing: float = 35

# Vertical offset from the top of the player's sprite where bullets spawn.
# Measured in pixels; negative values fire in front of (above) the ship,
# positive values fire behind (below) it. The default of -25 places the
# burst 25 pixels above the sprite's top edge.
@export_range(-200, 200, 0.5) var origin: float = -25.0


@export_subgroup("Spread")


# Horizontal distance between adjacent projectiles in a burst.
@export_range(0, 100, 0.25) var horizontal_offset: float = 6.5

# Total spread angle in degrees (only applied when projectiles >= 3).
@export_range(0, 360, 0.5) var spread_angle: float = 0.0

# Time delay per projectile index in a burst.
@export_range(0.01, 5.0, 0.05) var stagger_offset: float = 0.25

# When enabled, adjusts spawn vertical offsets so the geometric line
# from the center bullet to each outer bullet matches their velocity
# direction. Eliminates the optical illusion where the spread appears
# wider than the actual bullet trajectories (e.g. vanguard+). See the
# Debugging Checklist for the vertical offset pitfall on standard shots.
## WARNING: This flag uses a trigonometric formula (horizontal_offset / tan(angle)) that evaluates independently-tuned horizontal and spread angles in grouped shots ONLY!
@export var compensate_spawn_geometry: bool = false


@export_subgroup("Timing")


# Offset animation playback per projectile index.
@export var stagger_animation: bool = false


@export_subgroup("Effects")


# Rotate projectiles to point along their travel direction (requires >2 projectiles and spread_angle > 0).
@export var follow_angle: bool = false


@export_subgroup("Groups")


# Array of projectile groups defining layered, multi-directional fire patterns.
@export var groups: Array[WeaponProjectileGroup] = []


@export_subgroup("Power & Composition")


# The power level at which this weapon becomes active.
# Weapons with power_level <= current power level are considered active.
@export_range(0, 20, 1) var power_level: int = 0

# If true, collecting this weapon removes any existing weapon whose
# power_level matches this weapon's power_level. Use this instead of
# force_replace_all for rank-up replacements (e.g. stock → tri → spread).
@export var replaces_at_same_level: bool = false

# If true, this weapon replaces ALL active weapons (ignores power_level).
# Used for rank-based transformations where the entire arsenal changes.
@export var force_replace_all: bool = false