FPS（下）：武器、敌人与导航

## 方式一：PhysicsDirectSpaceState3D.intersect_ray —— 不需要节点，随时查询一次。
## 适合"一次性"的检测：开枪、霰弹枪的每颗弹丸、敌人的视线。
func _cast_query(from: Vector3, to: Vector3) -> Dictionary:
	var space := get_world_3d().direct_space_state
	var query := PhysicsRayQueryParameters3D.create(from, to, HIT_MASK, [player.get_rid()])
	return space.intersect_ray(query)   # 没打中返回 {}；打中有 position、normal、collider 等字段

## 方式二：RayCast3D 节点 —— 在场景里摆好（这里是 Camera3D/AimRay），
## 它每个物理帧自动检测一次；临时改了方向就调用 force_raycast_update() 立即刷新。
## 适合"持续"的检测：脚下是否有地面、准星指着什么。
func _cast_node(from: Vector3, to: Vector3) -> Dictionary:
	aim_ray.collision_mask = HIT_MASK
	aim_ray.global_position = from
	aim_ray.target_position = aim_ray.to_local(to)
	aim_ray.force_raycast_update()
	if not aim_ray.is_colliding():
		return {}
	return {
		"position": aim_ray.get_collision_point(),
		"normal": aim_ray.get_collision_normal(),
		"collider": aim_ray.get_collider(),
	}

## 防穿墙：枪模型比玩家的碰撞胶囊伸得更远，贴墙时枪管会插进墙里。
## 每个物理帧从相机往前打一条很短的射线，离墙越近，枪越往回收、枪口越往上抬。
const WALL_REACH := 0.75   # 枪口到相机的大致距离（米）


func _check_wall() -> void:
	var from := camera.global_position
	var to := from - camera.global_basis.z * WALL_REACH
	var query := PhysicsRayQueryParameters3D.create(from, to, 1, [player.get_rid()])   # 只检测第 1 层"世界"
	var hit := get_world_3d().direct_space_state.intersect_ray(query)
	_wall_target = 0.0 if hit.is_empty() else 1.0 - from.distance_to(hit.position) / WALL_REACH

[layer_names]

3d_physics/layer_1="世界"
3d_physics/layer_2="玩家"
3d_physics/layer_3="敌人"
3d_physics/layer_4="碎片"

func _try_fire() -> void:
	var w := weapons[current]
	if _cooldown > 0.0 or _reload_left > 0.0 or _switch_left > 0.0:
		return
	if ammo[current] <= 0:
		reload()
		return
	ammo[current] -= 1
	_cooldown = 1.0 / w.fire_rate
	var spread := current_spread()
	var from := camera.global_position
	for i in w.pellets:
		var dir := _random_in_cone(spread)
		var to := from + dir * w.max_range
		var hit := _cast_query(from, to) if hit_method == "intersect_ray" else _cast_node(from, to)
		_apply_hit(hit, from, to, dir, w)
	bloom = minf(bloom + w.spread_per_shot, w.max_spread)
	# 后坐力：视角上跳 recoil 度，左右随机偏一点；Player 里会自动恢复
	player.add_recoil(w.recoil, randf_range(-0.35, 0.35) * w.recoil)
	_kick = 1.0
	models[current].flash()
	_emit_ammo()
	if ammo[current] == 0:
		reload()

## 当前散布（度）= 基础散布 + 连射累积 + 移动惩罚，空中再加，蹲下打折。
func current_spread() -> float:
	var w := weapons[current]
	var s := w.spread + bloom
	var speed := Vector2(player.velocity.x, player.velocity.z).length()
	s += speed / player.walk_speed * w.move_spread
	if not player.is_on_floor():
		s += 3.0
	if player.is_crouching():
		s *= 0.6
	return s


## 在半角为 spread_deg 的圆锥里随机取一个方向。
## 先在距离相机 1 米的平面上取一个半径为 tan(spread) 的圆盘内的点，
## 半径用 sqrt(randf())，点在圆盘里才是均匀分布的（直接用 randf() 会扎堆在中心）。
func _random_in_cone(spread_deg: float) -> Vector3:
	var r := tan(deg_to_rad(spread_deg)) * sqrt(randf())
	var a := randf() * TAU
	var local := Vector3(cos(a) * r, sin(a) * r, -1.0).normalized()
	return camera.global_basis * local

