sc2nachos.gamedata
The game's data tables: unit types, abilities, upgrades and effects.
1"""The game's data tables: unit types, abilities, upgrades and effects.""" 2 3from sc2nachos.gamedata._ability_data import AbilityData, OrderBehavior, TargetType 4from sc2nachos.gamedata._cost import Cost 5from sc2nachos.gamedata._creep_requirement import CreepRequirement 6from sc2nachos.gamedata._effect_data import EffectData 7from sc2nachos.gamedata._game_data import GameData 8from sc2nachos.gamedata._resources import Resources 9from sc2nachos.gamedata._tech import Tech 10from sc2nachos.gamedata._tech_requirements import TechRequirements 11from sc2nachos.gamedata._unit_type_data import Attribute, TargetDomain, UnitTypeData, Weapon 12from sc2nachos.gamedata._unit_type_upgrade import UnitTypeUpgrade, WeaponUpgrade 13from sc2nachos.gamedata._upgrade_data import UpgradeData, UpgradeType 14 15__all__ = [ 16 "AbilityData", 17 "Attribute", 18 "Cost", 19 "CreepRequirement", 20 "EffectData", 21 "GameData", 22 "OrderBehavior", 23 "Resources", 24 "Tech", 25 "TechRequirements", 26 "TargetDomain", 27 "TargetType", 28 "UnitTypeData", 29 "UnitTypeUpgrade", 30 "UpgradeData", 31 "UpgradeType", 32 "Weapon", 33 "WeaponUpgrade", 34]
210@final 211@dataclass(frozen=True, slots=True) 212class AbilityData: 213 """One ability: what the game's table says about it, and what ordering it takes.""" 214 215 id: AbilityId 216 """The ability described.""" 217 target_type: TargetType 218 """What an order of it must be aimed at.""" 219 cast_range: float 220 """Its range, or zero if it has none of its own.""" 221 footprint_radius: float | None 222 """The radius around the ordered point that must be clear, or `None` if nothing is placed: half a structure's 223 width, and for an add-on the reach past the far side of the structure it attaches to.""" 224 needs_placement: bool 225 """Whether ordering it places a structure.""" 226 allows_autocast: bool 227 """Whether it can be set to autocast, for some type that carries it out. An unburrow can for a roach and not for a 228 drone (in game), and the switch takes effect only under each type's own game id, not `UNBURROW`'s.""" 229 performers: frozenset[UnitTypeId] 230 """The unit types offered it. An action several types perform is offered to each under its one id, though the 231 game offers each type its own. The off half of a toggle, offered only once its on half has taken, has its on half's. 232 Empty for an ability the sweep never saw offered: `GATEWAY_MORPH_WARP_GATE`, which the game orders every gateway to 233 carry out once the research is done, and offers a gateway turned back from a warp gate (in game); `MORPH_ARCHON`, 234 which two templar carry out together; and `CARRIER_BUILD_INTERCEPTORS`.""" 235 products: Mapping[UnitTypeId, UnitTypeId | UpgradeId] = field(hash=False) 236 """The unit type it makes, or the upgrade it researches, by the unit type that carries it out: `LIFT` 237 makes a flying barracks of a barracks and a flying starport of a starport. Empty for an ability that makes 238 nothing.""" 239 cost: Cost 240 """What ordering it charges. For a morph that is the difference from the source type: 150 for an orbital command, 241 not the 550 its row holds as everything spent to reach it. Supply is charged as the product starts, less what the 242 unit used up gives back: 1 for a marine, -1 for a spawning pool, 0 for a baneling. Its time is the build time the 243 tables give what it makes, the source's taken off: 560 steps for an orbital command, none for a siege, and a 244 warp-in's that of its unit's train at a gateway, not how long the warp-in takes. An action several types perform 245 costs the same for each. An ability that makes nothing costs nothing.""" 246 multi_unit: bool 247 """Whether every unit one command names carries it out, so that `api.orders.issue` gives it to several in one 248 command: a move, an attack, a burrow, a lift, a stim, a toggle, a tank's siege or an unload (tool `sweep_orders`). 249 Any other ability one unit of a command carries out, and `issue` gives it to each unit in a command of its own: 250 what costs minerals or vespene, a build, an add-on, a train, a research or a morph (in game); every spell but a 251 toggle; a landing, a load or a liberator's siege; and an ability no one has seen a group carry out. Orders of it 252 given apart may go out as one command too, as `joins_other_orders` says.""" 253 joins_other_orders: bool 254 """Whether orders of it given apart in one turn go out as one command where they are aimed at the same unit, or at 255 the same point as the game keeps it, and queued alike, as one order to all their units would: every ability that is 256 `multi_unit` but an archon's merge, which merges the two templar each of its orders names, and a load-all, which 257 one command naming two command centers was seen to carry out for one of them (tool `sweep_orders`).""" 258 cancelled_by: AbilityId | None 259 """The ability that cancels this one on a structure carrying it out. For a train or a research it is 260 `CANCEL_LAST`, which takes the last item off a barracks, an engineering bay and a command center alike (in 261 game). For a morph, an add-on and arming a nuke it is `CANCEL`, since those answer `CANCEL_LAST` 262 with `ERROR` (tool `sweep_tech_tree`). `None` for everything else, a warp-in and a build among them: a warp gate 263 keeps no queue, and a structure under construction is cancelled on itself with `CANCEL`.""" 264 order_behavior: OrderBehavior 265 """What ordering it does to the unit's orders: the behavior the types carrying it out share, or `REPLACES` 266 where they differ; `order_behavior_for` gives each unit type's.""" 267 sent_as: Mapping[UnitTypeId, SentAs] = field(hash=False) 268 """The game's ability it goes out as for each unit type named, and what that is aimed at; any other type is sent 269 the ability itself. `UNLOAD` goes out to a medivac as its unload at a point aimed at the medivac, and a 270 custom id names every type it can be given to: `SIEGE` a tank's siege mode and an observer's surveillance mode, 271 aimed at nothing. Empty for most abilities.""" 272 _behaviors_by_performer: Mapping[UnitTypeId, OrderBehavior] = field(repr=False, compare=False) 273 274 @property 275 def is_research(self) -> bool: 276 """Whether it researches an upgrade.""" 277 return any(isinstance(product, UpgradeId) for product in self.products.values()) 278 279 @property 280 def places_at_target(self) -> bool: 281 """Whether, aimed at a point or a unit, it puts a structure or a unit there, where only one fits: a build, an 282 add-on, a creep tumor, a landing, a rooting or a warp-in.""" 283 return self.needs_placement or self.id in ABILITIES_PLACING_AT_THE_TARGET 284 285 def order_behavior_for(self, unit_type: UnitTypeId) -> OrderBehavior: 286 """What ordering it does to the orders of a unit of `unit_type`: what that type's own does, as a 287 ghost's hold fire keeps its orders and a burrowed lurker's takes it off its attack, and keeping the orders of 288 the types `KEEPS_ORDERS_BY_TYPE` names for it, such as a barracks given a smart (in game).""" 289 return self._behaviors_by_performer.get(unit_type, self.order_behavior) 290 291 @classmethod 292 def _from_proto( 293 cls, 294 data: data_pb2.AbilityData, 295 tech_tree: TechTree, 296 behaviors: Mapping[AbilityId, OrderBehaviors], 297 costs: Mapping[AbilityId, Cost], 298 cancels: Mapping[AbilityId, AbilityId], 299 ) -> Self: 300 """Read one ability from the game's table, with what `tech_tree`, `behaviors`, `costs` and `cancels` say about 301 it.""" 302 ability = AbilityId(data.ability_id) 303 behavior = behaviors.get(ability, _REPLACES) 304 return cls( 305 id=ability, 306 target_type=TargetType(data.target), 307 cast_range=data.cast_range, 308 footprint_radius=data.footprint_radius if data.HasField("footprint_radius") else None, 309 needs_placement=data.is_building, 310 allows_autocast=data.allow_autocast, 311 performers=_performers_including_sent_as(ability, tech_tree), 312 products=tech_tree.ability(ability).products, 313 cost=costs.get(ability, _FREE), 314 multi_unit=ability in MULTI_UNIT_ABILITIES, 315 joins_other_orders=ability in ABILITIES_JOINING_OTHER_ORDERS, 316 cancelled_by=cancels.get(ability), 317 order_behavior=behavior.own, 318 sent_as=ABILITIES_SENT_AS_ANOTHER.get(ability, SENT_UNCHANGED), 319 _behaviors_by_performer=behavior.by_type, 320 ) 321 322 @classmethod 323 def _custom( 324 cls, 325 ability: AbilityId, 326 tech_tree: TechTree, 327 behaviors: Mapping[AbilityId, OrderBehaviors], 328 costs: Mapping[AbilityId, Cost], 329 cancels: Mapping[AbilityId, AbilityId], 330 ) -> Self: 331 """The custom ability `ability`, sent as `ABILITIES_SENT_AS_ANOTHER` names for each type, with what 332 `tech_tree`, `behaviors`, `costs` and `cancels` say about it. It takes no target and has no range.""" 333 sent_as = ABILITIES_SENT_AS_ANOTHER[ability] 334 behavior = behaviors.get(ability, _REPLACES) 335 return cls( 336 id=ability, 337 target_type=TargetType.NOTHING, 338 cast_range=0.0, 339 footprint_radius=None, 340 needs_placement=False, 341 allows_autocast=False, 342 performers=_performers_including_sent_as(ability, tech_tree), 343 products=tech_tree.ability(ability).products, 344 cost=costs.get(ability, _FREE), 345 multi_unit=ability in MULTI_UNIT_ABILITIES, 346 joins_other_orders=ability in ABILITIES_JOINING_OTHER_ORDERS, 347 cancelled_by=cancels.get(ability), 348 order_behavior=behavior.own, 349 sent_as=sent_as, 350 _behaviors_by_performer=behavior.by_type, 351 )
One ability: what the game's table says about it, and what ordering it takes.
The radius around the ordered point that must be clear, or None if nothing is placed: half a structure's
width, and for an add-on the reach past the far side of the structure it attaches to.
Whether it can be set to autocast, for some type that carries it out. An unburrow can for a roach and not for a
drone (in game), and the switch takes effect only under each type's own game id, not UNBURROW's.
The unit types offered it. An action several types perform is offered to each under its one id, though the
game offers each type its own. The off half of a toggle, offered only once its on half has taken, has its on half's.
Empty for an ability the sweep never saw offered: GATEWAY_MORPH_WARP_GATE, which the game orders every gateway to
carry out once the research is done, and offers a gateway turned back from a warp gate (in game); MORPH_ARCHON,
which two templar carry out together; and CARRIER_BUILD_INTERCEPTORS.
The unit type it makes, or the upgrade it researches, by the unit type that carries it out: LIFT
makes a flying barracks of a barracks and a flying starport of a starport. Empty for an ability that makes
nothing.
What ordering it charges. For a morph that is the difference from the source type: 150 for an orbital command, not the 550 its row holds as everything spent to reach it. Supply is charged as the product starts, less what the unit used up gives back: 1 for a marine, -1 for a spawning pool, 0 for a baneling. Its time is the build time the tables give what it makes, the source's taken off: 560 steps for an orbital command, none for a siege, and a warp-in's that of its unit's train at a gateway, not how long the warp-in takes. An action several types perform costs the same for each. An ability that makes nothing costs nothing.
Whether every unit one command names carries it out, so that api.orders.issue gives it to several in one
command: a move, an attack, a burrow, a lift, a stim, a toggle, a tank's siege or an unload (tool sweep_orders).
Any other ability one unit of a command carries out, and issue gives it to each unit in a command of its own:
what costs minerals or vespene, a build, an add-on, a train, a research or a morph (in game); every spell but a
toggle; a landing, a load or a liberator's siege; and an ability no one has seen a group carry out. Orders of it
given apart may go out as one command too, as joins_other_orders says.
Whether orders of it given apart in one turn go out as one command where they are aimed at the same unit, or at
the same point as the game keeps it, and queued alike, as one order to all their units would: every ability that is
multi_unit but an archon's merge, which merges the two templar each of its orders names, and a load-all, which
one command naming two command centers was seen to carry out for one of them (tool sweep_orders).
The ability that cancels this one on a structure carrying it out. For a train or a research it is
CANCEL_LAST, which takes the last item off a barracks, an engineering bay and a command center alike (in
game). For a morph, an add-on and arming a nuke it is CANCEL, since those answer CANCEL_LAST
with ERROR (tool sweep_tech_tree). None for everything else, a warp-in and a build among them: a warp gate
keeps no queue, and a structure under construction is cancelled on itself with CANCEL.
What ordering it does to the unit's orders: the behavior the types carrying it out share, or REPLACES
where they differ; order_behavior_for gives each unit type's.
The game's ability it goes out as for each unit type named, and what that is aimed at; any other type is sent
the ability itself. UNLOAD goes out to a medivac as its unload at a point aimed at the medivac, and a
custom id names every type it can be given to: SIEGE a tank's siege mode and an observer's surveillance mode,
aimed at nothing. Empty for most abilities.
274 @property 275 def is_research(self) -> bool: 276 """Whether it researches an upgrade.""" 277 return any(isinstance(product, UpgradeId) for product in self.products.values())
Whether it researches an upgrade.
279 @property 280 def places_at_target(self) -> bool: 281 """Whether, aimed at a point or a unit, it puts a structure or a unit there, where only one fits: a build, an 282 add-on, a creep tumor, a landing, a rooting or a warp-in.""" 283 return self.needs_placement or self.id in ABILITIES_PLACING_AT_THE_TARGET
Whether, aimed at a point or a unit, it puts a structure or a unit there, where only one fits: a build, an add-on, a creep tumor, a landing, a rooting or a warp-in.
285 def order_behavior_for(self, unit_type: UnitTypeId) -> OrderBehavior: 286 """What ordering it does to the orders of a unit of `unit_type`: what that type's own does, as a 287 ghost's hold fire keeps its orders and a burrowed lurker's takes it off its attack, and keeping the orders of 288 the types `KEEPS_ORDERS_BY_TYPE` names for it, such as a barracks given a smart (in game).""" 289 return self._behaviors_by_performer.get(unit_type, self.order_behavior)
What ordering it does to the orders of a unit of unit_type: what that type's own does, as a
ghost's hold fire keeps its orders and a burrowed lurker's takes it off its attack, and keeping the orders of
the types KEEPS_ORDERS_BY_TYPE names for it, such as a barracks given a smart (in game).
44class Attribute(ReadableIntEnum): 45 """A property of a unit that weapons deal bonus damage against.""" 46 47 LIGHT = data_pb2.Attribute.Light 48 ARMORED = data_pb2.Attribute.Armored 49 BIOLOGICAL = data_pb2.Attribute.Biological 50 MECHANICAL = data_pb2.Attribute.Mechanical 51 ROBOTIC = data_pb2.Attribute.Robotic 52 PSIONIC = data_pb2.Attribute.Psionic 53 MASSIVE = data_pb2.Attribute.Massive 54 STRUCTURE = data_pb2.Attribute.Structure 55 HOVER = data_pb2.Attribute.Hover 56 HEROIC = data_pb2.Attribute.Heroic 57 SUMMONED = data_pb2.Attribute.Summoned
A property of a unit that weapons deal bonus damage against.
13@final 14@dataclass(frozen=True, slots=True) 15class Cost: 16 """The cost of making something: minerals, vespene, supply and the time it takes. 17 18 Not a `Resources`, which is an amount a player holds, earns or spends. Supply is room under the cap, so compare 19 `cost.resources` against `api.resources` and `cost.supply` against `api.supply.left`. Costs added up add their 20 times too, which makes the production time they take one after another, not how long they take side by side. 21 """ 22 23 minerals: float 24 """Minerals.""" 25 vespene: float 26 """Vespene.""" 27 supply: float = 0.0 28 """Supply taken, or given back when negative: -1 for a spawning pool, which uses up a drone.""" 29 time: GameTime = GameTime.ZERO 30 """The time production takes, at the normal rate: a whole number of steps from the tables, fractional once scaled 31 or divided; zero for an order that makes nothing, for a switch that costs nothing, such as a siege, and where the 32 tables give none, as for an interceptor.""" 33 34 @property 35 def resources(self) -> Resources: 36 """The minerals and vespene, to compare against what the player has.""" 37 return Resources(self.minerals, self.vespene) 38 39 @property 40 def is_free(self) -> bool: 41 """Whether it takes no minerals, vespene or supply, whatever its time: a siege, a MULE's calldown.""" 42 return not (self.minerals or self.vespene or self.supply) 43 44 def __add__(self, other: Cost) -> Cost: 45 """The sum of the two costs.""" 46 return Cost( 47 self.minerals + other.minerals, 48 self.vespene + other.vespene, 49 self.supply + other.supply, 50 self.time + other.time, 51 ) 52 53 def __sub__(self, other: Cost) -> Cost: 54 """This cost less `other`.""" 55 return Cost( 56 self.minerals - other.minerals, 57 self.vespene - other.vespene, 58 self.supply - other.supply, 59 self.time - other.time, 60 ) 61 62 def __mul__(self, count: float) -> Cost: 63 """This cost `count` times over.""" 64 return Cost(self.minerals * count, self.vespene * count, self.supply * count, self.time * count) 65 66 def __rmul__(self, count: float) -> Cost: 67 """This cost `count` times over.""" 68 return self * count 69 70 def __truediv__(self, divisor: float) -> Cost: 71 """This cost divided by `divisor`.""" 72 return Cost(self.minerals / divisor, self.vespene / divisor, self.supply / divisor, self.time / divisor) 73 74 def __neg__(self) -> Cost: 75 """This cost negated: given back rather than paid.""" 76 return Cost(-self.minerals, -self.vespene, -self.supply, -self.time)
The cost of making something: minerals, vespene, supply and the time it takes.
Not a Resources, which is an amount a player holds, earns or spends. Supply is room under the cap, so compare
cost.resources against api.resources and cost.supply against api.supply.left. Costs added up add their
times too, which makes the production time they take one after another, not how long they take side by side.
Supply taken, or given back when negative: -1 for a spawning pool, which uses up a drone.
The time production takes, at the normal rate: a whole number of steps from the tables, fractional once scaled or divided; zero for an order that makes nothing, for a switch that costs nothing, such as a siege, and where the tables give none, as for an interceptor.
34 @property 35 def resources(self) -> Resources: 36 """The minerals and vespene, to compare against what the player has.""" 37 return Resources(self.minerals, self.vespene)
The minerals and vespene, to compare against what the player has.
39 @property 40 def is_free(self) -> bool: 41 """Whether it takes no minerals, vespene or supply, whatever its time: a siege, a MULE's calldown.""" 42 return not (self.minerals or self.vespene or self.supply)
Whether it takes no minerals, vespene or supply, whatever its time: a siege, a MULE's calldown.
7class CreepRequirement(ReadableIntEnum): 8 """Whether a structure of a type may stand on creep, as the game answered its placement on creep and off it.""" 9 10 ON_CREEP = 1 11 """Only on creep, under every tile: a zerg structure but a hatchery or a nydus worm, and a creep tumor.""" 12 OFF_CREEP = 2 13 """Only off creep: a terran or protoss structure but a raven's auto turret or an oracle's stasis ward.""" 14 NONE = 3 15 """On creep or off it, as either comes: a hatchery, a nydus worm, a raven's auto turret and an oracle's stasis 16 ward."""
Whether a structure of a type may stand on creep, as the game answered its placement on creep and off it.
Only on creep, under every tile: a zerg structure but a hatchery or a nydus worm, and a creep tumor.
Only off creep: a terran or protoss structure but a raven's auto turret or an oracle's stasis ward.
On creep or off it, as either comes: a hatchery, a nydus worm, a raven's auto turret and an oracle's stasis ward.
15@final 16@dataclass(frozen=True, slots=True) 17class EffectData: 18 """One effect: a patch of ground something is happening on, as the game's table describes it.""" 19 20 id: EffectId 21 """The effect described.""" 22 radius: float 23 """Its radius around its center.""" 24 25 @classmethod 26 def _from_proto(cls, data: data_pb2.EffectData) -> Self: 27 """Read one effect from the game's table.""" 28 return cls( 29 id=EffectId(data.effect_id), 30 radius=data.radius, 31 )
One effect: a patch of ground something is happening on, as the game's table describes it.
39@final 40class GameData: 41 """The game's tables of unit types, abilities, upgrades and effects, as they stand before any upgrade. 42 43 A table holds only the rows the curated ids name, which leaves out most of what the game describes. 44 """ 45 46 __slots__ = ( 47 "_abilities", 48 "_effects", 49 "_placing_abilities", 50 "_types_granting", 51 "_unit_trainers", 52 "_units", 53 "_upgrades", 54 ) 55 56 def __init__(self, data: sc2api_pb2.ResponseData) -> None: 57 """Read the tables from the game's answer to `RequestData`.""" 58 unit_rows = _read_table(data.units, lambda unit: UnitTypeData._from_proto(unit, TECH_TREE), lambda row: row.id) 59 unit_rows = _with_build_times_borrowed(_with_build_times_corrected(unit_rows), TECH_TREE) 60 unit_rows = _with_build_times_in_whole_costs(_with_turning(with_missing_attacks(unit_rows))) 61 step_costs = _step_costs(unit_rows) 62 self._units = _with_costs_from_steps(unit_rows, step_costs) 63 structures = frozenset(row.id for row in self._units.values() if Attribute.STRUCTURE in row.attributes) 64 behaviors = order_behaviors(TECH_TREE, structures, frozenset(self._units.keys() - structures)) 65 self._upgrades = _read_table( 66 data.upgrades, lambda upgrade: UpgradeData._from_proto(upgrade, TECH_TREE), lambda row: row.id 67 ) 68 # An ability's cost is derived from its product, so the other tables come first. 69 costs = ability_costs(step_costs, self._upgrades, TECH_TREE) 70 cancels = cancel_abilities(TECH_TREE, behaviors) 71 rows = _read_table( 72 data.abilities, 73 lambda ability: AbilityData._from_proto(ability, TECH_TREE, behaviors, costs, cancels), 74 lambda row: row.id, 75 ) 76 game_rows = {row.ability_id: row for row in data.abilities} 77 custom = { 78 ability: AbilityData._custom(ability, TECH_TREE, behaviors, costs, cancels) 79 for ability, sent_as in ABILITIES_SENT_AS_ANOTHER.items() 80 if ability.is_custom and all(sending.ability in game_rows for sending in sent_as.values()) 81 } 82 self._abilities = MappingProxyType({**rows, **custom}) 83 self._types_granting = _types_granting_each(self._units) 84 self._effects = _read_table(data.effects, EffectData._from_proto, lambda row: row.id) 85 # Read by `OwnUnit.is_constructing` and `production_capacity`, worked out once a game. 86 self._placing_abilities = frozenset(ability for ability, row in self._abilities.items() if row.needs_placement) 87 self._unit_trainers = frozenset( 88 producer 89 for row in self._units.values() 90 if row.id not in structures 91 for producer in row.producers 92 if producer in structures 93 ) 94 95 @property 96 def units(self) -> Mapping[UnitTypeId, UnitTypeData]: 97 """The unit types, by id.""" 98 return self._units 99 100 @property 101 def abilities(self) -> Mapping[AbilityId, AbilityData]: 102 """The abilities, by id, the custom ones included.""" 103 return self._abilities 104 105 @property 106 def upgrades(self) -> Mapping[UpgradeId, UpgradeData]: 107 """The upgrades, by id.""" 108 return self._upgrades 109 110 @property 111 def effects(self) -> Mapping[EffectId, EffectData]: 112 """The effects, by id.""" 113 return self._effects 114 115 def types_granting(self, tech: Tech) -> frozenset[UnitTypeId]: 116 """Every unit type whose `techs_granted` hold `tech`: a spire and a greater spire for `Tech.SPIRE`, a supply 117 depot and a lowered one for `Tech.SUPPLY_DEPOT`.""" 118 return self._types_granting[tech]
The game's tables of unit types, abilities, upgrades and effects, as they stand before any upgrade.
A table holds only the rows the curated ids name, which leaves out most of what the game describes.
56 def __init__(self, data: sc2api_pb2.ResponseData) -> None: 57 """Read the tables from the game's answer to `RequestData`.""" 58 unit_rows = _read_table(data.units, lambda unit: UnitTypeData._from_proto(unit, TECH_TREE), lambda row: row.id) 59 unit_rows = _with_build_times_borrowed(_with_build_times_corrected(unit_rows), TECH_TREE) 60 unit_rows = _with_build_times_in_whole_costs(_with_turning(with_missing_attacks(unit_rows))) 61 step_costs = _step_costs(unit_rows) 62 self._units = _with_costs_from_steps(unit_rows, step_costs) 63 structures = frozenset(row.id for row in self._units.values() if Attribute.STRUCTURE in row.attributes) 64 behaviors = order_behaviors(TECH_TREE, structures, frozenset(self._units.keys() - structures)) 65 self._upgrades = _read_table( 66 data.upgrades, lambda upgrade: UpgradeData._from_proto(upgrade, TECH_TREE), lambda row: row.id 67 ) 68 # An ability's cost is derived from its product, so the other tables come first. 69 costs = ability_costs(step_costs, self._upgrades, TECH_TREE) 70 cancels = cancel_abilities(TECH_TREE, behaviors) 71 rows = _read_table( 72 data.abilities, 73 lambda ability: AbilityData._from_proto(ability, TECH_TREE, behaviors, costs, cancels), 74 lambda row: row.id, 75 ) 76 game_rows = {row.ability_id: row for row in data.abilities} 77 custom = { 78 ability: AbilityData._custom(ability, TECH_TREE, behaviors, costs, cancels) 79 for ability, sent_as in ABILITIES_SENT_AS_ANOTHER.items() 80 if ability.is_custom and all(sending.ability in game_rows for sending in sent_as.values()) 81 } 82 self._abilities = MappingProxyType({**rows, **custom}) 83 self._types_granting = _types_granting_each(self._units) 84 self._effects = _read_table(data.effects, EffectData._from_proto, lambda row: row.id) 85 # Read by `OwnUnit.is_constructing` and `production_capacity`, worked out once a game. 86 self._placing_abilities = frozenset(ability for ability, row in self._abilities.items() if row.needs_placement) 87 self._unit_trainers = frozenset( 88 producer 89 for row in self._units.values() 90 if row.id not in structures 91 for producer in row.producers 92 if producer in structures 93 )
Read the tables from the game's answer to RequestData.
95 @property 96 def units(self) -> Mapping[UnitTypeId, UnitTypeData]: 97 """The unit types, by id.""" 98 return self._units
The unit types, by id.
100 @property 101 def abilities(self) -> Mapping[AbilityId, AbilityData]: 102 """The abilities, by id, the custom ones included.""" 103 return self._abilities
The abilities, by id, the custom ones included.
105 @property 106 def upgrades(self) -> Mapping[UpgradeId, UpgradeData]: 107 """The upgrades, by id.""" 108 return self._upgrades
The upgrades, by id.
110 @property 111 def effects(self) -> Mapping[EffectId, EffectData]: 112 """The effects, by id.""" 113 return self._effects
The effects, by id.
115 def types_granting(self, tech: Tech) -> frozenset[UnitTypeId]: 116 """Every unit type whose `techs_granted` hold `tech`: a spire and a greater spire for `Tech.SPIRE`, a supply 117 depot and a lowered one for `Tech.SUPPLY_DEPOT`.""" 118 return self._types_granting[tech]
Every unit type whose techs_granted hold tech: a spire and a greater spire for Tech.SPIRE, a supply
depot and a lowered one for Tech.SUPPLY_DEPOT.
45class OrderBehavior(Enum): 46 """What ordering an ability does to the unit's orders (tool `sweep_orders`).""" 47 48 REPLACES = "replaces" 49 """Drops the unit's orders and runs instead: a move, an attack, a worker's build.""" 50 QUEUES = "queues" 51 """Goes behind whatever the structure is making, queued or not: a train or a research.""" 52 NEEDS_IDLE = "needs idle" 53 """A structure accepts it only while making nothing, and otherwise answers `NOT_SUPPORTED`: an add-on, a morph, a 54 lift.""" 55 KEEPS_ORDERS = "keeps orders" 56 """Runs without disturbing the unit's orders, so it competes with nothing: stim, both halves of a toggle and the 57 rest of `KEEPS_ORDERS_ABILITIES`, plus every ability that makes nothing and is offered only to types that hold no 58 order of their own — a structure's own rally, load, cancel and energy casts. Ordered on a producer, each of those 59 leaves what it is making at its current progress (in game). `CANCEL` is not one of them: a ghost and an 60 infestor are offered it too, and it takes them off what they are channeling."""
What ordering an ability does to the unit's orders (tool sweep_orders).
Drops the unit's orders and runs instead: a move, an attack, a worker's build.
Goes behind whatever the structure is making, queued or not: a train or a research.
A structure accepts it only while making nothing, and otherwise answers NOT_SUPPORTED: an add-on, a morph, a
lift.
Runs without disturbing the unit's orders, so it competes with nothing: stim, both halves of a toggle and the
rest of KEEPS_ORDERS_ABILITIES, plus every ability that makes nothing and is offered only to types that hold no
order of their own — a structure's own rally, load, cancel and energy casts. Ordered on a producer, each of those
leaves what it is making at its current progress (in game). CANCEL is not one of them: a ghost and an
infestor are offered it too, and it takes them off what they are channeling.
10@final 11@dataclass(frozen=True, slots=True) 12class Resources: 13 """An amount of minerals and vespene: spent, held, earned or averaged. 14 15 Whole when it comes from the game or from adding such amounts up; fractional once scaled or divided. 16 """ 17 18 minerals: float 19 """Minerals.""" 20 vespene: float 21 """Vespene.""" 22 23 @property 24 def total(self) -> float: 25 """Minerals plus vespene, counted alike.""" 26 return self.minerals + self.vespene 27 28 def __add__(self, other: Resources) -> Resources: 29 """The sum of the two amounts.""" 30 return Resources(self.minerals + other.minerals, self.vespene + other.vespene) 31 32 def __sub__(self, other: Resources) -> Resources: 33 """This amount less `other`; negative where `other` is more.""" 34 return Resources(self.minerals - other.minerals, self.vespene - other.vespene) 35 36 def __neg__(self) -> Resources: 37 """This amount negated: owed rather than held.""" 38 return Resources(-self.minerals, -self.vespene) 39 40 def __mul__(self, factor: float) -> Resources: 41 """This amount `factor` times over.""" 42 return Resources(self.minerals * factor, self.vespene * factor) 43 44 def __rmul__(self, factor: float) -> Resources: 45 """This amount `factor` times over.""" 46 return self * factor 47 48 def __truediv__(self, divisor: float) -> Resources: 49 """This amount divided by `divisor`.""" 50 return Resources(self.minerals / divisor, self.vespene / divisor) 51 52 def covers(self, other: Resources) -> bool: 53 """Whether this amount is at least `other` in both minerals and vespene.""" 54 return self.minerals >= other.minerals and self.vespene >= other.vespene 55 56 def minimum(self, other: Resources) -> Resources: 57 """The smaller of the two amounts of each resource, each on its own: 75/50 of 100/50 and 75/80.""" 58 return Resources(min(self.minerals, other.minerals), min(self.vespene, other.vespene)) 59 60 def maximum(self, other: Resources) -> Resources: 61 """The larger of the two amounts of each resource; `maximum(Resources(0, 0))` drops what is owed.""" 62 return Resources(max(self.minerals, other.minerals), max(self.vespene, other.vespene))
An amount of minerals and vespene: spent, held, earned or averaged.
Whole when it comes from the game or from adding such amounts up; fractional once scaled or divided.
23 @property 24 def total(self) -> float: 25 """Minerals plus vespene, counted alike.""" 26 return self.minerals + self.vespene
Minerals plus vespene, counted alike.
52 def covers(self, other: Resources) -> bool: 53 """Whether this amount is at least `other` in both minerals and vespene.""" 54 return self.minerals >= other.minerals and self.vespene >= other.vespene
Whether this amount is at least other in both minerals and vespene.
56 def minimum(self, other: Resources) -> Resources: 57 """The smaller of the two amounts of each resource, each on its own: 75/50 of 100/50 and 75/80.""" 58 return Resources(min(self.minerals, other.minerals), min(self.vespene, other.vespene))
The smaller of the two amounts of each resource, each on its own: 75/50 of 100/50 and 75/80.
60 def maximum(self, other: Resources) -> Resources: 61 """The larger of the two amounts of each resource; `maximum(Resources(0, 0))` drops what is owed.""" 62 return Resources(max(self.minerals, other.minerals), max(self.vespene, other.vespene))
The larger of the two amounts of each resource; maximum(Resources(0, 0)) drops what is owed.
11class Tech(Enum): 12 """What a tech requirement names, which a player has while a structure of a type granting it stands. A spire and a 13 greater spire both grant `SPIRE`, and `UnitTypeData.techs_granted` says what each type grants. Each is valued by 14 the type it is named after, its `base_type`, but never equals that `UnitTypeId`.""" 15 16 _value_: UnitTypeId 17 18 SUPPLY_DEPOT = UnitTypeId.SUPPLY_DEPOT 19 COMMAND_CENTER = UnitTypeId.COMMAND_CENTER 20 BARRACKS = UnitTypeId.BARRACKS 21 ENGINEERING_BAY = UnitTypeId.ENGINEERING_BAY 22 FACTORY = UnitTypeId.FACTORY 23 GHOST_ACADEMY = UnitTypeId.GHOST_ACADEMY 24 ARMORY = UnitTypeId.ARMORY 25 STARPORT = UnitTypeId.STARPORT 26 FUSION_CORE = UnitTypeId.FUSION_CORE 27 28 HATCHERY = UnitTypeId.HATCHERY 29 SPAWNING_POOL = UnitTypeId.SPAWNING_POOL 30 LAIR = UnitTypeId.LAIR 31 BANELING_NEST = UnitTypeId.BANELING_NEST 32 ROACH_WARREN = UnitTypeId.ROACH_WARREN 33 HYDRALISK_DEN = UnitTypeId.HYDRALISK_DEN 34 LURKER_DEN = UnitTypeId.LURKER_DEN 35 INFESTATION_PIT = UnitTypeId.INFESTATION_PIT 36 SPIRE = UnitTypeId.SPIRE 37 HIVE = UnitTypeId.HIVE 38 GREATER_SPIRE = UnitTypeId.GREATER_SPIRE 39 ULTRALISK_CAVERN = UnitTypeId.ULTRALISK_CAVERN 40 41 NEXUS = UnitTypeId.NEXUS 42 GATEWAY = UnitTypeId.GATEWAY 43 FORGE = UnitTypeId.FORGE 44 CYBERNETICS_CORE = UnitTypeId.CYBERNETICS_CORE 45 TWILIGHT_COUNCIL = UnitTypeId.TWILIGHT_COUNCIL 46 ROBOTICS_FACILITY = UnitTypeId.ROBOTICS_FACILITY 47 STARGATE = UnitTypeId.STARGATE 48 TEMPLAR_ARCHIVE = UnitTypeId.TEMPLAR_ARCHIVE 49 DARK_SHRINE = UnitTypeId.DARK_SHRINE 50 ROBOTICS_BAY = UnitTypeId.ROBOTICS_BAY 51 FLEET_BEACON = UnitTypeId.FLEET_BEACON 52 53 @property 54 def base_type(self) -> UnitTypeId: 55 """The type it is named after, from which every other type granting it is morphed, in one step or more: a spire, 56 for `SPIRE`, from which a greater spire is morphed.""" 57 return self.value
What a tech requirement names, which a player has while a structure of a type granting it stands. A spire and a
greater spire both grant SPIRE, and UnitTypeData.techs_granted says what each type grants. Each is valued by
the type it is named after, its base_type, but never equals that UnitTypeId.
53 @property 54 def base_type(self) -> UnitTypeId: 55 """The type it is named after, from which every other type granting it is morphed, in one step or more: a spire, 56 for `SPIRE`, from which a greater spire is morphed.""" 57 return self.value
The type it is named after, from which every other type granting it is morphed, in one step or more: a spire,
for SPIRE, from which a greater spire is morphed.
14@final 15@dataclass(frozen=True, slots=True) 16class TechRequirements: 17 """The techs, tech lab and upgrades a unit needs before it is offered an ability, beyond the ability's cost.""" 18 19 techs: frozenset[Tech] = frozenset() 20 """Every tech this player must have: a structure of a type granting it must stand, a spire or a greater spire for 21 `Tech.SPIRE`, as `GameData.types_granting` lists them.""" 22 needs_tech_lab: bool = False 23 """Whether the unit itself must have a tech lab: a barracks trains a ghost only with its own. No requirement names 24 a reactor, or another structure's add-on (tool `sweep_tech_tree`).""" 25 upgrades: frozenset[UpgradeId] = frozenset() 26 """Every upgrade that must be researched."""
The techs, tech lab and upgrades a unit needs before it is offered an ability, beyond the ability's cost.
Every tech this player must have: a structure of a type granting it must stand, a spire or a greater spire for
Tech.SPIRE, as GameData.types_granting lists them.
60class TargetDomain(ReadableIntEnum): 61 """Whether a weapon fires at ground, air or both.""" 62 63 GROUND = data_pb2.Weapon.TargetType.Ground 64 AIR = data_pb2.Weapon.TargetType.Air 65 ANY = data_pb2.Weapon.TargetType.Any
Whether a weapon fires at ground, air or both.
34class TargetType(ReadableIntEnum): 35 """What an ability must be aimed at.""" 36 37 # The game names this value `None`, which is not a valid attribute name, so it is read off the descriptor. 38 NOTHING = data_pb2.AbilityData.Target.Value("None") 39 POINT = data_pb2.AbilityData.Target.Point 40 UNIT = data_pb2.AbilityData.Target.Unit 41 POINT_OR_UNIT = data_pb2.AbilityData.Target.PointOrUnit 42 POINT_OR_NOTHING = data_pb2.AbilityData.Target.PointOrNone
What an ability must be aimed at.
181@final 182@dataclass(frozen=True, slots=True) 183class UnitTypeData: 184 """One unit type, before any upgrade unless `with_upgrades` made it.""" 185 186 id: UnitTypeId 187 """The unit type described.""" 188 race: Race 189 """The race it belongs to.""" 190 cost: Cost 191 """What the order that made one cost: the cost of its last step that cost anything, so every form of a unit costs 192 the same. An orbital command is 150, a baneling 25/25, a sieged tank the tank's 150/125 and 3 supply, a warp gate 193 the gateway's 150, and an archon nothing (tool `sweep_orders`). A zergling's is half its order of two, 25 minerals 194 and half a supply; a structure a drone becomes gives the drone's supply back, -1; a cocoon's is that of what it 195 becomes; and a MULE and an auto-turret, which energy pays for, cost nothing (tool `sweep_orders`). Its time is that 196 step's build time. What ordering an ability costs is the ability's `cost`, nothing for a siege.""" 197 total_cost: Cost 198 """What every order that made one cost, step by step back along `morphed_from` to the first: an orbital command 199 550 with its command center, a hatchery 350 with its drone, a lair 500/100, a baneling 50/25 and half a supply with 200 its zergling, and a sieged tank the tank's 150/125. An archon counts two high templar, 100/300 and 4 supply; a 201 cocoon what it becomes; a MULE and an auto-turret nothing. Its time is the build time of each step that costs 202 something, one after another, an archon's merge of 192 steps included.""" 203 build_time: GameTime 204 """The time to make one: the tables' build time rounded up to a whole step, as a train takes it, a void ray's 963.2 205 steps as 964 (in game); for a morph, only the last stage, which a unit's morph keeps to within a step. A lurker 206 takes the 403 steps it took in game, where its row reads 553.33, and an archon the 192 it took from when it was 207 first listed, where its row gives none (`docs/reference/game-behavior/upgrades-and-tables.md`). Any other type the 208 table gives none takes the build time of the one other type its creation ability makes: a rich gas building its 209 plain one's.""" 210 supply_provided: float 211 """What it adds to the supply cap.""" 212 supply_used: float 213 """The supply one takes, as the tables give it: half for a zergling, 3 for a sieged tank, 4 for an archon.""" 214 cargo_size: int 215 """Slots it fills in a transport.""" 216 sight_range: float 217 """Its sight range.""" 218 speed: float 219 """Its movement speed, in distance per second at the game's Faster speed (22.4 steps); zero for a structure.""" 220 armor: float 221 """The damage it takes off each hit.""" 222 attributes: frozenset[Attribute] 223 """Its attributes, which weapons deal bonus damage against.""" 224 weapons: tuple[Weapon, ...] 225 """Its attacks: the tables', or for the battlecruiser, the oracle, the void ray and the sentry, which the tables 226 give none, the attacks `tools/sweep_combat.py` measured. An oracle's fires only while its beam is on.""" 227 creation_ability: AbilityId | None 228 """The ability that makes one, or `None` where the tables tie it to no curated ability: for every type of the map's 229 own; for a larva, an egg, a cocoon, a broodling, a force field, an adept's shade, a KD8 charge, a parasitic bomb 230 left behind, a burrowed creep tumor, a flying locust and a bare tech lab or reactor; and for a MULE, an interceptor, 231 a changeling and an archon, though something makes each.""" 232 producers: frozenset[UnitTypeId] 233 """The unit types that make one: a gateway and a warp gate, for a zealot; a high and a dark templar, for an archon. 234 Empty for a type nothing is recorded making, such as a larva, a MULE or an interceptor.""" 235 tech_requirements: TechRequirements 236 """What a producer needs before it is offered what makes one, each producer's `ability_requirements` for the 237 ability it makes one by: `Tech.BARRACKS` for a factory, `Tech.GHOST_ACADEMY` and the barracks's own tech lab for a 238 ghost, and `Tech.CYBERNETICS_CORE` for an adept, to a gateway and a warp gate alike. Every producer of a type needs 239 the same (tool `sweep_tech_tree`). Empty for a type nothing is recorded making, and for a warp gate, which no 240 gateway is offered: the game turns each gateway once Warp Gate is researched.""" 241 morphed_from: UnitTypeId | None 242 """The unit type used up to make one: a command center for an orbital command, a larva for a zergling, `None` for 243 a marine.""" 244 equivalent_types: type[UnitType.AnyType] 245 """The `UnitType` group of the types a unit of this type converts between and back, at will: 246 `UnitType.AnySiegeTank` for a siege tank sieged or not, and `UnitType.AnyHellion` for a hellion and a hellbat. A 247 type in none has its own class, such as `UnitType.Marine`. The class's `types_are_equivalent` reads True either way. 248 A morph that costs something makes another unit, so a lair, a baneling's cocoon and an overlord transport have their 249 own class, and `UnitType.AnyOrbitalCommand` holds no command center. A changeling, a creep tumor and a locust are 250 not converted back and forth: the game disguises a changeling (stated) and burrows a tumor, and a locust takes off 251 by itself and a swoop lands it (in game). So each of their types has its own class too, and 252 `UnitType.AnyChangeling`, `AnyCreepTumor` and `AnyLocust` hold them. A gas building on a rich geyser is another 253 structure than one on a plain geyser and has its own class, though both are built by the same `creation_ability`, 254 and `UnitType.AnyRefinery`, `AnyExtractor` and `AnyAssimilator` hold both. `equivalent_types.type_ids` holds every 255 type of it, the same in any tables, though tables made up for a test may hold no row of some.""" 256 ability_requirements: Mapping[AbilityId, TechRequirements] 257 """The abilities a unit of this type can be offered, with the tech each needs first.""" 258 needs_power: bool 259 """Whether it needs to be powered by a pylon or a warp prism.""" 260 creep_requirement: CreepRequirement | None 261 """Whether a structure of this type may stand on creep, as the game answered its placement on creep and off it, 262 for every type a unit places at a point; `None` for any other type, such as a gas building, which goes on a 263 geyser, an add-on, or a form a structure morphs into.""" 264 techs_granted: frozenset[Tech] 265 """The techs it grants: the one named after it, if any, and the one named after each type back along 266 `morphed_from`. A greater spire grants `Tech.SPIRE` and `Tech.GREATER_SPIRE`, a hive `HATCHERY`, `LAIR` and `HIVE`, 267 an orbital command `COMMAND_CENTER` and a lowered supply depot `SUPPLY_DEPOT`; a marine grants none.""" 268 has_minerals: bool 269 """Whether minerals can be mined from it.""" 270 has_vespene: bool 271 """Whether vespene can be mined from it.""" 272 footprint: Footprint | None 273 """The tiles one covers where it stands, as measured in game, for every structure type that stands and every type 274 of the map's own. `None` for any other type, such as a unit, an egg or a force field, and for the few the game would 275 not create to be measured: the acceleration zones and the flying inhibitor zones.""" 276 upgrades: Mapping[UpgradeId, UnitTypeUpgrade] 277 """Every upgrade that affects it, with what each adds to its weapons, their attack speed, its armor and its speed. 278 An upgrade that only raises a level its units report, such as a shields level, adds nothing.""" 279 _whole_cost: Cost = field(repr=False, compare=False) 280 """Everything the tables say was spent to reach this type, what it morphed from included, an orbital command's 550, 281 with the build time of each stage that costs something: what a repair is priced from (tool `sweep_repair`). Unlike 282 `total_cost`, a MULE's is 50, an auto-turret's 100, an archon's 175/275 and a hatchery's 325.""" 283 _unrounded_build_time: GameTime = field(repr=False, compare=False) 284 """The tables' build time before `build_time` rounds it up, a void ray's 963.2 steps: a train's progress, an egg's, 285 and a structure's build progress, are the steps done over it (in game).""" 286 turn_rate: float | None = None 287 """The most it turns in a step, in radians: a whole number of 1/4096 of a full turn, 711 for a marine (62.49 288 degrees) and 512 for a thor (45) (in game). A turn takes its angle over this, rounded up, in steps, give or take 289 one, from the step it begins. `None` for a type whose facing the game never changes, such as a colossus or an 290 immortal, and for one that does not move (`docs/reference/game-behavior/units.md`).""" 291 moves_while_turning: bool | None = None 292 """Whether a unit of this type moves while it still turns, from the step after its turn begins, as most do; false 293 for a thor, an ultralisk and a siege tank, which move only once they face where they go (in game). `None` wherever 294 `turn_rate` is.""" 295 296 @property 297 def abilities(self) -> frozenset[AbilityId]: 298 """The abilities a unit of this type can be offered.""" 299 return frozenset(self.ability_requirements) 300 301 def with_upgrades(self, upgrades: Iterable[UpgradeId]) -> UnitTypeData: 302 """This type with `upgrades` researched: the weapons, their attack speed, the armor and the speed they change. 303 304 Nothing else an upgrade does is applied. Anabolic Synthesis counts whether or not the unit is on creep, as in 305 the game's rows. 306 """ 307 changes = [self.upgrades[upgrade] for upgrade in sorted(set(upgrades) & self.upgrades.keys())] 308 changes = [change for change in changes if change != _NO_CHANGE] 309 if not changes: 310 return self 311 weapons = tuple( 312 weapon._with_weapon_upgrade( 313 sum((change.weapons[index] for change in changes if change.weapons), _NO_WEAPON_CHANGE) 314 ) 315 for index, weapon in enumerate(self.weapons) 316 ) 317 return replace( 318 self, 319 armor=self.armor + sum(change.armor for change in changes), 320 speed=self.speed + sum(change.speed for change in changes), 321 weapons=weapons, 322 ) 323 324 @classmethod 325 def _from_proto(cls, unit: data_pb2.UnitTypeData, tech_tree: TechTree) -> Self: 326 """Read one unit type from the game's table, with what `tech_tree` says about it.""" 327 unit_type = UnitTypeId(unit.unit_id) 328 in_tree = tech_tree.unit_type(unit_type) 329 return cls( 330 id=unit_type, 331 race=Race(unit.race), 332 # The tables' whole cost, until `GameData` works out the cost of each step. 333 cost=Cost(unit.mineral_cost, unit.vespene_cost, unit.food_required), 334 total_cost=Cost(unit.mineral_cost, unit.vespene_cost, unit.food_required), 335 build_time=GameTime(steps=math.ceil(unit.build_time)), 336 supply_provided=unit.food_provided, 337 supply_used=unit.food_required, 338 cargo_size=unit.cargo_size, 339 sight_range=unit.sight_range, 340 # The game gives it in distance per second at Normal speed, 16 steps a second. 341 speed=unit.movement_speed * FASTER_PER_NORMAL_SPEED, 342 armor=unit.armor, 343 attributes=frozenset(Attribute(attribute) for attribute in unit.attributes), 344 weapons=tuple(Weapon._from_proto(weapon) for weapon in unit.weapons), 345 creation_ability=in_tree.creation_ability, 346 producers=in_tree.producers or PRODUCERS_FALLBACK.get(unit_type, frozenset()), 347 tech_requirements=in_tree.tech_requirements, 348 morphed_from=in_tree.morphed_from, 349 equivalent_types=EQUIVALENT_UNIT_TYPES[unit_type], 350 ability_requirements=in_tree.ability_requirements, 351 needs_power=in_tree.needs_power, 352 creep_requirement=CREEP_REQUIREMENTS.get(unit_type), 353 techs_granted=frozenset(Tech(stage) for stage in tech_tree.morph_stages_of(unit_type) if stage in Tech), 354 has_minerals=unit.has_minerals, 355 has_vespene=unit.has_vespene, 356 footprint=FOOTPRINTS.get(unit_type), 357 upgrades=in_tree.upgrades, 358 # `GameData` gives it the build time of each stage that costs something. 359 _whole_cost=Cost(unit.mineral_cost, unit.vespene_cost, unit.food_required), 360 _unrounded_build_time=GameTime(steps=unit.build_time), 361 )
One unit type, before any upgrade unless with_upgrades made it.
What the order that made one cost: the cost of its last step that cost anything, so every form of a unit costs
the same. An orbital command is 150, a baneling 25/25, a sieged tank the tank's 150/125 and 3 supply, a warp gate
the gateway's 150, and an archon nothing (tool sweep_orders). A zergling's is half its order of two, 25 minerals
and half a supply; a structure a drone becomes gives the drone's supply back, -1; a cocoon's is that of what it
becomes; and a MULE and an auto-turret, which energy pays for, cost nothing (tool sweep_orders). Its time is that
step's build time. What ordering an ability costs is the ability's cost, nothing for a siege.
What every order that made one cost, step by step back along morphed_from to the first: an orbital command
550 with its command center, a hatchery 350 with its drone, a lair 500/100, a baneling 50/25 and half a supply with
its zergling, and a sieged tank the tank's 150/125. An archon counts two high templar, 100/300 and 4 supply; a
cocoon what it becomes; a MULE and an auto-turret nothing. Its time is the build time of each step that costs
something, one after another, an archon's merge of 192 steps included.
The time to make one: the tables' build time rounded up to a whole step, as a train takes it, a void ray's 963.2
steps as 964 (in game); for a morph, only the last stage, which a unit's morph keeps to within a step. A lurker
takes the 403 steps it took in game, where its row reads 553.33, and an archon the 192 it took from when it was
first listed, where its row gives none (docs/reference/game-behavior/upgrades-and-tables.md). Any other type the
table gives none takes the build time of the one other type its creation ability makes: a rich gas building its
plain one's.
The supply one takes, as the tables give it: half for a zergling, 3 for a sieged tank, 4 for an archon.
Its movement speed, in distance per second at the game's Faster speed (22.4 steps); zero for a structure.
Its attacks: the tables', or for the battlecruiser, the oracle, the void ray and the sentry, which the tables
give none, the attacks tools/sweep_combat.py measured. An oracle's fires only while its beam is on.
The ability that makes one, or None where the tables tie it to no curated ability: for every type of the map's
own; for a larva, an egg, a cocoon, a broodling, a force field, an adept's shade, a KD8 charge, a parasitic bomb
left behind, a burrowed creep tumor, a flying locust and a bare tech lab or reactor; and for a MULE, an interceptor,
a changeling and an archon, though something makes each.
The unit types that make one: a gateway and a warp gate, for a zealot; a high and a dark templar, for an archon. Empty for a type nothing is recorded making, such as a larva, a MULE or an interceptor.
What a producer needs before it is offered what makes one, each producer's ability_requirements for the
ability it makes one by: Tech.BARRACKS for a factory, Tech.GHOST_ACADEMY and the barracks's own tech lab for a
ghost, and Tech.CYBERNETICS_CORE for an adept, to a gateway and a warp gate alike. Every producer of a type needs
the same (tool sweep_tech_tree). Empty for a type nothing is recorded making, and for a warp gate, which no
gateway is offered: the game turns each gateway once Warp Gate is researched.
The unit type used up to make one: a command center for an orbital command, a larva for a zergling, None for
a marine.
The UnitType group of the types a unit of this type converts between and back, at will:
UnitType.AnySiegeTank for a siege tank sieged or not, and UnitType.AnyHellion for a hellion and a hellbat. A
type in none has its own class, such as UnitType.Marine. The class's types_are_equivalent reads True either way.
A morph that costs something makes another unit, so a lair, a baneling's cocoon and an overlord transport have their
own class, and UnitType.AnyOrbitalCommand holds no command center. A changeling, a creep tumor and a locust are
not converted back and forth: the game disguises a changeling (stated) and burrows a tumor, and a locust takes off
by itself and a swoop lands it (in game). So each of their types has its own class too, and
UnitType.AnyChangeling, AnyCreepTumor and AnyLocust hold them. A gas building on a rich geyser is another
structure than one on a plain geyser and has its own class, though both are built by the same creation_ability,
and UnitType.AnyRefinery, AnyExtractor and AnyAssimilator hold both. equivalent_types.type_ids holds every
type of it, the same in any tables, though tables made up for a test may hold no row of some.
The abilities a unit of this type can be offered, with the tech each needs first.
Whether a structure of this type may stand on creep, as the game answered its placement on creep and off it,
for every type a unit places at a point; None for any other type, such as a gas building, which goes on a
geyser, an add-on, or a form a structure morphs into.
The techs it grants: the one named after it, if any, and the one named after each type back along
morphed_from. A greater spire grants Tech.SPIRE and Tech.GREATER_SPIRE, a hive HATCHERY, LAIR and HIVE,
an orbital command COMMAND_CENTER and a lowered supply depot SUPPLY_DEPOT; a marine grants none.
The tiles one covers where it stands, as measured in game, for every structure type that stands and every type
of the map's own. None for any other type, such as a unit, an egg or a force field, and for the few the game would
not create to be measured: the acceleration zones and the flying inhibitor zones.
Every upgrade that affects it, with what each adds to its weapons, their attack speed, its armor and its speed. An upgrade that only raises a level its units report, such as a shields level, adds nothing.
The most it turns in a step, in radians: a whole number of 1/4096 of a full turn, 711 for a marine (62.49
degrees) and 512 for a thor (45) (in game). A turn takes its angle over this, rounded up, in steps, give or take
one, from the step it begins. None for a type whose facing the game never changes, such as a colossus or an
immortal, and for one that does not move (docs/reference/game-behavior/units.md).
Whether a unit of this type moves while it still turns, from the step after its turn begins, as most do; false
for a thor, an ultralisk and a siege tank, which move only once they face where they go (in game). None wherever
turn_rate is.
296 @property 297 def abilities(self) -> frozenset[AbilityId]: 298 """The abilities a unit of this type can be offered.""" 299 return frozenset(self.ability_requirements)
The abilities a unit of this type can be offered.
301 def with_upgrades(self, upgrades: Iterable[UpgradeId]) -> UnitTypeData: 302 """This type with `upgrades` researched: the weapons, their attack speed, the armor and the speed they change. 303 304 Nothing else an upgrade does is applied. Anabolic Synthesis counts whether or not the unit is on creep, as in 305 the game's rows. 306 """ 307 changes = [self.upgrades[upgrade] for upgrade in sorted(set(upgrades) & self.upgrades.keys())] 308 changes = [change for change in changes if change != _NO_CHANGE] 309 if not changes: 310 return self 311 weapons = tuple( 312 weapon._with_weapon_upgrade( 313 sum((change.weapons[index] for change in changes if change.weapons), _NO_WEAPON_CHANGE) 314 ) 315 for index, weapon in enumerate(self.weapons) 316 ) 317 return replace( 318 self, 319 armor=self.armor + sum(change.armor for change in changes), 320 speed=self.speed + sum(change.speed for change in changes), 321 weapons=weapons, 322 )
This type with upgrades researched: the weapons, their attack speed, the armor and the speed they change.
Nothing else an upgrade does is applied. Anabolic Synthesis counts whether or not the unit is on creep, as in the game's rows.
44@final 45@dataclass(frozen=True, slots=True) 46class UnitTypeUpgrade: 47 """What an upgrade adds to one type of unit.""" 48 49 armor: float = 0.0 50 """Added armor.""" 51 speed: float = 0.0 52 """Added movement speed, in distance per second at the game's Faster speed (22.4 steps).""" 53 weapons: tuple[WeaponUpgrade, ...] = () 54 """The change to each weapon, in the type's weapon order, with a `WeaponUpgrade()` for a weapon left alone. Empty if 55 no weapon changes."""
What an upgrade adds to one type of unit.
The change to each weapon, in the type's weapon order, with a WeaponUpgrade() for a weapon left alone. Empty if
no weapon changes.
34@final 35@dataclass(frozen=True, slots=True) 36class UpgradeData: 37 """One upgrade, as the game's table describes it.""" 38 39 id: UpgradeId 40 """The upgrade described.""" 41 cost: Cost 42 """The cost of researching it. Its time is the research time, a whole number of steps for every upgrade in the 43 game's tables and above 0 for every curated one (corpus), which a research takes exactly (in game).""" 44 research_ability: AbilityId | None 45 """The ability that researches it.""" 46 researchers: frozenset[UnitTypeId] 47 """The structure types whose `research_ability` researches it: an engineering bay for infantry weapons, a spire and 48 a greater spire for flyer attacks. Empty for an upgrade nothing researches.""" 49 tech_requirements: TechRequirements 50 """What a researcher needs before it is offered `research_ability`: `Tech.ARMORY` and level 1 for infantry weapons 51 level 2. Every researcher of an upgrade needs the same (tool `sweep_tech_tree`).""" 52 upgrade_type: UpgradeType 53 """The upgrade level the units it affects report it adding to, or `OTHER` if they report nothing of it.""" 54 level: int 55 """Its level within its line, from 1; 0 for an upgrade that is no level, such as Chitinous Plating.""" 56 57 @classmethod 58 def _from_proto(cls, data: data_pb2.UpgradeData, tech_tree: TechTree) -> Self: 59 """Read one upgrade from the game's table, with what `tech_tree` says about it.""" 60 upgrade = UpgradeId(data.upgrade_id) 61 in_tree = tech_tree.upgrade(upgrade) 62 return cls( 63 id=upgrade, 64 cost=Cost(data.mineral_cost, data.vespene_cost, time=GameTime(steps=round(data.research_time))), 65 research_ability=AbilityId.get(data.ability_id) or in_tree.research_ability, 66 researchers=in_tree.researchers, 67 tech_requirements=in_tree.tech_requirements, 68 upgrade_type=in_tree.upgrade_type, 69 level=in_tree.level, 70 )
One upgrade, as the game's table describes it.
The cost of researching it. Its time is the research time, a whole number of steps for every upgrade in the game's tables and above 0 for every curated one (corpus), which a research takes exactly (in game).
The structure types whose research_ability researches it: an engineering bay for infantry weapons, a spire and
a greater spire for flyer attacks. Empty for an upgrade nothing researches.
What a researcher needs before it is offered research_ability: Tech.ARMORY and level 1 for infantry weapons
level 2. Every researcher of an upgrade needs the same (tool sweep_tech_tree).
The upgrade level the units it affects report it adding to, or OTHER if they report nothing of it.
21class UpgradeType(ReadableIntEnum): 22 """The upgrade level a unit reports an upgrade adding to.""" 23 24 OTHER = 0 25 """An upgrade a unit reports nothing of, such as Stimpack or Grooved Spines.""" 26 ATTACK = 1 27 """`Unit.attack_upgrade_level`, a count of levels.""" 28 ARMOR = 2 29 """`Unit.armor_upgrade_level`, the armor its upgrades add.""" 30 SHIELD = 3 31 """`Unit.shield_upgrade_level`, a count of levels."""
The upgrade level a unit reports an upgrade adding to.
An upgrade a unit reports nothing of, such as Stimpack or Grooved Spines.
68@final 69@dataclass(frozen=True, slots=True) 70class Weapon: 71 """One of a unit type's attacks, before any upgrade unless `UnitTypeData.with_upgrades` made it.""" 72 73 target_domain: TargetDomain 74 """Whether it can fire at ground, air or both.""" 75 damage: float 76 """The damage of one hit, before the target's armor.""" 77 attacks: int 78 """Hits per attack: two for a colossus.""" 79 range: float 80 """Its range.""" 81 base_cooldown: GameTime 82 """The time from one attack to the next before the random delay the game adds to each: the tables' cooldown, 83 shortened by an upgrade that speeds the attack.""" 84 damage_bonuses: Mapping[Attribute, float] 85 """The extra damage per hit against a target with each attribute.""" 86 ignores_armor: bool = False 87 """Whether a hit takes off its whole damage, whatever the target's armor and shield armor: an oracle's beam's (in 88 game).""" 89 mean_delay: GameTime = _MEAN_ATTACK_DELAY 90 """The mean of the random delay the game adds to each attack: 0.4996 steps for a weapon from the tables, whose delay 91 runs from -1 to 2 steps, and nothing for the weapons measured for the types the tables give none (in game).""" 92 turns_to_fire: bool = True 93 """Whether its unit must face a target to fire it, as most do, to within a degree; false for one that fires at any 94 angle off its facing, such as a battlecruiser's or a planetary fortress's, though a turret the game does not report 95 may still take some steps to come round (in game; `docs/reference/game-behavior/damage-and-buffs.md`). True for a 96 weapon never seen to fire, such as a sieged liberator's.""" 97 98 @property 99 def average_cooldown(self) -> GameTime: 100 """The time from one attack to the next on average, the random delay counted. A thor's and an ultralisk's 101 attacks were not seen to keep to it. A unit's own `weapon_cooldown` counts down the delay drawn for its last 102 attack.""" 103 return self.base_cooldown + self.mean_delay 104 105 @property 106 def total_damage(self) -> float: 107 """The damage of one attack, every hit of it, before bonuses and the target's armor: `damage` times 108 `attacks`.""" 109 return self.damage * self.attacks 110 111 @property 112 def dps(self) -> float: 113 """Damage per second of real time at the game's Faster speed: `total_damage` each `average_cooldown`, 114 against a target with no armor and no attribute it has a bonus against.""" 115 return self.total_damage / self.average_cooldown.seconds 116 117 def bonus_per_hit_against(self, attributes: Collection[Attribute]) -> float: 118 """The extra damage of one hit against a target with `attributes`: the `damage_bonuses` for them, summed. 0 for 119 none.""" 120 return sum((bonus for attribute, bonus in self.damage_bonuses.items() if attribute in attributes), start=0.0) 121 122 def damage_against( 123 self, *, attributes: Collection[Attribute], armor: float, shield_armor: float = 0.0, shield: float = 0.0 124 ) -> float: 125 """What one attack takes off a target with these attributes, armor and shield, its shield and health together. 126 127 Each hit takes off the damage and its bonus against the target's attributes: from the shield first, less 128 `shield_armor`, and what is more than the shield has left goes on to health less `armor`, at nothing at least; 129 from health alone, less `armor`, but at least 0.5 (in game). A weapon that `ignores_armor` takes off the whole 130 hit. Each hit of an attack of several finds the shield the one before left. The damage may come to more than 131 the target has left. 132 """ 133 hit_damage = self.damage + self.bonus_per_hit_against(attributes) 134 if self.ignores_armor: 135 armor = shield_armor = 0.0 136 damage_taken = 0.0 137 for _ in range(self.attacks): 138 if shield <= 0: 139 damage_taken += max(hit_damage - armor, _MINIMUM_DAMAGE) 140 continue 141 # Taken to be at least 0.5, as off health: no hit seen was small enough to tell. 142 off_shield = max(hit_damage - shield_armor, _MINIMUM_DAMAGE) 143 if off_shield <= shield: 144 damage_taken += off_shield 145 shield -= off_shield 146 else: 147 damage_taken += shield + max(off_shield - shield - armor, 0.0) 148 shield = 0.0 149 return damage_taken 150 151 @classmethod 152 def _from_proto(cls, weapon: data_pb2.Weapon) -> Self: 153 """Read one weapon from the game's table.""" 154 damage_bonuses = {Attribute(bonus.attribute): bonus.bonus for bonus in weapon.damage_bonus} 155 return cls( 156 target_domain=TargetDomain(weapon.type), 157 damage=weapon.damage, 158 attacks=weapon.attacks, 159 range=weapon.range, 160 # The game calls this the weapon's speed, though a larger value is a slower weapon, and gives it in 161 # seconds at Normal speed. 162 base_cooldown=GameTime(normal_seconds=weapon.speed), 163 damage_bonuses=MappingProxyType(damage_bonuses), 164 ) 165 166 def _with_weapon_upgrade(self, change: WeaponUpgrade) -> Weapon: 167 """This weapon with `change` added, and its base cooldown divided by the change's attack speed multiplier: 168 what speeds an attack leaves the random delay as it is (in game).""" 169 bonuses = dict(self.damage_bonuses) 170 for attribute, bonus in change.damage_bonuses.items(): 171 bonuses[attribute] = bonuses.get(attribute, 0.0) + bonus 172 return replace( 173 self, 174 damage=self.damage + change.damage, 175 range=self.range + change.range, 176 base_cooldown=self.base_cooldown / change.attack_speed_multiplier, 177 damage_bonuses=MappingProxyType(bonuses), 178 )
One of a unit type's attacks, before any upgrade unless UnitTypeData.with_upgrades made it.
The time from one attack to the next before the random delay the game adds to each: the tables' cooldown, shortened by an upgrade that speeds the attack.
The extra damage per hit against a target with each attribute.
Whether a hit takes off its whole damage, whatever the target's armor and shield armor: an oracle's beam's (in game).
The mean of the random delay the game adds to each attack: 0.4996 steps for a weapon from the tables, whose delay runs from -1 to 2 steps, and nothing for the weapons measured for the types the tables give none (in game).
Whether its unit must face a target to fire it, as most do, to within a degree; false for one that fires at any
angle off its facing, such as a battlecruiser's or a planetary fortress's, though a turret the game does not report
may still take some steps to come round (in game; docs/reference/game-behavior/damage-and-buffs.md). True for a
weapon never seen to fire, such as a sieged liberator's.
98 @property 99 def average_cooldown(self) -> GameTime: 100 """The time from one attack to the next on average, the random delay counted. A thor's and an ultralisk's 101 attacks were not seen to keep to it. A unit's own `weapon_cooldown` counts down the delay drawn for its last 102 attack.""" 103 return self.base_cooldown + self.mean_delay
The time from one attack to the next on average, the random delay counted. A thor's and an ultralisk's
attacks were not seen to keep to it. A unit's own weapon_cooldown counts down the delay drawn for its last
attack.
111 @property 112 def dps(self) -> float: 113 """Damage per second of real time at the game's Faster speed: `total_damage` each `average_cooldown`, 114 against a target with no armor and no attribute it has a bonus against.""" 115 return self.total_damage / self.average_cooldown.seconds
Damage per second of real time at the game's Faster speed: total_damage each average_cooldown,
against a target with no armor and no attribute it has a bonus against.
117 def bonus_per_hit_against(self, attributes: Collection[Attribute]) -> float: 118 """The extra damage of one hit against a target with `attributes`: the `damage_bonuses` for them, summed. 0 for 119 none.""" 120 return sum((bonus for attribute, bonus in self.damage_bonuses.items() if attribute in attributes), start=0.0)
The extra damage of one hit against a target with attributes: the damage_bonuses for them, summed. 0 for
none.
122 def damage_against( 123 self, *, attributes: Collection[Attribute], armor: float, shield_armor: float = 0.0, shield: float = 0.0 124 ) -> float: 125 """What one attack takes off a target with these attributes, armor and shield, its shield and health together. 126 127 Each hit takes off the damage and its bonus against the target's attributes: from the shield first, less 128 `shield_armor`, and what is more than the shield has left goes on to health less `armor`, at nothing at least; 129 from health alone, less `armor`, but at least 0.5 (in game). A weapon that `ignores_armor` takes off the whole 130 hit. Each hit of an attack of several finds the shield the one before left. The damage may come to more than 131 the target has left. 132 """ 133 hit_damage = self.damage + self.bonus_per_hit_against(attributes) 134 if self.ignores_armor: 135 armor = shield_armor = 0.0 136 damage_taken = 0.0 137 for _ in range(self.attacks): 138 if shield <= 0: 139 damage_taken += max(hit_damage - armor, _MINIMUM_DAMAGE) 140 continue 141 # Taken to be at least 0.5, as off health: no hit seen was small enough to tell. 142 off_shield = max(hit_damage - shield_armor, _MINIMUM_DAMAGE) 143 if off_shield <= shield: 144 damage_taken += off_shield 145 shield -= off_shield 146 else: 147 damage_taken += shield + max(off_shield - shield - armor, 0.0) 148 shield = 0.0 149 return damage_taken
What one attack takes off a target with these attributes, armor and shield, its shield and health together.
Each hit takes off the damage and its bonus against the target's attributes: from the shield first, less
shield_armor, and what is more than the shield has left goes on to health less armor, at nothing at least;
from health alone, less armor, but at least 0.5 (in game). A weapon that ignores_armor takes off the whole
hit. Each hit of an attack of several finds the shield the one before left. The damage may come to more than
the target has left.
16@final 17@dataclass(frozen=True, slots=True) 18class WeaponUpgrade: 19 """What an upgrade adds to one of a unit type's weapons.""" 20 21 damage: float = 0.0 22 """Added damage per hit.""" 23 damage_bonuses: Mapping[Attribute, float] = field(default_factory=lambda: MappingProxyType({})) 24 """Added bonus damage against each attribute, including attributes the weapon had no bonus against.""" 25 range: float = 0.0 26 """Added range.""" 27 attack_speed_multiplier: float = 1.0 28 """How many times as often the weapon attacks: 1.4 for a zergling's with Adrenal Glands (in game).""" 29 30 def __add__(self, other: WeaponUpgrade) -> WeaponUpgrade: 31 """What the two upgrades add to the weapon together: their damage, bonuses and range added, and their attack 32 speed multipliers multiplied.""" 33 bonuses = dict(self.damage_bonuses) 34 for attribute, bonus in other.damage_bonuses.items(): 35 bonuses[attribute] = bonuses.get(attribute, 0.0) + bonus 36 return WeaponUpgrade( 37 damage=self.damage + other.damage, 38 damage_bonuses=MappingProxyType(bonuses), 39 range=self.range + other.range, 40 attack_speed_multiplier=self.attack_speed_multiplier * other.attack_speed_multiplier, 41 )
What an upgrade adds to one of a unit type's weapons.
Added bonus damage against each attribute, including attributes the weapon had no bonus against.