Kerrigan Survival 2 - Clara AI 系统文档

1. 概述

Clara 是凯瑞甘生存2（Kerrigan Survival 2）中的虫族防守方 AI 系统。当游戏中缺少真人凯瑞甘玩家时，Clara 会自动接管（takeover）防守方的全部操作，包括经济、建筑、升级、兵种生产、英雄微操和战术决策。

• 代码位置：地图 MPQ Scripts\ai\clara\ 目录（60+ 个 Galaxy 脚本文件）
• UI 布局：Base.SC2Data\UI\Layout\KS2ClaraUI.SC2Layout
• 最大版本：gv_claraMaxVersion = 4

2. 版本/难度系统

Clara 根据对手的 MMR 自动选择版本（难度等级）：

版本选择逻辑（gf_ClaraAutosetVersion）：

1. 获取队友生存者的理想凯瑞甘 MMR
2. 从最高版本向下遍历，找到第一个 MMR 匹配的版本
3. 如果没有匹配，从低到高找第一个上界覆盖的版本
4. 兜底：使用版本4或随机版本

3. 版本功能差异

gf_ClaraApplyVersionSettings 定义了各版本的功能设置：

更新说明（2026-08 地图版本）：进攻/探索从旧的布尔开关（gv_claraOffenseIS_ENABLED / gv_claraExploreIS_ENABLED）改为 0.0–1.0 的活跃度浮点（gv_claraOffenseActivity / gv_claraExploreActivity），表示每个周期/每个候选单位实际执行的比例。实现为概率闸门：进攻点评估用 if (RandomFixed(0.0, 1.0) >= gv_claraOffenseActivity) continue; 跳过，探索派单用 RandomFixed(0.0, 1.0) < gv_claraExploreActivity 逐单位筛选。所有 == true 判断改为 > 0.0。

关键差异总结：

• Clara1：纯防守型，完全不进攻不探索
• Clara2：新增轻度进攻/探索（约 15% / 10% 的机会执行），反应较慢——此前为纯防守
• Clara3：中度进攻/探索（45% / 35%），反应快
• Clara4：进攻/探索全开（100%），全功能，零延迟反应，最具攻击性

难度曲线相比旧版更平滑：原本 Clara2 与 Clara3 之间有「完全不进攻 → 全力进攻」的断崖，现在被 0.15/0.45 的渐进活跃度填平。

4. 模块架构

4.1 核心模块 (Scripts\ai\clara\src\)

4.2 工具模块

• util/base.galaxy — 通用工具函数（1985行），包含单位查询、建筑管理、寻路等
• util/pathing/base.galaxy — 寻路工具

4.3 测试模块

• test/ — 单元测试框架，支持 pass-through 模式

5. 任务优先级系统

Clara 使用统一的任务优先级系统来调度所有单位命令。高优先级命令会覆盖低优先级命令：

优先级值  任务类型
───────────────────────────────
  1       IDLE（空闲）
  9       EXPLORE_RELOCATE（探索重定位）
 10       EXPLORE（探索）= EFFECTIVELY_IDLE
 20       LAY_CREEP（铺菌毯）
 25       MOVE（移动）
 40-49    GATHER1-3（集结）
 50       ATTACK（攻击）
 60       ATTACK_REGROUP（攻击重组）
 70       PATROL（巡逻）
 71       SPAWN_UNITS（生产单位）
 72       DEFEND（防守，须高于生产单位）
 76       DRONE_BUILD（工蜂建造）
 77       STRUCTURE_OPERATION（建筑操作）
 80       RETREAT（撤退）
154       SNIPE_MOVE（狙杀移动）
155       SNIPE（狙杀）
160       HALTRESET（停止重置）
170       SPELL（技能释放）
175       SKILL_POINT（技能点）
190       UNSTUCK（反卡死）
200       MANUAL（手动）= HIGHEST

更新说明（2026-08 地图版本）：DEFEND 优先级从 30 提升到 72（源码注释：musst be higher than spawn units）。这是一处显著的行为变化——防守命令现在高于 SPAWN_UNITS(71)，即遭遇进攻时 Clara 会打断兵种生产去优先防守，而旧版防守优先级(30)低于生产、移动之上而已。

6. Maphack 机制详细分析

6.1 核心作弊函数

gf_ClaraUtilgetEnemyInRange（所有版本）