func _apply_hit(hit: Dictionary, from: Vector3, to: Vector3, dir: Vector3, w: WeaponData) -> void:
	var end: Vector3 = hit.get("position", to)
	if DebugDraw.show_rays:
		DebugDraw.line(from + camera.global_basis.y * -0.08, end, Color(1.0, 0.85, 0.2), 1.2)
	if hit.is_empty():
		return
	var target: Object = hit.collider
	if target.has_method("take_damage"):
		# 鸭子类型：谁有 take_damage 方法，谁就能被打。不需要知道它是敌人还是油桶
		var result: Dictionary = target.take_damage(w.damage, end, dir)
		hit_landed.emit(result.get("killed", false), result.get("headshot", false))
		Effects.spark(end, hit.normal, Color(1.0, 0.35, 0.25))
	else:
		Effects.bullet_hole(end, hit.normal)
		Effects.spark(end, hit.normal, Color(1.0, 0.8, 0.45))

## 伤害数字：Label3D 设成 billboard（永远面向相机）、no_depth_test（不被墙挡住），
## 往上飘 0.8 米并淡出，然后自己删掉。爆头用更大的黄色字。
static func damage_number(pos: Vector3, amount: float, headshot: bool) -> void:
	if not _instance:
		return
	var label := Label3D.new()
	label.text = ("爆头 %d" if headshot else "%d") % roundi(amount)
	label.billboard = BaseMaterial3D.BILLBOARD_ENABLED
	label.no_depth_test = true
	label.fixed_size = true                  # 远近都一样大
	label.pixel_size = 0.0012
	label.font_size = 40 if headshot else 30
	label.outline_size = 10
	label.modulate = Color(1.0, 0.85, 0.2) if headshot else Color(1, 1, 1)
	label.outline_modulate = Color(0.1, 0.05, 0.05, 0.8)
	_instance.add_child(label)
	label.global_position = pos + Vector3(randf_range(-0.2, 0.2), 0.2, 0)
	var tw := label.create_tween().set_parallel()
	tw.tween_property(label, "global_position:y", label.global_position.y + 0.8, 0.7).set_ease(Tween.EASE_OUT).set_trans(Tween.TRANS_CUBIC)
	tw.tween_property(label, "modulate:a", 0.0, 0.7).set_delay(0.25)
	tw.chain().tween_callback(label.queue_free)

## 弹孔。Compatibility 渲染器不支持 Decal 节点（实测放上去什么都不显示），
## 所以用一个贴着表面的小四边形代替：位置沿法线抬起 5 毫米防止和墙面"打架"（z-fighting），
## 朝向让四边形的 +Z（正面）对准法线。用对象池循环复用，最多同时存在 48 个。
static func bullet_hole(pos: Vector3, normal: Vector3) -> void:
	if _instance:
		_instance._add_hole(pos, normal)


func _add_hole(pos: Vector3, normal: Vector3) -> void:
	var hole: MeshInstance3D
	if _holes.size() < MAX_HOLES:
		hole = MeshInstance3D.new()
		hole.mesh = _hole_mesh
		hole.cast_shadow = GeometryInstance3D.SHADOW_CASTING_SETTING_OFF
		add_child(hole)
		_holes.append(hole)
	else:
		hole = _holes[_next_hole]        # 池满了就覆盖最旧的那个
		_next_hole = (_next_hole + 1) % MAX_HOLES
	var up := Vector3.UP if absf(normal.y) < 0.99 else Vector3.RIGHT
	# looking_at 让 -Z 指向给定方向；我们要 +Z 朝外（= 法线），所以让 -Z 指向 -normal
	hole.global_basis = Basis.looking_at(-normal, up)
	hole.rotate_object_local(Vector3.BACK, randf() * TAU)
	hole.global_position = pos + normal * 0.005

func _physics_process(delta: float) -> void:
	if state == State.DEAD:
		return
	# 感知不用每帧做：每 0.15 秒打一次射线就够了，还能省性能
	_think -= delta
	if _think <= 0.0:
		_think = 0.15
		can_see = _can_see_player()
		if can_see:
			last_known = _player.global_position
			_lost_time = 0.0
	var dist := global_position.distance_to(_player.global_position)
	match state:
		State.PATROL:
			if can_see:
				_enter(State.CHASE)
			elif agent.is_navigation_finished():
				_pick_patrol_point()
		State.CHASE:
			if can_see and dist < attack_range:
				_enter(State.ATTACK)
			else:
				agent.target_position = last_known
				if not can_see:
					_lost_time += delta
					if _lost_time > 6.0 and agent.is_navigation_finished():
						_enter(State.PATROL)        # 跟丢了，回去巡逻
		State.ATTACK:
			if not can_see or dist > attack_range * 1.25 or _player.is_dead:
				_enter(State.CHASE)
			else:
				_attack(delta)
	_move()
	_update_visuals(delta)


