Files

T

joywayerandClaude Opus 5 364ebe4c62 docs(plan): E1-③ 子弹归航逐任务实现计划（5 任务 · 含 wrapf 跨 ±π 判据与 R-H1 性能守卫）

Task0 建分支 / Task1 法术 VM 侧 / Task2 bullet_manager 转向+删死快照 /
Task3 设计器字段（含补漏的 bounce）/ Task4 MCP 运行时验收。

验收脚本全部用确定性数值断言：单帧转角上限、速率守恒、跨 ±π 的最短转向
（该摆位下有无 wrapf 会给出符号相反的结果，是有效判据）、目标失效重选、
空场直行、bounce 协同改写 homing_target_id、两层折叠 6.0。

Task4 Step7 实测 spec R-H1 病态场景（50 敌全在射程外 + 300 归航弹），
超 2ms/帧则按 spec §5 启用失败退避逃生方案。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

2026-07-30 13:51:18 +08:00

27 KiB

Raw Blame History

子弹归航（Homing）Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: 子弹在飞行途中以受限角速度转向锁定的敌人（中度制导），激活 homing 深度维度；配 modifier_homing 词条。

Architecture: 镜像现有 bounce 管线。CastStats.homing_add（float 累加）→ _apply_modifier 折叠 meta → _push_projectile 写子弹冷数据 → bullet_manager._gd_integrate 每帧在位置积分之前转向。目标策略为「发射后锁定」：仅在目标死亡（get_pos_by_id 返回哨兵）或首帧时经 _find_nearest_unvisited 重选，配空场守卫，使 query_circle 不进入每帧热路径。同时删除无人消费的 _enemy_pos_snapshot 及其生产者。纯 GDScript 回退路径。

Tech Stack: Godot 4.7.1 Mono / GDScript / 纯 JSON 数据驱动 / godot-mcp-pro 运行时实测（无 pytest；转向行为经运行中战斗场景 execute_game_script 数值断言）。

规范：所有 .gd 改动后 validate_script；纯数据驱动；提交中文。spec：docs_dev/specs/2026-07-30-bullet-homing-design.md。 关键既有事实：子弹 SoA BULLET_STRIDE=12，x/y=slot+0/+1，vx/vy=slot+2/+3，lifetime=slot+4，damage_mult=slot+7。EnemyManager.get_pos_by_id 未命中返回 Vector2(-9999.0, -9999.0)。EnemyManager.get_active_count() 存在（:313）。_find_nearest_unvisited(origin, radius, visited) -> int 已存在（bullet_manager.gd:201，bounce 期引入，已滤哨兵与已访问）。SpellType.MODIFIER=1。SpatialGrid.insert(entity_id, pos) / clear() / query_circle(center, radius)；spawn_enemy 不自动插网格。

Task 0: 建功能分支

Step 1: 从 master 切分支

当前在 master，CLAUDE.md 规定主分支上不做功能开发。

git checkout -b feat/bullet-homing

Expected: Switched to a new branch 'feat/bullet-homing'

Task 1: 法术 VM 侧 —— CastStats.homing_add + 折叠 + 发射写冷数据 + 分支快照 + modifier_homing 数据

Files:

Modify: scripts/domain/spell_system/cast_stats.gd（字段 :15 之后、reset :27 之后）
Modify: scripts/domain/spell_system/spell_evaluator.gd（_push_projectile :438 之后、_apply_modifier :533 之后、分支快照 :615/:625/:652）
Modify: data/spells.json（加 modifier_homing）
Step 1: CastStats 加 homing_add 字段

cast_stats.gd：在 var bounce_add: int = 0 ...（:15）之后新增：

var homing_add:       float = 0.0   # MODIFIER 累加的归航角速度(弧度/秒，叠加到 ACTION 自带 homing)

在 reset() 内 bounce_add = 0（:27）之后新增：

	homing_add      = 0.0

Step 2: _apply_modifier 折叠 homing

spell_evaluator.gd 的 _apply_modifier，在 if meta.has("bounce"): ctx.stats.bounce_add += int(meta["bounce"])（:532-533）之后新增：

	if meta.has("homing"):
		ctx.stats.homing_add += float(meta["homing"])

