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]
@final
@dataclass(frozen=True, slots=True)
class AbilityData:
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.

AbilityData( id: sc2nachos.AbilityId, target_type: TargetType, cast_range: float, footprint_radius: float | None, needs_placement: bool, allows_autocast: bool, performers: frozenset[sc2nachos.UnitTypeId], products: Mapping[sc2nachos.UnitTypeId, sc2nachos.UnitTypeId | sc2nachos.UpgradeId], cost: Cost, multi_unit: bool, joins_other_orders: bool, cancelled_by: sc2nachos.AbilityId | None, order_behavior: OrderBehavior, sent_as: Mapping[sc2nachos.UnitTypeId, sc2nachos.gamedata._sent_as.SentAs], _behaviors_by_performer: Mapping[sc2nachos.UnitTypeId, OrderBehavior])

The ability described.

target_type: TargetType

What an order of it must be aimed at.

cast_range: float

Its range, or zero if it has none of its own.

footprint_radius: float | None

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.

needs_placement: bool

Whether ordering it places a structure.

allows_autocast: bool

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.

performers: frozenset[sc2nachos.UnitTypeId]

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.

cost: Cost

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.

multi_unit: bool

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.

joins_other_orders: bool

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).

cancelled_by: sc2nachos.AbilityId | None

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.

order_behavior: OrderBehavior

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.

sent_as: Mapping[sc2nachos.UnitTypeId, sc2nachos.gamedata._sent_as.SentAs]

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.

is_research: bool
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.

places_at_target: bool
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.

def order_behavior_for( self, unit_type: sc2nachos.UnitTypeId) -> OrderBehavior:
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).

class Attribute(sc2nachos._shared.readable_int_enum.ReadableIntEnum):
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.

LIGHT = <Attribute.LIGHT: 1>
ARMORED = <Attribute.ARMORED: 2>
BIOLOGICAL = <Attribute.BIOLOGICAL: 3>
MECHANICAL = <Attribute.MECHANICAL: 4>
ROBOTIC = <Attribute.ROBOTIC: 5>
PSIONIC = <Attribute.PSIONIC: 6>
MASSIVE = <Attribute.MASSIVE: 7>
STRUCTURE = <Attribute.STRUCTURE: 8>
HOVER = <Attribute.HOVER: 9>
HEROIC = <Attribute.HEROIC: 10>
SUMMONED = <Attribute.SUMMONED: 11>
@final
@dataclass(frozen=True, slots=True)
class Cost:
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.

Cost( minerals: float, vespene: float, supply: float = 0.0, time: sc2nachos.GameTime = GameTime(steps=0))
minerals: float

Minerals.

vespene: float

Vespene.

supply: float

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.

resources: Resources
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.

is_free: bool
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.

class CreepRequirement(sc2nachos._shared.readable_int_enum.ReadableIntEnum):
 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.

ON_CREEP = <CreepRequirement.ON_CREEP: 1>

Only on creep, under every tile: a zerg structure but a hatchery or a nydus worm, and a creep tumor.

OFF_CREEP = <CreepRequirement.OFF_CREEP: 2>

Only off creep: a terran or protoss structure but a raven's auto turret or an oracle's stasis ward.

NONE = <CreepRequirement.NONE: 3>

On creep or off it, as either comes: a hatchery, a nydus worm, a raven's auto turret and an oracle's stasis ward.

@final
@dataclass(frozen=True, slots=True)
class EffectData:
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.

EffectData(id: sc2nachos.ids.EffectId, radius: float)

The effect described.

radius: float

Its radius around its center.

@final
class GameData:
 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.

GameData(data: s2clientprotocol.sc2api_pb2.ResponseData)
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.

units: Mapping[sc2nachos.UnitTypeId, UnitTypeData]
95    @property
96    def units(self) -> Mapping[UnitTypeId, UnitTypeData]:
97        """The unit types, by id."""
98        return self._units

The unit types, by id.

abilities: Mapping[sc2nachos.AbilityId, AbilityData]
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.

upgrades: Mapping[sc2nachos.UpgradeId, UpgradeData]
105    @property
106    def upgrades(self) -> Mapping[UpgradeId, UpgradeData]:
107        """The upgrades, by id."""
108        return self._upgrades

The upgrades, by id.

effects: Mapping[sc2nachos.ids.EffectId, EffectData]
110    @property
111    def effects(self) -> Mapping[EffectId, EffectData]:
112        """The effects, by id."""
113        return self._effects

The effects, by id.

