三消（下）：下落、连锁与动画

## 重力压缩：每一列用两个指针从下往上走。
## read 找宝石，write 指向"下一个应该放宝石的位置"。遇到宝石就搬到 write，write 上移一格。
## 每列只走一遍，O(H)；整个棋盘 O(W·H)。返回移动列表 [{from, to}]，给动画用。
func collapse() -> Array[Dictionary]:
	var moves: Array[Dictionary] = []
	for x in width:
		var write := height - 1
		for read in range(height - 1, -1, -1):
			var from := Vector2i(x, read)
			if cells[idx(from)] == EMPTY:
				continue
			if read != write:
				var to := Vector2i(x, write)
				cells[idx(to)] = cells[idx(from)]
				special[idx(to)] = special[idx(from)]
				cells[idx(from)] = EMPTY
				special[idx(from)] = Special.NONE
				moves.append({"from": from, "to": to})
			write -= 1
	return moves

## 压缩之后，空位只会出现在每列顶部。把它们补满新宝石。
## 补充时不避开三连：新掉下来的宝石凑成三连，就是"天降连锁"。
## 返回 [{cell, kind, drop}]，drop = 这一列补了几个，动画里新宝石从棋盘上方 drop 格处落下。
func refill() -> Array[Dictionary]:
	var spawns: Array[Dictionary] = []
	for x in width:
		var empty_count := 0
		while empty_count < height and cells[idx(Vector2i(x, empty_count))] == EMPTY:
			empty_count += 1
		for y in empty_count:
			var c := Vector2i(x, y)
			cells[idx(c)] = rng.randi_range(0, kinds - 1)
			special[idx(c)] = Special.NONE
			spawns.append({"cell": c, "kind": cells[idx(c)], "drop": empty_count})
	return spawns

## 不带动画的完整一回合：交换 → 循环（检测 → 消除 → 压缩 → 补充）直到没有消除 → 死局洗牌。
## main.gd 用 await 做的是同一件事，只是每一步之间插入了动画。测试脚本直接调用这个函数。
func play_move(a: Vector2i, b: Vector2i) -> Dictionary:
	if not is_valid_swap(a, b):
		return {"ok": false}
	var bomb_swap := kind_at(a) == RAINBOW or kind_at(b) == RAINBOW
	swap(a, b)
	var extra: Array[Vector2i] = []
	if bomb_swap:
		extra = activate_color_bomb(a, b)
	var prefer: Array[Vector2i] = [b, a]
	var chain := 0
	var cleared := 0
	var spawned := 0
	while true:
		var groups := find_matches()
		if groups.is_empty() and extra.is_empty():
			break
		chain += 1
		var res := clear_matches(groups, prefer, extra)
		extra = []
		prefer = []
		cleared += res.cleared.size()
		spawned += res.spawned.size()
		collapse()
		refill()
	var shuffled := find_valid_moves().is_empty()
	if shuffled:
		shuffle()
	return {"ok": true, "chain": chain, "cleared": cleared, "spawned": spawned, "shuffled": shuffled}

## 1000 次随机交换（一半随便挑相邻两格，一半从可行步里挑），每回合结束后检查不变量。
func _test_random_play(n: int) -> void:
	var rng := RandomNumberGenerator.new()
	rng.seed = 2024
	var b: Board
	var stats := {"ok": 0, "rejected": 0, "chain": 0, "spawned": 0, "shuffled": 0}
	for i in n:
		if i % 100 == 0:   # 每 100 步换一种棋盘配置
			b = Board.new(rng.randi_range(5, 10), rng.randi_range(5, 10), rng.randi_range(3, 7), rng.randi())
			b.fill_without_matches()
		var a := Vector2i(rng.randi_range(0, b.width - 1), rng.randi_range(0, b.height - 1))
		var c: Vector2i = a + [Vector2i.RIGHT, Vector2i.DOWN, Vector2i.LEFT, Vector2i.UP][rng.randi_range(0, 3)]
		if i % 2 == 0:
			var moves := b.find_valid_moves()
			var m: Array = moves[rng.randi_range(0, moves.size() - 1)]
			a = m[0]
			c = m[1]
		var before := b.cells.duplicate()
		var expect_ok := b.is_valid_swap(a, c)
		var res := b.play_move(a, c)
		_check(res.ok == expect_ok, "第 %d 步：play_move 和 is_valid_swap 不一致" % i)
		if not res.ok:
			stats.rejected += 1
			_check(b.cells == before, "第 %d 步：无效交换改动了棋盘" % i)
			continue
		stats.ok += 1
		stats.chain = maxi(stats.chain, res.chain)
		stats.spawned += res.spawned
		stats.shuffled += 1 if res.shuffled else 0
		_check_invariants(b, "第 %d 步" % i)
	print("随机交换 %d 次：有效 %d，被拒 %d，最长连锁 %d，生成特殊宝石 %d，死局洗牌 %d" % [
		n, stats.ok, stats.rejected, stats.chain, stats.spawned, stats.shuffled])
	_check(stats.ok > n / 3 and stats.rejected > 0, "有效/被拒的次数不合理")


