小球防围困机制测试指南

概述

本指南介绍如何测试小球的防围困机制，特别是在完全垂直或水平方向下的表现。防围困机制旨在防止小球在狭窄空间内来回弹跳，提升游戏体验。

测试功能

1. 测试模式开关

在 BallController 组件中，新增了 testMode 属性：

位置: Inspector面板中的BallController组件
功能: 启用后，小球只会向上/下/左/右四个基本方向移动
默认值: true（测试模式开启）

2. 方向限制

测试模式下，小球初始方向被限制为：

向上 (0, 1)
向下 (0, -1)
向右 (1, 0)
向左 (-1, 0)

3. 详细日志输出

测试模式会在控制台输出详细信息：

小球初始方向
撞击统计（次数/阈值）
防围困机制触发
偏移尝试和方向改变
穿透模式启用

测试步骤

准备工作

确保测试模式开启
- 在Inspector中找到BallController组件
- 确认 Test Mode 复选框已勾选
设置测试场景
- 在游戏区域放置一些方块
- 创建可能导致小球来回弹跳的布局
- 建议创建狭窄通道或角落区域

执行测试

启动游戏
- 运行游戏场景
- 点击开始按钮创建小球
观察初始方向
- 查看控制台输出的初始方向信息
- 确认小球确实按基本方向移动
监控防围困机制
- 观察小球与方块的碰撞
- 注意控制台的撞击统计信息
- 等待防围困机制触发

测试用例

用例1：垂直通道测试

布局：创建垂直狭窄通道
期望：小球垂直移动时遇到阻碍能够偏移脱困
观察：偏移反弹是否改变方向

用例2：水平通道测试

布局：创建水平狭窄通道
期望：小球水平移动时遇到阻碍能够偏移脱困
观察：偏移反弹是否改变方向

用例3：角落陷阱测试

布局：创建L形或U形陷阱
期望：小球被困时能够通过穿透模式脱困
观察：穿透模式是否正常工作

防围困机制参数

核心参数

antiTrapTimeWindow: 5.0秒 - 撞击历史时间窗口
antiTrapHitThreshold: 5次 - 触发防围困的撞击次数
deflectionAttemptThreshold: 3次 - 偏移尝试次数上限
antiTrapDeflectionMultiplier: 3.0倍 - 偏移增强倍数

增强防围困参数

oscillationTimeWindow: 3.0秒 - 振荡检测时间窗口
directionChangeThreshold: 4次 - 触发振荡检测的方向改变次数
positionHistorySize: 20个 - 位置历史记录数量
oscillationDistanceThreshold: 100像素 - 振荡距离阈值

工作流程

基础防围困机制

撞击记录: 记录小球在时间窗口内的撞击次数
阈值检查: 撞击次数达到阈值时触发防围困
偏移尝试: 优先使用增强偏移反弹改变方向
穿透模式: 偏移无效时启用0.5秒穿透模式

增强防围困机制（解决长距离振荡）

运动追踪: 实时记录小球位置和方向历史
方向检测: 监测小球方向的显著改变（>90度）
振荡分析: 分析位置历史判断是否为水平或垂直振荡
智能干预: 根据振荡轴向施加垂直方向的随机冲量
状态重置: 干预后重置振荡检测数据

预期结果

正常表现

✅ 初始方向正确: 小球按四个基本方向之一移动
✅ 撞击统计准确: 控制台显示正确的撞击计数
✅ 防围困触发: 达到阈值时正确触发机制
✅ 偏移有效: 偏移反弹改变小球方向
✅ 穿透工作: 穿透模式让小球暂时忽略碰撞
✅ 脱困成功: 小球能够从陷阱中脱困
✅ 振荡检测: 小球在长距离墙体或方块间来回弹跳时能被检测并干预
✅ 智能冲量: 水平振荡时给予垂直冲量，垂直振荡时给予水平冲量
✅ 增强日志: 控制台输出详细的振荡检测信息和干预记录

异常情况

❌ 方向异常: 小球方向不是基本方向 → 检查testMode设置
❌ 无防围困日志: 没有撞击统计输出 → 检查方块碰撞体group设置
❌ 防围困无效: 小球仍然来回弹跳 → 调整参数阈值
❌ 偏移无效: 方向改变不明显 → 增加偏移倍数
❌ 振荡检测失效: 检查oscillationDistanceThreshold是否过大或过小
❌ 冲量过强: 调整冲量系数（当前为baseSpeed * 0.8）
❌ 检测过敏: 增加directionChangeThreshold或oscillationTimeWindow

参数调优

基础参数调整

增加敏感度: 降低antiTrapHitThreshold（如改为3-4次）
减少敏感度: 增加antiTrapHitThreshold（如改为6-8次）
延长检测窗口: 增加antiTrapTimeWindow（如改为6-8秒）
增强偏移效果: 增加antiTrapDeflectionMultiplier（如改为4-5倍）

增强防围困参数调整

振荡检测敏感度: 调整directionChangeThreshold（2-6次）
检测时间窗口: 调整oscillationTimeWindow（2-5秒）
位置历史精度: 调整positionHistorySize（10-30个）
距离阈值: 调整oscillationDistanceThreshold（50-200像素）
冲量强度: 修改代码中的冲量系数（0.5-1.2倍baseSpeed）

防围困过于敏感

问题：防围困触发太频繁
解决：增加 antiTrapHitThreshold 或减少 antiTrapTimeWindow

防围困不够敏感

问题：小球长时间被困才触发
解决：减少 antiTrapHitThreshold 或增加 antiTrapTimeWindow

偏移效果不足

问题：偏移后仍然容易被困
解决：增加 antiTrapDeflectionMultiplier

穿透时间不当

问题：穿透时间过短或过长
解决：修改代码中的穿透持续时间（当前0.5秒）

测试脚本

运行 test_ball_anti_trap.js 获取详细的测试指导和配置信息：

node test_ball_anti_trap.js

测试脚本运行

基础防围困测试

// 在浏览器控制台中运行
startAntiTrapTest();

增强防围困测试（新增）

// 测试长距离振荡检测功能
startEnhancedAntiTrapTest();

快速测试

// 30秒快速基础测试
quickAntiTrapTest();

// 30秒快速增强测试
quickEnhancedAntiTrapTest();

关闭测试模式

测试完成后，记得关闭测试模式：

在Inspector中取消勾选 Test Mode
小球将恢复随机方向移动
防围困机制仍然正常工作，但日志输出会减少

注意事项

测试模式仅影响小球初始方向，不影响防围困机制本身
防围困机制在正常游戏中也会工作，测试模式只是便于观察
建议在不同的方块布局下进行多次测试
注意观察控制台输出，它提供了机制工作的详细信息
增强功能：新增的振荡检测功能专门解决长距离来回弹跳问题
内存管理：位置和方向历史会占用内存，已设置合理上限
实时监控：增强防围困机制会实时分析小球运动模式
智能干预：根据振荡轴向自动选择最佳干预方向

小球防围困机制测试指南.md 7.1 KB Histórico Em bruto