Class: Sc2::UnitGroup

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Includes:
Enumerable
Defined in:
lib/sc2ai/unit_group.rb,
lib/sc2ai/unit_group/geo_ext.rb,
lib/sc2ai/unit_group/action_ext.rb,
lib/sc2ai/unit_group/filter_ext.rb

Overview

Manage virtual control groups of units, similar to Hash or Array.

Direct Known Subclasses

UnitGroupNotSelector

Defined Under Namespace

Classes: UnitGroupNotSelector

Constant Summary collapse

TYPE_WORKER =

An array of all worker unit type ids

Returns:

[Api::UnitTypeId::SCV, Api::UnitTypeId::MULE, Api::UnitTypeId::DRONE, Api::UnitTypeId::DRONEBURROWED, Api::UnitTypeId::PROBE].freeze
TYPE_GAS_STRUCTURE =

An array of all gas structure unit type ids

Returns:

[
  Api::UnitTypeId::REFINERY,
  Api::UnitTypeId::REFINERYRICH,
  Api::UnitTypeId::ASSIMILATOR,
  Api::UnitTypeId::ASSIMILATORRICH,
  Api::UnitTypeId::EXTRACTOR,
  Api::UnitTypeId::EXTRACTORRICH
].freeze
TYPE_MINERAL =

An array of all mineral unit type ids

Returns:

[
  Api::UnitTypeId::MINERALCRYSTAL,
  Api::UnitTypeId::RICHMINERALFIELD,
  Api::UnitTypeId::RICHMINERALFIELD750,
  Api::UnitTypeId::MINERALFIELD,
  Api::UnitTypeId::MINERALFIELD450,
  Api::UnitTypeId::MINERALFIELD750,
  Api::UnitTypeId::LABMINERALFIELD,
  Api::UnitTypeId::LABMINERALFIELD750,
  Api::UnitTypeId::PURIFIERRICHMINERALFIELD,
  Api::UnitTypeId::PURIFIERRICHMINERALFIELD750,
  Api::UnitTypeId::PURIFIERMINERALFIELD,
  Api::UnitTypeId::PURIFIERMINERALFIELD750,
  Api::UnitTypeId::BATTLESTATIONMINERALFIELD,
  Api::UnitTypeId::BATTLESTATIONMINERALFIELD750,
  Api::UnitTypeId::MINERALFIELDOPAQUE,
  Api::UnitTypeId::MINERALFIELDOPAQUE900
].freeze
TYPE_GEYSER =

An array of all open geyser unit type ids

Returns:

[
  Api::UnitTypeId::VESPENEGEYSER,
  Api::UnitTypeId::SPACEPLATFORMGEYSER,
  Api::UnitTypeId::RICHVESPENEGEYSER,
  Api::UnitTypeId::PROTOSSVESPENEGEYSER,
  Api::UnitTypeId::PURIFIERVESPENEGEYSER,
  Api::UnitTypeId::SHAKURASVESPENEGEYSER
].freeze
TYPE_REJECT_DEBRIS =

An array of all debris unit type ids

Returns:

((TYPE_MINERAL + TYPE_GEYSER) << Api::UnitTypeId::XELNAGATOWER).freeze
TYPE_TECHLAB = 
[
  Api::UnitTypeId::TECHLAB,
  Api::UnitTypeId::BARRACKSTECHLAB,
  Api::UnitTypeId::FACTORYTECHLAB,
  Api::UnitTypeId::STARPORTTECHLAB
].freeze
TYPE_REACTOR =

An array of all reactor structure unit type ids

Returns:

[
  Api::UnitTypeId::REACTOR,
  Api::UnitTypeId::BARRACKSREACTOR,
  Api::UnitTypeId::FACTORYREACTOR,
  Api::UnitTypeId::STARPORTREACTOR
].freeze
TYPE_BASES =

An array of all base structures unit type ids

Returns:

[
  Api::UnitTypeId::COMMANDCENTER, Api::UnitTypeId::COMMANDCENTERFLYING,
  Api::UnitTypeId::ORBITALCOMMAND, Api::UnitTypeId::ORBITALCOMMANDFLYING,
  Api::UnitTypeId::PLANETARYFORTRESS,
  Api::UnitTypeId::HATCHERY, Api::UnitTypeId::HIVE, Api::UnitTypeId::LAIR,
  Api::UnitTypeId::NEXUS
].freeze
TYPE_DETECTORS =

An array of passive detector unit types. Does not include units with detection abilities, such as Oracle/Ghost

Returns:

[
  Api::UnitTypeId::RAVEN, Api::UnitTypeId::MISSILETURRET,
  Api::UnitTypeId::OBSERVER, Api::UnitTypeId::OBSERVERSIEGEMODE,
  Api::UnitTypeId::PHOTONCANNON,
  Api::UnitTypeId::OVERSEER, Api::UnitTypeId::OVERSEERSIEGEMODE,
  Api::UnitTypeId::SPORECRAWLER
].freeze
TYPE_WARPGATE_UNIT =

Protoss: An array of unit types warped from Warp Gate.

Returns:

[
  Api::UnitTypeId::ZEALOT,
  Api::UnitTypeId::STALKER,
  Api::UnitTypeId::HIGHTEMPLAR,
  Api::UnitTypeId::DARKTEMPLAR,
  Api::UnitTypeId::SENTRY,
  Api::UnitTypeId::ADEPT
].freeze
TYPE_MELEE =

An array of all melee units

Returns:

[
  Api::UnitTypeId::SCV,
  Api::UnitTypeId::HELLIONTANK,
  Api::UnitTypeId::PROBE,
  Api::UnitTypeId::DARKTEMPLAR,
  Api::UnitTypeId::ZEALOT,
  Api::UnitTypeId::DRONE,
  Api::UnitTypeId::DRONEBURROWED,
  Api::UnitTypeId::ZERGLING,
  Api::UnitTypeId::ZERGLINGBURROWED,
  Api::UnitTypeId::BANELING,
  Api::UnitTypeId::BANELINGBURROWED,
  Api::UnitTypeId::ULTRALISK,
  Api::UnitTypeId::ULTRALISKBURROWED,
  Api::UnitTypeId::BROODLING
].freeze
TYPE_RANGE =