func _check_invariants(b: Board, where: String) -> void:
	_check(b.cells.size() == b.width * b.height, where + "：格子数变了")
	for i in b.cells.size():
		var k := b.cells[i]
		var sp := b.special[i]
		_check(k != Board.EMPTY, where + "：回合结束后还有空格")
		_check((k >= 0 and k < b.kinds) or k == Board.RAINBOW, where + "：非法颜色 %d" % k)
		_check((k == Board.RAINBOW) == (sp == Board.Special.COLOR), where + "：同色炸弹和颜色不一致")
	_check(b.find_matches().is_empty(), where + "：回合结束后棋盘上还有三连")
	var moves := b.find_valid_moves()
	_check(not moves.is_empty(), where + "：回合结束后无步可走（应该已经洗牌）")
	# 可行步检测和"真的交换再扫描"结果一致
	for m in moves:
		b.swap(m[0], m[1])
		var real := not b.find_matches().is_empty() or b.kind_at(m[0]) == Board.RAINBOW or b.kind_at(m[1]) == Board.RAINBOW
		b.swap(m[0], m[1])
		_check(real, where + "：%s↔%s 被报告为可行步，但交换后没有三连" % [m[0], m[1]])

## 一回合：交换 →（检测 → 消除 → 下落补充）循环 → 死局检查。
## 每个 await 都会把这个函数挂起，等动画播完再往下走。挂起期间 _busy 为 true，输入一律忽略。
func _play_turn(a: Vector2i, b: Vector2i) -> void:
	_busy = true
	_set_hint([])
	var bomb_swap := board.kind_at(a) == Board.RAINBOW or board.kind_at(b) == Board.RAINBOW
	board.swap(a, b)
	await _animate_swap(a, b)
	if not bomb_swap and board.find_matches().is_empty():
		board.swap(a, b)                    # 没有形成消除：逻辑上换回去
		await _animate_swap(a, b)           # 画面上也换回去
		_finish_turn()
		return
	_moves_used += 1
	moves_left -= 1
	var extra: Array[Vector2i] = []
	if bomb_swap:
		extra = board.activate_color_bomb(a, b)
		fx.ring(view.cell_to_pixel(b if board.kind_at(b) == Board.RAINBOW else a), view.cell_size * 4.0, Color.WHITE)
	var prefer: Array[Vector2i] = [b, a]    # 新的特殊宝石优先出现在玩家拖过去的位置
	chain = 0
	while not _rebuild_pending:
		var groups := board.find_matches()
		if groups.is_empty() and extra.is_empty():
			break
		chain += 1
		var res := board.clear_matches(groups, prefer, extra)
		extra = []
		prefer = []
		_add_score(res, groups)
		await _animate_clear(res)
		if _rebuild_pending:
			break
		var moves := board.collapse()
		var spawns := board.refill()
		await _animate_fall(moves, spawns)
		if chain_delay > 0.0:
			await get_tree().create_timer(chain_delay).timeout
	if not _rebuild_pending and board.find_valid_moves().is_empty():
		await _shuffle_board("没有可走的步了，自动洗牌")
	_finish_turn()


func _finish_turn() -> void:
	_busy = false
	_idle = 0.0
	if _rebuild_pending:
		_new_game()
		return
	_valid_count = board.find_valid_moves().size()
	_refresh_hud()
	if moves_left <= 0 and not _game_over:
		_game_over = true
		hud.show_result(score, target_score)