unitgroup gf_ClaraUtilgetEnemyInRange (int lp_range, point lp_point) {
    return UnitGroupAlliance(gf_ClaragetPlayer(), c_unitAllianceEnemy,
        RegionCircle(lp_point, lp_range),
        UnitFilter(0, 0, (1 << c_targetFilterMissile),
            (1 << (c_targetFilterDead - 32)) | (1 << (c_targetFilterHidden - 32))
            | (1 << (c_targetFilterInvulnerable - 32))), 0);
}

关键点：SC2 的 UnitGroupAlliance 函数不受战争迷雾限制，能获取指定区域内所有敌方单位，无论 Clara 是否有视野。这是 Clara 最基础的信息优势来源。

更新说明（2026-08 地图版本）：过滤器新增排除 c_targetFilterInvulnerable（无敌单位）。此前 Clara 会把无敌单位（如处于无敌状态的技能载体、无敌建筑）计入敌方战力与狙杀/进攻评估，现在会将其忽略——避免因无敌目标误判防御强度而做出错误的进攻/撤退决策。这是对核心作弊函数的一处校正，影响所有调用它的防守/进攻/破基地评估。

gf_ClaraHeuristicsEnemyEffectCombatStrengthCHEATING

int gf_ClaraHeuristicsEnemyEffectCombatStrengthCHEATING (point lp_point) {
    return RoundI(gf_ClaraHeuristicsEnemyEffectiveCombatStrength(
        UnitGroupAlliance(gf_ClaragetPlayer(), c_unitAllianceEnemy,
            RegionCircle(lp_point, 15.0), ...)));
}

• 评估某点 15 范围内的敌方总战斗力，穿透迷雾
• 开发者在函数名中明确标注了 CHEATING
• 用于探索决策：如果迷雾中有强敌就不派单位去探索

gf_ClaraSubroutinesIssueTraceAttackToUnitsCHEAT

• 进攻时对迷雾中的敌方单位下达精确追踪攻击指令
• 沿路径逐点下达攻击命令，考虑地形高度差
• 开发者同样在函数名中标注了 CHEAT

6.2 对塔防建筑的具体影响

进攻点发现（Clara3/4）

// gf_ClaraOffenseFindStructures
UnitGroup(null, c_playerAny, RegionEntireMap(),
    gv_claraMemoryStructuresUNIT_FILTERS, gv_claraOffenseNumPoints);

• 搜索全图所有单位（c_playerAny + RegionEntireMap()）
• 过滤器保留：敌方地面非英雄建筑/单位
• 首次发现需要真实视野（第98行有 IsVisibleToPlayer 检查）
• 但一旦注册进攻点，后续评估全部穿透迷雾

进攻评估穿透迷雾

unitgroup gf_ClaraOffenseEnemyUnits (int lp_whichPoint) {
    return gf_ClaraUtilgetEnemyInRange(12, gf_ClaraOffensePoint(lp_whichPoint));
}

一旦某个位置被注册为进攻点，Clara 能实时感知该区域的防御变化：

• 新建建筑 → Clara 感知防御增强，可能推迟进攻
• 拆除建筑 → Clara 感知防御减弱，可能发动进攻
• 升级建筑 → Clara 通过战斗力评估感知变化

防守评估

// gf_ClaraDefendCommandPoint
lv_enemyUnitGroup = gf_ClaraUtilgetEnemyInRange(10, attackingPoint);

• 防守时同样穿透迷雾评估来犯之敌
• Clara4 的 0 秒反应时间 + 穿透迷雾 = 瞬间精确评估敌方火力

破基地评估（BaseBreak）

lv_enemyUnitGroup = gf_ClaraUtilgetEnemyInRange(40, gv_claraBaseBreakPosition);
if (UnitGroupCount(lv_enemyUnitGroup, c_unitCountAlive) <= 4) {
    // 判定已清除，撤退
}

• 40 范围穿透迷雾搜索评估基地防御
• 精确知道基地内有多少防御建筑
• 防御 ≤ 4 单位时自动判定"已清除"

6.3 记忆系统（相对公平）

// gf_ClaraMemoryRecord
if (libNtve_gf_UnitIsVisibleToPlayer(unit, gf_ClaragetPlayer()) == true) {
    UnitGroupAdd(gv_claraMemory, unit);
    gf_ClaraMemoryWriteLocation(unit);
}

• 只记录曾经可见的敌方单位位置
• 有明确的可见性检查
• 使用 DataTable 存储单位最后已知位置
• 类似真人玩家记住敌人上次出现的位置

6.4 各版本作弊利用程度

6.5 实际游戏影响

7. 关键数据结构

struct gs_Clara {
    int lv_player;          // 控制的玩家 ID
    int lv_version;         // 当前版本
    int lv_currentActions;  // 当前动作计数（APM 统计）
    int lv_lastMinuteStarted; // 上一分钟开始时间
};

