extends CharacterBody3D

# Hoof positions in bull local space — dust emitter offsets
const HOOF_OFFSETS: Array = [
	Vector3(-0.30, -0.25, -0.50),
	Vector3( 0.30, -0.25, -0.50),
	Vector3(-0.30, -0.25,  0.60),
	Vector3( 0.30, -0.25,  0.60),
]

# Bull animation clips (Armature|* action names in art/characters/bull.fbx). IDLE is the
# looping base pose; the others are one-shot ability clips that return to it.
const _ANIM_IDLE: StringName = &"Armature|IDLE"
const _ANIM_KICK: StringName = &"Armature|KICK"
const _ANIM_SLAM: StringName = &"Armature|SLAM"
const _ANIM_DASH: StringName = &"Armature|DASH"
const _ANIM_WALK: StringName = &"Armature|WALK"
const _ANIM_ROLL: StringName = &"Armature|ROLL"
const _ANIM_DEATH: StringName = &"Armature|DEATH"

@onready var camera_pivot: Node3D = $Camera3D
@onready var cube_guy:     Node3D = $bull

var _hoof_emitters: Array[CPUParticles3D] = []
var _legs: Node

var _was_on_floor: bool         = false
var _pre_slide_vel_y: float     = 0.0

# Built once and reused: a fresh StandardMaterial3D/SphereMesh per spawn makes a mobile WebGL
# driver recompile the shader + re-upload the mesh — a hitch "when attacking" absent on desktop.
var _unshaded_mat: StandardMaterial3D = null
var _particle_sphere_cache: Dictionary = {}   # "radius:seg:ring" -> SphereMesh (shared)
var _impact_fx: Node = null   # bull_impact_fx.gd — the coded (non-particle) slam rings + kick flash

# Ability system — kick=0, dash=1, slam=2, roll=3
var ability_cd:      Array[float] = [0.0, 0.0, 0.0, 0.0]
var _ability_active: bool         = false
var _ability_timer:  float        = 0.0
var _active_ability: int          = -1
var _dash_dir:       Vector3      = Vector3.ZERO
var _dash_speed_cur: float        = 0.0
var _roll_dir:       Vector3      = Vector3.ZERO
var _roll_ramp:      float        = 0.0
var _roll_spin:      float        = 0.0
var _roll_target:    Node3D       = null
var _roll_chains_left: int        = 0
var _roll_hit:       Array[Node]  = []
var _bull_anim:      AnimationPlayer = null
# Locomotion animation state: true while the looping DASH clip is driving WASD
# movement, false while idling. Flipping it cross-fades between the two clips.
var _locomotion_moving: bool = false

var _slam_pending: bool = false
var _charge_trail_emitter: CPUParticles3D = null
var _roll_spark_emitter:   CPUParticles3D = null
var _cube_scale: Vector3 = Vector3.ONE

# One clean hit ends the run — see take_sword_hit(). The HUD listens for `died`
# to raise the lose screen (the `cause` tags how it happened, for the death notice);
# _dead latches so a flurry of hits fires it only once.
signal died(cause: String)
var _dead: bool = false

# HP system — the bull soaks several clean hits instead of dying to the first.
# Each landed blade drops one pip and starts an i-frame window (so one pass can't
# empty the bar); at 0 the run ends via `died`. The HUD listens on `health_changed`.
signal health_changed(current: int, max_hp: int)
# Fired on every landed hit (after i-frames pass) so the HUD can flash the damage
# vignette; `cause` mirrors take_sword_hit ("gored" / "thrown").
signal hit_taken(cause: String)
var _max_hp:      int   = 10
var _hp:          int   = 10
# Bonus pips granted by lobby rewards (e.g. smashing every barrel). Tacked on top of the
# base bar; the HUD paints these top pips yellow instead of red.
var _bonus_hp:    int   = 0
var _hit_iframes: float = 0.0

var _huff_player:     AudioStreamPlayer   = null
var _crowd_player:    AudioStreamPlayer   = null
var _huff_timer:      float               = 0.0

enum DustState { NONE, WALK, CHARGE }
var _dust_state: DustState = DustState.NONE
# Hoof-dust scale/velocity per state (the look — mesh, colour, curve — lives in bull_hoof_dust.tscn).
# A charge sprint kicks up bigger, faster dust than a walk.
const _WALK_DUST_SCALE:   Vector2 = Vector2(0.20, 0.40)
const _WALK_DUST_VEL:     Vector2 = Vector2(0.8, 1.8)
const _CHARGE_DUST_SCALE: Vector2 = Vector2(0.35, 0.70)
const _CHARGE_DUST_VEL:   Vector2 = Vector2(2.8, 5.5)


const RigidSkin = preload("res://systems/render/rigid_skin.gd")

var _hit_flash_tween: Tween


func _ready() -> void:
	add_to_group(&"player")
	# Native GPU skinning by default (the old Mali/ANGLE invisible-skinning bug is fixed in the
	# 4.7 web templates). rigid_skin is now an opt-in fallback — see Controls.rigid_skin_enabled().
	if Controls.rigid_skin_enabled():
		RigidSkin.convert_tree(self)
	_max_hp = maxi(1, int(DP.f("bull_max_hp")))
	_hp = _max_hp
	# Carry any run-long bonus pips (barrel reward) into this level so they survive the
	# scene reload between fights; the HUD paints these top pips yellow.
	_bonus_hp = Run.bonus_hp
	_max_hp += _bonus_hp
	_hp += _bonus_hp
	_cube_scale = cube_guy.scale
	_setup_impact_fx()
	_setup_hoof_dust()
	_setup_legs()
	_setup_charge_trail()
	_setup_roll_sparks()
	_setup_audio()
	_bull_anim = _find_anim_player(cube_guy)
	_setup_bull_idle()