Typical units you would consider to be Ranged Units Includes: BROODLORD and CARRIER even though they spawn units and don’t attack by themselves. ORACLE. and all BURROWED variants of units. Excludes strict spellcasters: MEDIVAC, RAVEN, INFESTOR, SWARMHOSTMP, DISRUPTOR

[
  # Terran
  Api::UnitTypeId::MARINE,
  Api::UnitTypeId::MARAUDER,
  Api::UnitTypeId::REAPER,
  Api::UnitTypeId::GHOST,
  Api::UnitTypeId::HELLION,
  Api::UnitTypeId::WIDOWMINE,
  Api::UnitTypeId::WIDOWMINEBURROWED,
  Api::UnitTypeId::SIEGETANK,
  Api::UnitTypeId::SIEGETANKSIEGED,
  Api::UnitTypeId::CYCLONE,
  Api::UnitTypeId::THOR,
  Api::UnitTypeId::THORAP,
  Api::UnitTypeId::VIKINGASSAULT,
  Api::UnitTypeId::VIKINGFIGHTER,
  Api::UnitTypeId::AUTOTURRET,
  Api::UnitTypeId::BANSHEE,
  Api::UnitTypeId::BATTLECRUISER,
  Api::UnitTypeId::LIBERATOR,
  Api::UnitTypeId::LIBERATORAG,
  Api::UnitTypeId::MISSILETURRET,

  # Zerg
  Api::UnitTypeId::ROACH,
  Api::UnitTypeId::ROACHBURROWED,
  Api::UnitTypeId::RAVAGER,
  Api::UnitTypeId::RAVAGERBURROWED,
  Api::UnitTypeId::HYDRALISK,
  Api::UnitTypeId::HYDRALISKBURROWED,
  Api::UnitTypeId::MUTALISK,
  Api::UnitTypeId::CORRUPTOR,
  Api::UnitTypeId::BROODLORD,
  Api::UnitTypeId::QUEEN,
  Api::UnitTypeId::QUEENBURROWED,
  Api::UnitTypeId::LURKERMP,
  Api::UnitTypeId::LURKERMPBURROWED,
  Api::UnitTypeId::LOCUSTMP,
  Api::UnitTypeId::SPINECRAWLER,
  Api::UnitTypeId::SPINECRAWLERUPROOTED,
  Api::UnitTypeId::SPORECRAWLER,
  Api::UnitTypeId::SPORECRAWLERUPROOTED,

  # Protoss
  Api::UnitTypeId::SENTRY,
  Api::UnitTypeId::STALKER,
  Api::UnitTypeId::IMMORTAL,
  Api::UnitTypeId::ARCHON,
  Api::UnitTypeId::HIGHTEMPLAR,
  Api::UnitTypeId::ADEPT,
  Api::UnitTypeId::ORACLE,
  Api::UnitTypeId::PHOENIX,
  Api::UnitTypeId::VOIDRAY,
  Api::UnitTypeId::TEMPEST,
  Api::UnitTypeId::INTERCEPTOR,
  Api::UnitTypeId::CARRIER,
  Api::UnitTypeId::MOTHERSHIP,
  Api::UnitTypeId::PHOTONCANNON
].freeze
TYPE_TERRAN_INFANTRY =

Terran: An array if infantry (Barracks) unit types

Returns:

[
  Api::UnitTypeId::REAPER,
  Api::UnitTypeId::MARINE,
  Api::UnitTypeId::MARAUDER,
  Api::UnitTypeId::GHOST
].freeze
TYPE_TERRAN_VEHICLE =

Terran: An array if vehicle (Factory) unit types

Returns:

[
  Api::UnitTypeId::HELLION,
  Api::UnitTypeId::HELLIONTANK,
  Api::UnitTypeId::WIDOWMINE,
  Api::UnitTypeId::WIDOWMINEBURROWED,
  Api::UnitTypeId::SIEGETANK,
  Api::UnitTypeId::SIEGETANKSIEGED,
  Api::UnitTypeId::THOR,
  Api::UnitTypeId::THORAP
].freeze
TYPE_ZERG_MELEE =

Zerg: An array unit types which are Melee and benefit from Melee upgrades

Returns:

[
  Api::UnitTypeId::DRONE,
  Api::UnitTypeId::DRONEBURROWED,
  Api::UnitTypeId::ZERGLING,
  Api::UnitTypeId::ZERGLINGBURROWED,
  Api::UnitTypeId::BANELING,
  Api::UnitTypeId::BANELINGBURROWED,
  Api::UnitTypeId::ULTRALISK,
  Api::UnitTypeId::ULTRALISKBURROWED,
  Api::UnitTypeId::BROODLING
].freeze
TYPE_ZERG_MISSILE =

Zerg: An array of unit types which use missile attacks and upgrades

Returns:

[
  Api::UnitTypeId::ROACH,
  Api::UnitTypeId::ROACHBURROWED,
  Api::UnitTypeId::RAVAGER,
  Api::UnitTypeId::RAVAGERBURROWED,
  Api::UnitTypeId::HYDRALISK,
  Api::UnitTypeId::HYDRALISKBURROWED,
  Api::UnitTypeId::QUEEN,
  Api::UnitTypeId::QUEENBURROWED,
  Api::UnitTypeId::LURKERMP,
  Api::UnitTypeId::LURKERMPBURROWED,
  Api::UnitTypeId::LOCUSTMP,
  Api::UnitTypeId::SPINECRAWLER,
  Api::UnitTypeId::SPINECRAWLERUPROOTED,
  Api::UnitTypeId::SPORECRAWLER,
  Api::UnitTypeId::SPORECRAWLERUPROOTED
].freeze
TYPE_FLYING =

An array of flying unit types Exceptions: Locusts are always ground units

Returns:

[
  # Terran
  Api::UnitTypeId::MEDIVAC,
  Api::UnitTypeId::VIKINGFIGHTER,
  Api::UnitTypeId::BANSHEE,
  Api::UnitTypeId::RAVEN,
  Api::UnitTypeId::BATTLECRUISER,
  Api::UnitTypeId::POINTDEFENSEDRONE,
  Api::UnitTypeId::LIBERATOR,

  # Zerg
  Api::UnitTypeId::OVERLORD, Api::UnitTypeId::OVERLORDCOCOON,
  Api::UnitTypeId::OVERSEER, Api::UnitTypeId::OVERSEERSIEGEMODE,
  Api::UnitTypeId::MUTALISK,
  Api::UnitTypeId::CORRUPTOR,
  Api::UnitTypeId::BROODLORD, Api::UnitTypeId::BROODLORDCOCOON,

  # Protoss
  Api::UnitTypeId::OBSERVER, Api::UnitTypeId::OBSERVERSIEGEMODE,
  Api::UnitTypeId::WARPPRISM, Api::UnitTypeId::WARPPRISMPHASING,
  Api::UnitTypeId::PHOENIX,
  Api::UnitTypeId::VOIDRAY,
  Api::UnitTypeId::CARRIER,
  Api::UnitTypeId::INTERCEPTOR,
  Api::UnitTypeId::MOTHERSHIP,
  Api::UnitTypeId::ORACLE,
  Api::UnitTypeId::TEMPEST
].freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(units = nil) ⇒ Object

Returns Sc2::UnitGroup new unit group.

Parameters:



18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
 
# File 'lib/sc2ai/unit_group.rb', line 18

def initialize(units = nil)
  @units = {}
  case units
  when Array
    units.each do |unit|
      @units[unit.tag] = unit
    end
  when Hash
    @units = units
  when UnitGroup
    @units = units.units
  else
    # noop
  end

  @_cache_hash = {}
  @_cache = {}
end

Instance Attribute Details

#units ⇒ Hash<Integer, Api::Unit>

A hash of units by tag.

Returns:

  • (Hash<Integer, Api::Unit>) —

    Api::Unit.tag => Api::Unit



14
15
16
 
# File 'lib/sc2ai/unit_group.rb', line 14

def units
  @units
end

#use_kdtree ⇒ Boolean

Whether we should be building a kdtree Added to allow the disabling of this property i.e. allows optimization of not to build if group is too big:

return @units.size > 200

If you don’t do a lot of repeat filtering and don’t get gains from repeated searches then override the attribute and set this to: @units.size > 120

Returns:

  • (Boolean) 


613
614
615
 
# File 'lib/sc2ai/unit_group/filter_ext.rb', line 613

def use_kdtree
  @use_kdtree
end

Instance Method Details

#:@units(: []) ⇒ Object

Forwards to hash of #units.

See Also:

  • Hash#:[]


50
 
# File 'lib/sc2ai/unit_group.rb', line 50

def_delegator :@units, :<

#[]=(unit_tag, unit) ⇒ Object

Associates a given unit tag with a given unit.

See Also:



132
133
134
135
 
# File 'lib/sc2ai/unit_group.rb', line 132

def []=(unit_tag, unit)
  return if unit_tag.nil? || unit.nil?
  @units[unit_tag] = unit
end

#ability_available?(ability_id) ⇒ Sc2::UnitGroup

Selects units which have this ability available Queries API if necessary

Parameters:

  • ability_id (Integer)

Returns:



484
485
486
 
# File 'lib/sc2ai/unit_group/filter_ext.rb', line 484

def ability_available?(ability_id)
  select { |unit| unit.ability_available?(ability_id) }
end

#action(ability_id:, target: nil, queue_command: false) ⇒ void

This method returns an undefined value.

Performs action on all units in this group

Parameters:

  • ability_id (Integer)
  • target (Api::Unit, Integer, Api::Point2D) (defaults to: nil) —

    is a unit, unit tag or a Api::Point2D

  • queue_command (Boolean) (defaults to: false) —

    shift+command



18
19
20
21
22
23
24
 
# File 'lib/sc2ai/unit_group/action_ext.rb', line 18

def action(ability_id:, target: nil, queue_command: false)
  return if size.zero?

  # We're simply not letting unit groups be bot aware if units already are.
  # Grab the first unit's bot to perform actions, if necessary
  bot&.action(units: self, ability_id:, target:, queue_command:)
end

#add(units) ⇒ self Also known as: push

Adds a unit or units to the group.

Parameters:

Returns:

  • (self) 


140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
 
# File 'lib/sc2ai/unit_group.rb', line 140

def add(units)
  case units
  when Api::Unit
    @units[units.tag] = units
  when Array
    units.each do |unit|
      @units[unit.tag] = unit
    end
  when Hash
    @units.merge(units.units)
  when UnitGroup
    @units.merge(units)
  else
    # noop
  end
  @units
end

#army ⇒ Sc2::UnitGroup

Selects non army units workers. Generally run on Sc2::Player#units

Examples:

in the Player context

fighters = units.army
enemy_fighters = units.army

Returns:

See Also:



412
413
414
 
# File 'lib/sc2ai/unit_group/filter_ext.rb', line 412

def army
  reject_type(non_army_unit_type_ids)
end

#at(index) ⇒ Api::Unit

Gets the Unit at an index

Returns:



89
90
91
 
# File 'lib/sc2ai/unit_group.rb', line 89

def at(index)
  @units[tags.at(index)]
end

#attack(target:, queue_command: false) ⇒ Object

Shorthand for performing action ATTACK

Parameters:

  • target (Api::Unit, Integer, Api::Point2D) —

    is a unit, unit tag or a Api::Point2D

  • queue_command (Boolean) (defaults to: false) —

    shift+command



89
90
91
 
# File 'lib/sc2ai/unit_group/action_ext.rb', line 89

def attack(target:, queue_command: false)
  action(ability_id: Api::AbilityId::ATTACK, target:, queue_command:)
end

#bases ⇒ Sc2::UnitGroup Also known as: hq, townhalls

Selects command posts (CC, OC, PF, Nexus, Hatch, Hive, Lair) Aliases are #hq and #townhalls

Returns:



441
442
443
 
# File 'lib/sc2ai/unit_group/filter_ext.rb', line 441