def types_granting( self, tech: Tech) -> frozenset[sc2nachos.UnitTypeId]:
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.

class OrderBehavior(enum.Enum):
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).

REPLACES = <OrderBehavior.REPLACES: 'replaces'>

Drops the unit's orders and runs instead: a move, an attack, a worker's build.

QUEUES = <OrderBehavior.QUEUES: 'queues'>

Goes behind whatever the structure is making, queued or not: a train or a research.

NEEDS_IDLE = <OrderBehavior.NEEDS_IDLE: 'needs idle'>

A structure accepts it only while making nothing, and otherwise answers NOT_SUPPORTED: an add-on, a morph, a lift.

KEEPS_ORDERS = <OrderBehavior.KEEPS_ORDERS: 'keeps orders'>

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.

@final
@dataclass(frozen=True, slots=True)
class Resources:
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.

Resources(minerals: float, vespene: float)
minerals: float

Minerals.

vespene: float

Vespene.

total: float
23    @property
24    def total(self) -> float:
25        """Minerals plus vespene, counted alike."""
26        return self.minerals + self.vespene

Minerals plus vespene, counted alike.

def covers(self, other: Resources) -> bool:
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.

def minimum( self, other: Resources) -> Resources:
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.

def maximum( self, other: Resources) -> Resources:
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.

class Tech(enum.Enum):
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.

SUPPLY_DEPOT = <Tech.SUPPLY_DEPOT: <UnitTypeId.SUPPLY_DEPOT: 19>>
COMMAND_CENTER = <Tech.COMMAND_CENTER: <UnitTypeId.COMMAND_CENTER: 18>>
BARRACKS = <Tech.BARRACKS: <UnitTypeId.BARRACKS: 21>>
ENGINEERING_BAY = <Tech.ENGINEERING_BAY: <UnitTypeId.ENGINEERING_BAY: 22>>
FACTORY = <Tech.FACTORY: <UnitTypeId.FACTORY: 27>>
GHOST_ACADEMY = <Tech.GHOST_ACADEMY: <UnitTypeId.GHOST_ACADEMY: 26>>
ARMORY = <Tech.ARMORY: <UnitTypeId.ARMORY: 29>>
STARPORT = <Tech.STARPORT: <UnitTypeId.STARPORT: 28>>
FUSION_CORE = <Tech.FUSION_CORE: <UnitTypeId.FUSION_CORE: 30>>
HATCHERY = <Tech.HATCHERY: <UnitTypeId.HATCHERY: 86>>
SPAWNING_POOL = <Tech.SPAWNING_POOL: <UnitTypeId.SPAWNING_POOL: 89>>
LAIR = <Tech.LAIR: <UnitTypeId.LAIR: 100>>
BANELING_NEST = <Tech.BANELING_NEST: <UnitTypeId.BANELING_NEST: 96>>
ROACH_WARREN = <Tech.ROACH_WARREN: <UnitTypeId.ROACH_WARREN: 97>>
HYDRALISK_DEN = <Tech.HYDRALISK_DEN: <UnitTypeId.HYDRALISK_DEN: 91>>
LURKER_DEN = <Tech.LURKER_DEN: <UnitTypeId.LURKER_DEN: 504>>
INFESTATION_PIT = <Tech.INFESTATION_PIT: <UnitTypeId.INFESTATION_PIT: 94>>
SPIRE = <Tech.SPIRE: <UnitTypeId.SPIRE: 92>>
HIVE = <Tech.HIVE: <UnitTypeId.HIVE: 101>>
GREATER_SPIRE = <Tech.GREATER_SPIRE: <UnitTypeId.GREATER_SPIRE: 102>>
ULTRALISK_CAVERN = <Tech.ULTRALISK_CAVERN: <UnitTypeId.ULTRALISK_CAVERN: 93>>
NEXUS = <Tech.NEXUS: <UnitTypeId.NEXUS: 59>>
GATEWAY = <Tech.GATEWAY: <UnitTypeId.GATEWAY: 62>>
FORGE = <Tech.FORGE: <UnitTypeId.FORGE: 63>>
CYBERNETICS_CORE = <Tech.CYBERNETICS_CORE: <UnitTypeId.CYBERNETICS_CORE: 72>>
TWILIGHT_COUNCIL = <Tech.TWILIGHT_COUNCIL: <UnitTypeId.TWILIGHT_COUNCIL: 65>>
ROBOTICS_FACILITY = <Tech.ROBOTICS_FACILITY: <UnitTypeId.ROBOTICS_FACILITY: 71>>
STARGATE = <Tech.STARGATE: <UnitTypeId.STARGATE: 67>>
TEMPLAR_ARCHIVE = <Tech.TEMPLAR_ARCHIVE: <UnitTypeId.TEMPLAR_ARCHIVE: 68>>
DARK_SHRINE = <Tech.DARK_SHRINE: <UnitTypeId.DARK_SHRINE: 69>>
ROBOTICS_BAY = <Tech.ROBOTICS_BAY: <UnitTypeId.ROBOTICS_BAY: 70>>
FLEET_BEACON = <Tech.FLEET_BEACON: <UnitTypeId.FLEET_BEACON: 64>>
base_type: sc2nachos.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.