func _setup_legs() -> void:
	_legs = Node.new()
	_legs.set_script(load("res://actors/player/bull_legs.gd"))
	add_child(_legs)
	_legs.call(&"setup", self, cube_guy)


func _setup_impact_fx() -> void:
	_impact_fx = Node.new()
	_impact_fx.set_script(load("res://actors/player/bull_impact_fx.gd"))
	add_child(_impact_fx)
	_impact_fx.call(&"setup", self)


# The bull's ability/movement particle effects are authored as scenes in systems/fx/ (so Siim can
# tune them in the inspector). The continuous ones follow the bull — instanced once here as
# children, then toggled via `emitting`. The one-shots are fired on demand through Fx.spawn().
func _setup_hoof_dust() -> void:
	for offset: Vector3 in HOOF_OFFSETS:
		var p := Fx.attach(&"bull_hoof_dust", cube_guy) as CPUParticles3D
		if p == null:
			continue
		p.position = offset
		_hoof_emitters.append(p)


func _setup_charge_trail() -> void:
	_charge_trail_emitter = Fx.attach(&"bull_charge_trail", cube_guy) as CPUParticles3D
	if _charge_trail_emitter != null:
		_charge_trail_emitter.position = Vector3(0.0, 0.25, 0.3)


func _setup_roll_sparks() -> void:
	_roll_spark_emitter = Fx.attach(&"bull_roll_sparks", cube_guy) as CPUParticles3D
	if _roll_spark_emitter != null:
		_roll_spark_emitter.position = Vector3(0.0, 0.10, 0.0)


func _setup_audio() -> void:
	if ResourceLoader.exists("res://sounds/bull_huff.ogg"):
		_huff_player = AudioStreamPlayer.new()
		_huff_player.stream = load("res://sounds/bull_huff.ogg")
		_huff_player.volume_db = 0.0
		_huff_player.bus = &"Effects"
		add_child(_huff_player)
	if ResourceLoader.exists("res://sounds/crowd_ambient.ogg"):
		_crowd_player = AudioStreamPlayer.new()
		var s := load("res://sounds/crowd_ambient.ogg") as AudioStreamOggVorbis
		if s:
			s.loop = true
		_crowd_player.stream = s
		_crowd_player.volume_db = -14.0
		_crowd_player.autoplay = true
		_crowd_player.bus = &"Ambient"
		add_child(_crowd_player)


# Toggle the hoof emitters and swap their scale/velocity for the walk vs charge feel. The blue
# charge trail is the roll/dash ability's, driven from the roll loop, not by dust state.
func _set_dust_state(new_state: DustState) -> void:
	if new_state == _dust_state:
		return
	_dust_state = new_state
	var scale := _CHARGE_DUST_SCALE if new_state == DustState.CHARGE else _WALK_DUST_SCALE
	var vel := _CHARGE_DUST_VEL if new_state == DustState.CHARGE else _WALK_DUST_VEL
	for p: CPUParticles3D in _hoof_emitters:
		p.scale_amount_min = scale.x
		p.scale_amount_max = scale.y
		p.initial_velocity_min = vel.x
		p.initial_velocity_max = vel.y
		p.emitting = new_state != DustState.NONE


func _find_anim_player(node: Node) -> AnimationPlayer:
	if node is AnimationPlayer:
		return node as AnimationPlayer
	for child: Node in node.get_children():
		var r := _find_anim_player(child)
		if r:
			return r
	return null


# IDLE ships one-shot; make it loop and start it so the bull breathes at rest
# instead of freezing on a bind pose. It's the base every ability blends back to.
func _setup_bull_idle() -> void:
	if _bull_anim == null:
		return
	# IDLE, DASH and ROLL loop as continuous states (DASH doubles as the WASD
	# locomotion cycle); the remaining ability clips are one-shot.
	for clip: StringName in [_ANIM_IDLE, _ANIM_DASH, _ANIM_ROLL]:
		if _bull_anim.has_animation(clip):
			_bull_anim.get_animation(clip).loop_mode = Animation.LOOP_LINEAR
	_play_idle()


# Return to the looping idle (and undo any ability speed-scale). Cross-fades so a
# finishing ability clip eases back to idle instead of snapping.
func _play_idle() -> void:
	_locomotion_moving = false
	if _bull_anim == null:
		return
	_bull_anim.speed_scale = 1.0
	if _bull_anim.has_animation(_ANIM_IDLE):
		_bull_anim.play(_ANIM_IDLE, 0.05)