def bases
  select_type(TYPE_BASES)
end

#bot ⇒ Sc2::Player?

Our first unit’s bot object. Returns nil if units are empty, so use safety operator bot&.method(…)

Returns:



9
10
11
 
# File 'lib/sc2ai/unit_group/action_ext.rb', line 9

def bot
  @bot ||= first&.bot
end

#build(unit_type_id:, target: nil, queue_command: false) ⇒ Object Also known as: train

Builds target unit type, i.e. issuing a build command to worker.build(…Api::UnitTypeId::BARRACKS)

Parameters:

  • unit_type_id (Integer) —

    Api::UnitTypeId the unit type you wish to build

  • target (Api::Point2D, Api::Unit, Integer, nil) (defaults to: nil) —

    is a unit tag or a Api::Point2D. Nil for addons/orbital

  • queue_command (Boolean) (defaults to: false) —

    shift+command



30
31
32
33
34
 
# File 'lib/sc2ai/unit_group/action_ext.rb', line 30

def build(unit_type_id:, target: nil, queue_command: false)
  return if size.zero?

  bot&.build(units: self, unit_type_id:, target:, queue_command:)
end

#clear ⇒ Object

Forwards to hash of #units.

See Also:

  • Hash#clear


69
 
# File 'lib/sc2ai/unit_group.rb', line 69

def_delegator :@units, :clear

#completed ⇒ Sc2::UnitGroup

Selects only units which have finished constructing, i.o.w. build_progress == 1.0

Returns:



464
465
466
 
# File 'lib/sc2ai/unit_group/filter_ext.rb', line 464

def completed
  select(&:is_completed?)
end

#contains?(unit) ⇒ Boolean

Checks whether this group contains a unit.

Parameters:

  • unit (Api::Unit, Integer) —

    a unit or a tag.

Returns:

  • (Boolean) —

    A boolean indicating if the #units include? unit.



125
126
127
128
 
# File 'lib/sc2ai/unit_group.rb', line 125

def contains?(unit)
  tag = unit.is_a?(Api::Unit) ? unit.tag : unit
  @units.include?(tag)
end

#creep_tumors ⇒ Sc2::UnitGroup Also known as: tumors

Selects creep tumors (all) CREEPTUMORQUEEN is still building & burrowing while CREEPTUMOR was spread from another tumor still building & burrowing and CREEPTUMORBURROWED are burrowed tumors which have already spread or can still spread more

Returns:

See Also:



571
572
573
 
# File 'lib/sc2ai/unit_group/filter_ext.rb', line 571

def creep_tumors
  select_type([Api::UnitTypeId::CREEPTUMORQUEEN, Api::UnitTypeId::CREEPTUMOR, Api::UnitTypeId::CREEPTUMORBURROWED])
end

#creep_tumors_burrowed ⇒ Sc2::UnitGroup

Selects creep tumors which are burrowed. Burrowed tumors have already been spread or are spread-ready. No way to distinguish spreadable tumors without manual tracking.

Returns:

  • (Sc2::UnitGroup) —

    burrowed tumors (with and without spread ability)



580
581
582
 
# File 'lib/sc2ai/unit_group/filter_ext.rb', line 580

def creep_tumors_burrowed
  select_type(Api::UnitTypeId::CREEPTUMORBURROWED)
end

#debris ⇒ Sc2::UnitGroup

Reverse filters our minerals, geysers and towers to get what is hopefully debris

Examples:

# Typically a Player selects via group @neutral
@neutral.debris

Returns:



529
530
531
 
# File 'lib/sc2ai/unit_group/filter_ext.rb', line 529

def debris
  reject_type(TYPE_REJECT_DEBRIS)
end

#delete_if ⇒ Object

Forwards to hash of #units.

See Also:

  • Hash#delete_if


70
 
# File 'lib/sc2ai/unit_group.rb', line 70

def_delegator :@units, :delete_if

#detect ⇒ Api::Unit Also known as: find

Returns the first Unit for which the block returns a truthy value

Returns:



256
257
258
 
# File 'lib/sc2ai/unit_group.rb', line 256

def detect(...)
  @units.values.find(...)
end

#detectors ⇒ Sc2::UnitGroup

Selects units passively have Detection

Returns:



458
459
460
 
# File 'lib/sc2ai/unit_group/filter_ext.rb', line 458

def detectors
  select_type(TYPE_DETECTORS)
end

#each {|unit| ... } ⇒ Object

Calls the given block with each Api::Unit value

Examples:

unit_group.each do |unit|
   puts unit.tag #=> 1234 ...
end

Yield Parameters:



105
106
107
 
# File 'lib/sc2ai/unit_group.rb', line 105

def each(&)
  @units.each_value(&)
end

#each_with_tag {|tag, unit| ... } ⇒ self

Calls the given block with each key-value pair

Examples:

unit_group.each_with_tag do |tag, unit|
   puts "#{tag}: #{unit}"} #=> "12345: #<Api::Unit ...>"
end

Yield Parameters:

Returns:

  • (self) —

    a new unit group with items merged



117
118
119
120
 
# File 'lib/sc2ai/unit_group.rb', line 117

def each_with_tag(&)
  @units.each(&)
  self
end

#eggs ⇒ Sc2::UnitGroup

Selects eggs. Eggs come from Larva and turn into Units.

Returns:



543
544
545
 
# File 'lib/sc2ai/unit_group/filter_ext.rb', line 543

def eggs
  select_type(Api::UnitTypeId::EGG)
end

#empty? ⇒ Object

Forwards to hash of #units.

See Also:

  • Hash#empty?


41
 
# File 'lib/sc2ai/unit_group.rb', line 41

def_delegator :@units, :empty?

#eql? ⇒ Object

Forwards to hash of #units.

See Also:

  • Hash#eql?


42
 
# File 'lib/sc2ai/unit_group.rb', line 42

def_delegator :@units, :eql?

#except ⇒ Sc2::UnitGroup

Returns a copy of self with units removed for specified tags.

Returns:



229
230
231
 
# File 'lib/sc2ai/unit_group.rb', line 229

def except(...)
  UnitGroup.new(@units.except(...))