struct gs_ClaraVersionInfo {
    int lv_version;
    string lv_desiredBounds;      // 显示用字符串如 "1500 - 2000"
    int lv_desiredUpperBound;     // MMR 上界
    int lv_desiredLowerBound;     // MMR 下界
    fixed lv_extra_autocreep_rate; // 额外自动铺菌毯率
};

struct gs_ClaraHeroDecideBestOffensiveAnalysis {
    point lv_point;         // 最佳进攻点
    int lv_attack_type;     // SNIPE(0) 或 BREAK(1) 或 NONE(2)
    fixed lv_snipe_value;   // 狙杀价值
    fixed lv_break_value;   // 破基地价值
    fixed lv_best_value;    // 最佳价值
};

struct gs_ClaraOffenseAttackPosition {
    point lv_point;         // 进攻点位置
    int lv_textTag;         // 调试文本标签
    fixed lv_time;          // 注册时间
};

struct gs_ClaraVisionQueueRecord {
    point lv_vision_coord;  // 视野坐标
    int lv_unseen_time;     // 未被观察时间
};

// 以下为 2026-08 地图版本新增

struct gs_ClaraHeroSnipeOffenseValue {
    fixed lv_value;         // 狙杀价值
    point lv_point;         // 最佳狙杀点
};
// gf_ClaraHeroDecideSnipeOffenseValue 从「返回 fixed」改为「填充此结构体」，
// 让狙杀价值与最佳狙杀点一次算出，避免上层再重复调用 gf_ClaraSnipeBestPoint（重复穿透迷雾查询）。

struct gs_ClaraUpgradeNextResearchCost {
    int lv_mineral;         // 下一项研究的矿物成本
    int lv_gas;             // 下一项研究的气体成本
    int lv_buildingTier;    // 所需建筑等级：0=无, 1=Lair, 2=Hive
};
// 由 gf_ClaraUpgradeNextResearchCostBoth(structref) 一次性填充，替代旧的
// gf_ClaraUpgradeNextResearchCostMineral() / ...CostGas() 两个分离函数。

8. 关键全局变量

// 核心状态
bool gv_clara_running;           // 是否正在运行
bool gv_clara_isInitialized;     // 是否已初始化
int gv_claraplayer;              // 控制的玩家
fixed gv_clara_start_time;       // 接管开始时间
int gv_claraPlayingVersion;      // 当前版本

// MMR 数据
int[1001] gv_clara_MMR;          // 各版本对应的 MMR 值

// 功能开关 / 活跃度
fixed gv_claraOffenseActivity;   // 进攻活跃度 0.0-1.0（原 bool gv_claraOffenseIS_ENABLED）
fixed gv_claraExploreActivity;   // 探索活跃度 0.0-1.0（原 bool gv_claraExploreIS_ENABLED）
bool gv_claraRetreatIS_ENABLED;
bool gv_claraRepositionENABLED;
bool gv_claraHeroOffenseIS_ENABLED;
bool gv_claraMemoryStructuresEarlyLingEnabled;
bool gv_claraUpgradeAllResearched;    // 升级全部完成的缓存标志（2026-08 新增）

// 参数
fixed gv_claraDefendReactionTime;     // 防守反应时间
fixed gv_claraMaxUpgradeDelayMinutes; // 升级延迟

// UI
bool gv_clarauseText;            // 是否显示文本
bool gv_claramoveCamera;         // 是否移动摄像机
fixed gv_claraAPMAverage;        // 平均 APM

9. 探索系统详解

Clara 维护一个 128×128 的可见性地图（gv_claraVisibilityMap），每个格子代表 2×2 游戏单位的区域：

• 更新频率：每 0.5 秒（gf_ClaraExploreInfoThread）
• 可见性值：0 = 当前可见，每次更新 +1（越大表示越久没看到）
• 地形感知：维护高度图（gv_claraHeightMap），同高度的相邻格子共享视野
• 寻路感知：维护可通行地图（gv_claraPathableMap）

探索决策：

• 局部探索（gf_ClaraExploreLocal）：空闲单位探索附近 5 格范围内最久未见的区域
• 全局探索（gf_ClaraExploreGlobal）：非小狗单位前往全图最久未见的点
• CHEATING 避险：如果目标点的 EnemyEffectCombatStrengthCHEATING > 50，大概率不去

10. 战斗力评估系统

单位战斗力计算（gf_ClaraHeuristicsCombatStrengthOfUnit）

乘数因子（gf_ClaraHeuristicsMultiplierStrength）

