太空射击：对象池、碰撞层与粒子

## 发射一颗子弹。pos/vel 用 Field 的局部坐标。
func spawn(pos: Vector2, vel: Vector2, kind: Bullet.Kind) -> Bullet:
	var b: Bullet
	if use_pool and not _free.is_empty():
		b = _free.pop_back()                 # 有空闲的：直接拿来用，零分配
	else:
		b = _create()                        # 没开池，或池被掏空了：现场新建
		b.from_pool = use_pool
		if use_pool:
			_owned += 1                      # 池不够用时自动扩容（也可以选择丢弃这颗子弹）
	b.setup(pos, vel, kind)
	b.active = true
	b.show()
	b.process_mode = Node.PROCESS_MODE_INHERIT   # 重新加入物理空间，开始参与碰撞
	active.append(b)
	return b

## 回收一颗子弹。命中时它是在物理回调里被调用的，
## 这时不能把 Area2D 移出物理空间，所以真正的"停用"推迟到这一帧末尾。
func release(b: Bullet) -> void:
	if not b.active:
		return
	b.active = false
	b.hide()
	if b.from_pool:
		_park.call_deferred(b)
	else:
		b.queue_free()                       # 不用池：直接销毁，下次再新建


func _park(b: Bullet) -> void:
	# PROCESS_MODE_DISABLED：不再处理，并且（disable_mode 默认是 REMOVE）从物理空间里拿掉。
	b.process_mode = Node.PROCESS_MODE_DISABLED
	if _owned > pool_size and use_pool:
		_owned -= 1                          # 池缩小了：多出来的直接释放
		b.queue_free()
	elif not use_pool:
		_owned -= 1                          # 运行中关掉了池：旧子弹用完就扔
		b.queue_free()
	else:
		_free.append(b)

## 每次从池里取出（或新建）后调用，把所有状态重置一遍——池化对象最容易出的 bug 就是"带着上一条命的状态"。
func setup(pos: Vector2, vel: Vector2, k: Kind) -> void:
	position = pos
	velocity = vel
	accel = 0.0
	turn = 0.0
	damage = 1
	if k != kind or sprite.texture == null:
		kind = k
		sprite.texture = TEXTURES[k]
		shape.scale = Vector2.ONE * HIT_SCALE.get(k, 1.0)
	rotation = vel.angle() if k == Kind.RICE or k == Kind.PLAYER else 0.0

## 所有活动子弹在这一个循环里移动。被回收的从数组里"交换删除"（和最后一个交换再 pop），O(1)。
func _physics_process(delta: float) -> void:
	var i := 0
	while i < active.size():
		var b := active[i]
		if b.active:
			if b.turn != 0.0:
				b.velocity = b.velocity.rotated(b.turn * delta)
				b.rotation = b.velocity.angle() if b.kind == Bullet.Kind.RICE else 0.0
			if b.accel != 0.0:
				b.velocity += b.velocity.normalized() * b.accel * delta
			b.position += b.velocity * delta
			if not bounds.has_point(b.position):
				release(b)
		if not b.active:
			active[i] = active[active.size() - 1]
			active.pop_back()
			continue
		i += 1

[node name="Player" type="Area2D"]
collision_layer = 1
collision_mask = 12
script = ExtResource("1")

[node name="Hurtbox" type="CollisionShape2D" parent="."]
shape = SubResource("hurt")

[node name="PickupArea" type="Area2D" parent="."]
collision_layer = 0
collision_mask = 16
monitorable = false

[node name="Shape" type="CollisionShape2D" parent="PickupArea"]
shape = SubResource("magnet")

func _on_area_entered(area: Area2D) -> void:
	if area is Bullet:
		if not area.active:
			return
		area.pool.release(area)               # 敌弹撞到玩家就消失
	elif not (area is Enemy or area is Boss):
		return
	if invincible or _invul > 0.0:
		return
	if shield:
		shield = false
		_invul = 1.0
		game.fx.ring(position, Color(0.4, 1.8, 2.4), 70.0)
		Audio.play("hurt", -6.0)
		return
	_invul = 2.5
	hit.emit()

[layer_names]

2d_physics/layer_1="player"
2d_physics/layer_2="player_bullet"
2d_physics/layer_3="enemy"
2d_physics/layer_4="enemy_bullet"
2d_physics/layer_5="pickup"