end

#filter! ⇒ Object

Forwards to hash of #units.

See Also:

  • Hash#filter!


72
 
# File 'lib/sc2ai/unit_group.rb', line 72

def_delegator :@units, :filter!

#first ⇒ Api::Unit

Returns:




# File 'lib/sc2ai/unit_group.rb', line 93

#gas ⇒ Sc2::UnitGroup Also known as: refineries, extractors, assimilators

Selects gas structures (refinery/extractor/assimilator)

Returns:



449
450
451
 
# File 'lib/sc2ai/unit_group/filter_ext.rb', line 449

def gas
  select_type(TYPE_GAS_STRUCTURE)
end

#geysers ⇒ Sc2::UnitGroup

Selects gas geysers

Examples:

# Typically a Player selects via group @neutral
@neutral.geysers

Returns:



511
512
513
 
# File 'lib/sc2ai/unit_group/filter_ext.rb', line 511

def geysers
  select_type(TYPE_GEYSER)
end

#hash ⇒ Object

Forwards to hash of #units.

See Also:

  • Hash#hash


84
 
# File 'lib/sc2ai/unit_group.rb', line 84

def_delegator :@units, :hash

#hold(queue_command: false) ⇒ Object Also known as: hold_position

Shorthand for performing action HOLDPOSITION

Parameters:

  • queue_command (Boolean) (defaults to: false) —

    shift+command



81
82
83
 
# File 'lib/sc2ai/unit_group/action_ext.rb', line 81

def hold(queue_command: false)
  action(ability_id: Api::AbilityId::HOLDPOSITION, queue_command:)
end

#idle ⇒ Sc2::UnitGroup

Selects only units which do not have orders

Returns:



476
477
478
 
# File 'lib/sc2ai/unit_group/filter_ext.rb', line 476

def idle
  select(&:is_idle?)
end

#incomplete ⇒ Sc2::UnitGroup

Selects only units which have finished constructing, i.o.w. build_progress != 1.0

Returns:



470
471
472
 
# File 'lib/sc2ai/unit_group/filter_ext.rb', line 470

def incomplete
  reject(&:is_completed?)
end

#intersection(other_unit_group) ⇒ Sc2::UnitGroup Also known as: &

Returns a new unit group containing each element found both in self and in all of the given other_arrays; duplicates are omitted; items are compared using eql? (items must also implement hash correctly):

Parameters:

Returns:



242
243
244
 
# File 'lib/sc2ai/unit_group.rb', line 242

def intersection(other_unit_group)
  slice(*other_unit_group.tags)
end

#is_performing_ability?(ability_ids) ⇒ Boolean

Checks whether any unit’s first order matches these abilities

Parameters:

  • ability_ids (Integer, Array<Integer>) —

    accepts one or an array of Api::AbilityId

Returns:

  • (Boolean) 


491
492
493
 
# File 'lib/sc2ai/unit_group/filter_ext.rb', line 491

def is_performing_ability?(ability_ids)
  any? { |unit| unit.is_performing_ability?(ability_ids) }
end

#kdtree ⇒ ::Kdtree

Builds a kdtree if not already built and returns it

Returns:

  • (::Kdtree) 


617
618
619
620
 
# File 'lib/sc2ai/unit_group/filter_ext.rb', line 617

def kdtree
  return @kdtree unless @kdtree.nil?
  @kdtree = Kdtree.new(@units.values.each_with_index.map { |unit, index| [unit.pos.x, unit.pos.y, index] })
end

#keep_if ⇒ Object

Forwards to hash of #units.

See Also:

  • Hash#keep_if


73
 
# File 'lib/sc2ai/unit_group.rb', line 73

def_delegator :@units, :keep_if

#keys ⇒ Object

Forwards to hash of #units.

See Also:

  • Hash#keys


61
 
# File 'lib/sc2ai/unit_group.rb', line 61

def_delegator :@units, :keys

#larva ⇒ Sc2::UnitGroup Also known as: larvae

ZERG —————————————— Selects larva units

Returns:



536
537
538
 
# File 'lib/sc2ai/unit_group/filter_ext.rb', line 536

def larva
  select_type(Api::UnitTypeId::LARVA)
end

#last ⇒ Api::Unit

Returns:




# File 'lib/sc2ai/unit_group.rb', line 93

#length ⇒ Object

Forwards to hash of #units.

See Also:

  • Hash#length


43
 
# File 'lib/sc2ai/unit_group.rb', line 43

def_delegator :@units, :length

#merge(unit_group) ⇒ Sc2::UnitGroup Also known as: +

Merges unit_group with our units and returns a new unit group

Returns:



190
191
192
 
# File 'lib/sc2ai/unit_group.rb', line 190

def merge(unit_group)
  UnitGroup.new(@units.merge(unit_group))
end

#merge!(unit_group) ⇒ self

Merges unit_group.units into self.units and returns self

Returns:

  • (self) 


197
198
199
200
 
# File 'lib/sc2ai/unit_group.rb', line 197

def merge!(unit_group)
  @units.merge!(unit_group.units)
  self
end

#minerals ⇒ Sc2::UnitGroup

Selects mineral fields

Examples:

# Typically a Player selects via group @neutral
@neutral.minerals

Returns:



502
503
504
 
# File 'lib/sc2ai/unit_group/filter_ext.rb', line 502

def minerals
  select_type(TYPE_MINERAL)
end

#move(target:, queue_command: false) ⇒ Object

Shorthand for performing action MOVE

Parameters:

  • target (Api::Unit, Integer, Api::Point2D) —

    is a unit, unit tag or a Api::Point2D

  • queue_command (Boolean) (defaults to: false) —

    shift+command



69
70
71
 
# File 'lib/sc2ai/unit_group/action_ext.rb', line 69

def move(target:, queue_command: false)
  action(ability_id: Api::AbilityId::MOVE, target:, queue_command:)
end

#nearest_to(pos:, amount: nil) ⇒ Sc2::UnitGroup, ...

Returns an

Parameters:

Returns:



625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
 
# File 'lib/sc2ai/unit_group/filter_ext.rb', line 625

