# 反透视插件 - AntiESP
[](https://github.com/114514h/AntiESP)
[](https://minecraft.net)
[](https://openjdk.java.net)
[](LICENSE)
## 📖 简介 / Introduction
### 中文
AntiESP是一个专为Minecraft服务器设计的反透视插件，通过实时计算玩家视线连接来防止透视外挂。插件采用先进的射线投射算法，精确检测玩家之间的视线遮挡，并智能拦截可能暴露玩家位置的数据包。
### English
AntiESP is an anti-ESP (Extra Sensory Perception) plugin designed for Minecraft servers. It prevents ESP hacks by calculating player line-of-sight in real-time using advanced raycasting algorithms. The plugin intelligently detects visual obstructions between players and intercepts data packets that could expose player positions.
---
## ✨ 功能特性 / Features
### 🛡️ 核心功能 / Core Features
| 功能 / Feature | 中文描述 | English Description |
|---|---|---|
| **实时视线检测** | 使用射线投射算法实时计算玩家视线连接 | Real-time line-of-sight detection using raycasting algorithms |
| **智能数据包拦截** | 拦截可能暴露玩家位置的数据包 | Intelligent packet interception to prevent position exposure |
| **严格模式检测** | 可配置的阻挡阈值，要求玩家完全被遮挡才隐藏 | Configurable blocking thresholds for strict detection |
| **多角度检测** | 检查玩家周围的多个点，提高检测精度 | Multi-angle detection for improved accuracy |
| **队伍豁免系统** | 同队玩家之间不进行反透视处理 | Team exemption system for same-team players |
| **近距离豁免** | 近距离玩家始终可见，避免误判 | Close-range exemption to prevent false positives |
| **多语言支持** | 支持中文和英文界面 | Multi-language support (Chinese & English) |
| **详细调试模式** | 完整的调试信息输出 | Comprehensive debug mode with detailed logging |
### 🎯 高级功能 / Advanced Features
| 功能 / Feature | 中文描述 | English Description |
|---|---|---|
| **眼睛高度检测** | 使用玩家眼睛高度进行视线检测 | Eye-height detection for realistic line-of-sight |
| **透明方块识别** | 智能识别透明和半透明方块 | Intelligent transparent block detection |
| **性能优化** | 异步处理和批量处理优化 | Performance optimization with async processing |
| **配置热重载** | 无需重启服务器即可重载配置 | Hot-reload configuration without server restart |
| **权限系统** | 完整的权限控制和绕过机制 | Complete permission system with bypass options |
| **队伍检测** | 支持计分板和权限两种队伍检测方法 | Team detection via scoreboard and permissions |
---
## 🔧 功能原理 / How It Works
### 中文
#### 1. 视线检测原理
插件使用射线投射（Raycasting）算法来检测两个玩家之间是否有视线连接：
1. **起点计算**: 从观察者玩家的眼睛位置开始
2. **终点计算**: 到目标玩家的眼睛位置结束
3. **路径采样**: 沿着视线路径以固定步长采样点
4. **方块检测**: 检查每个采样点是否有阻挡方块
5. **结果判断**: 根据阻挡比例和连续阻挡区域判断是否可见
#### 2. 数据包拦截原理
当检测到玩家被遮挡时，插件会：
1. **隐藏玩家**: 使用Bukkit API隐藏被遮挡的玩家
2. **拦截数据包**: 阻止可能暴露位置的数据包发送
3. **动态更新**: 实时更新玩家可见性状态
#### 3. 队伍豁免原理
同队玩家之间的豁免机制：
1. **队伍检测**: 检查玩家是否在同一队伍（计分板或权限）
2. **豁免应用**: 同队玩家跳过视线检测，始终可见
3. **动态更新**: 队伍变化时自动更新豁免状态
### English
#### 1. Line-of-Sight Detection
The plugin uses raycasting algorithms to detect line-of-sight connections between players:
1. **Start Point**: Calculate from observer's eye position
2. **End Point**: Calculate to target player's eye position
3. **Path Sampling**: Sample points along the line-of-sight path
4. **Block Detection**: Check each sample point for blocking blocks
5. **Result Judgment**: Determine visibility based on blocking ratio and consecutive blocked areas
#### 2. Packet Interception
When a player is detected as blocked:
1. **Hide Player**: Use Bukkit API to hide the blocked player
2. **Intercept Packets**: Prevent position-exposing packets from being sent
3. **Dynamic Updates**: Real-time visibility state updates
#### 3. Team Exemption
Same-team player exemption mechanism:
1. **Team Detection**: Check if players are in the same team (scoreboard or permissions)
2. **Exemption Application**: Same-team players skip line-of-sight detection, always visible
3. **Dynamic Updates**: Automatic exemption state updates when teams change
---
## 📋 安装指南 / Installation
### 中文
#### 系统要求
- **Minecraft版本**: 1.21.4
- **服务器类型**: Spigot/Paper
- **Java版本**: 17或更高
- **内存要求**: 建议2GB以上
#### 安装步骤
1. 下载最新版本的`AntiESP-1.1.4.jar`
2. 将插件文件放入服务器的`plugins`文件夹
3. 重启服务器
4. 插件将自动生成配置文件
5. 根据需要修改`config.yml`配置
### English
#### System Requirements
- **Minecraft Version**: 1.21.4
- **Server Type**: Spigot/Paper
- **Java Version**: 17 or higher
- **Memory**: Recommended 2GB+
#### Installation Steps
1. Download the latest `AntiESP-1.1.4.jar`
2. Place the plugin file in your server's `plugins` folder
3. Restart the server
4. The plugin will automatically generate configuration files
5. Modify `config.yml` as needed
---
## ⚙️ 配置说明 / Configuration
### 中文
#### 基础配置
```yaml
# 调试模式
debug: false
# 检查间隔（tick）
check-interval: 2
# 最大检测距离
max-distance: 64.0
# 最小检测距离（近距离豁免）
min-distance: 5.0
# 队伍豁免设置
team-exemption:
enabled: true
detection-method: "scoreboard" # scoreboard/permission/both
# 严格模式设置
advanced:
strict-mode:
enabled: true
blocking-threshold: 0.7 # 阻挡阈值
multi-angle-check: true
use-eye-height: true
```
#### 配置说明
- **debug**: 启用调试模式，输出详细信息
- **check-interval**: 视线检查间隔，数值越小检查越频繁
- **max-distance**: 最大检测距离，超过此距离不检测
- **min-distance**: 近距离豁免，小于此距离始终可见
- **blocking-threshold**: 阻挡阈值，0.7表示70%路径被阻挡才隐藏
### English
#### Basic Configuration
```yaml
# Debug mode
debug: false
# Check interval (ticks)
check-interval: 2
# Maximum detection distance
max-distance: 64.0
# Minimum detection distance (close-range exemption)
min-distance: 5.0
# Team exemption settings
team-exemption:
enabled: true
detection-method: "scoreboard" # scoreboard/permission/both
# Strict mode settings
advanced:
strict-mode:
enabled: true
blocking-threshold: 0.7 # Blocking threshold
multi-angle-check: true
use-eye-height: true
```
#### Configuration Explanation
- **debug**: Enable debug mode for detailed output
- **check-interval**: Line-of-sight check interval, smaller values = more frequent checks
- **max-distance**: Maximum detection distance, players beyond this distance are not detected
- **min-distance**: Close-range exemption, players within this distance are always visible
- **blocking-threshold**: Blocking threshold, 0.7 means hide when 70% of path is blocked
---
## 🎮 使用教程 / Usage Guide
### 中文
#### 基础命令
```
/antiesp # 显示帮助信息
/antiesp reload # 重载配置
/antiesp status # 查看插件状态
/antiesp debug on/off # 启用/禁用调试模式
/antiesp info # 查看插件信息
/antiesp stats # 查看统计信息
```
#### 队伍管理命令
```
/antiesp team # 查看队伍豁免设置
/antiesp team enable/disable # 启用/禁用队伍豁免
/antiesp team method <方法> # 设置检测方法
/antiesp team info <玩家名> # 查看玩家队伍信息
```
#### 严格模式命令
```
/antiesp strict on/off # 启用/禁用严格模式
/antiesp strict threshold <值> # 设置阻挡阈值
/antiesp strict multiangle on/off # 启用/禁用多角度检测
```
#### 语言设置命令
```
/antiesp lang zh # 设置为中文
/antiesp lang en # 设置为英文
```
### English
#### Basic Commands
```
/antiesp # Show help information
/antiesp reload # Reload configuration
/antiesp status # View plugin status
/antiesp debug on/off # Enable/disable debug mode
/antiesp info # View plugin information
/antiesp stats # View statistics
```
#### Team Management Commands
```
/antiesp team # View team exemption settings
/antiesp team enable/disable # Enable/disable team exemption
/antiesp team method # Set detection method
/antiesp team info # View player team information
```
#### Strict Mode Commands
```
/antiesp strict on/off # Enable/disable strict mode
/antiesp strict threshold # Set blocking threshold
/antiesp strict multiangle on/off # Enable/disable multi-angle detection
```
#### Language Commands
```
/antiesp lang zh # Set to Chinese
/antiesp lang en # Set to English
```
---
## 🔍 调试教程 / Debug Guide
### 中文
#### 启用调试模式
```
/antiesp debug on
```
#### 调试信息说明
启用调试模式后，控制台会输出详细信息：
**可见性更新日志**:
```
[INFO] === 开始可见性更新 ===
[INFO] 在线玩家数量: 5
[INFO] 处理时间: 1703123456789
[INFO] 开始处理玩家: Player1 (uuid)
[INFO] 观察者位置: (world, 100.00, 64.00, 200.00)
[INFO] 检查目标: Player2 距离: 15.50
```
**队伍豁免日志**:
```
[INFO] 队伍豁免检查: Player1 vs Player2 | 同队: true | 豁免生效: true
[INFO] 队伍豁免生效: Player1 和 Player2 在同一队伍，跳过反透视
[INFO] 队伍豁免显示: Player1 现在可以看到 Player2 (队伍豁免)
```
**视线检测日志**:
```
[INFO] 使用眼睛高度检测: 观察者 (world, 100.00, 65.60, 200.00) -> 目标 (world, 115.50, 65.60, 200.00)
[INFO] 视线检测结果: 可见 | 方法: 智能检测 | 距离: 15.50 | 耗时: 150μs
[INFO] 严格模式: 启用 | 阻挡阈值: 70%
```
#### 性能统计日志
```
[INFO] === 可见性更新完成 ===
[INFO] 处理玩家数量: 5
[INFO] 总耗时: 25ms
[INFO] 平均耗时: 5ms/玩家
```
### English
#### Enable Debug Mode
```
/antiesp debug on
```
#### Debug Information
When debug mode is enabled, the console will output detailed information:
**Visibility Update Logs**:
```
[INFO] === Starting Visibility Update ===
[INFO] Online players: 5
[INFO] Processing time: 1703123456789
[INFO] Processing player: Player1 (uuid)
[INFO] Observer location: (world, 100.00, 64.00, 200.00)
[INFO] Checking target: Player2 distance: 15.50
```
**Team Exemption Logs**:
```
[INFO] Team exemption check: Player1 vs Player2 | Same team: true | Exemption active: true
[INFO] Team exemption active: Player1 and Player2 are in the same team, skipping anti-ESP
[INFO] Team exemption show: Player1 can now see Player2 (team exemption)
```
**Line-of-Sight Detection Logs**:
```
[INFO] Using eye height detection: Observer (world, 100.00, 65.60, 200.00) -> Target (world, 115.50, 65.60, 200.00)
[INFO] Line-of-sight result: Visible | Method: Smart detection | Distance: 15.50 | Time: 150μs
[INFO] Strict mode: Enabled | Blocking threshold: 70%
```
**Performance Statistics Logs**:
```
[INFO] === Visibility Update Complete ===
[INFO] Processed players: 5
[INFO] Total time: 25ms
[INFO] Average time: 5ms/player
```
---
## 🛡️ 权限系统 / Permission System
### 中文
#### 权限列表
| 权限 | 描述 | 默认 |
|---|---|---|
| `antiesp.admin` | 管理员权限，可以使用所有命令 | OP |
| `antiesp.bypass` | 绕过反透视检测 | 无 |
| `antiesp.team.` | 队伍权限，用于权限检测方法 | 无 |
| `antiesp.team.exemption` | 队伍豁免权限 | 无 |
#### 权限配置示例
```yaml
# LuckPerms 配置示例
lp user Player1 permission set antiesp.team.red true
lp user Player2 permission set antiesp.team.red true
lp user Player3 permission set antiesp.bypass true
```
### English
#### Permission List
| Permission | Description | Default |
|---|---|---|
| `antiesp.admin` | Admin permission, can use all commands | OP |
| `antiesp.bypass` | Bypass anti-ESP detection | None |
| `antiesp.team.` | Team permission for permission detection method | None |
| `antiesp.team.exemption` | Team exemption permission | None |
#### Permission Configuration Example
```yaml
# LuckPerms configuration example
lp user Player1 permission set antiesp.team.red true
lp user Player2 permission set antiesp.team.red true
lp user Player3 permission set antiesp.bypass true
```
---
## 🎯 使用场景 / Use Cases
### 中文
#### 1. PvP服务器
- **团队战斗**: 同队玩家可以互相看到，即使被方块遮挡
- **竞技比赛**: 防止透视外挂，保证公平竞争
- **生存服务器**: 保护玩家隐私，防止恶意透视
#### 2. 合作服务器
- **建筑项目**: 队友之间保持可见性，便于协作
- **冒险模式**: 团队探险时保持联系
- **创造模式**: 多人协作时的可见性管理
#### 3. 混合服务器
- **角色扮演**: 不同阵营之间的视线管理
- **经济服务器**: 保护玩家基地隐私
- **小游戏**: 各种小游戏中的反透视需求
### English
#### 1. PvP Servers
- **Team Battles**: Same-team players can see each other even when blocked by blocks
- **Competitive Matches**: Prevent ESP hacks for fair competition
- **Survival Servers**: Protect player privacy from malicious ESP
#### 2. Cooperative Servers
- **Building Projects**: Maintain visibility between teammates for collaboration
- **Adventure Mode**: Keep team members connected during exploration
- **Creative Mode**: Visibility management for multiplayer collaboration
#### 3. Mixed Servers
- **Roleplay**: Line-of-sight management between different factions
- **Economy Servers**: Protect player base privacy
- **Mini-games**: Anti-ESP requirements for various mini-games
---
## 📊 性能优化 / Performance Optimization
### 中文
#### 性能建议
1. **检查间隔**: 建议设置为2-5tick，平衡性能和效果
2. **检测距离**: 根据服务器规模调整最大检测距离
3. **异步处理**: 启用异步处理提高性能
4. **批量处理**: 调整批量处理大小优化内存使用
#### 性能监控
```
/antiesp stats # 查看性能统计
```
### English
#### Performance Recommendations
1. **Check Interval**: Recommended 2-5 ticks to balance performance and effectiveness
2. **Detection Distance**: Adjust maximum detection distance based on server size
3. **Async Processing**: Enable async processing for better performance
4. **Batch Processing**: Adjust batch size to optimize memory usage
#### Performance Monitoring
```
/antiesp stats # View performance statistics
```
---
## 🐛 故障排除 / Troubleshooting
### 中文
#### 常见问题
**Q: 同队玩家仍然被隐藏**
A: 检查以下项目：
1. 队伍豁免是否启用：`/antiesp team`
2. 玩家是否在同一队伍：`/antiesp team info <玩家名>`
3. 调试模式是否启用：`/antiesp debug on`
4. 配置文件是否正确
**Q: 插件性能问题**
A: 优化建议：
1. 增加检查间隔：`check-interval: 5`
2. 减少检测距离：`max-distance: 32.0`
3. 启用异步处理：`async-processing: true`
**Q: 配置不生效**
A: 解决方案：
1. 重载配置：`/antiesp reload`
2. 检查配置文件语法
3. 重启服务器
### English
#### Common Issues
**Q: Same-team players are still hidden**
A: Check the following:
1. Is team exemption enabled: `/antiesp team`
2. Are players in the same team: `/antiesp team info `
3. Is debug mode enabled: `/antiesp debug on`
4. Is the configuration file correct
**Q: Plugin performance issues**
A: Optimization suggestions:
1. Increase check interval: `check-interval: 5`
2. Reduce detection distance: `max-distance: 32.0`
3. Enable async processing: `async-processing: true`
**Q: Configuration not working**
A: Solutions:
1. Reload configuration: `/antiesp reload`
2. Check configuration file syntax
3. Restart the server
---
## 📞 支持与反馈 / Support & Feedback
### 中文
- **问题报告**: 请提供详细的错误信息和调试日志
- **功能建议**: 欢迎提出改进建议
- **技术支持**: 通过GitHub Issues获取支持
### English
- **Bug Reports**: Please provide detailed error information and debug logs
- **Feature Suggestions**: Welcome to suggest improvements
- **Technical Support**: Get support through GitHub Issues
---
## 📄 许可证 / License
本项目采用MIT许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
---
## 👨💻 作者 / Author
**114514h** - 插件开发者
**114514h** - Plugin Developer
---
## 🙏 致谢 / Acknowledgments
感谢为这个项目做出贡献的我。
Thanks to me contributed to this project.