const PLAYER := 1 << 0          # 第 1 层 → 0b00001 = 1
const PLAYER_BULLET := 1 << 1   # 第 2 层 → 0b00010 = 2
const ENEMY := 1 << 2           # 第 3 层 → 0b00100 = 4
const ENEMY_BULLET := 1 << 3    # 第 4 层 → 0b01000 = 8
const PICKUP := 1 << 4          # 第 5 层 → 0b10000 = 16


func setup_player_hurtbox(area: Area2D) -> void:
	area.collision_layer = PLAYER                 # 我是谁：玩家
	area.collision_mask = ENEMY | ENEMY_BULLET    # 我检测谁：敌人和敌弹，4 | 8 = 12
	# 也可以按层号（从 1 开始）逐个开关，不用自己算位：
	area.set_collision_mask_value(5, false)       # 不检测道具
	print(area.get_collision_mask_value(4))       # true


## "A 能发现 B" 的条件：A 的 mask 和 B 的 layer 至少有一位相同。
static func detects(a_mask: int, b_layer: int) -> bool:
	return (a_mask & b_layer) != 0

func _spawn(w: WaveData, path: Path2D) -> void:
	var follow := PathFollow2D.new()
	follow.loop = false
	follow.rotates = false           # 敌人始终"脸朝下"，不跟着曲线转
	var e: Enemy = ENEMY_SCENE.instantiate()
	e.setup(w, game, follow, enemy_speed, hp_mult)
	follow.add_child(e)
	path.add_child(follow)

if _hold_left > 0.0:
	_hold_left -= delta                     # 停在半路射击
else:
	follow.progress += speed * delta        # progress 是沿曲线走过的像素长度
if not _held and data.hold_at >= 0.0 and follow.progress_ratio >= data.hold_at:
	_held = true
	_hold_left = data.hold_time
if follow.progress_ratio >= 1.0:            # 走完整条路径：飞出屏幕，悄悄消失（不加分）
	follow.queue_free()
	return

## 每条 Path2D 复制一份左右镜像的：scale.x = -1 再平移到右边，曲线数据本身不用改。
func _mirror_paths() -> void:
	for p: Path2D in paths.get_children():
		var m := Path2D.new()
		m.name = p.name + "_M"
		m.curve = p.curve
		m.scale = Vector2(-1, 1)
		m.position = Vector2(600.0 - p.position.x, p.position.y)
		paths.add_child(m)

@export var label := ""                       ## 显示在屏幕上的名字
@export var kind := Kind.DRONE                ## 敌人类型（决定外形、血量基数）
@export var path_name: StringName = &"SwoopLeft"   ## 沿哪条 Path2D 飞
@export var mirror := false                   ## 同时在左右镜像的路径上各出一队
@export var count := 6                        ## 一队几架
@export var gap := 1.0                        ## 同队相邻两架的出发间隔（乘以全局"生成间隔"）
@export var speed_scale := 1.0                ## 相对全局"敌人速度"的倍数
@export var hp := 3                           ## 血量（还会乘以全局"血量倍数"）
@export var fire := Fire.NONE                 ## 射击方式
@export var fire_interval := 1.5              ## 射击间隔（秒）
@export_range(-1.0, 1.0) var hold_at := -1.0  ## 走到路径的这个比例时停下来（-1 表示不停）
@export var hold_time := 0.0                  ## 停多久
@export var wait_after := 3.0                 ## 这一波最后一架出发后，再等几秒开始下一波
@export_range(0.0, 1.0) var drop_chance := 0.12   ## 击落后掉道具的概率

[sub_resource type="Resource" id="Resource_0ng37"]
script = ExtResource("2_tf8uh")
label = "狙击小队"
kind = 1
path_name = &"ZigZag"
count = 4
gap = 2.2
speed_scale = 0.8
hp = 5
fire = 1
fire_interval = 1.4

[sub_resource type="Resource" id="Resource_gntdf"]
script = ExtResource("2_tf8uh")
label = "回旋编队"

func _physics_process(delta: float) -> void:
	_clock += delta
	while not _pending.is_empty() and _pending[0][0] <= _clock:
		var item: Array = _pending.pop_front()
		_spawn(item[1], item[2])
	if not running:
		return
	if _pending.is_empty() and _clock >= _next_wave_at:
		if wave_index + 1 < stage.waves.size():
			_start_wave(wave_index + 1)
		elif game.enemy_count() == 0:          # 最后一波打完（或飞走）了，交给 Boss
			running = false
			stage_cleared.emit()