# Drive the WASD locomotion clip: the looping DASH doubles as the run cycle while a
# direction is held, easing back to idle when the bull coasts to a stop. Cross-fades
# on each transition so idle↔run (and steering into it after an ability) blend rather
# than snap. Abilities own the animation while active, so this yields to them.
func _update_locomotion_anim(moving: bool) -> void:
	if _ability_active or _bull_anim == null or moving == _locomotion_moving:
		return
	_locomotion_moving = moving
	if moving:
		if _bull_anim.has_animation(_ANIM_WALK):
			_bull_anim.speed_scale = 2.0
			_bull_anim.play(_ANIM_WALK, 1)
			var anim = _bull_anim.get_animation(_ANIM_WALK)
			anim.loop_mode = Animation.LOOP_LINEAR
	else:
		_play_idle()


func _unhandled_input(event: InputEvent) -> void:
	if _dead:
		return
	# Abilities can be chained: a new one interrupts whatever is currently
	# active, gated only by each ability's own cooldown.
	if event.is_action_pressed(&"ability_kick"):
		try_activate_ability(0)
	elif event.is_action_pressed(&"ability_dash"):
		try_activate_ability(1)
	elif event.is_action_pressed(&"ability_slam"):
		try_activate_ability(2)
	elif event.is_action_pressed(&"ability_roll"):
		try_activate_ability(3)


# Public ability entry point shared by keyboard/gamepad input and the on-screen
# touch buttons. Slot order matches ability_cd — kick=0, dash=1, slam=2, roll=3.
# No-ops if the bull is dead or the slot is still cooling down.
func try_activate_ability(slot: int) -> void:
	if _dead or slot < 0 or slot >= ability_cd.size() or ability_cd[slot] > 0.0:
		return
	match slot:
		0: _activate_kick()
		1: _activate_dash()
		2: _activate_slam()
		3: _activate_roll()


func ability_cooldown_fraction(slot: int) -> float:
	var maxcd := 0.0
	match slot:
		0: maxcd = DP.f("kick_cooldown")
		1: maxcd = DP.f("dash_cooldown")
		2: maxcd = DP.f("slam_cooldown")
		3: maxcd = DP.f("roll_cooldown")
	return ability_cd[slot] / maxcd if maxcd > 0.0 else 0.0


func ability_cooldown_remaining(slot: int) -> float:
	return ability_cd[slot]


func _activate_kick() -> void:
	ability_cd[0]   = DP.f("kick_cooldown")
	_ability_active = true
	_active_ability = 0
	_ability_timer  = 0.3
	if _bull_anim:
		_bull_anim.speed_scale = 2.0
	if _bull_anim and _bull_anim.has_animation(_ANIM_KICK):
		_bull_anim.play(_ANIM_KICK)
		_ability_timer = _bull_anim.get_animation(_ANIM_KICK).length
	var raw  := cube_guy.global_transform.basis.z
	var back := -Vector3(raw.x, 0.0, raw.z).normalized()
	_spawn_kick_fx(back)
	get_tree().create_timer(0.2).timeout.connect(
		func() -> void: _hit_matadors_cone(DP.f("kick_range"), deg_to_rad(85.0), DP.f("kick_strength"), back)
	)


func _activate_slam() -> void:
	ability_cd[2]   = DP.f("slam_cooldown")
	_ability_active = true
	_active_ability = 2
	_legs.set(&"tail_ragdoll", true)
	_slam_pending = true
	SpearProjectile.shed_all.call_deferred(self)  # the leap shakes off any stuck spears
	var jump_vel  := DP.f("slam_jump_velocity")
	velocity.y     = jump_vel
	# Airtime with an accelerated descent: rise (v/g) + fall (v / (g·√mult)).
	var fall_mult := maxf(DP.f("slam_fall_mult"), 0.01)
	var air_time  := (jump_vel / 9.8) * (1.0 + 1.0 / sqrt(fall_mult))
	_ability_timer = air_time + 0.3
	if _bull_anim and _bull_anim.has_animation(_ANIM_SLAM):
		var anim_len := _bull_anim.get_animation(_ANIM_SLAM).length
		_bull_anim.speed_scale = anim_len / maxf(air_time, 0.01)
		_bull_anim.play(_ANIM_SLAM)


func _activate_dash() -> void:
	ability_cd[1]   = DP.f("dash_cooldown")
	_ability_active = true
	_active_ability = 1
	_ability_timer  = 0.45
	if _bull_anim:
		_bull_anim.speed_scale = 1.0
	if _bull_anim and _bull_anim.has_animation(_ANIM_DASH):
		_bull_anim.play(_ANIM_DASH)
		_ability_timer = _bull_anim.get_animation(_ANIM_DASH).length
	var raw := cube_guy.global_transform.basis.z
	_dash_dir = Vector3(raw.x, 0.0, raw.z).normalized()
	_dash_speed_cur = DP.f("dash_speed")
	velocity.x = _dash_dir.x * _dash_speed_cur
	velocity.z = _dash_dir.z * _dash_speed_cur
	_spawn_dash_burst()
	_legs.set(&"charge_pitch_target", DP.f("charge_head_pitch"))
	if _huff_player:
		_huff_player.pitch_scale = randf_range(0.9, 1.1)
		_huff_player.play()