（缩进：与 if meta.has("bounce"): 同层，函数体一级缩进。）

Step 3: _push_projectile 写归航冷数据

spell_evaluator.gd 的 _push_projectile，在现有 bounce 冷数据块最后一行 cold["bounce_range"] = float(meta.get("bounce_range", 250.0))（:438）之后新增：

			var homing: float = float(meta.get("homing", 0.0)) + ctx.stats.homing_add
			if homing > 0.0:
				cold["homing_strength"]  = homing
				cold["homing_range"]     = float(meta.get("homing_range", 400.0))
				cold["homing_target_id"] = -1

（缩进：var homing 与 var bounce（:433）同层，在 for i in spread: 循环体内；cold[...] 再深一级。）

Step 4: CIRCUIT 分支快照/还原纳入 homing_add

spell_evaluator.gd 的 _run_branch_payload。在快照段 var b_bnc: int = s.bounce_add（:625）之后新增：

	var b_hom:  float = s.homing_add

在还原段 s.bounce_add = b_bnc（:652）之后新增：

	s.homing_add      = b_hom

把 :615 的注释「快照分支前 CastStats（9 字段，无分配）」改为「（10 字段，无分配）」。

Step 5: spells.json 加 modifier_homing

在 data/spells.json 中 modifier_bounce 行之后（同为 type 1 修饰器区）新增一行（注意逗号）：

  "modifier_homing":      { "type": 1, "display_name": "Homing",      "description": "后续法术获得归航（飞行中以受限角速度转向锁定的敌人）。", "element_tags": [], "meta": { "homing": 3.0, "mana_cost": 8, "shop_cost": 18 } },

Step 6: 校验语法 + 数据

Run: godot-mcp-pro validate_script on res://scripts/domain/spell_system/cast_stats.gd 与 res://scripts/domain/spell_system/spell_evaluator.gd — 均无错误。

Run: godot-mcp-pro execute_editor_script：

var d = JSON.parse_string(FileAccess.get_file_as_string("res://data/spells.json"))
var ok: bool = d is Dictionary and d.has("modifier_homing") \
	and abs(float(d["modifier_homing"]["meta"].get("homing", 0.0)) - 3.0) < 0.001 \
	and int(d["modifier_homing"]["meta"].get("shop_cost", 0)) == 18
_mcp_print("FAILS=%d" % (0 if ok else 1))

Expected: FAILS=0

Step 7: 提交

git add scripts/domain/spell_system/cast_stats.gd scripts/domain/spell_system/spell_evaluator.gd data/spells.json
git commit -F- <<'EOF'
feat(homing): CastStats.homing_add + 修饰器折叠 + 发射写归航冷数据 + 分支快照; modifier_homing 词条

homing_add 为 float（角速度，弧度/秒），镜像 bounce_add 的 int 累加路径。
发射时不解析目标，homing_target_id 留 -1 由 bullet_manager 首帧惰性获取，
使 spell_evaluator 不必接触 SpatialGrid。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
EOF

Task 2: 子弹归航转向 —— bullet_manager + 删除死快照

Files:

Modify: scripts/autoloads/bullet_manager.gd（文件头注释 :21、成员 :22、_physics_process :31、_gd_integrate :36-51、bounce 块 :119 之后、新增 _apply_homing）
Modify: scripts/autoloads/enemy_manager.gd（删 fill_pos_snapshot :345-350）
Step 1: 删除无人消费的敌人位置快照

bullet_manager.gd：删除第 21-22 两行：

# 敌人位置快照（homing 共用，由 _physics_process 帧头建立）
var _enemy_pos_snapshot: PackedVector2Array = PackedVector2Array()

并删除 _physics_process（:30-33）内的第 31 行 EnemyManager.fill_pos_snapshot(_enemy_pos_snapshot)，使其变为：

func _physics_process(delta: float) -> void:
	if not _cs_node:
		_gd_integrate(delta)

不要动文件头第 8 行的冷数据注释 —— 它列出的 homing 正是本期要实现的冷数据字段，删除的只是那份按槽位存位置、无人消费的快照。

enemy_manager.gd：删除 :345-350 整个函数（含其上的 ## 注释行）：

