# mod-ac-guardian

**Repository Path**: xsdjsjwy/mod-ac-guardian

## Basic Information

- **Project Name**: mod-ac-guardian
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-12
- **Last Updated**: 2026-01-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# mod-ac-guardian（AzerothCore WotLK）

适用于 AzerothCore WotLK 的 **mod-only** 反外挂检测与可选处置模块。

核心思路是“**多证据 → 风险分（半衰期衰减）→ 分层处置**”：
- 多个检测器提供证据（并带降噪窗口/白名单）。
- 风险分随时间衰减，避免偶发抖动长期“记仇”。
- 达到阈值后再触发 GM 通知/可选拦截/可选惩罚（Debuff/Jail/Kick）。

## 特点

- **低误判优先**：Teleport/位移技能/登录切图等都有宽限期；支持 Aura/Spell 白名单。
- **可运维**：可选周期性 report（窗口 + 文件），便于观察与调参。
- **处置可渐进**：默认建议“只告警/只记录”，确认命中质量后再逐步开启强硬动作。
- **NoClip（穿门/穿模）**：基于服务端射线检测（vmaps 静态碰撞 + 动态 GO 碰撞）。
- **协议层辅证（OpAck）**：追踪部分 server->client 强制状态变更并期待 ACK。
- **惩罚持久化**：Debuff 的累计次数/到期时间存 character DB。

## 覆盖的检测类型（当前实现）

- **时间/加速类**：TimeManipulation（含 time backwards strike）、SpeedEnvelope
- **瞬移/大跳**：Teleport
- **飞天/离地**：FlyHack（高度与飞行状态相关）
- **穿门/穿模**：NoClip（warn 或 rollback）
- **挂机/脚本倾向**：AfkBot（小范围移动 + 拾取窗口，含“商业技能制作/采集”排除窗口）
- **协议异常证据**：OpAck（missing/unexpected/canfly）

## 安装与启用

### 1) 放入 modules

clone本项目到 AzerothCore 的 `modules/` 目录下，例如：

```text
modules/mod-ac-guardian
```

### 2) 编译

使用 acore.sh：

```bash
./acore.sh compiler build
```

### 3) 配置文件

该模块的配置模板在：

```text
modules/mod-ac-guardian/conf/AcGuardian.conf.dist
```

运行构建后，模块配置会被复制到运行目录的：

```text
build/bin/<配置>/configs/modules/AcGuardian.conf.dist
```

把 `.dist` 复制一份改名为 `.conf`：

```text
.../configs/modules/AcGuardian.conf
```

说明：AzerothCore 约定 **`.conf` 才是实际加载配置**；`.conf.dist` 是模板/分发文件。

### 4) 数据库（character 库）

模块包含一张 character DB 表用于累计次数与惩罚到期：

```text
modules/mod-ac-guardian/data/sql/db-characters/base/001_acg_cheat_record.sql
```

如果你的环境已启用并正确配置 DBUpdater，通常会自动应用模块 SQL；否则请手动导入。

### 5) 启动验证

启动 worldserver 后，建议先：
- 观察启动日志是否出现模块启用相关日志。
- 先保持“只告警”运行一段时间（见下方运维建议）。

## 配置速览（最常用）

下面键名以 `AcGuardian.conf.dist` 为准：

### 全局/日志

- `AcGuardian.Enabled`：总开关
- `AcGuardian.EnabledOnGmAccounts`：是否对 GM 账号启用检测
- `AcGuardian.Log`：模块内部日志

### 降误判（强烈建议保留）

- `AcGuardian.Accuracy.TeleportGraceMs`：传送/切图后的宽限期
- `AcGuardian.Accuracy.MobilitySpellGraceMs`：位移技能后的宽限期
- `AcGuardian.Accuracy.MobilityGraceByEffects`：根据 SpellEffect 自动识别位移类技能
- `AcGuardian.Accuracy.TeleportGraceByEffects`：根据 SpellEffect 自动识别传送类技能
- `AcGuardian.Whitelist.AuraIds`：Aura 白名单（载具/剧情飞行/特殊状态等）
- `AcGuardian.Whitelist.TeleportSpellIds`：传送技能白名单

### NoClip（穿门/穿模）

- `AcGuardian.Detector.NoClip.Enabled`
- `AcGuardian.Detector.NoClip.Action`：`warn` 或 `rollback`

说明：NoClip 强烈建议先用 `warn` 跑一段时间，确认命中质量后再开 `rollback`。

### OpAck（协议 ACK 异常）

- `AcGuardian.Detector.OpAck.Enabled`
- `AcGuardian.Detector.OpAck.TrackRoot` / `TrackCanFly`：默认建议开启
- `AcGuardian.Detector.OpAck.TrackSpeed`：默认建议关闭，仅在需要时再开

### 自动处置（建议从弱到强逐步启用）

- GM 通知：`AcGuardian.NotifyGMs`、`AcGuardian.NotifyGMs.MinScore`
- 拦截移动包：`AcGuardian.BlockMovement.Enabled`
- Debuff（DB 驱动分级持续时间）：`AcGuardian.AutoAction.Debuff.*`
- Jail（可选送监狱）：`AcGuardian.AutoAction.Jail.*`
- Kick（踢下线）：`AcGuardian.AutoAction.Kick.*`

## GM 解除 debuff

使用 AzerothCore 原生命令：

```text
.unaura <spellId>
```

模块会把该移除识别为 GM 手动解除，并写入惩罚状态，避免“刚清就补挂”。

## 附：白名单辅助脚本

在 `apps/` 下提供了生成/辅助维护白名单的脚本（按需使用）：
- `apps/acg_generate_whitelists.py`
- `apps/acg_generate_whitelists.ps1`