func _activate_roll() -> void:
	ability_cd[3]   = DP.f("roll_cooldown")
	_ability_active = true
	_active_ability = 3
	_ability_timer  = DP.f("roll_duration")
	_roll_ramp      = 0.0
	_roll_spin      = 0.0
	_roll_chains_left = int(DP.f("roll_chain_count"))
	_roll_hit.clear()
	# Lock onto the closest matador and curl into the ball aimed at it; if the arena
	# is empty, launch along the current heading (or facing when standing still).
	_roll_target = _roll_pick_target()
	var flat := Vector3(velocity.x, 0.0, velocity.z)
	if _roll_target != null:
		var to_t := _roll_target.global_position - global_position
		_roll_dir = Vector3(to_t.x, 0.0, to_t.z).normalized()
	elif flat.length() > 1.0:
		_roll_dir = flat.normalized()
	else:
		var f := cube_guy.global_transform.basis.z
		_roll_dir = Vector3(f.x, 0.0, f.z).normalized()
	var launch := DP.f("roll_base_speed")
	velocity.x = _roll_dir.x * launch
	velocity.z = _roll_dir.z * launch
	if _bull_anim and _bull_anim.has_animation(_ANIM_ROLL):
		_bull_anim.speed_scale = 1.0
		_bull_anim.play(_ANIM_ROLL)
	_legs.set(&"tail_ragdoll", true)                           # tail streams out behind
	_legs.set(&"charge_pitch_target", DP.f("charge_head_pitch"))  # horns down, plowing
	_legs.set(&"external_rotation", true)   # roll owns the model's full orientation (tumble)
	if _roll_spark_emitter:
		_roll_spark_emitter.emitting = true
	_spawn_dash_burst()
	camera_pivot.call(&"trigger_hit", 0.35)
	if _huff_player:
		_huff_player.pitch_scale = randf_range(0.8, 1.0)
		_huff_player.play()


# One rolling frame: home on the current target matador, accelerate the longer the
# roll lasts, move (walls just slide), then pop the ball on contact and chain to the
# next closest. Fully replaces the normal locomotion path while active. `steer` is
# ignored — the roll auto-targets — but kept so the caller stays uniform.
func _tick_roll(delta: float, _steer: Vector3) -> void:
	# Reacquire if the target ragdolled or was freed before we reached it.
	if not _roll_target_valid():
		_roll_target = _roll_pick_target()
	if _roll_target != null:
		var to_t := _roll_target.global_position - global_position
		var flat := Vector3(to_t.x, 0.0, to_t.z)
		if flat.length() > 0.1:
			var t := clampf(DP.f("roll_turn") * delta, 0.0, 1.0)
			_roll_dir = _roll_dir.slerp(flat.normalized(), t).normalized()

	# Speed builds over time: base → max across roll_rampup_time, so a long roll
	# winds up into a runaway boulder while a quick tap barely gets going.
	_roll_ramp += delta
	var ramp := clampf(_roll_ramp / maxf(DP.f("roll_rampup_time"), 0.01), 0.0, 1.0)
	var top := DP.f("roll_max_speed")
	var speed := lerpf(DP.f("roll_base_speed"), top, ramp)
	velocity.x = _roll_dir.x * speed
	velocity.z = _roll_dir.z * speed

	# Tumble the whole model like a Powerball: face the travel direction (yaw) then
	# spin forward about the horizontal axis perpendicular to it, angular speed = v/r
	# so it "rolls" without slipping. Legs yield rotation control while active.
	var radius := maxf(DP.f("roll_spin_radius"), 0.1)
	_roll_spin = wrapf(_roll_spin + (speed / radius) * delta, 0.0, TAU)
	var facing := Basis(Vector3.UP, atan2(_roll_dir.x, _roll_dir.z))
	var tumble_axis := Vector3.UP.cross(_roll_dir).normalized()
	cube_guy.basis = (Basis(tumble_axis, _roll_spin) * facing).scaled(_cube_scale)
	if _bull_anim and _bull_anim.has_animation(_ANIM_ROLL):
		_bull_anim.speed_scale = clampf(speed / maxf(top, 1.0), 0.6, 2.4)

	_set_dust_state(DustState.CHARGE)
	if _charge_trail_emitter:
		_charge_trail_emitter.emitting = true
		_charge_trail_emitter.direction = (-_roll_dir + Vector3(0.0, 0.25, 0.0)).normalized()

	move_and_slide()
	_was_on_floor = is_on_floor()
	_smash_barrels_in_radius(DP.f("roll_hit_radius"))
	_roll_try_pop(speed)


# Pop the ball on ramming a matador: launch every matador in the hit radius up and
# outward, then either CHAIN to the next closest (if chains remain and a target is
# left) or end the roll. Returns true if it popped so the caller can stop touching
# roll state this frame.
func _roll_try_pop(speed: float) -> bool:
	var radius := DP.f("roll_hit_radius")
	for mat: Node in get_tree().get_nodes_in_group(&"matador"):
		if _roll_hit.has(mat) or not _mat_active(mat):
			continue
		var to_mat: Vector3 = (mat as Node3D).global_position - global_position
		to_mat.y = 0.0
		if to_mat.length() > radius:
			continue
		# Record everyone this pop reaches so the chain never re-picks a downed body.
		for m: Node in get_tree().get_nodes_in_group(&"matador"):
			var d: Vector3 = (m as Node3D).global_position - global_position
			d.y = 0.0
			if d.length() <= radius and not _roll_hit.has(m):
				_roll_hit.append(m)
		_hit_matadors_radius(radius, DP.f("roll_hit_strength"), DP.f("roll_knockup"))
		camera_pivot.call(&"trigger_hit", clampf(speed / 90.0, 0.35, 1.0))
		if _huff_player:
			_huff_player.pitch_scale = randf_range(1.05, 1.35)
			_huff_player.play()
		if _roll_chains_left > 0:
			var next := _roll_pick_target()
			if next != null:
				_roll_chains_left -= 1
				_roll_target = next
				return true   # keep rolling — the ball carries on to the next target
		_end_roll()
		return true
	return false


