掌握python-sc2核心BotAI类：on_step游戏循环与游戏内全量数据完全解析

掌握python-sc2核心BotAI类on_step游戏循环与游戏内全量数据完全解析【免费下载链接】python-sc2A StarCraft II bot api client library for Python 3项目地址: https://gitcode.com/gh_mirrors/pyt/python-sc2python-sc2 是面向 Python 3 的星际争霸 IIStarCraft II机器人开发库其核心是 BotAI 基类。本文面向新手完整解析 on_step 游戏循环的调用时序以及 BotAI 在游戏内提供的单位、资源、供给、地图等全量数据接口帮助你快速上手写出第一个星际 II 机器人 python-sc2 是什么Python 写星际 II 机器人的利器python-sc2 的目标是“简单”一个最简单的工人rush机器人只需不到 20 行代码。你只需做两件事定义一个继承自BotAI的类并实现on_step方法用run_game启动一局游戏。安装方式为pip install --upgrade burnysc2需要 Python 3.9 和星际争霸 II 客户端。核心库代码集中在sc2/目录下其中与本文相关的关键文件是sc2/bot_ai.py—— BotAI 基类所有机器人逻辑的起点sc2/bot_ai_internal.py—— 内部类 BotAIInternal负责数据准备与单位分类sc2/main.py—— 游戏主循环驱动 BotAI 运行on_step 游戏循环一个完整帧的执行时序在sc2/main.py中每一帧frame的实际执行顺序如下理解它你就理解了整个框架 观察通过client.observation()获取最新的游戏状态准备_prepare_step()更新self.state刷新矿物、瓦斯、供给值并把本帧所有单位重新分类到self.units、self.workers等属性中见sc2/bot_ai_internal.py触发事件issue_events()自动对比上一帧数据触发on_unit_created、on_unit_destroyed等回调你的逻辑调用你实现的on_step(iteration)iteration是第几帧的序号从 0 开始递增提交动作_after_step()把self.actions列表中的命令一次性提交给游戏客户端并清空列表推进非实时模式下调用client.step()让游戏前进一帧。⚡ 关键认知在on_step里你读到的数据是“上一帧提交动作后”的快照你发出的命令要等本帧结束才真正生效。这也是为什么 BotAI 内置了self.do()统一收集动作的机制。四个生命周期回调一览回调方法触发时机典型用途on_before_start()开局前、首帧数据未就绪时实时模式realtimeTrue下抢首帧造工兵on_start()第一帧game_data/game_info/state 均已可用初始化变量、设置self.client.game_stepon_step(iteration)每一帧都会调用核心决策逻辑必须实现on_end(result)游戏结束时输出统计、结算数据时间相关的三个实用属性定义于sc2/bot_ai.pyself.time—— 当前游戏秒数按 22.4 帧/秒换算self.time_formatted—— “分:秒”格式字符串方便日志输出self.step_time—— 返回 on_step 耗时四元组最小/平均/最大/上一次毫秒数排查性能问题必用。on_step 中可用的游戏内全量数据进入on_step后几乎一切游戏信息都挂在self上。下面按类别整理这是本文的精华部分 1. 我方单位数据属性含义self.units我方所有非建筑单位self.workers工兵SCV / 探机 / 农民self.larva虫族的卵用于变形出单位self.structures我方所有建筑self.townhalls主基地CC / 枢纽 / 孵化场等含进化形态self.gas_buildings已完成且已开采的瓦斯建筑self.all_own_units单位 建筑的全集所有属性都是Units集合支持self.units(UnitTypeId.MARINE)按类型筛选、.ready/.idle状态过滤、.closest_to(pos)等便捷方法。2. 资源与供给数据每帧由_prepare_step自动刷新属性含义self.minerals/self.vespene当前矿物 / 瓦斯self.supply_cap/self.supply_used/self.supply_left供给上限 / 已用 / 剩余self.supply_army/self.supply_workers军队供给 / 工兵供给self.idle_worker_count/self.army_count空闲工兵数 / 军队数self.warp_gate_count星灵传送门数量实时刷新避免遍历提示通过self.do()发出建造/训练命令时可以传入subtract_costTrue让上述资源数值“即时扣减”同一帧内连续决策时避免重复花钱 3. 敌方与侦察数据属性含义self.enemy_units/self.enemy_structures视野内的敌方单位 / 建筑self.all_enemy_units视野内敌方全部单位self.enemy_race敌方种族随机种族时会自动从首见单位推断self.blips哨兵塔探测到的信号点信息有限但可提前预警self.enemy_start_locations敌方可能的出生点列表4. 地图数据self.game_info地图信息开局不变加载在GameInfo对象中sc2/game_info.pyself.game_info.map_ramps—— 所有斜坡self.main_base_ramp直接给出主基地最近坡道含barracks_correct_placement等摆位辅助self.game_info.terrain_height/pathing_grid/placement_grid—— 地形高度、寻路、建筑摆放像素网格self.game_info.playable_area/map_center—— 地图边界与中心。BotAI 在此之上封装了高频方法self.expansion_locations_list所有矿点位置、await self.get_next_expansion()下一个可扩矿点、self.get_terrain_height(pos)、self.is_visible(pos)、self.has_creep(pos)。5. 瞬时状态self.stateGameStatesc2/game_state.py保存本帧原始信息self.state.alerts—— 本帧事件告警配合self.alert(Alert.BuildingUnderAttack)使用比轮询高效self.state.upgrades—— 已完成科技self.state.creep/visibility—— 虫群蠕虫与视野网格。最常用辅助方法速查表这些方法都在sc2/bot_ai.py中覆盖了 80% 的常见需求方法作用can_afford(item)资源供给是否足够建造/训练can_feed(unit)供给是否足够calculate_cost(item)/calculate_supply_cost(unit)计算实际花费含虫族变形差价already_pending(unit)该单位/建筑“在产”数量含队列与在途structure_type_build_progress(unit)建筑建造进度 0~1tech_requirement_progress(unit)前置科技完成进度await build(building, near)自动找位建造train(unit, amount)智能批量训练自动利用反应堆research(upgrade)自动找建筑科研await expand_now()一键扩矿await distribute_workers()自动分配工兵await can_cast(unit, ability)技能是否可释放能量/冷却/射程新手实战20 行写出第一个机器人以下是经典的工人rush机器人完整示例见examples/worker_rush.pyfrom sc2 import maps from sc2.bot_ai import BotAI from sc2.data import Difficulty, Race from sc2.main import run_game from sc2.player import Bot, Computer class WorkerRushBot(BotAI): async def on_step(self, iteration: int): if iteration 0: for worker in self.workers: worker.attack(self.enemy_start_locations[0]) run_game( maps.get(Abyssal Reef LE), [Bot(Race.Zerg, WorkerRushBot()), Computer(Race.Protoss, Difficulty.Medium)], realtimeFalse, )直接运行python examples/worker_rush.py即可开战。更多策略参考examples/下的protoss/cannon_rush.py、terran/proxy_rax.py、zerg/zerg_rush.py等现成实现 性能调优让 on_step 更快更稳降频执行在on_start中设置self.client.game_step 2每 2 帧才回调一次 on_step大幅降低 CPU 压力注意不要在__init__里设置此时客户端尚未初始化距离计算加速self.distance_calculation_method 2使用 scipy cdist 批量计算所有单位间距离并自动缓存减少选单位开销在__init__中设置self.raw_affects_selection True用事件代替轮询通过on_building_construction_complete、on_upgrade_complete等回调响应变化而不是每帧检查善用帧内缓存expansion_locations_dict等属性已加property_cache_once_per_frame装饰器同一帧内重复访问不会重复计算盯住耗时用self.step_time监控每帧耗时实时模式下超时会直接跳帧。小结BotAI 是 python-sc2 的核心继承它、实现on_step你就拥有了一个机器人骨架每一帧的固定时序是“观察 → 数据刷新 → 事件触发 → on_step → 动作提交 → 推进”理解它能避免大量新手困惑self.units系列、资源供给、game_info地图数据、state瞬时状态四大数据板块覆盖了游戏内全量信息配合can_afford、already_pending、build/train/research等辅助方法复杂策略也能用很少的代码实现。掌握以上内容后打开examples/中的示例逐个阅读你就能从“能跑”走向“能赢”了 ✨【免费下载链接】python-sc2A StarCraft II bot api client library for Python 3项目地址: https://gitcode.com/gh_mirrors/pyt/python-sc2创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考