func _start_wave(i: int) -> void:
	wave_index = i
	var w: WaveData = stage.waves[i]
	wave_started.emit(i, w)
	_next_wave_at = _schedule(w) + w.wait_after


## 把一波敌人排进待出发队列，返回最后一架的出发时间。Boss 召唤护卫也用它。
func _schedule(w: WaveData) -> float:
	var paths: Array[Path2D] = [game.get_path2d(w.path_name)]
	if w.mirror:
		paths.append(game.get_path2d(StringName(str(w.path_name) + "_M")))
	var t := _clock
	for k in w.count:
		for p in paths:
			_pending.append([t, w, p])
		t += w.gap * spawn_interval
	_pending.sort_custom(func(a: Array, b: Array) -> bool: return a[0] < b[0])
	return t


func spawn_escort() -> void:
	var w := WaveData.new()
	w.kind = WaveData.Kind.DRONE
	w.path_name = &"SwoopLeft"
	w.mirror = true
	w.count = 3
	w.hp = 3
	w.drop_chance = 0.2
	_schedule(w)

## 环形：n 颗子弹均匀分布在一整圈上，第 i 颗的角度 θᵢ = offset + i × (2π / n)。
static func ring(pool: BulletPool, origin: Vector2, n: int, speed: float,
		offset := 0.0, kind := Bullet.Kind.PINK) -> void:
	for i in n:
		var theta := offset + TAU * i / n
		pool.spawn(origin, Vector2.from_angle(theta) * speed, kind)

## 螺旋：每次只发 arms 颗（均匀分布），但发射角 angle 由调用者每帧累加。
## 子弹沿直线飞，不同时刻发出的子弹排在一起，看起来就是一条旋转的螺旋臂。
static func spiral(pool: BulletPool, origin: Vector2, angle: float, arms: int, speed: float,
		kind := Bullet.Kind.VIOLET) -> void:
	ring(pool, origin, arms, speed, angle, kind)

## 自机狙：先求出从发射点指向玩家的角度 base = atan2(dy, dx)，
## 再在 base 两边均匀张开 spread 弧度的扇形（n = 1 时就是正对玩家的一颗）。
static func aimed(pool: BulletPool, origin: Vector2, target: Vector2, n: int, spread: float,
		speed: float, kind := Bullet.Kind.RICE) -> void:
	var base := (target - origin).angle()          # 等价于 atan2(target.y - origin.y, target.x - origin.x)
	for i in n:
		var t := 0.0 if n == 1 else float(i) / (n - 1) - 0.5    # -0.5 … +0.5
		pool.spawn(origin, Vector2.from_angle(base + t * spread) * speed, kind)

## 花瓣：仍是一圈，但速率随角度变化 v(θ) = v₀ × (1 + depth × sin(petals × θ))，
## 跑得快的方向形成"花瓣尖"。
static func flower(pool: BulletPool, origin: Vector2, n: int, speed: float, petals: int,
		depth: float, offset := 0.0, kind := Bullet.Kind.ORANGE) -> void:
	for i in n:
		var theta := offset + TAU * i / n
		var v := speed * (1.0 + depth * sin(petals * (theta - offset)))
		pool.spawn(origin, Vector2.from_angle(theta) * v, kind)

func _phase_rings(delta: float) -> void:
	var dens := game.director.bullet_density
	var spd := game.director.bullet_speed
	_timers[0] -= delta
	if _timers[0] <= 0.0:
		_timers[0] = 0.9
		var n := maxi(6, roundi(24 * dens))
		_spin += PI / n                    # 每圈旋转半格
		Danmaku.ring(game.enemy_bullets, position, n, 125.0 * spd, _spin, Bullet.Kind.PINK)
		Audio.play("enemy_shot", -4.0)
	_timers[1] -= delta
	if _timers[1] <= 0.0:
		_timers[1] = 1.7
		Danmaku.aimed(game.enemy_bullets, position, game.player.position, maxi(3, roundi(7 * dens)),
			0.8, 210.0 * spd)