def nearest_to(pos:, amount: nil)
  unless amount.nil?
    return UnitGroup.new if amount <= 0
    return self if amount > @units.size
  end

  if use_kdtree || use_kdtree.nil?
    if amount.nil?
      index = kdtree.nearest(pos.x, pos.y)
      return @units.values[index]
    else
      result_indexes = kdtree.nearestk(pos.x, pos.y, amount)
      return UnitGroup.new(@units.values.values_at(*result_indexes))
    end
  end

  # Traditional array min_by with distance calcs on the fly
  if amount.nil?
    # noinspection RubyMismatchedReturnType
    @units.values.min_by { |unit| unit.distance_to(pos) }
  else
    UnitGroup.new(@units.values.min_by(amount) { |unit| unit.distance_to(pos) })
  end
end

#non_army_unit_type_ids ⇒ Object

Contains an array non-army types Override to remove or add units you want units.army to exclude

Examples:

# i.e. to have units.army to exclude Overseers
@non_army_unit_types.push(Api::UnitTypeId::OVERSEER)
# i.e. to have units.army to include Queens
@non_army_unit_types.delete(Api::UnitTypeId::QUEEN)
@non_army_unit_types.delete(Api::UnitTypeId::QUEENBURROWED)


430
431
432
433
434
435
436
 
# File 'lib/sc2ai/unit_group/filter_ext.rb', line 430

def non_army_unit_type_ids
  @non_army_unit_type_ids ||= TYPE_WORKER + [
    Api::UnitTypeId::QUEEN, Api::UnitTypeId::QUEENBURROWED,
    Api::UnitTypeId::OVERLORD, Api::UnitTypeId::OVERLORDCOCOON,
    Api::UnitTypeId::LARVA
  ]
end

#not ⇒ Sc2::UnitGroup::UnitGroupNotSelector

Creates a negative selector, which will perform the opposite on the current scope

for it's next select_type/reject_type call.

Examples:

structures.not.creep_tumors #=> all structures
structures.not.pylons #=>
units.not.workers # equivalent of units.army, but works too

Returns:



320
321
322
 
# File 'lib/sc2ai/unit_group/filter_ext.rb', line 320

def not
  UnitGroupNotSelector.new(self)
end

#overlords ⇒ Sc2::UnitGroup

Selects overlords

Returns:



555
556
557
 
# File 'lib/sc2ai/unit_group/filter_ext.rb', line 555

def overlords
  select_type([Api::UnitTypeId::OVERLORD, Api::UnitTypeId::OVERLORDTRANSPORT, Api::UnitTypeId::TRANSPORTOVERLORDCOCOON])
end

#overseers ⇒ Sc2::UnitGroup

Selects overseers

Returns:



561
562
563
 
# File 'lib/sc2ai/unit_group/filter_ext.rb', line 561

def overseers
  select_type([Api::UnitTypeId::OVERLORDCOCOON, Api::UnitTypeId::OVERSEER, Api::UnitTypeId::OVERSEERSIEGEMODE])
end

#owned ⇒ Sc2::UnitGroup

Selects units you own i.e. @bot.all_units.owned # => Units you own

Returns:



394
395
396
397
398
 
# File 'lib/sc2ai/unit_group/filter_ext.rb', line 394

def owned
  cached("#{__method__}:SELF") do
    select { |unit| unit.alliance == :SELF }
  end
end

#pos_centroid ⇒ Api::Point2D?

Returns the center (average) position of all units or nil if the group is empty. Outliers effect this point

Returns:



9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
 
# File 'lib/sc2ai/unit_group/geo_ext.rb', line 9

def pos_centroid
  return nil if size == 0
  size = @units.size
  sum_x = 0.0
  sum_y = 0.0
  i = 0

  while i < size
    unit = at(i)
    sum_x += unit.pos.x.to_f
    sum_y += unit.pos.y.to_f
    i += 1
  end

  Api::Point2D[sum_x / size.to_f, sum_y / size.to_f]
end

#pylons ⇒ Sc2::UnitGroup

Selects pylons

Returns:



588
589
590
 
# File 'lib/sc2ai/unit_group/filter_ext.rb', line 588

def pylons
  select_type(Api::UnitTypeId::PYLON)
end

#queens ⇒ Sc2::UnitGroup

Selects queens

Returns:



549
550
551
 
# File 'lib/sc2ai/unit_group/filter_ext.rb', line 549

def queens
  select_type([Api::UnitTypeId::QUEEN, Api::UnitTypeId::QUEENBURROWED])
end

#reject(&block) ⇒ Sc2::UnitGroup

Returns a new UnitGroup object whose entries are all those from #units for which the block returns false or nil noinspection RubyMismatchedReturnType # UnitGroup acts as an array, so sig is ok.

Returns:



222
223
224
225
 
# File 'lib/sc2ai/unit_group.rb', line 222

def reject(&block)
  result = @units.reject { |_tag, unit| yield unit }
  UnitGroup.new(result)
end

#reject! ⇒ Object

Forwards to hash of #units.

See Also:

  • Hash#reject!


78
 
# File 'lib/sc2ai/unit_group.rb', line 78

def_delegator :@units, :reject!

#reject_attribute(attributes) ⇒ Sc2::UnitGroup

Returns a new UnitGroup containing all units excluding attribute id(s) Multiple values work as an “AND” filter

Examples:

# Single
ug.reject_attribute(Api::Attribute::STRUCTURE) #=> <UnitGroup: ...>
ug.reject_attribute(:Structure) #=> <UnitGroup: ...>
# Multiple - reject mechanical flying units
ug.reject_attribute(:Mechanical, :Flying) #=> <UnitGroup: ...>

Parameters:

  • attributes (Integer, Array<Integer>) —

    one or an array of unit Api::UnitTypeId

Returns:



379
380
381
382
383
384
385
386
387
 
# File 'lib/sc2ai/unit_group/filter_ext.rb', line 379

def reject_attribute(attributes)
  cached("#{__method__}:#{attributes.hash}") do
    attributes = [attributes] unless attributes.is_a? Array
    attributes = attributes.map { |a| a.is_a?(Symbol) ? Api::Attribute.lookup(a) : a }
    reject do |unit|
      unit.attributes & attributes == attributes
    end
  end