# Closest thing the roll should home on — an active matador (arena) or an intact barrel
# (lobby) we haven't already smashed this roll. Null if nothing is left to hit.
func _roll_pick_target() -> Node3D:
	var best: Node3D = null
	var best_d := INF
	for cand: Node3D in _roll_targets():
		var d: float = cand.global_position.distance_squared_to(global_position)
		if d < best_d:
			best_d = d
			best = cand
	return best


# Live roll targets: active matadors plus standing barrels, minus anything already popped.
func _roll_targets() -> Array[Node3D]:
	var out: Array[Node3D] = []
	for mat: Node in get_tree().get_nodes_in_group(&"matador"):
		if not _roll_hit.has(mat) and _mat_active(mat):
			out.append(mat as Node3D)
	for barrel: Node in get_tree().get_nodes_in_group(&"barrel"):
		if _barrel_alive(barrel):
			out.append(barrel as Node3D)
	return out


func _roll_target_valid() -> bool:
	if not is_instance_valid(_roll_target):
		return false
	if _roll_target.is_in_group(&"barrel"):
		return _barrel_alive(_roll_target)
	return _mat_active(_roll_target)


# A matador still in play — valid, not ragdolled/consumed. Ragdolled bodies report
# is_active() == false, so a popped target is skipped on the next chain search.
func _mat_active(mat: Node) -> bool:
	return is_instance_valid(mat) and mat.has_method(&"is_active") and mat.call(&"is_active")


# A lobby barrel still standing — valid and not already queued for removal by an earlier hit.
func _barrel_alive(barrel: Node) -> bool:
	return is_instance_valid(barrel) and not barrel.is_queued_for_deletion()


# Burst every barrel whose centre sits within range_m on the ground plane. Shared by the
# boulder roll (which ploughs straight through them) and the slam shockwave. Each barrel
# self-removes and leaves the &"barrel" group, so the HUD's clear-the-lobby tally counts it
# exactly once.
func _smash_barrels_in_radius(range_m: float) -> void:
	for barrel: Node in get_tree().get_nodes_in_group(&"barrel"):
		if not _barrel_alive(barrel):
			continue
		var to_b: Vector3 = (barrel as Node3D).global_position - global_position
		to_b.y = 0.0
		if to_b.length() <= range_m:
			barrel.call(&"destroy_barrel")


# True while the boulder roll is live — matadors defer their charge-gore to the roll's own pop
# (is_rolling guard in matador._take_bull_charge) so the ball pops instead of quietly goring.
func is_rolling() -> bool:
	return _active_ability == 3 and _ability_active


# True while the dash ability is live. A dash is a committed lunge — it gores/rams on contact
# regardless of angle (enemies bypass their horns-first cone while it's set).
func is_dashing() -> bool:
	return _active_ability == 1 and _ability_active


# End the Powerball early: brake hard (the ball "pops" and unrolls) and drop back to the normal
# locomotion path next frame.
func _end_roll() -> void:
	_ability_active = false
	_active_ability = -1
	_ability_timer  = 0.0
	_roll_ramp      = 0.0
	_roll_target    = null
	_roll_chains_left = 0
	_roll_hit.clear()
	_legs.set(&"charge_pitch_target", 0.0)
	_legs.set(&"tail_ragdoll", false)
	_legs.set(&"external_rotation", false)
	if _roll_spark_emitter:
		_roll_spark_emitter.emitting = false
	if _charge_trail_emitter:
		_charge_trail_emitter.emitting = false
	velocity.x *= 0.15
	velocity.z *= 0.15
	_play_idle()


func _hit_matadors_cone(range_m: float, half_angle_rad: float, strength: float,
		dir: Vector3 = Vector3.ZERO) -> void:
	var raw     := cube_guy.global_transform.basis.z
	var forward := dir if dir.length_squared() > 0.01 else Vector3(raw.x, 0.0, raw.z).normalized()
	for mat: Node in get_tree().get_nodes_in_group(&"matador"):
		var to_mat: Vector3 = (mat as Node3D).global_position - global_position
		to_mat.y = 0.0
		var dist := to_mat.length()
		if dist > range_m:
			continue
		if dist > 0.01 and forward.dot(to_mat / dist) < cos(half_angle_rad):
			continue
		mat.call(&"apply_ability_hit", (forward + Vector3.UP * 0.4).normalized(), strength)


func _hit_matadors_radius(range_m: float, strength: float, up_boost: float = 0.0) -> void:
	for mat: Node in get_tree().get_nodes_in_group(&"matador"):
		var to_mat: Vector3 = (mat as Node3D).global_position - global_position
		to_mat.y = 0.0
		var dist := to_mat.length()
		if dist > range_m:
			continue
		var away := to_mat / dist if dist > 0.01 \
			else Vector3(randf() - 0.5, 0.0, randf() - 0.5).normalized()
		mat.call(&"apply_ability_hit", (away + Vector3.UP * 0.6).normalized(), strength, up_boost)