某些单位会增加整体乘数：

• Technician（无加速时）：+1.0
• Scientist Magellan：+0.5
• Selendis Core：+0.5

11. 英雄决策系统

Clara 的英雄有两种进攻模式：

SNIPE（狙杀）

• 目标：高价值但防御薄弱的区域
• 计算：snipe_value - (travel_time + return_time) × cost_of_time
• 适用：远程英雄快速击杀经济单位后撤退

BREAK（破基地）

• 目标：防御密集但价值高的区域
• 计算：(defense_value × discount + combat_value) × push_discount - travel_cost
• 适用：集结大军正面推进

防守 vs 进攻决策

• gf_ClaraHeroDecideDefendOverOffense：当防守压力大于最佳进攻价值时选择防守
• gf_ClaraHeroDecideHunterNeedsHelp：判断队友猎人是否需要帮助

12. UI 系统

Clara 有专属的游戏内 UI（KS2ClaraUI）：

• APM 显示（左上）：显示 "Clara APM: XXX"
• 状态面板（左下）：显示当前命令状态
• 按钮：BaseBreak 按钮（后期解锁）、Outpost 按钮
• 游戏内名称：显示为 "Clara" + 版本号（如 "Clara4"）
• Boss Bar：覆盖显示 Clara 名称

13. 聊天命令

14. 关键常量

const int gv_claraMaxVersion = 4;
const int gv_claraMacroNUM_UPGS = 15;              // 升级数量
const int gv_claraOffenseNumPoints = 20;            // 最大进攻点数
const fixed gv_claraBaseBreakBundleTime = 30.0;     // 破基地集结时间(秒)
const int gv_claraDefendPrePositionDistanceOriginal = 20; // 防守预部署距离
const fixed gv_claraDefendCloseAttackMentionTime = 16.0;  // 近距离攻击提示时间
const fixed gv_claraRepositionUnitsGlobalRepositionTime = 30.0; // 重新站位间隔
const int gv_claraLingSupplyminNumberLings = 30;    // 最小小狗数量
const fixed gv_claraLingSupplyCheckingTime = 30.0;  // 小狗检查间隔
const int gv_claraExploreVISIBILITY_POINTS = 128;  // 可见性地图分辨率
const int gv_claraVisionQueueSIZE = 5;              // 视野队列大小
const fixed gv_claraAntiStuckCheckingTime = 7.0;    // 反卡死检测间隔
const fixed gv_claraSelectionDurationTakeover = 0.75; // 接管选择持续时间
const int gv_claraTextMINIMUM_PING_FREQ = 30;       // 最小 ping 频率
const fixed gv_claraUtilPathCostUNPATHABLE = 99999.0; // 不可通行路径代价

15. 初始化流程

gf_ClaraInitAnnotated(player, and_run, annotation) 的执行顺序：

1. 验证没有其他 Clara 实例在运行
2. gf_ClaraSetupTakeOverFor(player) — 接管指定玩家
3. gf_ClaraOrderHistoryInit() — 初始化命令历史
4. gf_ClaraActivateTriggers() — 激活所有触发器
5. gf_ClaraDisableAutoEconomy() — 禁用自动经济
6. gf_ClaraExploreInit() — 初始化探索系统（构建地形/可通行地图）
7. gf_ClaraTaskInit() — 初始化任务系统
8. gf_ClaraMacroUpgradeInit() — 初始化升级系统
9. gf_ClaraHeroSetCommand(SpreadCreep) — 默认命令：铺菌毯
10. gf_AiZergClaraSetAlliance(...) — 设置联盟关系
11. gf_ClaraInitTime() — 初始化时间基准
12. gf_ClaraCreepTriggerInit() — 初始化菌毯触发器
13. 如果启用文本：写入 UI 名称并运行文本系统
14. 如果 and_run：启动主循环

16. 周期性方法

gf_ClaraPeriodicMethods() 每个循环执行：

1. gf_ClaraBaseBreakInformPingChange() — 破基地 ping 更新
2. gf_ClaraHandleStuck() — 处理卡住的单位
3. gf_ClaraSporesTimeRun() — 孢子塔时间管理
4. gf_ClaraUtilLearn() — 学习/适应
5. gf_ClaraUtilParasite(hero) — 寄生技能使用
6. gf_ClaraDefendCheckSneak() — 检测偷袭
7. gf_ClaraArmyWave() — 兵波管理（如果可用）
8. gf_ClaraRepositionUnitsRun() — 重新站位
9. gf_ClaraLingSupplyRun() — 小狗补给
10. gf_ClaraDynamicPositionDistanceRun() — 动态站位距离
11. gf_ClaraAntiStuckRun() — 反卡死
12. gf_ClaraDefendManageAttackingPoints() — 管理攻击点
13. 随机自动铺菌毯（概率 = extra_autocreep_rate）
14. gf_ClaraOffenseRun() — 进攻系统（如果启用）