end

#reject_type(unit_type_ids) ⇒ Sc2::UnitGroup

Returns a new UnitGroup excluding all units matching unit type id(s)

Examples:

# Single
ug.reject_type(Api::UnitTypeId::SCV) #=> <UnitGroup: ...>
# Multiple - reject immovable army
ug.reject_type([Api::UnitTypeId::SIEGETANKSIEGED, Api::UnitTypeId::WIDOWMINEBURROWED]) #=> <UnitGroup: ...>

Parameters:

  • unit_type_ids (Integer, Array<Integer>) —

    one or an array of unit Api::UnitTypeId

Returns:



303
304
305
306
307
308
309
310
311
 
# File 'lib/sc2ai/unit_group/filter_ext.rb', line 303

def reject_type(unit_type_ids)
  cached("#{__method__}:#{unit_type_ids.hash}") do
    if unit_type_ids.is_a? Array
      reject { |unit| unit_type_ids.include?(unit.unit_type) }
    else
      reject { |unit| unit_type_ids == unit.unit_type }
    end
  end
end

#remove(unit_group_unit_or_tag) ⇒ Hash<Integer, Api::Unit>, ... Also known as: delete

Remove a another UnitGroup’s units from ours or a singular Api::Unit either by object or Api::Unit#tag

Parameters:

Returns:



163
164
165
166
167
168
169
170
171
172
173
174
175
 
# File 'lib/sc2ai/unit_group.rb', line 163

def remove(unit_group_unit_or_tag)
  case unit_group_unit_or_tag
  when Sc2::UnitGroup
    @units.reject! { |tag, _unit| unit_group_unit_or_tag.units.has_key?(tag) }
  when Api::Unit
    @units.delete(unit_group_unit_or_tag.tag)
  when Integer
    # noinspection RubyMismatchedArgumentType
    @units.delete(unit_group_unit_or_tag)
  else
    # noop
  end
end

#repair(target:, queue_command: false) ⇒ Object

Issues repair command on target

Parameters:

  • target (Api::Unit, Integer) —

    is a unit or unit tag



95
96
97
 
# File 'lib/sc2ai/unit_group/action_ext.rb', line 95

def repair(target:, queue_command: false)
  action(ability_id: Api::AbilityId::EFFECT_REPAIR, target:, queue_command:)
end

#replace(unit_group) ⇒ void

This method returns an undefined value.

Replaces the entire contents of #units with the contents of a given unit_group. Synonymous with self.units = unit_group.units



205
206
207
 
# File 'lib/sc2ai/unit_group.rb', line 205

def replace(unit_group)
  @units = unit_group.units
end

#research(upgrade_id:, queue_command: false) ⇒ Object

Research a specific upgrade at one of these structures

Parameters:

  • upgrade_id (Integer) —

    Api::UpgradeId to research

  • queue_command (Boolean) (defaults to: false) —

    shift+command



53
54
55
56
57
 
# File 'lib/sc2ai/unit_group/action_ext.rb', line 53

def research(upgrade_id:, queue_command: false)
  return if size.zero?

  bot&.research(units: self, upgrade_id:, queue_command:)
end

#sample ⇒ Api::Unit Also known as: random

Selects a single random Unit without a parameter or an array of Units with a param, i.e. self.random(2)

Returns:



249
250
251
 
# File 'lib/sc2ai/unit_group.rb', line 249

def sample(...)
  @units.values.sample(...)
end

#select ⇒ Sc2::UnitGroup Also known as: filter

Returns a new UnitGroup object whose #units entries are those for which the block returns a truthy value noinspection RubyMismatchedReturnType # UnitGroup acts as an array, so sig is ok.

Returns:



212
213
214
215
 
# File 'lib/sc2ai/unit_group.rb', line 212

def select
  result = @units.select { |_tag, unit| yield unit }
  UnitGroup.new(result)
end

#select! ⇒ Object

Forwards to hash of #units.

See Also:

  • Hash#select!


71
 
# File 'lib/sc2ai/unit_group.rb', line 71

def_delegator :@units, :select!

#select_attribute(attributes) ⇒ Sc2::UnitGroup

Returns a new UnitGroup containing all units matching attribute id(s) Multiple values work as an “AND” filter

Examples:

# Single
ug.select_attribute(Api::Attribute::STRUCTURE) #=> <UnitGroup: ...>
ug.select_attribute(:Structure) #=> <UnitGroup: ...>
# Multiple - select mechanical flying units
ug.select_attribute([:MECHANICAL, :FLYING]) #=> <UnitGroup: ...>

Parameters:

  • attributes (Integer, Array<Integer>) —

    one or an array of unit Api::UnitTypeId

Returns:



359
360
361
362
363
364
365
366
367
 
# File 'lib/sc2ai/unit_group/filter_ext.rb', line 359

def select_attribute(attributes)
  cached("#{__method__}:#{attributes.hash}") do
    attributes = [attributes] unless attributes.is_a? Array
    attributes = attributes.map { |a| a.is_a?(Symbol) ? Api::Attribute.lookup(a) : a }
    select do |unit|
      attributes & unit.attributes == attributes
    end
  end
end

#select_in_circle(point:, radius:) ⇒ Sc2::UnitGroup

Selects units which are in a particular circle

Parameters:

Returns:



654
655
656
 
# File 'lib/sc2ai/unit_group/filter_ext.rb', line 654

def select_in_circle(point:, radius:)
  select { |unit| unit.in_circle?(point:, radius:) }
end

#select_type(unit_type_ids) ⇒ Sc2::UnitGroup

Returns a new UnitGroup containing all units matching unit type id(s) Multiple values work as an “OR” filter

Examples:

# Single
ug.select_type(Api::UnitTypeId::MARINE) #=> <UnitGroup: ...>
# Multiple - select space-men
ug.select_type([Api::UnitTypeId::MARINE, Api::UnitTypeId::REAPER]) #=> <UnitGroup: ...>

