# 小球防围困机制测试指南

## 概述

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

## 测试功能

### 1. 测试模式开关

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

### 2. 方向限制

测试模式下，小球初始方向被限制为：
- 向上 (0, 1)
- 向下 (0, -1) 
- 向右 (1, 0)
- 向左 (-1, 0)

### 3. 详细日志输出

测试模式会在控制台输出详细信息：
- 小球初始方向
- 撞击统计（次数/阈值）
- 防围困机制触发
- 偏移尝试和方向改变
- 穿透模式启用

## 测试步骤

### 准备工作

1. **确保测试模式开启**
   - 在Inspector中找到BallController组件
   - 确认 `Test Mode` 复选框已勾选

2. **设置测试场景**
   - 在游戏区域放置一些方块
   - 创建可能导致小球来回弹跳的布局
   - 建议创建狭窄通道或角落区域

### 执行测试

1. **启动游戏**
   - 运行游戏场景
   - 点击开始按钮创建小球

2. **观察初始方向**
   - 查看控制台输出的初始方向信息
   - 确认小球确实按基本方向移动

3. **监控防围困机制**
   - 观察小球与方块的碰撞
   - 注意控制台的撞击统计信息
   - 等待防围困机制触发

### 测试用例

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

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

#### 用例3：角落陷阱测试
```
布局：创建L形或U形陷阱
期望：小球被困时能够通过穿透模式脱困
观察：穿透模式是否正常工作
```

## 防围困机制参数

### 核心参数

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

### 增强防围困参数

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

### 工作流程

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

#### 增强防围困机制（解决长距离振荡）
1. **运动追踪**: 实时记录小球位置和方向历史
2. **方向检测**: 监测小球方向的显著改变（>90度）
3. **振荡分析**: 分析位置历史判断是否为水平或垂直振荡
4. **智能干预**: 根据振荡轴向施加垂直方向的随机冲量
5. **状态重置**: 干预后重置振荡检测数据

## 预期结果

### 正常表现

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

### 异常情况

❌ **方向异常**: 小球方向不是基本方向 → 检查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` 获取详细的测试指导和配置信息：

```bash
node test_ball_anti_trap.js
```

## 测试脚本运行

### 基础防围困测试
```javascript
// 在浏览器控制台中运行
startAntiTrapTest();
```

### 增强防围困测试（新增）
```javascript
// 测试长距离振荡检测功能
startEnhancedAntiTrapTest();
```

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

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

## 关闭测试模式

测试完成后，记得关闭测试模式：
1. 在Inspector中取消勾选 `Test Mode`
2. 小球将恢复随机方向移动
3. 防围困机制仍然正常工作，但日志输出会减少

## 注意事项

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