docs: 计划回填实际执行的验收脚本 + 订正权威文档自相矛盾处 + 性能数字改区间
【计划 Task 4】原稿四个脚本有缺陷，照它复跑会得到假失败与空通过，现已替换为 实际执行并通过的版本，每处旁注「原脚本为何有缺陷」，并勾上完成的复选框： - Step 2 敌人摆位 (400,200) 距原点 447px 已出 homing_range=400，实测 FAILS=1； 这是测试摆位错误而非实现缺陷（精确距离过滤行为正确）。改到 (300,150)。 - Step 6 内联复刻了折叠逻辑与商店谓词——在测自己；改调真实 _apply_modifier 与 ShopManager._available_pool()，另补 compile_wand→execute_compiled 端到端。 - Step 7 无墙钟起搏，40 帧全停在退避窗内、守卫沦为空断言；且几何让子弹直穿 敌人簇，多计约 1.5ms 碰撞开销。改为 60fps 起搏 + spec §5.2 环形摆位， frame1 与稳态峰值分开报。 - Step 8 只对源码 grep 字符串，不是往返；改为真实实例化 spell_tab 对真实 spells.json 做 8 条 type-1 的回读→写回比对。 回溯表补「观测方式」列，标出⑥是唯一一条状态推断而非直接观测。 【architecture_design.md】同一文档内自相矛盾： - CastStats 块 homing_force（「归航强度，向最近敌人偏转」）与 §4.2 新写的 「最大转向角速度 + 锁定式目标」冲突 → 订正为 homing_add(弧度/秒)； 顺带订正确证过的 pierce_add / bounce_add（原写 *_count）。该块其余字段 仍有既有漂移，加 ⚠️ 注明未核对、以 cast_stats.gd 为准，不扩大改动范围。 - ProjectileDef 的 homing_force 删除——projectile_def.gd 无任何 homing 字段， 归航冷数据由 _push_projectile 直接写入 BulletManager。 - §4.2 bounce 协同散文补上实际存在的 if cold.has("homing_strength") 前置守卫。 - get_nearest_pos 代码片段：_enemy_count → _active_count（前者不存在）、 未命中返回值 Vector2.ZERO → origin、删除不存在的 _visible_flags 过滤。 【spec】 - §4 第⑥条措辞「不触发 query_circle」字面为假（_check_collision 每帧无条件 发一次），改为「不因归航触发」，并写明这是唯一一条间接验证及其封闭性论证。 - §5.5 峰值改为区间表述（① 4~5ms / ② 5~7ms @1500），注明编辑器/调试构建、 运行间离散（同场景三次得 5.61/5.09/7.29ms），判定回归看是否出现周期性复发 尖峰与是否越过 16.67ms，勿拿单值比对；并记录几何对测量的影响。 - §5.4 勘误：「1493 个互异到期值」不可能成立（jitter 只能产出约 200 个整数值， 同帧失败又共用同一 now），复测为跨度 223ms / 222 个互异值，结论不变。 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Claude Opus 5
@@ -73,6 +73,9 @@ graph TD
|
||||
|
||||
#### A. 基础单元 (SpellNode)
|
||||
这是所有"部件"的基类。
|
||||
|
||||
> **⚠️ 本块与实现存在既有漂移（2026-07-30 部分订正）**：`pierce_add` / `bounce_add` / `homing_add` 三项已按 `scripts/domain/spell_system/cast_stats.gd` 实测订正（原写 `pierce_count` / `bounce_count` / `homing_force`）。**其余字段仍未核对**：实现里没有 `projectile_speed` / `spread_angle` / `projectile_size` / `range_mult`，实际为 `spread_count` / `speed_mult` / `radius_mult` / `lifetime` / `multicast_count`。此漂移早于本次归航改动，未一并订正以免超出改动范围 —— **以 `cast_stats.gd` 为准**。
|
||||
|
||||
```gdscript
|
||||
# cast_stats.gd - MODIFIER 节点的修改目标；通过 SpellContext.stats 访问
|
||||
class_name CastStats
|
||||
@@ -82,17 +85,18 @@ var damage_add: float = 0.0 # 累加伤害加成（所有 Dmg+ 修正
|
||||
var damage_mult: float = 1.0 # 乘算伤害系数（暴击、元素弱点等乘入）
|
||||
var projectile_speed: float = 600.0 # 弹道飞行速度（像素/秒）
|
||||
var spread_angle: float = 0.0 # 散射角度（度，0 = 直线）
|
||||
var pierce_count: int = 0 # 穿透次数（0 = 首次命中即销毁）
|
||||
var bounce_count: int = 0 # 弹射次数（0 = 不弹射）
|
||||
var homing_force: float = 0.0 # 归航强度（0 = 直线，>0 向最近敌人偏转）
|
||||
var pierce_add: int = 0 # MODIFIER 累加的穿透次数（叠加到 ACTION 自带 pierce）
|
||||
var bounce_add: int = 0 # MODIFIER 累加的弹跳次数（叠加到 ACTION 自带 bounce）
|
||||
var homing_add: float = 0.0 # MODIFIER 累加的归航【最大转向角速度】，单位 弧度/秒
|
||||
# （叠加到 ACTION 自带 homing；语义见 §4.2 Homing 受限角速度制导）
|
||||
var projectile_size: float = 1.0 # 弹道大小系数（影响碰撞半径与贴图缩放）
|
||||
var range_mult: float = 1.0 # 射程乘算系数（弹道消失前飞行距离倍率）
|
||||
var crit_chance: float = 0.0 # 本次施法暴击率追加量（0.0~1.0，叠加而非覆盖）
|
||||
|
||||
func reset() -> void:
|
||||
damage_add = 0.0; damage_mult = 1.0; projectile_speed = 600.0
|
||||
spread_angle = 0.0; pierce_count = 0; bounce_count = 0
|
||||
homing_force = 0.0; projectile_size = 1.0; range_mult = 1.0; crit_chance = 0.0
|
||||
spread_angle = 0.0; pierce_add = 0; bounce_add = 0
|
||||
homing_add = 0.0; projectile_size = 1.0; range_mult = 1.0; crit_chance = 0.0
|
||||
|
||||
# spell_context.gd - 使用 RefCounted 避免 GC 压力
|
||||
class_name SpellContext
|
||||
@@ -192,7 +196,10 @@ var damage_type: int = DamageType.PHYSICAL # DamageType 枚举（见上方定
|
||||
var speed: float = 600.0 # 初速度（像素/秒）
|
||||
var direction: Vector2 = Vector2.RIGHT
|
||||
var spread_angle_rad: float = 0.0 # 在 direction 基础上的随机偏转幅度
|
||||
var homing_force: float = 0.0 # 每帧转向力（0 = 直线）
|
||||
# 注：归航【不】经 ProjectileDef 传递。`projectile_def.gd` 无任何 homing 字段 ——
|
||||
# SpellEvaluator._push_projectile 直接把 homing_strength / homing_range /
|
||||
# homing_target_id 写进 BulletManager 的冷数据字典（详见 §4.2）。
|
||||
# 原此处的 `homing_force`（「每帧转向力」）语义与实现均不存在，2026-07-30 删除。
|
||||
var acceleration: float = 0.0 # 速度加速度（可为负，做减速球）
|
||||
|
||||
# ── 生命周期 ──────────────────────────────────────────────
|
||||
@@ -675,7 +682,13 @@ func _node_has_tag(node: SpellNode, tag_pattern: String) -> bool:
|
||||
|
||||
> **⚠️ 失败退避必须带抖动**（spec §5.4，本次最值得记住的一条）：重选**失败**时若不留记录，该子弹余生每帧都会重跑 `query_circle(r=400)`（半径 400 覆盖约 196 格 + 一次 `PackedInt32Array` 分配 ≈ 一百多次碰撞查询）。但**朴素固定退避会把子弹锁进同相、而非打散** —— 同帧失败的子弹拿到同一个 `now`，一个退避周期后又整齐地一起重试，尖峰每 12 帧永久复发。故抖动到期时刻，用「`bullet_idx` 在活跃弹数中的占比」铺满恰好一个退避周期（`HOMING_RETRY_MS` 一值两用：既是基础退避时长也是抖动窗口宽度）。实测数据见 spec §5.2 / §5.5，此处不复述以免两套数字分叉。
|
||||
|
||||
> **与 bounce 协同**：bounce 在命中瞬间硬重定向到「最近未访问敌」，若不协调，下一帧 homing 就会覆盖它、使 bounce 失效。语义定为**bounce 负责选目标、homing 负责追上去**：bounce 重定向块内改写 `cold["homing_target_id"] = next_id` 并 `cold.erase("homing_retry_at")`（新目标有效，须撤销过期退避）。
|
||||
> **与 bounce 协同**：bounce 在命中瞬间硬重定向到「最近未访问敌」，若不协调，下一帧 homing 就会覆盖它、使 bounce 失效。语义定为**bounce 负责选目标、homing 负责追上去**。bounce 重定向块内：
|
||||
> ```gdscript
|
||||
> if cold.has("homing_strength"): # 前置守卫：纯 bounce 弹不写 homing 键
|
||||
> cold["homing_target_id"] = next_id
|
||||
> cold.erase("homing_retry_at") # 新目标有效，须撤销过期退避
|
||||
> ```
|
||||
> `has("homing_strength")` 这个守卫不可省 —— 没有它，纯 bounce 子弹会被塞进一个永不被消费的 `homing_target_id`；而 `erase` 不可省是因为退避键若残留，子弹会对着 bounce 刚给的有效目标拒绝转向（该缺陷在实现期评审中实测复现并修复）。
|
||||
|
||||
* **EnemyManager 对外查询接口**：以下函数供 BulletManager、DropManager、BossManager、AudioManager 调用，均为 GDScript 侧接口（轻量读操作，非热路径）：
|
||||
|
||||
@@ -713,17 +726,16 @@ func _node_has_tag(node: SpellNode, tag_pattern: String) -> bool:
|
||||
func get_nearest_pos(origin: Vector2, max_dist: float = 9999.0) -> Vector2:
|
||||
# BulletManager.get_nearest_enemy_pos() 调用；直接线性扫描 SoA _data，O(M)
|
||||
# 仅在发射时调用，非每帧热路径（homing 走 get_pos_by_id 锁定目标，不经此函数）
|
||||
var best_pos := Vector2.ZERO
|
||||
var best_pos := origin # 无敌人时返回 origin（非 Vector2.ZERO）
|
||||
var best_dist := max_dist * max_dist # 比较平方距离，避免 sqrt
|
||||
for i in range(_enemy_count):
|
||||
if _visible_flags[i] == 0: continue # 跳过屏外（可选：也可全扫）
|
||||
for i in _active_count: # _active_count，不存在 _enemy_count
|
||||
var px := _data[i * ENEMY_STRIDE + 0]
|
||||
var py := _data[i * ENEMY_STRIDE + 1]
|
||||
var d2 := (px - origin.x) * (px - origin.x) + (py - origin.y) * (py - origin.y)
|
||||
if d2 < best_dist:
|
||||
best_dist = d2
|
||||
best_pos = Vector2(px, py)
|
||||
return best_pos
|
||||
return best_pos # 实现全扫存活敌人，不按 _visible_flags 过滤
|
||||
```
|
||||
|
||||
> **EnemyManager SoA 完整槽位布局**（权威来源：`implementation_plan.md §2.3.C`，P6-N45）：
|
||||
|
||||
@@ -15,7 +15,7 @@
|
||||
|
||||
### Task 0: 建功能分支
|
||||
|
||||
- [ ] **Step 1: 从 master 切分支**
|
||||
- [x] **Step 1: 从 master 切分支**
|
||||
|
||||
当前在 `master`，CLAUDE.md 规定主分支上不做功能开发。
|
||||
|
||||
@@ -34,7 +34,7 @@ Expected: `Switched to a new branch 'feat/bullet-homing'`
|
||||
- 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 字段**
|
||||
- [x] **Step 1: CastStats 加 homing_add 字段**
|
||||
|
||||
`cast_stats.gd`：在 `var bounce_add: int = 0 ...`（:15）之后新增：
|
||||
```gdscript
|
||||
@@ -45,7 +45,7 @@ var homing_add: float = 0.0 # MODIFIER 累加的归航角速度(弧度/
|
||||
homing_add = 0.0
|
||||
```
|
||||
|
||||
- [ ] **Step 2: `_apply_modifier` 折叠 homing**
|
||||
- [x] **Step 2: `_apply_modifier` 折叠 homing**
|
||||
|
||||
`spell_evaluator.gd` 的 `_apply_modifier`，在 `if meta.has("bounce"): ctx.stats.bounce_add += int(meta["bounce"])`（:532-533）之后新增：
|
||||
```gdscript
|
||||
@@ -54,7 +54,7 @@ var homing_add: float = 0.0 # MODIFIER 累加的归航角速度(弧度/
|
||||
```
|
||||
（缩进：与 `if meta.has("bounce"):` 同层，函数体一级缩进。）
|
||||
|
||||
- [ ] **Step 3: `_push_projectile` 写归航冷数据**
|
||||
- [x] **Step 3: `_push_projectile` 写归航冷数据**
|
||||
|
||||
`spell_evaluator.gd` 的 `_push_projectile`，在现有 bounce 冷数据块最后一行 `cold["bounce_range"] = float(meta.get("bounce_range", 250.0))`（:438）之后新增：
|
||||
```gdscript
|
||||
@@ -66,7 +66,7 @@ var homing_add: float = 0.0 # MODIFIER 累加的归航角速度(弧度/
|
||||
```
|
||||
（缩进：`var homing` 与 `var bounce`（:433）同层，在 `for i in spread:` 循环体内；`cold[...]` 再深一级。）
|
||||
|
||||
- [ ] **Step 4: CIRCUIT 分支快照/还原纳入 homing_add**
|
||||
- [x] **Step 4: CIRCUIT 分支快照/还原纳入 homing_add**
|
||||
|
||||
`spell_evaluator.gd` 的 `_run_branch_payload`。在快照段 `var b_bnc: int = s.bounce_add`（:625）之后新增：
|
||||
```gdscript
|
||||
@@ -78,14 +78,14 @@ var homing_add: float = 0.0 # MODIFIER 累加的归航角速度(弧度/
|
||||
```
|
||||
把 :615 的注释「快照分支前 CastStats（9 字段，无分配）」改为「（10 字段，无分配）」。
|
||||
|
||||
- [ ] **Step 5: spells.json 加 modifier_homing**
|
||||
- [x] **Step 5: spells.json 加 modifier_homing**
|
||||
|
||||
在 `data/spells.json` 中 `modifier_bounce` 行之后（同为 type 1 修饰器区）新增一行（注意逗号）：
|
||||
```json
|
||||
"modifier_homing": { "type": 1, "display_name": "Homing", "description": "后续法术获得归航（飞行中以受限角速度转向锁定的敌人）。", "element_tags": [], "meta": { "homing": 3.0, "mana_cost": 8, "shop_cost": 18 } },
|
||||
```
|
||||
|
||||
- [ ] **Step 6: 校验语法 + 数据**
|
||||
- [x] **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` — 均无错误。
|
||||
|
||||
@@ -99,7 +99,7 @@ _mcp_print("FAILS=%d" % (0 if ok else 1))
|
||||
```
|
||||
Expected: `FAILS=0`
|
||||
|
||||
- [ ] **Step 7: 提交**
|
||||
- [x] **Step 7: 提交**
|
||||
|
||||
```bash
|
||||
git add scripts/domain/spell_system/cast_stats.gd scripts/domain/spell_system/spell_evaluator.gd data/spells.json
|
||||
@@ -122,7 +122,7 @@ EOF
|
||||
- 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: 删除无人消费的敌人位置快照**
|
||||
- [x] **Step 1: 删除无人消费的敌人位置快照**
|
||||
|
||||
`bullet_manager.gd`：删除第 21-22 两行：
|
||||
```gdscript
|
||||
@@ -148,7 +148,7 @@ func fill_pos_snapshot(out_arr: PackedVector2Array) -> void:
|
||||
```
|
||||
（已 grep 确认全项目无其它调用方。）
|
||||
|
||||
- [ ] **Step 2: `_gd_integrate` 循环体顶部插入归航转向调用**
|
||||
- [x] **Step 2: `_gd_integrate` 循环体顶部插入归航转向调用**
|
||||
|
||||
`bullet_manager.gd` 的 `_gd_integrate`，改为（新增第 2 行 `has_cold` 与循环体内的两行 if）：
|
||||
```gdscript
|
||||
@@ -173,7 +173,7 @@ func _gd_integrate(delta: float) -> void:
|
||||
i += 1
|
||||
```
|
||||
|
||||
- [ ] **Step 3: 新增 `_apply_homing` 辅助**
|
||||
- [x] **Step 3: 新增 `_apply_homing` 辅助**
|
||||
|
||||
在 `bullet_manager.gd` 的 `_find_nearest_unvisited`（:201，删除快照两行后行号上移 2）之后新增：
|
||||
```gdscript
|
||||
@@ -209,7 +209,7 @@ func _apply_homing(bullet_idx: int, base: int, delta: float) -> void:
|
||||
_data[base + 3] = nv.y
|
||||
```
|
||||
|
||||
- [ ] **Step 4: bounce 重定向时改写 homing 目标（协同）**
|
||||
- [x] **Step 4: bounce 重定向时改写 homing 目标（协同）**
|
||||
|
||||
`bullet_manager.gd` 的 `_check_collision` 弹跳分支，在 `cold["bounce_remaining"] = bounce - 1`（:119）之前插入：
|
||||
```gdscript
|
||||
@@ -218,11 +218,11 @@ func _apply_homing(bullet_idx: int, base: int, delta: float) -> void:
|
||||
```
|
||||
（缩进：与 `cold["bounce_remaining"] = bounce - 1` 同层，在 `if next_id >= 0:` 块内。）
|
||||
|
||||
- [ ] **Step 5: 校验语法**
|
||||
- [x] **Step 5: 校验语法**
|
||||
|
||||
Run: godot-mcp-pro `validate_script` on `res://scripts/autoloads/bullet_manager.gd` 与 `res://scripts/autoloads/enemy_manager.gd` — 均无错误。
|
||||
|
||||
- [ ] **Step 6: 提交**
|
||||
- [x] **Step 6: 提交**
|
||||
|
||||
```bash
|
||||
git add scripts/autoloads/bullet_manager.gd scripts/autoloads/enemy_manager.gd
|
||||
@@ -247,7 +247,7 @@ EOF
|
||||
**Files:**
|
||||
- Modify: `addons/game_designer/spell_tab.gd`（MODIFIER schema :154 附近）
|
||||
|
||||
- [ ] **Step 1: MODIFIER schema 加两个字段**
|
||||
- [x] **Step 1: MODIFIER schema 加两个字段**
|
||||
|
||||
`spell_tab.gd` 的 `type 1`（MODIFIER）分支，在 `{"k": "pierce", "l": "穿透 pierce", "w": "i", "d": 0, "opt": true},`（:154）之后新增两行：
|
||||
```gdscript
|
||||
@@ -256,11 +256,11 @@ EOF
|
||||
```
|
||||
`bounce` 是补上期遗漏 —— 它至今掉在「其它(JSON)」逃生舱里（:81），违反 CLAUDE.md「字段化，禁止手写 JSON」。标签遵循「中文 English」双语序。
|
||||
|
||||
- [ ] **Step 2: 校验语法**
|
||||
- [x] **Step 2: 校验语法**
|
||||
|
||||
Run: godot-mcp-pro `validate_script` on `res://addons/game_designer/spell_tab.gd` — 无错误。
|
||||
|
||||
- [ ] **Step 3: 对真实数据验证 schema 覆盖**
|
||||
- [x] **Step 3: 对真实数据验证 schema 覆盖**
|
||||
|
||||
> ⚠️ dock 里驻留的旧 `@tool` 类需 `EditorInterface.restart_editor(true)` 清缓存才测得到新代码（`reload_project`/`reload_plugin` **不**重编译已加载类）。本步绕开类实例化，直接断言「schema 声明的键集合已覆盖真实 JSON 里所有 type 1 法术的 meta 键」，不受缓存影响。
|
||||
|
||||
@@ -283,7 +283,7 @@ _mcp_print("FAILS=%d missing=%s" % [missing.size(), str(missing)])
|
||||
```
|
||||
Expected: `FAILS=0 missing=[]`（改动前跑此脚本会报 `bounce` 缺失 —— 可先跑一次确认它确实抓得到回归。）
|
||||
|
||||
- [ ] **Step 4: 提交**
|
||||
- [x] **Step 4: 提交**
|
||||
|
||||
```bash
|
||||
git add addons/game_designer/spell_tab.gd
|
||||
@@ -303,22 +303,25 @@ EOF
|
||||
|
||||
**Files:** 无（运行时断言）+ 收尾文档
|
||||
|
||||
- [ ] **Step 1: 启动战斗场景**
|
||||
- [x] **Step 1: 启动战斗场景**
|
||||
|
||||
Run: godot-mcp-pro `play_scene` → `res://scenes/main/combat_s2.tscn`。确认运行、`get_editor_errors` count=0。
|
||||
|
||||
- [ ] **Step 2: 归航生效 + 角速度上限 + 速率守恒（验收①②③）**
|
||||
- [x] **Step 2: 归航生效 + 角速度上限 + 速率守恒（验收①②③）**
|
||||
|
||||
> 摆位：敌人在子弹**侧前方**，子弹沿 +x 直飞。归航子弹应逐帧朝敌人转向；对照组（无 homing 冷数据）方向恒定。
|
||||
> `delta = 1/60`，`strength = 3.0` → 单帧最大转角 `0.05 rad`。
|
||||
>
|
||||
> ⚠️ **本脚本已按实际执行版本替换（2026-07-30 验收期）**。原稿把敌人放在 `(400, 200)` —— 距原点 **447.2 px，超出 `homing_range = 400`**，`_find_nearest_unvisited` 的精确距离过滤（`best_sq = radius * radius`）会正确地拒绝它，于是归航完全不动、`FAILS=1`。这是**测试摆位错误，不是实现缺陷**（`query_circle` 按格子返回该敌，但精确距离判据把它滤掉了，行为正确）。已改到 `(300, 150)` = 335 px，落在射程内。**不要退回 `(400, 200)`。**
|
||||
|
||||
Run: godot-mcp-pro `execute_game_script`：
|
||||
```gdscript
|
||||
BulletManager.reset(); EnemyManager.reset(); SpatialGrid.clear()
|
||||
var e = EnemyManager.spawn_enemy(Vector2(400, 200), 100000.0, 0) # 侧前方，血厚防被打死
|
||||
SpatialGrid.insert(e, Vector2(400, 200))
|
||||
var ep := Vector2(300, 150) # dist=335 < homing_range 400（原稿 (400,200) 距 447 已出射程）
|
||||
var e = EnemyManager.spawn_enemy(ep, 100000.0, 0) # 血厚防被打死
|
||||
SpatialGrid.insert(e, ep)
|
||||
var dt := 1.0 / 60.0
|
||||
# 归航弹：起点远离敌人避免命中，沿 +x，速度 350
|
||||
# 归航弹：沿 +x，速度 350
|
||||
BulletManager.spawn_bullet(Vector2(0, 0), Vector2(350, 0), 5.0, 6.0, 1.0, 1.0, 0, -1, 0, 0.0,
|
||||
{"homing_strength": 3.0, "homing_range": 400.0, "homing_target_id": -1})
|
||||
# 对照弹：同起点同速度，无冷数据
|
||||
@@ -327,12 +330,16 @@ var fails := 0
|
||||
var max_step_seen := 0.0
|
||||
var prev_a := Vector2(BulletManager._data[2], BulletManager._data[3]).angle()
|
||||
var speed0 := Vector2(BulletManager._data[2], BulletManager._data[3]).length()
|
||||
var angles := []
|
||||
var speeds := []
|
||||
for k in 5:
|
||||
BulletManager._gd_integrate(dt)
|
||||
var v := Vector2(BulletManager._data[2], BulletManager._data[3])
|
||||
var step: float = abs(wrapf(v.angle() - prev_a, -PI, PI))
|
||||
if step > max_step_seen: max_step_seen = step
|
||||
prev_a = v.angle()
|
||||
angles.append("%.5f" % v.angle())
|
||||
speeds.append("%.4f" % v.length())
|
||||
var vh := Vector2(BulletManager._data[2], BulletManager._data[3]) # 归航弹
|
||||
var vc := Vector2(BulletManager._data[BulletManager.BULLET_STRIDE + 2],
|
||||
BulletManager._data[BulletManager.BULLET_STRIDE + 3]) # 对照弹
|
||||
@@ -340,12 +347,62 @@ if vh.angle() <= 0.001: fails += 1 # ① 已朝 +y 侧转
|
||||
if abs(vc.angle()) > 0.001: fails += 1 # ① 对照组仍是 +x
|
||||
if max_step_seen > 3.0 * dt + 0.0005: fails += 1 # ② 单帧转角 ≤ strength*delta
|
||||
if abs(vh.length() - speed0) > 0.5: fails += 1 # ③ 速率守恒
|
||||
_mcp_print("FAILS=%d ah=%.4f ac=%.4f max_step=%.4f cap=%.4f spd=%.2f→%.2f" %
|
||||
[fails, vh.angle(), vc.angle(), max_step_seen, 3.0 * dt, speed0, vh.length()])
|
||||
_mcp_print("FAILS=%d ah=%.5f ac=%.5f max_step=%.6f cap=%.6f spd=%.4f->%.4f ctrl_spd=%.4f" %
|
||||
[fails, vh.angle(), vc.angle(), max_step_seen, 3.0 * dt, speed0, vh.length(), vc.length()])
|
||||
_mcp_print("angles=%s" % str(angles))
|
||||
_mcp_print("speeds=%s tid=%d retry_key=%s" % [str(speeds),
|
||||
int(BulletManager._bullet_contexts[0]["homing_target_id"]),
|
||||
str(BulletManager._bullet_contexts[0].has("homing_retry_at"))])
|
||||
```
|
||||
Expected: `FAILS=0`，`ah` 明显 > 0（约 0.05×5 ≈ 0.25 rad，受实际几何略有出入但必为正），`ac ≈ 0`，`max_step ≤ 0.05`，速率两端均 ≈350。
|
||||
实测输出：
|
||||
```
|
||||
FAILS=0 ah=0.25000 ac=0.00000 max_step=0.050000 cap=0.050000 spd=350.0000->350.0000 ctrl_spd=350.0000
|
||||
angles=["0.05000", "0.10000", "0.15000", "0.20000", "0.25000"]
|
||||
speeds=["350.0000","350.0000","350.0000","350.0000","350.0000"] tid=1 retry_key=false
|
||||
```
|
||||
`max_step` 恰等于 `cap`，逐帧速率恒定 350。反事实检验：删掉 `clampf` 后 `max_step=0.4636` 远超 `cap=0.05`，断言变红。
|
||||
|
||||
- [ ] **Step 3: 最短转向方向（验收④）**
|
||||
- [x] **Step 2b: 归航「真的命中」端到端（验收① 补强）**
|
||||
|
||||
> Step 2 只断言了方向变化。补一条端到端：敌人侧偏 60 px（远超碰撞半径 22），归航弹须命中并造成伤害，对照弹须完全打空。
|
||||
|
||||
```gdscript
|
||||
var res := []
|
||||
var fails := 0
|
||||
for mode in 2:
|
||||
BulletManager.reset(); EnemyManager.reset(); SpatialGrid.clear()
|
||||
var ep := Vector2(300, 60)
|
||||
var e = EnemyManager.spawn_enemy(ep, 1000.0, 0)
|
||||
SpatialGrid.insert(e, ep)
|
||||
var hp0 := EnemyManager.get_hp_percent(e)
|
||||
if mode == 0:
|
||||
BulletManager.spawn_bullet(Vector2(0, 0), Vector2(350, 0), 5.0, 6.0, 100.0, 1.0, 0, -1, 0, 0.0,
|
||||
{"homing_strength": 3.0, "homing_range": 400.0, "homing_target_id": -1})
|
||||
else:
|
||||
BulletManager.spawn_bullet(Vector2(0, 0), Vector2(350, 0), 5.0, 6.0, 100.0, 1.0, 0, -1, 0, 0.0)
|
||||
var hit_frame := -1
|
||||
for k in 150:
|
||||
BulletManager._gd_integrate(1.0 / 60.0)
|
||||
if BulletManager.get_active_count() == 0:
|
||||
hit_frame = k
|
||||
break
|
||||
var hp1 := EnemyManager.get_hp_percent(e)
|
||||
if mode == 0 and (hit_frame < 0 or hp1 >= hp0): fails += 1 # 归航弹必须命中并造成伤害
|
||||
if mode == 1 and (hit_frame >= 0 or hp1 < hp0): fails += 1 # 对照弹必须完全没打中
|
||||
res.append("mode=%-7s hit_frame=%3d hp%% %.3f -> %.3f end_pos=(%.1f, %.1f)" %
|
||||
["homing" if mode == 0 else "control", hit_frame, hp0, hp1,
|
||||
BulletManager._data[0], BulletManager._data[1]])
|
||||
_mcp_print("FAILS=%d" % fails)
|
||||
for r in res: _mcp_print(r)
|
||||
```
|
||||
实测输出：
|
||||
```
|
||||
FAILS=0
|
||||
mode=homing hit_frame= 48 hp% 1.000 -> 0.900 end_pos=(280.2, 55.9)
|
||||
mode=control hit_frame= -1 hp% 1.000 -> 1.000 end_pos=(875.0, 0.0)
|
||||
```
|
||||
|
||||
- [x] **Step 3: 最短转向方向（验收④）**
|
||||
|
||||
> **必须跨越 ±π 分界才测得到 `wrapf`**。子弹速度方向 ≈ **+170°**（2.966 rad），目标方向 ≈ **−170°**（−2.966 rad）：
|
||||
> - 原始差值 `−2.966 − 2.966 = −5.932`，若**不**做 `wrapf` 会被 clamp 成 `−0.05`，朝**反方向绕远路**；
|
||||
@@ -363,17 +420,31 @@ SpatialGrid.insert(e, Vector2(-300, -53))
|
||||
BulletManager.spawn_bullet(Vector2(0, 0), Vector2(-350, 61.7), 5.0, 6.0, 1.0, 1.0, 0, -1, 0, 0.0,
|
||||
{"homing_strength": 3.0, "homing_range": 400.0, "homing_target_id": -1})
|
||||
var a0 := Vector2(BulletManager._data[2], BulletManager._data[3]).angle()
|
||||
var tgt_ang := (Vector2(-300, -53) - Vector2(0, 0)).angle()
|
||||
var raw_diff := tgt_ang - a0
|
||||
BulletManager._gd_integrate(1.0 / 60.0)
|
||||
var a1 := Vector2(BulletManager._data[2], BulletManager._data[3]).angle()
|
||||
var delta_a: float = wrapf(a1 - a0, -PI, PI)
|
||||
var fails := 0
|
||||
if delta_a <= 0.0: fails += 1 # 必须为正（短边）；无 wrapf 的实现会得到负值
|
||||
if abs(abs(delta_a) - 0.05) > 0.005: fails += 1 # 且恰好吃满单帧上限 3.0/60
|
||||
_mcp_print("FAILS=%d a0=%.4f a1=%.4f delta=%.4f" % [fails, a0, a1, delta_a])
|
||||
_mcp_print("FAILS=%d a0=%.4f(%.1fdeg) tgt=%.4f(%.1fdeg) raw_diff=%.4f wrapped=%.4f delta=%.5f dist=%.1f" %
|
||||
[fails, a0, rad_to_deg(a0), tgt_ang, rad_to_deg(tgt_ang), raw_diff,
|
||||
wrapf(raw_diff, -PI, PI), delta_a, Vector2(-300, -53).length()])
|
||||
# 自证本步非空断言：打印 |raw_diff| 是否真的跨过 ±π，以及无 wrapf 时 clamp 会得到什么
|
||||
_mcp_print("crosses_pi=%s (|raw_diff|=%.4f > PI 说明必须 wrap；无 wrapf 时 clamp 结果为 %.4f)" %
|
||||
[str(abs(raw_diff) > PI), abs(raw_diff), clampf(raw_diff, -0.05, 0.05)])
|
||||
```
|
||||
Expected: `FAILS=0`，`delta ≈ +0.0500`（正值）。若实现漏了 `wrapf`，此处会得到 `delta ≈ -0.0500` 并 `FAILS=1`。
|
||||
实测输出：
|
||||
```
|
||||
FAILS=0 a0=2.9671(170.0deg) tgt=-2.9667(-170.0deg) raw_diff=-5.9338 wrapped=0.3494 delta=0.05000 dist=304.6
|
||||
crosses_pi=true (|raw_diff|=5.9338 > PI 说明必须 wrap；无 wrapf 时 clamp 结果为 -0.0500)
|
||||
```
|
||||
> **本步的空断言自检已内建**：脚本自己打印 `crosses_pi` 与「无 wrapf 时的 clamp 结果」，任何人复跑都能立刻看出摆位是否真的跨过 ±π。若把目标挪到子弹正前方侧向，`crosses_pi` 会变 `false`，此时本步退化为空断言 —— **看到 `crosses_pi=false` 即说明摆位被改坏了**。反事实检验：删掉 `wrapf` 后实测 `delta=-0.05000`，符号反转，断言变红。
|
||||
|
||||
- [ ] **Step 4: 目标失效重选 + 空场直行（验收⑤⑥）**
|
||||
- [x] **Step 4: 目标失效重选 + 空场直行（验收⑤⑥）**
|
||||
|
||||
> ⚠️ **「不触发 `query_circle`」是本次唯一的间接验证**。无法给 autoload 方法挂调用计数器，故用状态判据替代：`_apply_homing` 内通往 `SpatialGrid` 的路径**有且仅有**一处 `_find_nearest_unvisited`，其后必然二选一 —— 成功写 `homing_target_id`（变新值）、失败写 `homing_retry_at`；两者皆未发生 ⟹ 该路径未执行。零敌人时 `_check_collision` 在 `:71` 即返回，bounce 路径不可达，不会混淆。详见 spec §4 第 ⑥ 条的封闭性论证。
|
||||
|
||||
Run: godot-mcp-pro `execute_game_script`：
|
||||
```gdscript
|
||||
@@ -388,25 +459,41 @@ BulletManager._gd_integrate(1.0 / 60.0)
|
||||
var locked: int = int(BulletManager._bullet_contexts[0]["homing_target_id"])
|
||||
var fails := 0
|
||||
if locked < 0: fails += 1 # 首帧应完成锁定
|
||||
var no_retry_on_first: bool = not BulletManager._bullet_contexts[0].has("homing_retry_at")
|
||||
if not no_retry_on_first: fails += 1 # 首次锁定成功不应写退避键
|
||||
# 杀掉被锁定的目标 → 下一帧应重选到另一个
|
||||
EnemyManager.despawn_enemy(locked)
|
||||
SpatialGrid.remove_entity(locked)
|
||||
BulletManager._gd_integrate(1.0 / 60.0)
|
||||
var relocked: int = int(BulletManager._bullet_contexts[0]["homing_target_id"])
|
||||
if relocked < 0 or relocked == locked: fails += 1 # ⑤ 已重选到另一个存活敌人
|
||||
# 清场 → 直行，方向不再变化
|
||||
# --- ⑥ 空场：直行 + 不【因归航】查询 ---
|
||||
EnemyManager.reset(); SpatialGrid.clear()
|
||||
BulletManager._gd_integrate(1.0 / 60.0)
|
||||
var a1 := Vector2(BulletManager._data[2], BulletManager._data[3]).angle()
|
||||
BulletManager._gd_integrate(1.0 / 60.0)
|
||||
var a2 := Vector2(BulletManager._data[2], BulletManager._data[3]).angle()
|
||||
if abs(a2 - a1) > 0.0001: fails += 1 # ⑥ 空场直行
|
||||
_mcp_print("FAILS=%d locked=%d relocked=%d a1=%.4f a2=%.4f" % [fails, locked, relocked, a1, a2])
|
||||
var angs := []
|
||||
for k in 6:
|
||||
BulletManager._gd_integrate(1.0 / 60.0)
|
||||
angs.append(Vector2(BulletManager._data[2], BulletManager._data[3]).angle())
|
||||
var a1: float = angs[0]
|
||||
var a_last: float = angs[angs.size() - 1]
|
||||
if abs(a_last - a1) > 0.0001: fails += 1 # ⑥ 空场直行
|
||||
var tid_after: int = int(BulletManager._bullet_contexts[0]["homing_target_id"])
|
||||
var no_retry: bool = not BulletManager._bullet_contexts[0].has("homing_retry_at")
|
||||
if tid_after != relocked: fails += 1 # 成功路径未走（目标 id 未变）
|
||||
if not no_retry: fails += 1 # 失败路径未走（无退避键）
|
||||
_mcp_print("FAILS=%d locked=%d relocked=%d a_first=%.6f a_last=%.6f" % [fails, locked, relocked, a1, a_last])
|
||||
_mcp_print("empty_field: tid_unchanged=%s(%d==%d) no_retry_key=%s angles=%s" %
|
||||
[str(tid_after == relocked), tid_after, relocked, str(no_retry), str(angs)])
|
||||
```
|
||||
Expected: `FAILS=0`，`relocked` 为另一个 entity_id，`a1 == a2`。
|
||||
> 适配注：若 `despawn_enemy` / `SpatialGrid.remove_entity` 签名不符，先 `read_script` 确认；核心断言是「锁定目标消失后 `homing_target_id` 变为另一存活敌人」与「无敌人时方向恒定」。
|
||||
实测输出：
|
||||
```
|
||||
FAILS=0 locked=1 relocked=2 a_first=-0.000000 a_last=-0.000000
|
||||
empty_field: tid_unchanged=true(2==2) no_retry_key=true angles=[-0.00000000544957, ×6 相同]
|
||||
```
|
||||
> 已确认 `despawn_enemy(id)` / `SpatialGrid.remove_entity(id)` 签名正确。原稿只跑 2 帧且未断言「无查询」，此处扩到 6 帧并补上两条状态判据。
|
||||
|
||||
- [ ] **Step 5: homing + bounce 协同（验收⑦）**
|
||||
- [x] **Step 5: homing + bounce 协同（验收⑦）**
|
||||
|
||||
> 相对原稿补强：预置一个**远未来的 `homing_retry_at`**，据此验证 bounce 路径的 `cold.erase("homing_retry_at")`（评审期修复的缺陷 —— 退避键残留会让子弹对着 bounce 刚给的有效目标拒绝转向）。原稿不写该键，测不到这条。
|
||||
|
||||
Run: godot-mcp-pro `execute_game_script`：
|
||||
```gdscript
|
||||
@@ -417,47 +504,101 @@ SpatialGrid.insert(e1, Vector2(300, 0))
|
||||
SpatialGrid.insert(e2, Vector2(300, 100))
|
||||
BulletManager.spawn_bullet(Vector2(300, 0), Vector2(200, 0), 5.0, 6.0, 100.0, 1.0, 0, -1, 0, 0.0,
|
||||
{"bounce_remaining": 1, "visited_targets": [], "bounce_decay": 0.9, "bounce_range": 250.0,
|
||||
"homing_strength": 3.0, "homing_range": 400.0, "homing_target_id": -1})
|
||||
"homing_strength": 3.0, "homing_range": 400.0, "homing_target_id": -1,
|
||||
"homing_retry_at": Time.get_ticks_msec() + 999999}) # 预置过期退避键，验证 bounce 会撤销它
|
||||
BulletManager._gd_integrate(1.0 / 60.0) # 命中 e1 → bounce 重定向到 e2 并改写 homing 目标
|
||||
var cold: Dictionary = BulletManager._bullet_contexts[0]
|
||||
var fails := 0
|
||||
if int(cold.get("homing_target_id", -1)) != e2: fails += 1 # ⑦ homing 目标 == bounce 选中的敌人
|
||||
if int(cold.get("bounce_remaining", -1)) != 0: fails += 1 # bounce 已消耗
|
||||
_mcp_print("FAILS=%d tgt=%d e2=%d bounce_left=%d" %
|
||||
[fails, int(cold.get("homing_target_id", -1)), e2, int(cold.get("bounce_remaining", -1))])
|
||||
if cold.has("homing_retry_at"): fails += 1 # bounce 给了有效目标，退避须被撤销
|
||||
_mcp_print("FAILS=%d tgt=%d e1=%d e2=%d bounce_left=%d visited=%s retry_key=%s" %
|
||||
[fails, int(cold.get("homing_target_id", -1)), e1, e2, int(cold.get("bounce_remaining", -1)),
|
||||
str(cold.get("visited_targets", [])), str(cold.has("homing_retry_at"))])
|
||||
_mcp_print("vel=(%.2f,%.2f) dmg_mult=%.3f" % [BulletManager._data[2], BulletManager._data[3], BulletManager._data[7]])
|
||||
```
|
||||
实测输出：
|
||||
```
|
||||
FAILS=0 tgt=2 e1=1 e2=2 bounce_left=0 visited=[1] retry_key=false
|
||||
vel=(-6.66,199.89) dmg_mult=0.900
|
||||
```
|
||||
Expected: `FAILS=0`，`tgt == e2`。
|
||||
|
||||
- [ ] **Step 6: 修饰器折叠 + 商店可购（验收⑧⑨前半）**
|
||||
- [x] **Step 6: 修饰器折叠 + 商店可购（验收⑧⑨前半）**
|
||||
|
||||
> ⚠️ **本脚本已按实际执行版本替换（2026-07-30 验收期）**。原稿有两处**在测试自己而非测实现**：
|
||||
> 1. 折叠部分把 `if meta.has("homing"): cs.homing_add += ...` **内联复刻**了一遍 —— 就算 `_apply_modifier` 里根本没写那两行，这段也照样 `folded=6.00` 通过。改为直接调真实的 `SpellEvaluator._apply_modifier(sp, ctx)`。
|
||||
> 2. 商店部分**复刻**了 `shop_manager.gd:33` 的谓词 —— 若真实 `_available_pool()` 的过滤逻辑变了，此处测不出来。改为直接调 `ShopManager._available_pool()`。
|
||||
>
|
||||
> **不要退回内联复刻写法。**
|
||||
|
||||
Run: godot-mcp-pro `execute_game_script`：
|
||||
```gdscript
|
||||
var fails := 0
|
||||
var sp = SpellRegistry.get_spell("modifier_homing")
|
||||
var sp: SpellNode = SpellRegistry.get_spell("modifier_homing")
|
||||
if sp == null: fails += 1
|
||||
if not ("modifier_homing" in SpellRegistry.get_all_ids()): fails += 1
|
||||
var cs = CastStats.new()
|
||||
var meta := {"homing": 3.0}
|
||||
# 折叠两层：模拟 _apply_modifier 对同一 meta 调用两次
|
||||
for k in 2:
|
||||
if meta.has("homing"):
|
||||
cs.homing_add += float(meta["homing"])
|
||||
var folded := cs.homing_add
|
||||
# ⑧ 走真实 _apply_modifier（而非内联复刻折叠逻辑）
|
||||
var ctx := SpellContext.new()
|
||||
ctx.stats = CastStats.new()
|
||||
ctx.stats.reset()
|
||||
SpellEvaluator._apply_modifier(sp, ctx)
|
||||
SpellEvaluator._apply_modifier(sp, ctx)
|
||||
var folded: float = ctx.stats.homing_add
|
||||
if abs(folded - 6.0) > 0.001: fails += 1 # ⑧ 两层 → 6.0
|
||||
cs.reset()
|
||||
if abs(cs.homing_add) > 0.001: fails += 1 # reset 归零
|
||||
# 商店可抽池条件（shop_manager.gd:33 注释）：shop_cost>0 且 unlock_cost==0 或已解锁
|
||||
var in_pool: bool = sp != null \
|
||||
and int(sp.meta.get("shop_cost", 0)) > 0 \
|
||||
and int(sp.meta.get("unlock_cost", 0)) == 0
|
||||
ctx.stats.reset()
|
||||
if abs(ctx.stats.homing_add) > 0.001: fails += 1 # reset 归零
|
||||
# ⑨ 前半：走真实商店可抽池（而非复刻谓词）
|
||||
var pool: Array = ShopManager._available_pool()
|
||||
var in_pool: bool = "modifier_homing" in pool
|
||||
if not in_pool: fails += 1
|
||||
_mcp_print("FAILS=%d folded=%.2f after_reset=%.2f in_pool=%s" %
|
||||
[fails, folded, cs.homing_add, in_pool])
|
||||
_mcp_print("FAILS=%d folded=%.2f after_reset=%.2f in_pool=%s pool_size=%d shop_cost=%d unlock_cost=%d mana_cost=%d" %
|
||||
[fails, folded, ctx.stats.homing_add, str(in_pool), pool.size(),
|
||||
int(sp.meta.get("shop_cost", 0)), int(sp.meta.get("unlock_cost", 0)), int(sp.meta.get("mana_cost", 0))])
|
||||
```
|
||||
实测输出：
|
||||
```
|
||||
FAILS=0 folded=6.00 after_reset=0.00 in_pool=true pool_size=17 shop_cost=18 unlock_cost=0 mana_cost=8
|
||||
```
|
||||
Expected: `FAILS=0 folded=6.00 after_reset=0.00 in_pool=true`
|
||||
> API 已确认存在：`SpellRegistry.get_spell(id)`（:36）、`get_all_ids()`（:39）、`CastStats` 为 `class_name` 注册的 RefCounted（可 `.new()`）。
|
||||
|
||||
- [ ] **Step 7: 性能回归守卫 —— R-H1 两种病态场景的单帧峰值**
|
||||
- [x] **Step 6b: 整条 VM 管线端到端（验收⑧ 补强）**
|
||||
|
||||
> Step 6 只验证了 `_apply_modifier` 这一环。补一条真实施法：`compile_wand([modifier_homing, modifier_homing, action_spark_bolt])` → `execute_compiled` → 断言落到子弹冷数据上的 `homing_strength == 6.0`，并用无修饰器的同一 ACTION 作对照（不应写任何 homing 键）。
|
||||
> ⚠️ ACTION 的真实 id 是 **`action_spark_bolt`**，不是 `spark_bolt`。
|
||||
|
||||
```gdscript
|
||||
BulletManager.reset(); EnemyManager.reset(); SpatialGrid.clear()
|
||||
var core := CoreDefinition.new()
|
||||
core.id = "test_core"; core.slot_count = 5; core.cpu_limit = 10; core.grid_cols = 5
|
||||
var nodes := [SpellRegistry.get_spell("modifier_homing"),
|
||||
SpellRegistry.get_spell("modifier_homing"),
|
||||
SpellRegistry.get_spell("action_spark_bolt")]
|
||||
var compiled = SpellEvaluator.compile_wand(core, nodes)
|
||||
PlayerStats.mana = 999.0
|
||||
SpellEvaluator.execute_compiled(compiled, -1, Vector2(0, 0))
|
||||
var fails := 0
|
||||
if BulletManager.get_active_count() < 1: fails += 1
|
||||
var cold: Dictionary = BulletManager._bullet_contexts.get(0, {})
|
||||
var hs: float = float(cold.get("homing_strength", -1.0))
|
||||
if abs(hs - 6.0) > 0.001: fails += 1
|
||||
if int(cold.get("homing_target_id", -99)) != -1: fails += 1 # 发射时不解析目标
|
||||
if abs(float(cold.get("homing_range", -1.0)) - 400.0) > 0.001: fails += 1
|
||||
# 对照：不带修饰器的同一 ACTION 不应写任何 homing 冷数据
|
||||
BulletManager.reset()
|
||||
var compiled2 = SpellEvaluator.compile_wand(core, [SpellRegistry.get_spell("action_spark_bolt")])
|
||||
PlayerStats.mana = 999.0
|
||||
SpellEvaluator.execute_compiled(compiled2, -1, Vector2(0, 0))
|
||||
var cold2: Dictionary = BulletManager._bullet_contexts.get(0, {})
|
||||
if cold2.has("homing_strength"): fails += 1
|
||||
_mcp_print("FAILS=%d homing_strength=%.3f cold=%s" % [fails, hs, str(cold)])
|
||||
_mcp_print("control_cold=%s" % str(cold2))
|
||||
```
|
||||
实测输出：
|
||||
```
|
||||
FAILS=0 homing_strength=6.000 cold={ "homing_strength": 6.0, "homing_range": 400.0, "homing_target_id": -1 }
|
||||
control_cold={ }
|
||||
```
|
||||
|
||||
- [x] **Step 7: 性能回归守卫 —— R-H1 两种病态场景的单帧峰值**
|
||||
|
||||
> **本步性质已变更（2026-07-30，Task 2 代码质量评审后）**：原本这是「决策关卡」—— 实测后再定要不要启用 spec §5 的退避方案。评审在 Task 2 阶段就直接实测并**证实触发**（300 弹规模即越过 2.0 ms 线），故退避 + 抖动**已随 Task 2 落地**。本步因此降级为**回归守卫**：确认退避与抖动仍生效、峰值未回弹。
|
||||
>
|
||||
@@ -467,63 +608,151 @@ Expected: `FAILS=0 folded=6.00 after_reset=0.00 in_pool=true`
|
||||
>
|
||||
> **指标是单帧最大值，不是 60 帧均值。** 退避把成本摊薄成「1 个重选帧 + 11 个退避帧」，均值会掩盖重选帧的尖峰；而帧预算只有 16.67 ms，尖峰才是会被玩家看见的东西。抖动的作用正是打散这个尖峰。
|
||||
|
||||
Run: godot-mcp-pro `execute_game_script`（两种场景各跑一次，改 `SCENARIO` 常量）：
|
||||
> ⚠️ **本脚本已按实际执行版本替换（2026-07-30 验收期）**。原稿有两处会让守卫失真：
|
||||
> 1. **没有墙钟起搏。** 退避基于 `Time.get_ticks_msec()`（墙钟）。连打 40 次 `_gd_integrate` 只跨几毫秒墙钟，40 帧**全部停在 `[200,400)` ms 退避窗内、一次重选都观测不到** —— 峰值看起来很低，但守卫**变成了空断言**。必须每帧补足到 16.67 ms（spec §5.5 即此方法）。
|
||||
> 2. **几何让子弹直穿敌人簇。** 原稿子弹自 `(0,k)` 沿 +x 飞、敌人在 `(200+k, 100+k)`，第 30–47 帧（x 175→274）正好穿过敌人簇，实测多出约 1.5 ms 的**碰撞**开销（`query_circle(r=22)` 命中 + `visited_targets` 线性扫描），那**不是归航成本**，验收期曾因此误读一次。改用 spec §5.2 的环形摆位：敌人置于环上（① 半径 3000 全出射程；② 半径 300 在射程 400 内、碰撞半径 22 外），子弹簇于原点附近。
|
||||
>
|
||||
> 另：**必须把 frame1 与稳态峰值分开报**。frame1 是 spec §5.6 已决策接受的「首次锁定尖峰」（不受退避约束，按设计如此），混进稳态峰值会掩盖真正要守的东西。
|
||||
|
||||
Run: godot-mcp-pro `execute_game_script`（一次跑完 6 组：基线/①/② × 300/1500）：
|
||||
```gdscript
|
||||
var SCENARIO := 1 # 1 = 敌人全在射程外；2 = 射程内全 visited
|
||||
var N_BULLETS := 300 # 也跑一遍 1500 作为压力上限
|
||||
BulletManager.reset(); EnemyManager.reset(); SpatialGrid.clear()
|
||||
var visited := []
|
||||
if SCENARIO == 1:
|
||||
for k in 50: # 全部远在 homing_range(400) 之外
|
||||
var eid = EnemyManager.spawn_enemy(Vector2(3000 + k * 10, 0), 1000.0, 0)
|
||||
SpatialGrid.insert(eid, Vector2(3000 + k * 10, 0))
|
||||
else:
|
||||
for k in 30: # 在射程内，但全部预置进 visited → 重选必然失败
|
||||
var eid = EnemyManager.spawn_enemy(Vector2(200 + k, 100 + k), 1000.0, 0)
|
||||
SpatialGrid.insert(eid, Vector2(200 + k, 100 + k))
|
||||
visited.append(eid)
|
||||
for k in N_BULLETS:
|
||||
var cold := {"homing_strength": 3.0, "homing_range": 400.0, "homing_target_id": -1}
|
||||
if SCENARIO == 2:
|
||||
cold["visited_targets"] = visited.duplicate()
|
||||
BulletManager.spawn_bullet(Vector2(0, k), Vector2(350, 0), 30.0, 6.0, 1.0, 1.0, 0, -1, 0, 0.0, cold)
|
||||
# 跑满一个退避周期以上，捕捉单帧峰值（含重选帧）
|
||||
var peak_us := 0
|
||||
var total_us := 0
|
||||
for k in 40:
|
||||
var t0 := Time.get_ticks_usec()
|
||||
BulletManager._gd_integrate(1.0 / 60.0)
|
||||
var dt_us := Time.get_ticks_usec() - t0
|
||||
total_us += dt_us
|
||||
if dt_us > peak_us: peak_us = dt_us
|
||||
_mcp_print("scenario=%d bullets=%d peak_ms=%.3f mean_ms=%.3f budget=16.670 over_budget=%s" %
|
||||
[SCENARIO, N_BULLETS, peak_us / 1000.0, total_us / 40.0 / 1000.0, str(peak_us / 1000.0 > 16.67)])
|
||||
var FRAMES := 40
|
||||
var FRAME_US := 16670
|
||||
var results := []
|
||||
var configs := [[0, 300], [0, 1500], [1, 300], [1, 1500], [2, 300], [2, 1500]] # [场景, 弹数]
|
||||
for cfg in configs:
|
||||
var SCEN: int = cfg[0] # 0=基线(无冷数据) 1=全出射程 2=射程内全 visited
|
||||
var N: int = cfg[1]
|
||||
BulletManager.reset(); EnemyManager.reset(); SpatialGrid.clear()
|
||||
var visited := []
|
||||
if SCEN != 0:
|
||||
var R: float = 3000.0 if SCEN == 1 else 300.0
|
||||
for k in 30:
|
||||
var a: float = TAU * k / 30.0
|
||||
var p := Vector2(cos(a), sin(a)) * R
|
||||
var eid = EnemyManager.spawn_enemy(p, 1000.0, 0)
|
||||
SpatialGrid.insert(eid, p)
|
||||
if SCEN == 2: visited.append(eid)
|
||||
for k in N:
|
||||
var sp0 := Vector2(0, k * 0.02) # 子弹簇于原点附近(30px 内)，不穿过敌人环
|
||||
if SCEN == 0:
|
||||
BulletManager.spawn_bullet(sp0, Vector2(350, 0), 30.0, 6.0, 1.0, 1.0, 0, -1, 0, 0.0)
|
||||
else:
|
||||
var cold := {"homing_strength": 3.0, "homing_range": 400.0, "homing_target_id": -1}
|
||||
if SCEN == 2: cold["visited_targets"] = visited.duplicate()
|
||||
BulletManager.spawn_bullet(sp0, Vector2(350, 0), 30.0, 6.0, 1.0, 1.0, 0, -1, 0, 0.0, cold)
|
||||
var pf := []
|
||||
for k in FRAMES:
|
||||
var t0 := Time.get_ticks_usec()
|
||||
BulletManager._gd_integrate(1.0 / 60.0)
|
||||
pf.append(Time.get_ticks_usec() - t0)
|
||||
# 按真实 60fps 起搏：退避基于墙钟，不补足帧间隔则全程停在退避窗内，守卫会变成空断言
|
||||
var rem := FRAME_US - (Time.get_ticks_usec() - t0)
|
||||
if rem > 0: OS.delay_usec(rem)
|
||||
var steady := 0
|
||||
var over := 0
|
||||
for k in range(1, FRAMES): # 跳过 frame1（§5.6 已接受的首次锁定尖峰）
|
||||
if pf[k] > steady: steady = pf[k]
|
||||
if pf[k] > 16670: over += 1
|
||||
results.append("scen=%d n=%4d frame1=%7.3f 稳态峰值=%6.3f 超预算=%d/%d 末弹数=%d" %
|
||||
[SCEN, N, pf[0]/1000.0, steady/1000.0, over, FRAMES-1, BulletManager.get_active_count()])
|
||||
for r in results: _mcp_print(r)
|
||||
```
|
||||
Expected：300 弹两种场景 `peak_ms` 均明显低于 2.0；1500 弹（压力上限）`over_budget=false`。
|
||||
> 若 `over_budget=true`，**停下来上报，不要自行加码** —— 那说明需要的是设计级方案（给 `visited_targets` 设上限、或让归航子弹连续失败 N 次后彻底放弃归航），属设计决策而非实现调优。
|
||||
> 注：编辑器/调试构建的绝对值偏高于 release，看**比例与是否越线**而非绝对数字。基线（普通弹、无冷数据）约 1.6 ms @1500 / 0.32 ms @300，可先跑一次作参照。
|
||||
实测输出：
|
||||
```
|
||||
scen=0 n= 300 frame1= 0.356 稳态峰值= 0.386 超预算=0/39 末弹数=300
|
||||
scen=0 n=1500 frame1= 1.707 稳态峰值= 1.824 超预算=0/39 末弹数=1500
|
||||
scen=1 n= 300 frame1= 3.600 稳态峰值= 0.936 超预算=0/39 末弹数=300
|
||||
scen=1 n=1500 frame1= 17.118 稳态峰值= 4.662 超预算=0/39 末弹数=1500
|
||||
scen=2 n= 300 frame1= 4.800 稳态峰值= 1.088 超预算=0/39 末弹数=300
|
||||
scen=2 n=1500 frame1= 23.125 稳态峰值= 5.088 超预算=0/39 末弹数=1500
|
||||
```
|
||||
逐帧 trace 确认抖动仍生效 —— 无每 12 帧复发的尖峰，重选成本平铺在第 13–25 帧的 0.9–1.1 ms 带内。反事实检验：去掉抖动项后第 12/24 帧重现 22.6 / 23.0 ms 尖峰、`over16.67=3/39`。
|
||||
|
||||
- [ ] **Step 8: 设计器字段回读往返（验收⑨后半）**
|
||||
> **数字按区间读**：编辑器/调试构建，运行间离散明显（scen2@1500 三次独立测量 5.61 / 5.09 / 7.29 ms，240 帧长跑收敛在 5–7 ms 带、无发散）。**判定回归看「是否出现周期性复发尖峰、是否有帧越过 16.67 ms」，不要拿单个数字比对。** 详见 spec §5.5。
|
||||
> 若稳态出现 `超预算 > 0`，**停下来上报，不要自行加码** —— 那说明需要的是设计级方案（给 `visited_targets` 设上限、或让归航子弹连续失败 N 次后彻底放弃归航），属设计决策而非实现调优。
|
||||
|
||||
- [x] **Step 8: 设计器字段回读往返（验收⑨后半）**
|
||||
|
||||
> ⚠️ **本脚本已按实际执行版本替换（2026-07-30 验收期）**。原稿只是**对源码文本 grep** `'"k": "homing"'` —— 那只证明字符串出现在文件里，**不是往返**：schema 里写了键但 `_on_select` / `_read_meta` 任何一侧坏掉，grep 照样通过。改为按 CLAUDE.md 记录的绕缓存法（`GDScript.new()` + 从磁盘读 `source_code` + `reload()`）真实实例化 `spell_tab`，对**真实 `data/spells.json`** 的全部 type-1 法术做 `_select_id` → `_on_apply` → 键集合与逐键数值比对，并断言「其它(JSON)」逃生舱为空。**不要退回 grep 写法。**
|
||||
|
||||
Run: godot-mcp-pro `stop_scene`，然后 `execute_editor_script`：
|
||||
```gdscript
|
||||
var gs := GDScript.new()
|
||||
gs.source_code = FileAccess.get_file_as_string("res://addons/game_designer/spell_tab.gd")
|
||||
var err := gs.reload() # 绕开 dock 里驻留的旧 @tool 类缓存
|
||||
if err != OK:
|
||||
_mcp_print("reload failed err=%d" % err)
|
||||
return
|
||||
var tab = gs.new()
|
||||
EditorInterface.get_base_control().add_child(tab) # 触发 _ready()，其中会加载真实 spells.json
|
||||
var truth = JSON.parse_string(FileAccess.get_file_as_string("res://data/spells.json"))
|
||||
var fails := []
|
||||
var checked := 0
|
||||
var homing_seen := 0
|
||||
var bounce_seen := 0
|
||||
for sid in truth.keys():
|
||||
if int(truth[sid].get("type", -1)) != 1:
|
||||
continue
|
||||
checked += 1
|
||||
var orig: Dictionary = truth[sid].get("meta", {})
|
||||
tab._select_id(sid) # 回读：JSON → 表单
|
||||
tab._on_apply() # 写回：表单 → _data
|
||||
var rt: Dictionary = tab._data[sid].get("meta", {})
|
||||
if orig.has("homing"): homing_seen += 1
|
||||
if orig.has("bounce"): bounce_seen += 1
|
||||
for k in orig.keys(): # 往返语义等价：键集合相同 + 逐键数值相等
|
||||
if not rt.has(k):
|
||||
fails.append("%s: lost key %s" % [sid, k]); continue
|
||||
if typeof(orig[k]) in [TYPE_INT, TYPE_FLOAT]:
|
||||
if absf(float(orig[k]) - float(rt[k])) > 0.0001:
|
||||
fails.append("%s.%s: %s -> %s" % [sid, k, str(orig[k]), str(rt[k])])
|
||||
elif str(orig[k]) != str(rt[k]):
|
||||
fails.append("%s.%s: %s -> %s" % [sid, k, str(orig[k]), str(rt[k])])
|
||||
for k in rt.keys():
|
||||
if not orig.has(k):
|
||||
fails.append("%s: extra key %s=%s" % [sid, k, str(rt[k])])
|
||||
if tab._extra.text.strip_edges() != "": # schema 已覆盖全部键，逃生舱应为空
|
||||
fails.append("%s: extra-JSON escape hatch not empty = %s" % [sid, tab._extra.text.strip_edges()])
|
||||
_mcp_print("FAILS=%d type1_checked=%d homing_fields=%d bounce_fields=%d" %
|
||||
[fails.size(), checked, homing_seen, bounce_seen])
|
||||
for f in fails: _mcp_print(" " + f)
|
||||
tab.queue_free()
|
||||
```
|
||||
实测输出：
|
||||
```
|
||||
FAILS=0 type1_checked=8 homing_fields=1 bounce_fields=1
|
||||
```
|
||||
> `homing_fields=1 bounce_fields=1` 证明这两个字段**确实被这轮往返走到了**，而不是「恰好没有法术用到它们」的空过。
|
||||
|
||||
- [x] **Step 8b: `validate_script` + 数据驱动断言（验收⑩ / Task 1 Step 6 复核）**
|
||||
|
||||
Run: godot-mcp-pro `stop_scene`，然后 `execute_editor_script`（复用 Task 3 Step 3 的 schema 覆盖脚本，此时应含 `homing`）：
|
||||
```gdscript
|
||||
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"))
|
||||
var generic := {"mana_cost": true, "shop_cost": true}
|
||||
var missing := []
|
||||
for id in d.keys():
|
||||
if int(d[id].get("type", -1)) != 1:
|
||||
continue
|
||||
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)])
|
||||
if generic.has(k): continue
|
||||
if not src.contains('"k": "%s"' % k): missing.append("%s.%s" % [id, k])
|
||||
var m = d.get("modifier_homing", {}).get("meta", {})
|
||||
var ok: bool = d.has("modifier_homing") \
|
||||
and absf(float(m.get("homing", 0.0)) - 3.0) < 0.001 \
|
||||
and int(m.get("shop_cost", 0)) == 18 and int(m.get("mana_cost", 0)) == 8 \
|
||||
and int(d["modifier_homing"].get("type", -1)) == 1
|
||||
_mcp_print("schema_FAILS=%d missing=%s" % [missing.size(), str(missing)])
|
||||
_mcp_print("json_FAILS=%d modifier_homing.meta=%s" % [(0 if ok else 1), str(m)])
|
||||
```
|
||||
Expected: `FAILS=0 missing=[]`
|
||||
实测输出：
|
||||
```
|
||||
schema_FAILS=0 missing=[]
|
||||
json_FAILS=0 modifier_homing.meta={ "homing": 3.0, "mana_cost": 8.0, "shop_cost": 18.0 }
|
||||
```
|
||||
`validate_script`：`bullet_manager.gd` / `enemy_manager.gd` / `spell_evaluator.gd` / `spell_tab.gd` 均 `Script compiles successfully`；`cast_stats.gd` 唯一报错是已知假阴性 `Class "CastStats" hides a global script class`（带 `class_name` 的脚本必然如此）。`get_editor_errors` count=0。
|
||||
|
||||
- [ ] **Step 9: 更新路线图 + memory + 提交**
|
||||
- [x] **Step 9: 更新路线图 + memory + 提交**
|
||||
|
||||
- `docs_dev/plans/2026-07-23-missing-features-roadmap.md`：
|
||||
- E1「现状」的「归航」行改为完成态，注明**偏离**：未消费 `_enemy_pos_snapshot` 而是将其删除（锁定语义需 entity_id，快照按槽位存位置不含 id）。
|
||||
@@ -547,16 +776,20 @@ EOF
|
||||
|
||||
## 验收标准回溯（spec §4）
|
||||
|
||||
| # | 验收标准 | 覆盖任务 |
|
||||
| :- | :-- | :-- |
|
||||
| 1 | 归航生效（画弧）+ 对照组直线 | Task 4 Step 2 (`ah`>0 / `ac`≈0) |
|
||||
| 2 | 单帧转角 ≤ `strength * delta` | Task 4 Step 2 (`max_step_seen`) |
|
||||
| 3 | 速率守恒 | Task 4 Step 2 (`vh.length()`) |
|
||||
| 4 | 最短转向方向（`wrapf`） | Task 4 Step 3 |
|
||||
| 5 | 目标失效后重选 | Task 4 Step 4 (`relocked`) |
|
||||
| 6 | 空场直行且不查询 | Task 4 Step 4 (`a1==a2`) |
|
||||
| 7 | bounce 协同改写 `homing_target_id` | Task 4 Step 5 |
|
||||
| 8 | 两层修饰器 → `homing_add == 6.0` | Task 4 Step 6 |
|
||||
| 9 | 商店可购 + 设计器字段往返 | Task 4 Step 6 / Step 8 |
|
||||
| 10 | `validate_script` 通过 / 无目标不崩 | Task 1 Step 6、Task 2 Step 5、Task 3 Step 2、Task 4 Step 4 |
|
||||
| — | R-H1 退避+抖动的性能回归守卫（两种病态场景 × 单帧峰值，spec §5） | Task 4 Step 7 |
|
||||
全部 ✅ 于 2026-07-30 实测通过（`FAILS=0`）。「观测方式」列区分**直接观测**与**状态推断**。
|
||||
|
||||
| # | 验收标准 | 覆盖任务 | 观测方式 | 结果 |
|
||||
| :- | :-- | :-- | :-- | :-- |
|
||||
| 1 | 归航生效（画弧）+ 对照组直线 | Step 2 (`ah=0.25` / `ac=0.00`)、Step 2b（真命中） | 直接 | ✅ |
|
||||
| 2 | 单帧转角 ≤ `strength * delta` | Step 2 (`max_step=0.050000 == cap`) | 直接 | ✅ |
|
||||
| 3 | 速率守恒 | Step 2 (逐帧 `350.0000`) | 直接 | ✅ |
|
||||
| 4 | 最短转向方向（`wrapf`） | Step 3 (`raw_diff=-5.93` 跨 ±π → `delta=+0.05`) | 直接 | ✅ |
|
||||
| 5 | 目标失效后重选 | Step 4 (`locked=1 → relocked=2`) | 直接 | ✅ |
|
||||
| 6 | 空场直行且**不因归航**查询 | Step 4 (方向 6 帧恒定；`tid` 未变 + 无 `homing_retry_at`) | **状态推断**（唯一一条非直接观测，论证见 spec §4⑥） | ✅ |
|
||||
| 7 | bounce 协同改写 `homing_target_id` | Step 5 (`tgt == e2`，且过期退避键被 erase) | 直接 | ✅ |
|
||||
| 8 | 两层修饰器 → `homing_add == 6.0` | Step 6（真实 `_apply_modifier`）、Step 6b（端到端施法） | 直接 | ✅ |
|
||||
| 9 | 商店可购 + 设计器字段往返 | Step 6（真实 `_available_pool()`）/ Step 8（真实实例往返 8 条） | 直接 | ✅ |
|
||||
| 10 | `validate_script` 通过 / 无目标不崩 | Task 1/2/3 各校验步 + Step 8b；无目标不崩由 Step 4 与 Step 7 数千次失败重选覆盖 | 直接 | ✅ |
|
||||
| — | R-H1 退避+抖动的性能回归守卫（两种病态场景 × 两规模 × 单帧峰值，spec §5） | Step 7 | 直接 | ✅ 稳态 0/39 超预算 |
|
||||
|
||||
> **frame1 不计入稳态守卫**：1500 弹场景 frame1 达 17.1 / 23.1 ms，这是 spec §5.6 **已决策接受**的「首次锁定尖峰」（同帧创建的归航弹首次 `query_circle` 必然落在同一帧，抖动按设计不作用于此）。它一次性、不复发，且触发条件是「≈1750 颗归航弹同帧创建且首选全部失败」这一合成最坏情况。**重新立项的判据按弹数算（≈9.5 µs/颗），不要按场景猜** —— 详见 spec §5.6。
|
||||
|
||||
@@ -171,7 +171,16 @@ MODIFIER（`type 1`）的 meta schema 加：
|
||||
3. **速率守恒**：转向前后 `Vector2(vx,vy).length()` 不变。
|
||||
4. **最短转向**：目标位于子弹正后方偏一侧时，转向方向为夹角较小的一侧（验证 `wrapf`）。
|
||||
5. **目标失效重选**：锁定目标死亡后，下一帧 `homing_target_id` 变为另一存活敌人。
|
||||
6. **空场直行**：场上无敌人时子弹保持直线，且不触发 `query_circle`。
|
||||
6. **空场直行**：场上无敌人时子弹保持直线，且**不因归航**触发 `query_circle`。
|
||||
> **措辞修正（2026-07-30 验收期）**：原写「不触发 `query_circle`」，字面为假 —— `_check_collision`（`bullet_manager.gd:69`）每帧对每颗子弹**无条件**发一次 `query_circle(pos, radius+16)`，与归航无关。被验证的命题是「`_apply_homing` 这条路径不发查询」。
|
||||
>
|
||||
> **⚠️ 本条是全部 10 条验收里唯一的间接验证**，值得留痕。无法给 autoload 的方法挂调用计数器，故改用状态判据：空场跑 6 帧后断言 `homing_target_id` 未变且冷数据无 `homing_retry_at` 键。其封闭性论证 ——
|
||||
> 1. `_apply_homing` 内通往 `SpatialGrid` 的路径**有且仅有**一处 `_find_nearest_unvisited`，无其它 `SpatialGrid` 访问；
|
||||
> 2. 该调用之后必然二选一：成功则写 `homing_target_id`（变为 ≥0 的新值），失败则写 `homing_retry_at`；
|
||||
> 3. 两者皆未发生 ⟹ 该调用未被执行 ⟹ 归航未发查询；
|
||||
> 4. 零敌人时 `_check_collision` 在 `:71`（`hits.is_empty()`）即返回，bounce 路径不可达，不会与之混淆。
|
||||
>
|
||||
> 论证对被限定后的命题成立，但**它是状态推断而非对调用次数的直接观测** —— 如实标注，不宣称为直接测量。
|
||||
7. **bounce 协同**：`homing + bounce` 子弹弹跳后 `homing_target_id == ` bounce 选中的 `next_id`。
|
||||
8. **修饰器折叠**：两层 `modifier_homing` → `ctx.stats.homing_add == 6.0`。
|
||||
9. **商店与设计器**：`modifier_homing` 可在商店买到；设计器 `homing`/`bounce` 字段回读往返一致（对真实 `data/spells.json`）。
|
||||
@@ -239,19 +248,25 @@ MODIFIER（`type 1`）的 meta schema 加：
|
||||
|
||||
到期时刻均匀铺满 `[200, 400)` ms ≈ 恰好一个退避周期 ≈ 12 帧。**用「`bullet_idx` 在活跃弹数中的占比」而非 `bullet_idx % HOMING_RETRY_MS`**：后者在弹数少于窗口宽度时只能铺开 `_active_count` 毫秒（20 颗弹 → 20 ms ≈ 1.2 帧，等于没打散），占比式则不论弹数多少都铺满整窗。`HOMING_RETRY_MS` 一值两用且刻意耦合 —— 既是基础退避时长也是抖动窗口宽度，「铺满恰好一个退避周期」正是消峰所需的性质，拆成两个常量反而掩盖这层关系。
|
||||
|
||||
实测打散质量：1500 颗同帧集体失败 → 到期偏移 200~415 ms、1493 个互异值、覆盖 14 帧、单帧最多 120 颗（理想 125）。
|
||||
实测打散质量（2026-07-30 验收期复测）：1500 颗同帧集体失败 → 到期时刻**跨度 223 ms**（≈ 恰好一个退避周期，即 13~14 帧）、**222 个互异毫秒值**，平均每毫秒约 6.8 颗、每帧约 110 颗（理想 １500/12 = 125）。
|
||||
|
||||
> **勘误**：本节初稿写「1493 个互异值」，该数**不可能成立** —— `jitter = (bullet_idx * 200) / _active_count` 对 1500 颗弹只能产出 0~199 共约 200 个整数值，同帧失败的子弹又共用同一个 `now`，故互异到期时刻上限就是 ~200 个。复测得 222，多出的 22 来自「遍历这 1500 颗本身耗时约 23 ms，期间 `now` 在推进」（与 §5.6 记录的首帧 23 ms 吻合）。**打散结论不变**（跨度铺满一个完整退避周期即消峰所需性质），只是原先那个数字是错的。
|
||||
|
||||
### 5.5 抖动前后单帧峰值对比（60fps 起搏 · 40 帧）
|
||||
|
||||
| 场景 · 规模 | 抖动前·复发尖峰 | 抖动后·稳态峰值 | 稳态超 16.67ms 帧数 |
|
||||
| 场景 · 规模 | 抖动前·复发尖峰 | 抖动后·稳态峰值（区间） | 稳态超 16.67ms 帧数 |
|
||||
| :-- | --: | --: | --: |
|
||||
| ① 全射程外 · 1500 | 13.6 ~ 15.7 ms（每 12 帧复发） | **4.40 ms** | 0/39 |
|
||||
| ① 全射程外 · 300 | 3.2 ms | **0.92 ms** | 0/39 |
|
||||
| ② 全 visited · 1500 | 20.9 ~ 21.9 ms（每 12 帧复发） | **5.61 ms** | 0/39 |
|
||||
| ② 全 visited · 300 | 4.6 ms | **1.15 ms** | 0/39 |
|
||||
| ① 全射程外 · 1500 | 13.6 ~ 15.7 ms（每 12 帧复发） | **4 ~ 5 ms** | 0/39 |
|
||||
| ① 全射程外 · 300 | 3.2 ms | **约 1 ms** | 0/39 |
|
||||
| ② 全 visited · 1500 | 20.9 ~ 21.9 ms（每 12 帧复发） | **5 ~ 7 ms** | 0/39 |
|
||||
| ② 全 visited · 300 | 4.6 ms | **1 ~ 2.5 ms** | 0/39 |
|
||||
|
||||
复发尖峰彻底消除，稳态全部回到帧预算内。
|
||||
|
||||
> **⚠️ 数字按区间读，不要按单值读**：以上均为**编辑器/调试构建**实测，运行间存在明显离散。同一场景 ②·1500 三次独立测量分别得 **5.61 / 5.09 / 7.29 ms**；240 帧长跑收敛在 5–7 ms 带内、无发散。写成单值会显得比数据本身更精确 —— 结论（稳态远低于 16.67 ms 帧预算、无复发尖峰）不受此离散影响，但**不要引用单个数字做后续推算**，也不要因复跑得到带内的不同值就判定为回归。判定回归请看：是否出现周期性复发尖峰、是否有帧越过 16.67 ms。
|
||||
>
|
||||
> 另注：稳态峰值对**测试几何**敏感。若子弹航线穿过敌人簇，`_check_collision` 的 `query_circle` + `visited_targets` 线性扫描会额外贡献 1~1.5 ms，那部分**不是归航成本**（验收期曾因此误读一次）。上表摆位为「敌人置于环上、子弹簇于原点」，刻意让子弹不穿过敌人簇。
|
||||
|
||||
### 5.6 残余：初次锁定帧 —— **已决策：接受，不处理**
|
||||
|
||||
抖动后仍有**一个**高耗时帧 —— 第 1 帧，1500 弹 `far` 16.2 ms / `visited` 22.0 ms。它**不是**退避尖峰，而是「§2.4 首次锁定即时、不受退避约束」的直接结果：1500 颗归航子弹在同一帧被创建时，它们的首次 `query_circle` 必然落在同一帧。抖动按设计不作用于此（已断言首帧即时锁定且不写退避键，手感不回退）。
|
||||
|
||||
Reference in New Issue
Block a user