# ── Blood-spurt particle helpers ──────────────────────────────────────────────
# The ability effects now live in systems/fx/; only the spear-wound blood below is still built in
# code. Shared material, built once so the mobile driver compiles this particle shader a single
# time (colour comes per-particle from the colour_ramp via vertex colour, not this material).
func _unshaded_material() -> StandardMaterial3D:
	if _unshaded_mat == null:
		_unshaded_mat = StandardMaterial3D.new()
		_unshaded_mat.shading_mode = BaseMaterial3D.SHADING_MODE_UNSHADED
		_unshaded_mat.transparency = BaseMaterial3D.TRANSPARENCY_ALPHA
		_unshaded_mat.vertex_color_use_as_albedo = true
		_unshaded_mat.cull_mode = BaseMaterial3D.CULL_DISABLED
	return _unshaded_mat


# Low-poly particle-sphere mesh (height = diameter), cached per size so repeats reuse one GPU upload.
func _particle_sphere(radius: float, segments: int, rings: int, mat: Material) -> SphereMesh:
	var key := "%.4f:%d:%d" % [radius, segments, rings]
	var cached: SphereMesh = _particle_sphere_cache.get(key)
	if cached != null:
		return cached
	var sphere := SphereMesh.new()
	sphere.radius = radius
	sphere.height = radius * 2.0
	sphere.radial_segments = segments
	sphere.rings = rings
	sphere.material = mat
	_particle_sphere_cache[key] = sphere
	return sphere


# Queue-free a transient FX node once its particles have finished.
func _free_after(node: Node, delay: float) -> void:
	get_tree().create_timer(delay).timeout.connect(func() -> void:
		if is_instance_valid(node):
			node.queue_free()
	)


func _spawn_slam_fx() -> void:
	var origin := global_position + Vector3(0.0, -0.5, 0.0)
	_impact_fx.call(&"slam_rings", origin, DP.f("slam_range"))
	Fx.spawn(&"bull_slam", Transform3D(Basis(), origin))
	camera_pivot.call(&"trigger_hit", 0.60)


func _spawn_kick_fx(back_dir: Vector3) -> void:
	var origin := global_position + back_dir * 0.55 + Vector3(0.0, -0.25, 0.0)
	Fx.spawn(&"bull_kick", _aimed_xform(origin, back_dir))
	_impact_fx.call(&"kick_flash", origin)
	camera_pivot.call(&"trigger_hit", 0.35)


func _spawn_dash_burst() -> void:
	Fx.spawn(&"bull_dash", _aimed_xform(global_position + Vector3(0.0, 0.2, 0.0), _dash_dir))


# A transform at `origin` whose local -Z faces `forward` (flattened to horizontal). The kick/dash
# effects bake their spray in local space, so aiming the spawn transform points the burst the
# right way. Falls back to an unrotated transform when `forward` has no horizontal component.
func _aimed_xform(origin: Vector3, forward: Vector3) -> Transform3D:
	var flat := Vector3(forward.x, 0.0, forward.z)
	if flat.length_squared() < 0.0001:
		return Transform3D(Basis(), origin)
	return Transform3D(Basis(), origin).looking_at(origin + flat.normalized(), Vector3.UP)