## 建立敌人位置快照（BulletManager homing 共用）
func fill_pos_snapshot(out_arr: PackedVector2Array) -> void:
	out_arr.resize(_active_count)
	for i in _active_count:
		var base: int = i * ENEMY_STRIDE
		out_arr[i] = Vector2(_data[base + 0], _data[base + 1])

（已 grep 确认全项目无其它调用方。）

Step 2: _gd_integrate 循环体顶部插入归航转向调用

bullet_manager.gd 的 _gd_integrate，改为（新增第 2 行 has_cold 与循环体内的两行 if）：

func _gd_integrate(delta: float) -> void:
	var has_cold: bool = not _bullet_contexts.is_empty()
	var i: int = 0
	while i < _active_count:
		var base: int = i * BULLET_STRIDE
		if has_cold and _bullet_contexts.has(i):
			_apply_homing(i, base, delta)          # 转向须在位置积分之前，子弹当帧即沿新方向前进
		_data[base + 0] += _data[base + 2] * delta  # x += vx * dt
		_data[base + 1] += _data[base + 3] * delta  # y += vy * dt
		_data[base + 2] += _data[base + 11] * delta # vx += accel * dt
		_data[base + 3] += _data[base + 11] * delta # vy += accel * dt
		_data[base + 4] -= delta                     # lifetime -= dt
		if _data[base + 4] <= 0.0:
			_swap_and_pop(i)
		elif _check_collision(i, base):
			# 命中处理已在 _check_collision 内完成，子弹被回收
			pass  # _active_count 已减少，i 不递增
		else:
			i += 1

Step 3: 新增 _apply_homing 辅助

在 bullet_manager.gd 的 _find_nearest_unvisited（:201，删除快照两行后行号上移 2）之后新增：

## 归航转向：以 homing_strength(弧度/秒) 为上限把速度矢量转向锁定目标，速率不变
## 目标失效（死亡/未锁定）时重选一次；场上无敌人或射程内无目标则保持直行
func _apply_homing(bullet_idx: int, base: int, delta: float) -> void:
	var cold: Dictionary = _bullet_contexts[bullet_idx]
	var strength: float = float(cold.get("homing_strength", 0.0))
	if strength <= 0.0:
		return
	var pos: Vector2 = Vector2(_data[base + 0], _data[base + 1])
	var tid: int = int(cold.get("homing_target_id", -1))
	var tpos: Vector2 = Vector2(-9999.0, -9999.0)
	if tid >= 0:
		tpos = EnemyManager.get_pos_by_id(tid)
	if tpos == Vector2(-9999.0, -9999.0):
		# 目标失效或首帧：重选。空场守卫避免清场瞬间全体子弹集体 query_circle
		if EnemyManager.get_active_count() == 0:
			return
		tid = _find_nearest_unvisited(pos, float(cold.get("homing_range", 400.0)), cold.get("visited_targets", []))
		cold["homing_target_id"] = tid
		_bullet_contexts[bullet_idx] = cold
		if tid < 0:
			return
		tpos = EnemyManager.get_pos_by_id(tid)
		if tpos == Vector2(-9999.0, -9999.0):
			return
	var vel: Vector2 = Vector2(_data[base + 2], _data[base + 3])
	var diff: float = wrapf((tpos - pos).angle() - vel.angle(), -PI, PI)   # 最短转向方向
	var max_step: float = strength * delta
	var nv: Vector2 = vel.rotated(clampf(diff, -max_step, max_step))       # rotated 保持速率不变
	_data[base + 2] = nv.x
	_data[base + 3] = nv.y

Step 4: bounce 重定向时改写 homing 目标（协同）

bullet_manager.gd 的 _check_collision 弹跳分支，在 cold["bounce_remaining"] = bounce - 1（:119）之前插入：

					if cold.has("homing_strength"):
						cold["homing_target_id"] = next_id   # bounce 选目标，homing 接手追上去

（缩进：与 cold["bounce_remaining"] = bounce - 1 同层，在 if next_id >= 0: 块内。）

Step 5: 校验语法

Run: godot-mcp-pro validate_script on res://scripts/autoloads/bullet_manager.gd 与 res://scripts/autoloads/enemy_manager.gd — 均无错误。