Parameters:

  • unit_type_ids (Integer, Array<Integer>) —

    one or an array of unit Api::UnitTypeId

Returns:



285
286
287
288
289
290
291
292
293
 
# File 'lib/sc2ai/unit_group/filter_ext.rb', line 285

def select_type(unit_type_ids)
  cached("#{__method__}:#{unit_type_ids.hash}") do
    if unit_type_ids.is_a? Array
      select { |unit| unit_type_ids.include?(unit.unit_type) }
    else
      select { |unit| unit_type_ids == unit.unit_type }
    end
  end
end

#shift ⇒ Object

Forwards to hash of #units.

See Also:

  • Hash#shift


79
 
# File 'lib/sc2ai/unit_group.rb', line 79

def_delegator :@units, :shift

#size ⇒ Object

Forwards to hash of #units.

See Also:

  • Hash#size


44
 
# File 'lib/sc2ai/unit_group.rb', line 44

def_delegator :@units, :size

#slice ⇒ Sc2::UnitGroup

Returns a new unit group containing the entries for given tag(s).

Returns:



235
236
237
 
# File 'lib/sc2ai/unit_group.rb', line 235

def slice(...)
  UnitGroup.new(@units.slice(...))
end

#smart(target: nil, queue_command: false) ⇒ Object

Shorthand for performing action SMART (right-click)

Parameters:

  • target (Api::Unit, Integer, Api::Point2D) (defaults to: nil) —

    is a unit, unit tag or a Api::Point2D

  • queue_command (Boolean) (defaults to: false) —

    shift+command



62
63
64
 
# File 'lib/sc2ai/unit_group/action_ext.rb', line 62

def smart(target: nil, queue_command: false)
  action(ability_id: Api::AbilityId::SMART, target:, queue_command:)
end

#stop(queue_command: false) ⇒ Object

Shorthand for performing action STOP

Parameters:

  • queue_command (Boolean) (defaults to: false) —

    shift+command



75
76
77
 
# File 'lib/sc2ai/unit_group/action_ext.rb', line 75

def stop(queue_command: false)
  action(ability_id: Api::AbilityId::STOP, queue_command:)
end

#structures ⇒ Sc2::UnitGroup

Selects units with attribute Structure

Returns:



418
419
420
 
# File 'lib/sc2ai/unit_group/filter_ext.rb', line 418

def structures
  select_attribute(Api::Attribute::STRUCTURE)
end

#subtract(other_unit_group) ⇒ Sc2::UnitGroup Also known as: -

Creates a new unit group which is the result of the two being subtracted

Parameters:

Returns:



182
183
184
 
# File 'lib/sc2ai/unit_group.rb', line 182

def subtract(other_unit_group)
  slice(*(tags - other_unit_group.tags))
end

#tags ⇒ Array<Integer>

Returns an array of unit tags

Returns:

  • (Array<Integer>) —

    array of unit#tag



272
273
274
 
# File 'lib/sc2ai/unit_group.rb', line 272

def tags
  keys
end

#to_a ⇒ Object

Forwards to hash of #units.

See Also:

  • Hash#to_a


81
 
# File 'lib/sc2ai/unit_group.rb', line 81

def_delegator :@units, :to_a

#to_h ⇒ Object

Forwards to hash of #units.

See Also:

  • Hash#to_h


82
 
# File 'lib/sc2ai/unit_group.rb', line 82

def_delegator :@units, :to_h

#to_hash ⇒ Object

Forwards to hash of #units.

See Also:

  • Hash#to_hash


83
 
# File 'lib/sc2ai/unit_group.rb', line 83

def_delegator :@units, :to_hash

#to_proc ⇒ Object

Forwards to hash of #units.

See Also:

  • Hash#to_proc


85
 
# File 'lib/sc2ai/unit_group.rb', line 85

def_delegator :@units, :to_proc

#values ⇒ Object

Forwards to hash of #units.

See Also:

  • Hash#values


62
 
# File 'lib/sc2ai/unit_group.rb', line 62

def_delegator :@units, :values

#values_at ⇒ Object

Forwards to hash of #units.

See Also:

  • Hash#values_at


63
 
# File 'lib/sc2ai/unit_group.rb', line 63

def_delegator :@units, :values_at

#warp(unit_type_id:, target:, queue_command: false) ⇒ Object

Warps in unit type at target (location or pylon) Will only have affect is this group consists of warp gates, i.e. bot.structures.warpgates

Parameters:

  • unit_type_id (Integer) —

    Api::UnitTypeId the unit type you wish to build

  • target (Api::Point2D) —

    a point, which should be inside an energy source

  • queue_command (Boolean) (defaults to: false) —

    shift+command



45
46
47
48
 
# File 'lib/sc2ai/unit_group/action_ext.rb', line 45

def warp(unit_type_id:, target:, queue_command: false)
  return if size.zero?
  bot&.warp(units: self, unit_type_id:, target:, queue_command:)
end

#warpables ⇒ Sc2::UnitGroup

Selects pylons and warp prisms in phasing mode

Returns:



600
601
602
 
# File 'lib/sc2ai/unit_group/filter_ext.rb', line 600

def warpables
  select_type([Api::UnitTypeId::PYLON, Api::UnitTypeId::WARPPRISMPHASING]).completed
end

#warpgates ⇒ Sc2::UnitGroup

Selects warp gates (not gateways)

Returns:



594
595
596
 
# File 'lib/sc2ai/unit_group/filter_ext.rb', line 594

def warpgates
  select_type(Api::UnitTypeId::WARPGATE)
end

#watchtowers ⇒ Sc2::UnitGroup

Selects xel’naga watchtowers

Examples:

# Typically a Player selects via group @neutral
@neutral.watchtowers

Returns:



520
521
522
 
# File 'lib/sc2ai/unit_group/filter_ext.rb', line 520

def watchtowers
  select_type(Api::UnitTypeId::XELNAGATOWER)
end

#workers ⇒ Sc2::UnitGroup

Selects worker units

Returns:



402
403
404
 
# File 'lib/sc2ai/unit_group/filter_ext.rb', line 402

def workers
  select_type(TYPE_WORKER)
end