## 交换动画：一个 Tween 同时移动两颗宝石（set_parallel），await finished 等它播完。
func _animate_swap(a: Vector2i, b: Vector2i) -> void:
	var ga: Gem = _gems[board.idx(a)]
	var gb: Gem = _gems[board.idx(b)]
	_gems[board.idx(a)] = gb               # 表现层的数组也跟着换，保持和 board 一一对应
	_gems[board.idx(b)] = ga
	ga.z_index = 1                         # 被拖动的那颗画在上面
	var tw := create_tween().set_parallel(true).set_trans(Tween.TRANS_QUAD).set_ease(Tween.EASE_IN_OUT)
	tw.tween_property(ga, "position", view.cell_to_pixel(b), swap_time)
	tw.tween_property(gb, "position", view.cell_to_pixel(a), swap_time)
	await tw.finished
	ga.z_index = 0

## 消除动画：所有要消的宝石放进同一个并行 Tween。每颗先放大再缩小淡出，
## 第二段用 set_delay 推迟开始，这样一个 Tween 里就能表达"先后"。
func _animate_clear(res: Dictionary) -> void:
	var tw := create_tween().set_parallel(true)
	tw.tween_interval(clear_time)          # 保证 Tween 里至少有一步（空 Tween 会报错）
	var dying: Array[Gem] = []
	for e: Dictionary in res.cleared:
		var i := board.idx(e.cell)
		var g: Gem = _gems[i]
		_gems[i] = null
		if g == null:
			continue
		dying.append(g)
		fx.burst(g.position, Gem.color_of(e.kind), view.cell_size)
		tw.tween_property(g, "scale", Vector2(1.25, 1.25), clear_time * 0.35).set_trans(Tween.TRANS_SINE)
		tw.tween_property(g, "scale", Vector2.ZERO, clear_time * 0.65).set_delay(clear_time * 0.35) \
				.set_trans(Tween.TRANS_BACK).set_ease(Tween.EASE_IN)
		tw.tween_property(g, "modulate:a", 0.0, clear_time * 0.65).set_delay(clear_time * 0.35)
	for t: Dictionary in res.triggered:
		_special_fx(t.cell, t.special)
	for s: Dictionary in res.spawned:       # 新生成的特殊宝石：原地变身 + 弹一下
		var g: Gem = _gems[board.idx(s.cell)]
		g.set_special(s.kind, s.special)
		g.scale = Vector2(1.6, 1.6)
		tw.tween_property(g, "scale", Vector2.ONE, clear_time * 1.2).set_trans(Tween.TRANS_BACK).set_ease(Tween.EASE_OUT)
	await tw.finished
	for g in dying:
		g.queue_free()

## 下落动画：已有宝石往下掉，新宝石从棋盘上方 drop 格处掉进来，全部并行。
## 落 n 格用时 fall_time·√n：自由落体 h = ½gt²，t 和 √h 成正比，远的掉得久一点但不会久太多。
func _animate_fall(moves: Array[Dictionary], spawns: Array[Dictionary]) -> void:
	var tw := create_tween().set_parallel(true)
	tw.tween_interval(0.01)
	for m in moves:
		var g: Gem = _gems[board.idx(m.from)]
		_gems[board.idx(m.from)] = null
		_gems[board.idx(m.to)] = g
		_fall(tw, g, m.to, m.to.y - m.from.y)
	for s in spawns:
		var g := _make_gem(s.cell)
		g.position = view.cell_to_pixel(s.cell - Vector2i(0, s.drop))
		_fall(tw, g, s.cell, s.drop)
	await tw.finished


func _fall(tw: Tween, g: Gem, to: Vector2i, cells: int) -> PropertyTweener:
	var t := fall_time * sqrt(float(cells))
	var pt := tw.tween_property(g, "position", view.cell_to_pixel(to), t)
	match fall_ease:
		"BOUNCE":
			pt.set_trans(Tween.TRANS_BOUNCE).set_ease(Tween.EASE_OUT)
		"BACK":
			pt.set_trans(Tween.TRANS_BACK).set_ease(Tween.EASE_OUT)
		"QUAD":
			pt.set_trans(Tween.TRANS_QUAD).set_ease(Tween.EASE_IN)
		_:
			pt.set_trans(Tween.TRANS_LINEAR)
	return pt

## 改了棋盘大小、颜色数、种子：要整个重建。动画播到一半时不能直接删宝石节点
## （正在 await 的协程醒来后会去操作已经释放的节点），所以先记下来，等回合结束再做。
func _request_rebuild(_force := false) -> void:
	if not _started:
		return
	if _busy:
		_rebuild_pending = true
	else:
		_new_game()