Step 6: 提交

git add scripts/autoloads/bullet_manager.gd scripts/autoloads/enemy_manager.gd
git commit -F- <<'EOF'
feat(homing): bullet_manager 受限角速度转向 + 锁定式目标重选 + bounce 协同; 删除无人消费的位置快照

_apply_homing 在位置积分前把速度矢量朝目标旋转，单帧转角上限 strength*delta，
rotated() 保持速率不变；wrapf 取最短转向方向。
目标仅在失效或首帧时经 _find_nearest_unvisited 重选，配 get_active_count()==0
空场守卫，避免 query_circle(r=400) 进入每帧热路径。
bounce 命中重定向时改写 homing_target_id，由 bounce 选目标 homing 追上去。
删除 _enemy_pos_snapshot 及 EnemyManager.fill_pos_snapshot（全项目唯一调用方）。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
EOF

Task 3: 设计器 MODIFIER 字段 —— 加 homing + 补漏掉的 bounce

Files:

Modify: addons/game_designer/spell_tab.gd（MODIFIER schema :154 附近）
Step 1: MODIFIER schema 加两个字段

spell_tab.gd 的 type 1（MODIFIER）分支，在 {"k": "pierce", "l": "穿透 pierce", "w": "i", "d": 0, "opt": true},（:154）之后新增两行：

			{"k": "bounce", "l": "弹跳 bounce", "w": "i", "d": 0, "opt": true},
			{"k": "homing", "l": "归航 homing", "w": "f", "d": 0.0, "opt": true},

bounce 是补上期遗漏 —— 它至今掉在「其它(JSON)」逃生舱里（:81），违反 CLAUDE.md「字段化，禁止手写 JSON」。标签遵循「中文 English」双语序。

Step 2: 校验语法

Run: godot-mcp-pro validate_script on res://addons/game_designer/spell_tab.gd — 无错误。

Step 3: 对真实数据验证 schema 覆盖

⚠️ dock 里驻留的旧 @tool 类需 EditorInterface.restart_editor(true) 清缓存才测得到新代码（reload_project/reload_plugin 不重编译已加载类）。本步绕开类实例化，直接断言「schema 声明的键集合已覆盖真实 JSON 里所有 type 1 法术的 meta 键」，不受缓存影响。

Run: godot-mcp-pro execute_editor_script：

var src := FileAccess.get_file_as_string("res://addons/game_designer/spell_tab.gd")
var d = JSON.parse_string(FileAccess.get_file_as_string("res://data/spells.json"))
# 通用键由表单固定处理，不进 meta schema
var generic := {"mana_cost": true, "shop_cost": true}
var missing := []
for id in d.keys():
	if int(d[id].get("type", -1)) != 1:
		continue
	for k in d[id].get("meta", {}).keys():
		if generic.has(k):
			continue
		if not src.contains('"k": "%s"' % k):
			missing.append("%s.%s" % [id, k])
_mcp_print("FAILS=%d missing=%s" % [missing.size(), str(missing)])

Expected: FAILS=0 missing=[]（改动前跑此脚本会报 bounce 缺失 —— 可先跑一次确认它确实抓得到回归。）

Step 4: 提交

git add addons/game_designer/spell_tab.gd
git commit -F- <<'EOF'
feat(homing): 设计器 MODIFIER 表单加 homing 字段，并补上期遗漏的 bounce 字段

bounce 自上期起一直掉在「其它(JSON)」逃生舱，违反 CLAUDE.md 字段化规范，
与 homing 同处 schema，一并补上。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
EOF

Task 4: 验收 —— 运行时集成实测（MCP）+ 收尾

Files: 无（运行时断言）+ 收尾文档

Step 1: 启动战斗场景

Run: godot-mcp-pro play_scene → res://scenes/main/combat_s2.tscn。确认运行、get_editor_errors count=0。

Step 2: 归航生效 + 角速度上限 + 速率守恒（验收①②③）

摆位：敌人在子弹侧前方，子弹沿 +x 直飞。归航子弹应逐帧朝敌人转向；对照组（无 homing 冷数据）方向恒定。 delta = 1/60，strength = 3.0 → 单帧最大转角 0.05 rad。