@final
@dataclass(frozen=True, slots=True)
class TechRequirements:
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.

TechRequirements( techs: frozenset[Tech] = frozenset(), needs_tech_lab: bool = False, upgrades: frozenset[sc2nachos.UpgradeId] = frozenset())
techs: frozenset[Tech]

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.

needs_tech_lab: bool

Whether the unit itself must have a tech lab: a barracks trains a ghost only with its own. No requirement names a reactor, or another structure's add-on (tool sweep_tech_tree).

upgrades: frozenset[sc2nachos.UpgradeId]

Every upgrade that must be researched.

class TargetDomain(sc2nachos._shared.readable_int_enum.ReadableIntEnum):
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.

GROUND = <TargetDomain.GROUND: 1>
AIR = <TargetDomain.AIR: 2>
ANY = <TargetDomain.ANY: 3>
class TargetType(sc2nachos._shared.readable_int_enum.ReadableIntEnum):
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.

NOTHING = <TargetType.NOTHING: 1>
POINT = <TargetType.POINT: 2>
UNIT = <TargetType.UNIT: 3>
POINT_OR_UNIT = <TargetType.POINT_OR_UNIT: 4>
POINT_OR_NOTHING = <TargetType.POINT_OR_NOTHING: 5>
@final
@dataclass(frozen=True, slots=True)
class UnitTypeData:
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.

UnitTypeData( id: sc2nachos.UnitTypeId, race: sc2nachos.Race, cost: Cost, total_cost: Cost, build_time: sc2nachos.GameTime, supply_provided: float, supply_used: float, cargo_size: int, sight_range: float, speed: float, armor: float, attributes: frozenset[Attribute], weapons: tuple[Weapon, ...], creation_ability: sc2nachos.AbilityId | None, producers: frozenset[sc2nachos.UnitTypeId], tech_requirements: TechRequirements, morphed_from: sc2nachos.UnitTypeId | None, equivalent_types: type[sc2nachos.UnitType.AnyType], ability_requirements: Mapping[sc2nachos.AbilityId, TechRequirements], needs_power: bool, creep_requirement: CreepRequirement | None, techs_granted: frozenset[Tech], has_minerals: bool, has_vespene: bool, footprint: sc2nachos.Footprint | None, upgrades: Mapping[sc2nachos.UpgradeId, UnitTypeUpgrade], _whole_cost: Cost, _unrounded_build_time: sc2nachos.GameTime, turn_rate: float | None = None, moves_while_turning: bool | None = None)

The unit type described.

The race it belongs to.

cost: Cost

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.

total_cost: Cost

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.

build_time: sc2nachos.GameTime

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.

supply_provided: float

What it adds to the supply cap.

supply_used: float

The supply one takes, as the tables give it: half for a zergling, 3 for a sieged tank, 4 for an archon.

cargo_size: int

Slots it fills in a transport.

sight_range: float

Its sight range.

speed: float

Its movement speed, in distance per second at the game's Faster speed (22.4 steps); zero for a structure.

armor: float

The damage it takes off each hit.

attributes: frozenset[Attribute]

Its attributes, which weapons deal bonus damage against.

weapons: tuple[Weapon, ...]

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.

creation_ability: sc2nachos.AbilityId | None

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.

producers: frozenset[sc2nachos.UnitTypeId]

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.

tech_requirements: TechRequirements

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.

morphed_from: sc2nachos.UnitTypeId | None

The unit type used up to make one: a command center for an orbital command, a larva for a zergling, None for a marine.

equivalent_types: type[sc2nachos.UnitType.AnyType]

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.

ability_requirements: Mapping[sc2nachos.AbilityId, TechRequirements]

The abilities a unit of this type can be offered, with the tech each needs first.

needs_power: bool

Whether it needs to be powered by a pylon or a warp prism.

creep_requirement: CreepRequirement | None

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.