17. Replay Stats

Clara 会在录像中记录统计数据：

• ReplayStatsClaraTakeoverTime — 接管时间点
• ReplayStatsClaraVersion — 使用的版本

18. 2026-08 地图版本变更汇总

本次地图更新对 Clara 的改动集中在难度平滑、升级系统解耦、以及若干正确性/性能修复，共涉及 14 个脚本文件。核心行为变化如下：

18.1 进攻/探索：布尔开关 → 活跃度浮点（行为变化）

见第 3 节。旧 gv_claraOffenseIS_ENABLED / gv_claraExploreIS_ENABLED（bool）→ gv_claraOffenseActivity / gv_claraExploreActivity（fixed 0.0–1.0），作为概率闸门逐单位/逐进攻点筛选。最显著影响：Clara2 从纯防守变为轻度进攻+探索，Clara3 从全开变为中度，难度曲线更平滑。

18.2 DEFEND 优先级 30 → 72（行为变化）

见第 5 节。防守现在高于 SPAWN_UNITS(71)，遭遇进攻会打断兵种生产优先防守。

18.3 升级系统重构（upgrade/base.galaxy 208 行改动）

• 成本改为从 catalog 实时读取：新增 gf_ClaraUtilResearchCost(abilityId, researchIndex, resourceIndex)，通过 CatalogFieldValueGetAsInt(c_gameCatalogAbil, "SwarmResearch", "InfoArray[i].Resource[j]", ...) 读取真实矿/气成本，不再硬编码。地图平衡改动不会再让 Clara 的升级判断悄悄漂移。
• 建筑等级按真实 CRequirement 判定：lv_buildingTier（0=无 / 1=Lair / 2=Hive）由 gf_ClaraUpgradeNextResearchBuildingTier() 给出，镜像 Swarm.xml 里每个升级的 CRequirement，替代旧的「按气矿成本猜建筑等级」（旧逻辑有误：如 ZergMeleeAttacksLevel3 花 1000 气却不需要任何建筑）。
• 新增 gv_claraUpgradeAllResearched 缓存标志：全部研究完成后 gf_ClaraUpgradeisDone() 锁定为 true，之后整个升级扫描块被跳过（省性能）。
• 气矿预留：gf_ClaraEcoSpendGas(hatch, reserveGas) 新增 reserveGas 参数，经济系统消耗气矿时会为下一项研究预留，避免升级卡气。
• 新增**雷兽穴（SwarmUltraliskCavern）**升级路径（自动建 Hive 前置 + 研究）。

18.4 maphack 校正：排除无敌单位（行为变化）

见第 6.1 节。gf_ClaraUtilgetEnemyInRange 过滤器新增 c_targetFilterInvulnerable，不再把无敌单位计入穿透迷雾的敌方战力评估，影响所有防守/进攻/破基地判断。

18.5 正确性/性能修复（无行为变化）

• 英雄狙杀/破基地决策：gf_ClaraHeroDecideSnipeOffenseValue / ...BreakOffenseValue 改为接收共享的 enemy_units 参数并（snipe）填充 gs_ClaraHeroSnipeOffenseValue 结构体，消除同一进攻点被重复穿透迷雾查询多次的开销。
• 菌毯放置：删除手写网格搜索 gf_ClaraSpreadCreepPlaceLocation，改用引擎 UnitOrderIsValid 对候选点做权威的占地/地形/碰撞合法性校验（gf_ClaraGetBestCreepSpot 直接返回可建点）。
• 盟友判定：多处 UnitGetOwner(...) != player + PlayerGetAlliance(...) 的组合判断改为 PlayerGroupHasPlayer(gf_TeamActiveKerrigan(), ...) / gf_TeamsKerriganDefenderHero()，更直接。
• 探索派单的 RandomInt(0,2)==1（旧的 1/3 概率）改为 RandomFixed(0,1) < (1/3) * gv_claraExploreActivity，把探索频率也纳入活跃度调制。

提取自 map 凯瑞甘生存2 最新版.SC2Map（2026-08-28 缓存，25,746,790 bytes），对比基线为 8-18 提取快照（ks2_extracted_latest）。新提取的 clara 源码在 D:\starcraft2\ks2_clara_20260828\。