func _enter(new_state: State) -> void:
	state = new_state
	match new_state:
		State.CHASE:
			agent.target_position = last_known
		State.ATTACK:
			_fire_timer = maxf(_fire_timer, WINDUP + 0.1)
		State.PATROL:
			_pick_patrol_point()

## 三道关：距离够近 → 在视野扇形里（已经在追的时候不限角度）→ 视线射线没被墙挡住。
func _can_see_player() -> bool:
	if _player.is_dead:
		return false
	var from := eye.global_position
	var target := _player.head.global_position
	var to := target - from
	if to.length() > sight_range:
		return false
	if state == State.PATROL:
		var forward := -global_basis.z                   # -Z 是前方
		var flat := Vector3(to.x, 0.0, to.z)
		if forward.angle_to(flat) > deg_to_rad(view_angle / 2.0):
			return false
	var query := PhysicsRayQueryParameters3D.create(from, target, SHOT_MASK, [get_rid()])
	var hit := get_world_3d().direct_space_state.intersect_ray(query)
	var seen: bool = not hit.is_empty() and hit.collider == _player
	if DebugDraw.show_rays:
		var end: Vector3 = hit.get("position", target)
		DebugDraw.line(from, end, Color(0.3, 1.0, 0.4) if seen else Color(1.0, 0.3, 0.3, 0.6), 0.15)
	return seen

func _attack(delta: float) -> void:
	_fire_timer -= delta
	if _fire_timer > 0.0:
		return
	_fire_timer = fire_interval
	var from := muzzle.global_position
	# 命中率：距离越远、玩家跑得越快，瞄准点的随机偏移越大
	var chest := _player.global_position + Vector3.UP * 1.2
	var player_speed := Vector2(_player.velocity.x, _player.velocity.z).length()
	var miss_radius := 0.2 + from.distance_to(chest) * 0.025 + player_speed * 0.09
	var aim := chest + Vector3(randf_range(-1, 1), randf_range(-1, 1), randf_range(-1, 1)).normalized() * randf() * miss_radius
	var to := from + (aim - from).normalized() * (sight_range + 5.0)
	var query := PhysicsRayQueryParameters3D.create(from, to, SHOT_MASK, [get_rid()])
	var hit := get_world_3d().direct_space_state.intersect_ray(query)
	var end: Vector3 = hit.get("position", to)
	Effects.tracer(from, end)
	if not hit.is_empty() and hit.collider == _player:
		_player.take_damage(shot_damage, global_position)
	elif not hit.is_empty():
		Effects.spark(end, hit.normal, Color(1.0, 0.5, 0.3))

## 运行时烘焙导航网格。NavigationMesh 的几个关键参数：
##   agent_radius：把障碍物"加粗"这么多，敌人的中心沿网格走就不会蹭墙
##   agent_height / agent_max_climb / agent_max_slope：多矮的洞钻不过去、多高的台阶迈得上、多陡的坡爬得上
##   cell_size / cell_height：体素大小，必须和导航地图的设置一致（默认 0.25）
func _bake() -> void:
	var nm := NavigationMesh.new()
	nm.agent_radius = 0.5
	nm.agent_height = 1.75                        # 取 cell_height 的整数倍，否则会被向上取整并打警告
	nm.agent_max_climb = 0.5
	nm.agent_max_slope = 40.0
	nm.cell_size = 0.25
	nm.cell_height = 0.25
	nm.geometry_parsed_geometry_type = NavigationMesh.PARSED_GEOMETRY_STATIC_COLLIDERS
	nm.geometry_collision_mask = 1                 # 只把"世界"层的碰撞体当作地形
	navigation_mesh = nm
	# CSG 的布尔运算在本帧末尾才执行，等一帧再取它的形状，然后再等物理服务器登记好新碰撞体
	await get_tree().process_frame
	for csg in _csg_walls:
		_csg_to_static_body(csg)
	await get_tree().physics_frame
	var t0 := Time.get_ticks_msec()
	bake_navigation_mesh(false)                   # false = 在主线程同步烘焙（Web 版没有线程）
	print("导航网格烘焙完成：%d 个多边形，用时 %d ms" % [nm.get_polygon_count(), Time.get_ticks_msec() - t0])
	baked.emit()

func _move() -> void:
	var desired := Vector3.ZERO
	if state != State.ATTACK and not agent.is_navigation_finished():
		var next := agent.get_next_path_position()       # 路径上的下一个拐点
		var dir := next - global_position
		dir.y = 0.0
		var speed := move_speed * (0.5 if state == State.PATROL else 1.0)
		desired = dir.normalized() * speed
	agent.max_speed = move_speed
	if agent.avoidance_enabled:
		agent.velocity = desired          # 交给避障系统，它算出不撞别人的速度后发 velocity_computed 信号
	else:
		_on_velocity_computed(desired)
	if DebugDraw.show_nav and state != State.ATTACK:
		DebugDraw.path(agent.get_current_navigation_path(), Color(1.0, 0.6, 0.1))