func _physics_process(delta: float) -> void:
	# ── Dead bull ─────────────────────────────────────────────────────────────
	# The run is over the instant HP hits zero, but the lose screen holds off a
	# beat before it appears (see HUD._show_game_over). Freeze the carcass through
	# that delay — no input, no abilities, just coast to a stop under gravity — so a
	# dead bull can't keep charging around while the screen is pending.
	if _dead:
		velocity.x = move_toward(velocity.x, 0.0, 40.0 * delta)
		velocity.z = move_toward(velocity.z, 0.0, 40.0 * delta)
		if not is_on_floor():
			velocity += get_gravity() * delta
		move_and_slide()
		return

	# ── Gravity ───────────────────────────────────────────────────────────────
	if not is_on_floor():
		var gravity := get_gravity()
		# Crash a slam down hard: full leap on the way up, accelerated descent so
		# the bull spends less time floating before the impact.
		if _slam_pending and velocity.y < 0.0:
			gravity *= DP.f("slam_fall_mult")
		velocity += gravity * delta

	# ── Camera-relative input direction ───────────────────────────────────────
	var input_dir    := Input.get_vector("move_left", "move_right", "move_forward", "move_back")
	var cam_basis    := camera_pivot.global_transform.basis
	var flat_forward := -Vector3(cam_basis.z.x, 0.0, cam_basis.z.z).normalized()
	var flat_right   :=  Vector3(cam_basis.x.x, 0.0, cam_basis.x.z).normalized()
	var direction    := (flat_forward * -input_dir.y + flat_right * input_dir.x).normalized()

	var on_floor := is_on_floor()

	# ── Ability cooldowns ────────────────────────────────────────────────────────
	_hit_iframes = maxf(0.0, _hit_iframes - delta)
	for i: int in 4:
		ability_cd[i] = maxf(0.0, ability_cd[i] - delta)
	if _ability_active:
		_ability_timer -= delta
		if _ability_timer <= 0.0:
			if _active_ability == 3:
				_end_roll()   # tears down roll-specific state (sparks, tumble control)
			else:
				_ability_active = false
				_active_ability = -1
				_legs.set(&"charge_pitch_target", 0.0)
				_legs.set(&"tail_ragdoll", false)
				_slam_pending = false
				_play_idle()

	# ── Boulder roll ──────────────────────────────────────────────────────────
	# While rolling, the ability owns movement entirely (its own accel, low friction
	# and wall ricochet) — bypass the normal input/kick/damping path below.
	if _active_ability == 3 and _ability_active:
		_tick_roll(delta, direction)
		return

	_was_on_floor = on_floor

	# ── Ground locomotion — smooth accelerate / friction ──────────────────────
	# WASD/arrows drive the bull directly: hold a direction to ramp up to max_speed
	# and steer, release to coast to a stop. Ability bursts (dash) and wall bounces
	# can exceed max_speed — while a direction is held we steer that momentum without
	# braking it (cap tracks the current speed); friction only bleeds the excess once
	# input is released.
	var flat_vel  := Vector3(velocity.x, 0.0, velocity.z)
	var max_speed := DP.f("max_speed")
	if _active_ability == 1 and _ability_active:
		# Dash: leave the barrel fast like a bullet, then bleed exponentially back
		# down to cruise speed (fastest drop right at the start), so it settles into
		# normal running by the time the clip ends instead of holding top speed.
		_dash_speed_cur = lerpf(_dash_speed_cur, max_speed, 1.0 - exp(-DP.f("dash_decel") * delta))
		flat_vel = _dash_dir * _dash_speed_cur
	elif direction.length_squared() > 0.01:
		var cap := maxf(max_speed, flat_vel.length())
		flat_vel = flat_vel.move_toward(direction * cap, DP.f("move_accel") * delta)
	else:
		flat_vel = flat_vel.move_toward(Vector3.ZERO, DP.f("move_friction") * delta)
	velocity.x = flat_vel.x
	velocity.z = flat_vel.z

	# ── Visual rotation follows velocity direction ─────────────────────────────
	var flat_speed := Vector2(velocity.x, velocity.z).length()
	if flat_speed > 0.4:
		var target_angle := atan2(velocity.x, velocity.z)
		cube_guy.rotation.y = lerp_angle(
			cube_guy.rotation.y, target_angle, delta * DP.f("visual_turn_speed"))

	# Looping WALK clip while genuinely moving on the ground, idle otherwise.
	_update_locomotion_anim(on_floor and flat_speed > 1.0)

	_pre_slide_vel_y = velocity.y
	var pre_wall_vel := Vector3(velocity.x, 0.0, velocity.z)
	move_and_slide()



	# ── Wall bounce — no sliding, guaranteed exit ────────────────────────────
	# pre_wall_vel is captured before move_and_slide strips the into-wall component,
	# so into_spd correctly reflects how hard the bull hit the wall even when stationary.
	for i in get_slide_collision_count():
		var col    := get_slide_collision(i)
		var normal := col.get_normal()
		if abs(normal.y) < 0.5:
			var flat_n   := Vector3(normal.x, 0.0, normal.z).normalized()
			var into_spd := -pre_wall_vel.dot(flat_n)
			var exit_spd := maxf(into_spd * DP.f("wall_bounce_restitution"),
				DP.f("wall_min_bounce_speed"))
			velocity.x   = flat_n.x * exit_spd
			velocity.z   = flat_n.z * exit_spd
			pre_wall_vel = Vector3(velocity.x, 0.0, velocity.z)

			# Ram straight through a barrel that formed the wall we bounced off.
			var hit := col.get_collider()
			if hit != null and hit.has_method(&"destroy_barrel"):
				hit.call(&"destroy_barrel")

	# ── Landing. Don't bounce ─────────────────────────────────────────────────────
	if is_on_floor() and not _was_on_floor:
		velocity.y = 0.0

	# ── Slam landing ──────────────────────────────────────────────────────────
	if _slam_pending and is_on_floor() and not _was_on_floor:
		_slam_pending   = false
		_ability_active = false
		_active_ability = -1
		_ability_timer  = 0.0
		_legs.set(&"charge_pitch_target", 0.0)
		_legs.set(&"tail_ragdoll", false)
		_play_idle()
		_spawn_slam_fx()
		_hit_matadors_radius(DP.f("slam_range"), DP.f("slam_strength"), DP.f("slam_launch_up"))
		_smash_barrels_in_radius(DP.f("slam_range"))

	# ── Dust ──────────────────────────────────────────────────────────────────
	if flat_speed > DP.f("dust_charge_spd") and on_floor:
		_set_dust_state(DustState.CHARGE)
	elif flat_speed > DP.f("dust_walk_spd") and on_floor:
		_set_dust_state(DustState.WALK)
	else:
		_set_dust_state(DustState.NONE)

	# ── Charge trail direction ────────────────────────────────────────────────
	if _dust_state == DustState.CHARGE and _charge_trail_emitter:
		var vel_flat := Vector3(velocity.x, 0.0, velocity.z)
		if vel_flat.length_squared() > 0.1:
			_charge_trail_emitter.direction = (-vel_flat.normalized() + Vector3(0.0, 0.25, 0.0)).normalized()


func get_hp() -> int:
	return _hp


func get_max_hp() -> int:
	return _max_hp


# Bonus pips currently on the bar — the HUD colours this many top pips yellow.
func get_bonus_hp() -> int:
	return _bonus_hp


