tanqiu/docs/AntiTrapMechanism.md

小球防围困机制

功能描述

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

配置参数

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

antiTrapTimeWindow (防围困检测时间窗口)

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

antiTrapHitThreshold (防围困撞击次数阈值)

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

工作原理

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

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

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

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

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

技术实现

核心数据结构

// 记录每个球的撞击时间历史
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 次