techs_granted: frozenset[Tech]

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.

has_minerals: bool

Whether minerals can be mined from it.

has_vespene: bool

Whether vespene can be mined from it.

footprint: sc2nachos.Footprint | 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.

upgrades: Mapping[sc2nachos.UpgradeId, UnitTypeUpgrade]

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.

turn_rate: float | None

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).

moves_while_turning: bool | None

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.

abilities: frozenset[sc2nachos.AbilityId]
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.

def with_upgrades( self, upgrades: Iterable[sc2nachos.UpgradeId]) -> UnitTypeData:
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.

@final
@dataclass(frozen=True, slots=True)
class UnitTypeUpgrade:
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.

UnitTypeUpgrade( armor: float = 0.0, speed: float = 0.0, weapons: tuple[WeaponUpgrade, ...] = ())
armor: float

Added armor.

speed: float

Added movement speed, in distance per second at the game's Faster speed (22.4 steps).

weapons: tuple[WeaponUpgrade, ...]

The change to each weapon, in the type's weapon order, with a WeaponUpgrade() for a weapon left alone. Empty if no weapon changes.

@final
@dataclass(frozen=True, slots=True)
class UpgradeData:
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.

UpgradeData( id: sc2nachos.UpgradeId, cost: Cost, research_ability: sc2nachos.AbilityId | None, researchers: frozenset[sc2nachos.UnitTypeId], tech_requirements: TechRequirements, upgrade_type: UpgradeType, level: int)

The upgrade described.

cost: Cost

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).

research_ability: sc2nachos.AbilityId | None

The ability that researches it.

researchers: frozenset[sc2nachos.UnitTypeId]

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.

tech_requirements: TechRequirements

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).

upgrade_type: UpgradeType

The upgrade level the units it affects report it adding to, or OTHER if they report nothing of it.

level: int

Its level within its line, from 1; 0 for an upgrade that is no level, such as Chitinous Plating.

class UpgradeType(sc2nachos._shared.readable_int_enum.ReadableIntEnum):
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.

OTHER = <UpgradeType.OTHER: 0>

An upgrade a unit reports nothing of, such as Stimpack or Grooved Spines.

ATTACK = <UpgradeType.ATTACK: 1>

Unit.attack_upgrade_level, a count of levels.

ARMOR = <UpgradeType.ARMOR: 2>

Unit.armor_upgrade_level, the armor its upgrades add.

SHIELD = <UpgradeType.SHIELD: 3>

Unit.shield_upgrade_level, a count of levels.

@final
@dataclass(frozen=True, slots=True)
class Weapon:
 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.

Weapon( target_domain: TargetDomain, damage: float, attacks: int, range: float, base_cooldown: sc2nachos.GameTime, damage_bonuses: Mapping[Attribute, float], ignores_armor: bool = False, mean_delay: sc2nachos.GameTime = GameTime(steps=0.4996337890625), turns_to_fire: bool = True)
target_domain: TargetDomain

Whether it can fire at ground, air or both.

damage: float

The damage of one hit, before the target's armor.

attacks: int

Hits per attack: two for a colossus.

range: float

Its range.

base_cooldown: sc2nachos.GameTime

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.

damage_bonuses: Mapping[Attribute, float]

The extra damage per hit against a target with each attribute.

ignores_armor: bool

Whether a hit takes off its whole damage, whatever the target's armor and shield armor: an oracle's beam's (in game).

mean_delay: sc2nachos.GameTime

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).

turns_to_fire: bool

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.

average_cooldown: sc2nachos.GameTime
 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.

total_damage: float
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

The damage of one attack, every hit of it, before bonuses and the target's armor: damage times attacks.

dps: float
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.

def bonus_per_hit_against( self, attributes: Collection[Attribute]) -> float:
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.

def damage_against( self, *, attributes: Collection[Attribute], armor: float, shield_armor: float = 0.0, shield: float = 0.0) -> float:
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.

@final
@dataclass(frozen=True, slots=True)
class WeaponUpgrade:
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.

WeaponUpgrade( damage: float = 0.0, damage_bonuses: Mapping[Attribute, float] = <factory>, range: float = 0.0, attack_speed_multiplier: float = 1.0)
damage: float

Added damage per hit.

damage_bonuses: Mapping[Attribute, float]

Added bonus damage against each attribute, including attributes the weapon had no bonus against.

range: float

Added range.

attack_speed_multiplier: float

How many times as often the weapon attacks: 1.4 for a zergling's with Adrenal Glands (in game).