# Award extra health (from a lobby reward): grows both the cap and the current bar so the
# new pips arrive full, and marks them as bonus so the HUD paints them yellow.
func grant_bonus_hp(amount: int) -> void:
	if amount <= 0:
		return
	_bonus_hp += amount
	_max_hp   += amount
	_hp       += amount
	health_changed.emit(_hp, _max_hp)


# A clean hit — thrown or swung blade — costs the bull one HP pip; the run ends only
# when the last pip is gone. `cause` ("gored" / "thrown") tags how it happened for the
# death notice. I-frames absorb a flurry so several blades in one pass drop one pip,
# not the whole bar; `_dead` latches so the lose screen is raised exactly once.
func take_sword_hit(cause: String = "", hit_pos: Vector3 = Vector3.ZERO) -> void:
	if _dead or _hit_iframes > 0.0:
		return
	_hp -= 1
	_hit_flash()
	_hit_iframes = DP.f("bull_hit_iframes")
	health_changed.emit(_hp, _max_hp)
	hit_taken.emit(cause)
	camera_pivot.call(&"trigger_hit", 0.7)
	# Vibrate controller 0 with half weak strength, full strong strength, for 0.2 seconds
	Controls.vibrate(0, 0.5, 1, 0.2)

	# A spear gores a spot — blood spurts from the entry wound (where it struck the
	# bull). Melee gores pass no position and skip the spurt; gore can be turned off.
	if cause == "thrown" and Settings.gore:
		_spawn_blood(hit_pos if hit_pos != Vector3.ZERO else global_position)
	if _huff_player:
		_huff_player.pitch_scale = randf_range(0.7, 0.9)
		_huff_player.play()
	if _hp <= 0:
		if _bull_anim.current_animation != _ANIM_DEATH:
			_bull_anim.speed_scale = 0.8
			_bull_anim.play(_ANIM_DEATH)
		_dead = true
		died.emit(cause)


# Pop the bull upward — a smash hitbox knocks it off its feet. Only ever raises the
# vertical speed so a downward-moving bull still gets launched.
func apply_knock_up(v: float) -> void:
	velocity.y = maxf(velocity.y, v)


# Typed entry point for the unified hit pipeline: a Hitbox (or any attacker) hands the bull a
# DamageEvent instead of calling take_sword_hit directly. A thin adapter over the existing pip /
# knock-up logic, so behaviour is unchanged while callers migrate off the stringly path.
func receive_damage(event: DamageEvent) -> void:
	take_sword_hit(event.cause_name(), event.hit_position)
	if event.knock_up > 0.0:
		apply_knock_up(event.knock_up)


# Blood spurt from a spear wound: a short-lived spray of dark-red gobs flung out of the
# entry point, biased outward from the bull's centre (so it reads as bursting from the
# hide) with a touch of lift before gravity drags it down.
func _spawn_blood(hit_pos: Vector3) -> void:
	var out := hit_pos - global_position
	out.y = 0.0
	out = out.normalized() if out.length() > 0.05 else Vector3(0.0, 0.0, 1.0)
	var dir := (out + Vector3.UP * 0.8).normalized()

	var sphere := _particle_sphere(0.05, 4, 2, _unshaded_material())

	var ramp := Gradient.new()
	ramp.set_color(0, Color(0.55, 0.02, 0.02, 1.0))
	ramp.set_color(1, Color(0.28, 0.0, 0.0, 0.0))

	var scale_curve := Curve.new()
	scale_curve.add_point(Vector2(0.0, 1.0))
	scale_curve.add_point(Vector2(0.6, 0.7))
	scale_curve.add_point(Vector2(1.0, 0.0))

	var p := CPUParticles3D.new()
	p.one_shot             = true
	p.explosiveness        = 0.9
	p.amount               = 34
	p.lifetime             = 0.7
	p.randomness           = 0.5
	p.local_coords         = false
	p.direction            = dir
	p.spread               = 42.0
	p.gravity              = Vector3(0.0, -14.0, 0.0)
	p.initial_velocity_min = 3.5
	p.initial_velocity_max = 8.0
	p.scale_amount_min     = 0.5
	p.scale_amount_max     = 1.6
	p.mesh                 = sphere
	p.color_ramp           = ramp
	p.scale_amount_curve   = scale_curve
	get_parent().add_child(p)
	p.global_position = hit_pos
	p.restart()
	_free_after(p, 1.5)


func _hit_flash() -> void:
	var meshes := find_children("*", "MeshInstance3D", true, false)

	for node in meshes:
		var mesh := node as MeshInstance3D
		if mesh:
			mesh.material_overlay = _make_hit_overlay()

	if _hit_flash_tween:
		_hit_flash_tween.kill()

	_hit_flash_tween = create_tween()
	_hit_flash_tween.tween_interval(0.08)
	_hit_flash_tween.tween_callback(_clear_hit_flash)


func _make_hit_overlay() -> StandardMaterial3D:
	var mat := StandardMaterial3D.new()
	mat.shading_mode = BaseMaterial3D.SHADING_MODE_UNSHADED
	mat.albedo_color = Color(1.0, 0.03, 0.03, 1.0)
	return mat


func _clear_hit_flash() -> void:
	var meshes := find_children("*", "MeshInstance3D", true, false)

	for node in meshes:
		var mesh := node as MeshInstance3D
		if mesh:
			mesh.material_overlay = null