## 执行一轮消除。groups 来自 find_matches()；prefer 是玩家刚交换的两个格子，
## 新的特殊宝石优先生成在那里；extra 是额外要清掉的格子（同色炸弹交换时用）。
## 返回 {cleared: [{cell, kind, special}], spawned: [{cell, kind, special}], triggered: [{cell, special}]}
func clear_matches(groups: Array[Dictionary], prefer: Array[Vector2i] = [], extra: Array[Vector2i] = []) -> Dictionary:
	var to_clear := {}       # 集合：要清掉的格子
	var protect := {}        # 这一轮新生成特殊宝石的格子，不清
	var spawned: Array[Dictionary] = []
	for g in groups:
		to_clear.merge(g.cells)
		var sp := classify(g) if specials_enabled else Special.NONE
		if sp != Special.NONE:
			var at := _spawn_cell(g, prefer)
			if at != NO_CELL and not protect.has(at):
				protect[at] = true
				spawned.append({"cell": at, "kind": RAINBOW if sp == Special.COLOR else g.kind, "special": sp})
	for c in extra:
		to_clear[c] = true
	for c in protect:
		to_clear.erase(c)

	# 链式触发：被清掉的格子里有特殊宝石，就把它的作用范围也加进来，
	# 新加进来的格子里如果又有特殊宝石，会在队列后面继续触发（广度优先）。
	var queue: Array = to_clear.keys()
	var triggered: Array[Dictionary] = []
	var head := 0
	while head < queue.size():
		var c: Vector2i = queue[head]
		head += 1
		var sp := special_at(c)
		if sp == Special.NONE:
			continue
		triggered.append({"cell": c, "special": sp})
		for t in effect_area(c, sp):
			if not to_clear.has(t) and not protect.has(t):
				to_clear[t] = true
				queue.append(t)

	var cleared: Array[Dictionary] = []
	for c: Vector2i in to_clear:
		cleared.append({"cell": c, "kind": kind_at(c), "special": special_at(c)})
		cells[idx(c)] = EMPTY
		special[idx(c)] = Special.NONE
	for s in spawned:
		cells[idx(s.cell)] = s.kind
		special[idx(s.cell)] = s.special
	return {"cleared": cleared, "spawned": spawned, "triggered": triggered}

## 特殊宝石生成在哪：玩家刚动过的格子 > L/T 的拐点 > 段的中间。已有特殊宝石的格子不用。
func _spawn_cell(g: Dictionary, prefer: Array[Vector2i]) -> Vector2i:
	var keys: Array = g.cells.keys()
	var candidates: Array = []
	candidates.append_array(prefer)
	candidates.append(g.corner)
	candidates.append(keys[keys.size() / 2])
	candidates.append_array(keys)
	for c in candidates:
		if g.cells.has(c) and special_at(c) == Special.NONE:
			return c
	return NO_CELL


## 特殊宝石被消除时影响的格子。
func effect_area(c: Vector2i, sp: int) -> Array[Vector2i]:
	var out: Array[Vector2i] = []
	match sp:
		Special.LINE_H:
			for x in width:
				out.append(Vector2i(x, c.y))
		Special.LINE_V:
			for y in height:
				out.append(Vector2i(c.x, y))
		Special.BOMB:
			for dy in range(-1, 2):
				for dx in range(-1, 2):
					if in_bounds(c + Vector2i(dx, dy)):
						out.append(c + Vector2i(dx, dy))
		Special.COLOR:
			var k := most_common_kind()
			for i in cells.size():
				if cells[i] == k:
					out.append(cell_of(i))
	return out


func most_common_kind() -> int:
	var counts := {}
	for k in cells:
		if _matchable(k):
			counts[k] = counts.get(k, 0) + 1
	var best := 0
	for k in counts:
		if counts[k] > counts.get(best, 0):
			best = k
	return best