func _on_velocity_computed(safe_velocity: Vector3) -> void:
	if state == State.DEAD:
		return
	var delta := get_physics_process_delta_time()
	velocity.x = safe_velocity.x + _knock.x
	velocity.z = safe_velocity.z + _knock.z
	velocity.y = 0.0 if is_on_floor() else velocity.y - 20.0 * delta
	_knock = _knock.lerp(Vector3.ZERO, 1.0 - exp(-8.0 * delta))
	move_and_slide()
	# 转向：攻击时面向玩家，否则面向移动方向。atan2(-x, -z) 求出让 -Z 对准某方向的偏航角
	var face := _player.global_position - global_position if state == State.ATTACK else safe_velocity
	if Vector2(face.x, face.z).length() > 0.1:
		rotation.y = lerp_angle(rotation.y, atan2(-face.x, -face.z), 1.0 - exp(-10.0 * delta))

## 敌人死亡时"爆开"：把身体上的每个网格换成一个 RigidBody3D 碎片，给一个向外的冲量。
## 碎片在第 4 层（碎片层），只和世界、碎片碰撞，不会挡住玩家和子弹。3 秒后缩小消失。
static func explode(parts: Array[MeshInstance3D], center: Vector3, push: Vector3) -> void:
	if not _instance:
		return
	for part in parts:
		var body := RigidBody3D.new()
		body.collision_layer = 8
		body.collision_mask = 1 | 8
		var shape := CollisionShape3D.new()
		var box := BoxShape3D.new()
		box.size = part.get_aabb().size.max(Vector3.ONE * 0.08)
		shape.shape = box
		shape.position = part.get_aabb().get_center()
		body.add_child(shape)
		var mi := MeshInstance3D.new()
		mi.mesh = part.mesh
		mi.material_override = part.get_active_material(0)
		body.add_child(mi)
		_instance.add_child(body)
		body.global_transform = part.global_transform
		var out := (part.global_position - center).normalized()
		body.apply_central_impulse((out * 2.5 + push * 2.0 + Vector3.UP * 2.5) * body.mass)
		body.angular_velocity = Vector3(randf_range(-8, 8), randf_range(-8, 8), randf_range(-8, 8))
		var tw := body.create_tween()
		tw.tween_interval(3.0)
		tw.tween_property(mi, "scale", Vector3.ZERO, 0.4)
		tw.tween_callback(body.queue_free)

## 散布是"角度"，准星是"像素"。相机的垂直视野角是 fov，屏幕半高对应 fov/2，
## 所以偏离中心 θ 角的点，在屏幕上离中心 tan(θ) / tan(fov/2) × 半高 个像素。
func spread_to_pixels(spread_deg: float) -> float:
	var half_fov := deg_to_rad(player.camera.fov / 2.0)
	return tan(deg_to_rad(spread_deg)) / tan(half_fov) * (size.y / 2.0)


func _draw_crosshair(c: Vector2) -> void:
	var gap := 4.0 + spread_to_pixels(weapons.current_spread())
	var length := 9.0
	var col := Color(1, 1, 1, 0.9)
	var shadow := Color(0, 0, 0, 0.5)
	for d: Vector2 in [Vector2.UP, Vector2.DOWN, Vector2.LEFT, Vector2.RIGHT]:
		var a := c + d * gap
		var b := c + d * (gap + length)
		draw_line(a + Vector2(1, 1), b + Vector2(1, 1), shadow, 2.0)
		draw_line(a, b, col, 2.0)
	draw_circle(c, 1.5, col)

## 伤害方向指示：把"攻击者位置"转换到玩家自己的坐标系里（乘 basis 的逆），
## 只看水平面：local.x 是右，-local.z 是前。atan2 得到相对正前方的角度，顺时针为正。
func _draw_damage_marks(c: Vector2) -> void:
	for m: Array in _damage_marks:
		var local: Vector3 = player.global_basis.inverse() * (m[0] - player.global_position)
		var angle := atan2(local.x, -local.z)
		var screen_angle := angle - PI / 2.0        # draw_arc 的 0 度在右边，屏幕"上"是 -90°
		var col := Color(1.0, 0.2, 0.15, clampf(m[1], 0.0, 1.0) * 0.85)
		draw_arc(c, 110.0, screen_angle - 0.32, screen_angle + 0.32, 20, col, 7.0, true)