func _phase_spiral(delta: float) -> void:
	var dens := game.director.bullet_density
	var spd := game.director.bullet_speed
	_timers[0] -= delta
	if _timers[0] <= 0.0:
		_timers[0] = 0.07
		var arms := maxi(2, roundi(4 * dens))
		_spin += 0.19
		# 两组螺旋：一组顺时针、一组逆时针，速度不同，交叉出网格
		Danmaku.spiral(game.enemy_bullets, position, _spin, arms, 120.0 * spd, Bullet.Kind.VIOLET)
		Danmaku.spiral(game.enemy_bullets, position, -_spin * 0.8, arms, 95.0 * spd, Bullet.Kind.PINK)
	_timers[1] -= delta
	if _timers[1] <= 0.0:
		_timers[1] = 0.6
		Audio.play("enemy_shot", -8.0)
	_timers[2] -= delta
	if _timers[2] <= 0.0:
		_timers[2] = 4.0
		game.director.spawn_escort()       # 召唤一队护卫机


func _phase_flower(delta: float) -> void:
	var dens := game.director.bullet_density
	var spd := game.director.bullet_speed
	_timers[0] -= delta
	if _timers[0] <= 0.0:
		_timers[0] = 0.55
		_spin += 0.21
		Danmaku.flower(game.enemy_bullets, position, maxi(10, roundi(40 * dens)), 110.0 * spd, 5, 0.45,
			_spin, Bullet.Kind.ORANGE)
		Audio.play("enemy_shot", -4.0)
	_timers[1] -= delta
	if _timers[1] <= 0.0:
		_timers[1] = 0.28
		Danmaku.aimed(game.enemy_bullets, position, game.player.position, 3, 0.25, 260.0 * spd)
	_timers[2] -= delta
	if _timers[2] <= 0.0:
		_timers[2] = 2.2
		Danmaku.ring(game.enemy_bullets, position, maxi(4, roundi(10 * dens)), 70.0 * spd, randf() * TAU,
			Bullet.Kind.BIG)

## 用代码搭一个 GPUParticles2D 当模板。CPU 模式下用 convert_from_particles() 把同样的设置抄过去。
func _make_gpu() -> GPUParticles2D:
	var p := GPUParticles2D.new()
	p.amount = maxi(1, particle_amount)
	p.lifetime = 0.7
	p.one_shot = true
	p.explosiveness = 1.0              # 1 = 所有粒子在同一瞬间发出
	p.emitting = false
	p.texture = SPARK
	var add := CanvasItemMaterial.new()
	add.blend_mode = CanvasItemMaterial.BLEND_MODE_ADD   # 加法混合：重叠处越叠越亮
	p.material = add
	var m := ParticleProcessMaterial.new()
	m.particle_flag_disable_z = true
	m.emission_shape = ParticleProcessMaterial.EMISSION_SHAPE_SPHERE
	m.emission_sphere_radius = 4.0
	m.spread = 180.0
	m.initial_velocity_min = 60.0
	m.initial_velocity_max = 280.0
	m.gravity = Vector3.ZERO
	m.damping_min = 150.0
	m.damping_max = 250.0
	m.scale_min = 0.9
	m.scale_max = 2.0
	var fade := Gradient.new()                   # 从亮白到透明
	fade.set_color(0, Color(1.25, 1.25, 1.25, 1.0))
	fade.set_color(1, Color(1, 1, 1, 0.0))
	var ramp := GradientTexture1D.new()
	ramp.gradient = fade
	m.color_ramp = ramp
	p.process_material = m
	return p


func _rebuild() -> void:
	if not is_inside_tree():
		return
	for e in _emitters:
		e.queue_free()
	_emitters.clear()
	if particle_amount <= 0:
		return
	for i in EMITTERS:
		var gpu := _make_gpu()
		if particle_mode == "CPU":
			var cpu := CPUParticles2D.new()
			cpu.convert_from_particles(gpu)      # 把 GPU 版的所有参数（包括过程材质）转换过来
			cpu.emitting = false
			cpu.material = gpu.material
			gpu.free()
			add_child(cpu)
			_emitters.append(cpu)
		else:
			add_child(gpu)
			_emitters.append(gpu)

## 屏幕震动用"创伤值"：每次受击加一点，随时间衰减；偏移量和创伤值的平方成正比，
## 小震动几乎察觉不到，大爆炸才明显。只动 Camera2D 的 offset，HUD 在 CanvasLayer 上不受影响。
func shake(amount: float) -> void:
	_trauma = minf(_trauma + amount / 24.0, 1.0)


func _update_shake(delta: float) -> void:
	_trauma = maxf(0.0, _trauma - delta * 1.8)
	var k := _trauma * _trauma * shake_strength * 2.0
	camera.offset = Vector2(randf_range(-k, k), randf_range(-k, k))