# 小球防围困机制

## 功能描述

防围困机制是为了防止小球被方块围住而无法继续游戏的情况。当小球在规定时间内撞击方块的次数达到阈值时，小球将进入短暂的穿透状态，可以无视碰撞体积穿过方块。

## 配置参数

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

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

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

## 工作原理

1. **撞击记录**: 每当小球撞击方块时，系统会记录撞击时间。

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

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

4. **穿透状态**: 小球进入穿透状态，持续 0.5 秒，期间可以穿过方块但仍会播放撞击特效。

5. **状态清理**: 穿透状态结束后，小球恢复正常碰撞，撞击历史被清空。

## 技术实现

### 核心数据结构

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

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

### 关键方法

- `onBeginContact()`: 碰撞检测的核心方法，包含防围困逻辑
- `cleanupExpiredAntiTrapStates()`: 清理过期的穿透状态
- `cleanupBallAntiTrapState()`: 清理单个小球的防围困状态

## 注意事项

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

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

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

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

## 调试信息

当小球进入穿透状态时，控制台会输出调试信息：
```
Ball {ballId} entered phase-through mode due to frequent collisions
```

## 配置建议

- **休闲模式**: 时间窗口 1.5 秒，阈值 3-4 次
- **普通模式**: 时间窗口 2.0 秒，阈值 5 次（默认）
- **困难模式**: 时间窗口 2.5 秒，阈值 6-7 次