## 玩家把同色炸弹和别的宝石交换：返回要清掉的格子（炸弹本身 + 所有和对方同色的宝石）。
## 两个同色炸弹互换：清空整个棋盘。调用前 a、b 已经交换过。
func activate_color_bomb(a: Vector2i, b: Vector2i) -> Array[Vector2i]:
	var out: Array[Vector2i] = []
	var ka := kind_at(a)
	var kb := kind_at(b)
	special[idx(a)] = Special.NONE if ka == RAINBOW else special[idx(a)]   # 引信用掉了，别在链式触发里再炸一次
	special[idx(b)] = Special.NONE if kb == RAINBOW else special[idx(b)]
	if ka == RAINBOW and kb == RAINBOW:
		for i in cells.size():
			out.append(cell_of(i))
		return out
	var target := kb if ka == RAINBOW else ka
	out.append(a if ka == RAINBOW else b)
	for i in cells.size():
		if cells[i] == target:
			out.append(cell_of(i))
	return out

## 死局洗牌：把所有宝石打乱（Fisher–Yates），直到"没有三连并且至少有一步可走"。
## 返回排列 perm：新下标 i 上的宝石来自旧下标 perm[i]（动画用它把宝石飞到新位置）。
## 洗 200 次都不行（颜色太少、棋盘太小）就重新生成，返回空数组。
func shuffle() -> PackedInt32Array:
	var old_cells := cells.duplicate()
	var old_special := special.duplicate()
	var perm := PackedInt32Array()
	perm.resize(cells.size())
	for attempt in 200:
		for i in perm.size():
			perm[i] = i
		for i in range(perm.size() - 1, 0, -1):
			var j := rng.randi_range(0, i)
			var t := perm[i]
			perm[i] = perm[j]
			perm[j] = t
		for i in perm.size():
			cells[i] = old_cells[perm[i]]
			special[i] = old_special[perm[i]]
		if find_matches().is_empty() and not find_valid_moves().is_empty():
			return perm
	fill_without_matches()
	return PackedInt32Array()

## 死局：没有任何一步能形成消除。逻辑层负责洗出一个"无三连、有步可走"的排列，
## 表现层按排列 perm 把每颗宝石飞到新位置。
func _shuffle_board(msg: String) -> void:
	_set_hint([])
	hud.toast(msg)
	var old := _gems.duplicate()
	var perm := board.shuffle()
	var tw := create_tween().set_parallel(true)
	tw.tween_interval(0.01)
	if perm.is_empty():                    # 洗不出来，逻辑层重新生成了：宝石全部重建
		for g in old:
			if g:
				g.queue_free()
		for i in _gems.size():
			_make_gem(board.cell_of(i)).scale = Vector2.ZERO
			tw.tween_property(_gems[i], "scale", Vector2.ONE, 0.3).set_trans(Tween.TRANS_BACK).set_ease(Tween.EASE_OUT)
	else:
		for i in perm.size():
			_gems[i] = old[perm[i]]
			tw.tween_property(_gems[i], "position", view.cell_to_pixel(board.cell_of(i)), 0.45) \
					.set_trans(Tween.TRANS_BACK).set_ease(Tween.EASE_IN_OUT).set_delay(_fx_rng.randf() * 0.12)
	await tw.finished

## 计分：每颗 10 分；一组超过 3 颗，每多一颗 +20；每触发一个特殊宝石 +30。
## 整轮得分再乘以连锁数：第 1 轮 ×1，第 2 轮 ×2……连锁越深越值钱。
func _add_score(res: Dictionary, groups: Array[Dictionary]) -> void:
	var base: int = res.cleared.size() * 10 + res.triggered.size() * 30
	for g in groups:
		base += maxi(0, g.cells.size() - 3) * 20
	var gained := base * chain
	score += gained
	max_chain = maxi(max_chain, chain)
	var center := Vector2.ZERO
	for e: Dictionary in res.cleared:
		center += view.cell_to_pixel(e.cell)
	center /= maxf(1.0, res.cleared.size())
	var col := Color("#fff2a8") if chain < 2 else Color("#ff9ad5")
	fx.float_text(center, "+%d" % gained, col, int(view.cell_size * (0.42 + 0.06 * mini(chain, 5))))
	if chain >= 2:
		hud.show_chain(chain)
		_shake = maxf(_shake, shake_strength * (0.5 + 0.25 * mini(chain, 4)))
	_refresh_hud()

## 星级：达到目标 1 星，1.5 倍 2 星，2 倍 3 星。进度条的满格是 2 倍目标。
static func stars_for(score: int, target: int) -> int:
	if score >= target * 2:
		return 3
	if score >= roundi(target * 1.5):
		return 2
	return 1 if score >= target else 0