# 小球防围困机制

## 功能描述

防围困机制是为了防止小球被方块围住而无法继续游戏的情况。当小球在规定时间内撞击方块的次数达到阈值时，系统会采用两阶段防围困策略：
1. **优先偏移**：首先尝试通过增强的角度偏移来帮助小球脱困
2. **备用穿透**：当偏移尝试失败后，才激活穿透状态使小球无视碰撞体积穿过方块

## 配置参数

在 `BallController` 组件中可以配置以下参数：

### antiTrapTimeWindow (防围困检测时间窗口)
- **类型**: number
- **默认值**: 2.0 秒
- **说明**: 用于检测频繁撞击的时间窗口。只有在这个时间窗口内的撞击才会被计入防围困检测。

### antiTrapHitThreshold (防围困撞击次数阈值)
- **类型**: number
- **默认值**: 5 次
- **说明**: 在时间窗口内达到这个撞击次数时，将触发防围困机制。

### deflectionAttemptThreshold (偏移尝试次数阈值)
- **类型**: number
- **默认值**: 3 次
- **说明**: 偏移尝试次数阈值。系统会优先尝试偏移方式，只有在偏移尝试次数达到此阈值后才会使用穿透方式。

### antiTrapDeflectionMultiplier (防围困偏移强度倍数)
- **类型**: number
- **默认值**: 3.0 倍
- **说明**: 防围困偏移强度倍数。用于增强偏移效果，帮助小球更容易脱困。

## 工作原理

### 两阶段防围困策略

#### 第一阶段：偏移尝试
1. **撞击记录**: 每当小球撞击方块时，系统会记录撞击时间。

2. **时间窗口清理**: 系统会自动清理超出时间窗口的旧撞击记录。

3. **阈值检测**: 当时间窗口内的撞击次数达到阈值时，触发防围困机制。

4. **偏移应用**: 达到阈值时，首先尝试应用增强的角度偏移
   - 计算当前速度方向和碰撞法线
   - 应用防围困增强偏移算法
   - 重新设置小球的运动方向
   - 清空撞击历史，给偏移一个机会

#### 第二阶段：穿透备用
5. **偏移失效检测**: 如果偏移尝试次数达到 `deflectionAttemptThreshold`

6. **穿透状态**: 激活0.5秒的穿透状态，小球可无视碰撞体积穿过方块但仍会播放撞击特效。

7. **状态清理**: 穿透状态结束后，小球恢复正常碰撞，撞击历史被清空，重置偏移尝试计数。

## 技术实现

### 核心数据结构

```typescript
// 记录每个球的撞击时间历史
private ballHitHistory: Map<string, number[]> = new Map();

// 记录每个球的穿透结束时间
private ballPhaseThrough: Map<string, number> = new Map();

// 记录每个球的偏移尝试次数
private ballDeflectionAttempts: Map<string, number> = new Map();
```

### 关键方法

- `onBeginContact()`: 碰撞检测的核心方法，包含两阶段防围困逻辑
- `calculateAntiTrapReflection()`: 计算防围困增强偏移反弹方向
- `cleanupExpiredAntiTrapStates()`: 清理过期的穿透状态
- `cleanupBallAntiTrapState()`: 清理单个小球的防围困状态

## 注意事项

1. **不改变碰撞组**: 该机制不会修改方块的碰撞组设置，只是临时禁用碰撞。

2. **视觉反馈**: 即使在穿透状态下，仍会播放撞击特效，保持视觉一致性。

3. **内存管理**: 系统会自动清理过期数据，防止内存泄漏。

4. **多球支持**: 每个小球都有独立的防围困状态，互不影响。

## 调试信息

系统会在控制台输出以下调试信息：
```
Ball {ballId} applied anti-trap deflection (attempt {current}/{max})
Ball {ballId} entered phase-through mode after {threshold} deflection attempts failed
Cleaned up anti-trap state for ball {ballId}
```

## 配置建议

- **时间窗口**: 建议设置为1.5-2.5秒，太短可能误触发，太长可能反应迟钝
- **撞击阈值**: 建议设置为3-7次，根据游戏难度调整
- **偏移尝试阈值**: 建议设置为2-5次，平衡偏移和穿透的使用频率
- **偏移强度倍数**: 建议设置为2.0-5.0，过低可能无效，过高可能过于激进
- **测试方法**: 可以通过创建密集的方块布局来测试两阶段防围困效果

## 优势

1. **减少穿透频率**: 优先使用偏移方式，只在必要时才使用穿透
2. **保持游戏体验**: 偏移方式保持了物理碰撞的真实感
3. **渐进式解决**: 从轻微干预到强力干预的渐进式防围困策略
4. **可配置性**: 多个参数可根据游戏需求灵活调整