sc2ai 0.0.0.pre → 0.0.3

data/lib/sc2ai/unit_group/filter_ext.rb

@@ -0,0 +1,379 @@
+# frozen_string_literal: true
+
+require "sc2ai/unit_group"
+require "kdtree"
+
+module Sc2
+  # Manage virtual control groups of units, similar to Hash or Array.
+  class UnitGroup
+    TYPE_WORKER = [Api::UnitTypeId::SCV, Api::UnitTypeId::MULE, Api::UnitTypeId::DRONE, Api::UnitTypeId::DRONEBURROWED, Api::UnitTypeId::PROBE].freeze
+    TYPE_GAS_STRUCTURE = [
+      Api::UnitTypeId::REFINERY,
+      Api::UnitTypeId::REFINERYRICH,
+      Api::UnitTypeId::ASSIMILATOR,
+      Api::UnitTypeId::ASSIMILATORRICH,
+      Api::UnitTypeId::EXTRACTOR,
+      Api::UnitTypeId::EXTRACTORRICH
+    ].freeze
+    TYPE_MINERAL = [
+      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 = [
+      Api::UnitTypeId::VESPENEGEYSER,
+      Api::UnitTypeId::SPACEPLATFORMGEYSER,
+      Api::UnitTypeId::RICHVESPENEGEYSER,
+      Api::UnitTypeId::PROTOSSVESPENEGEYSER,
+      Api::UnitTypeId::PURIFIERVESPENEGEYSER,
+      Api::UnitTypeId::SHAKURASVESPENEGEYSER
+    ].freeze
+    TYPE_REJECT_DEBRIS = ((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 = [
+      Api::UnitTypeId::REACTOR,
+      Api::UnitTypeId::BARRACKSREACTOR,
+      Api::UnitTypeId::FACTORYREACTOR,
+      Api::UnitTypeId::STARPORTREACTOR
+    ].freeze
+    TYPE_BASES = [
+      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
+    # Returns a new UnitGroup containing all units matching unit type id(s)
+    # Multiple values work as an "OR" filter
+    # @example
+    #   # Single
+    #   ug.select_type(Api::UnitTypeId::MARINE) #=> <UnitGroup: ...>
+    #   # Multiple - select space-men
+    #   ug.select_type([Api::UnitTypeId::MARINE, Api::UnitTypeId::REAPER]) #=> <UnitGroup: ...>
+    # @param unit_type_ids [Integer, Array<Integer>] one or an array of unit Api::UnitTypeId
+    # @return [UnitGroup]
+    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
+
+    # Returns a new UnitGroup excluding all units matching unit type id(s)
+    # @example
+    #   # Single
+    #   ug.reject_type(Api::UnitTypeId::SCV) #=> <UnitGroup: ...>
+    #   # Multiple - reject immovable army
+    #   ug.reject_type([Api::UnitTypeId::SIEGETANKSIEGED, Api::UnitTypeId::WIDOWMINEBURROWED]) #=> <UnitGroup: ...>
+    # @param unit_type_ids [Integer, Array<Integer>] one or an array of unit Api::UnitTypeId
+    # @return [UnitGroup]
+    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
+
+    # Creates a negative selector, which will perform the opposite on the current scope
+    #   for it's next select_type/reject_type call.
+    # @example
+    #   structures.not.creep_tumors #=> all structures
+    #   structures.not.pylons #=>
+    #   units.not.workers # equivalent of units.army, but works too
+    # @return [Sc2::UnitGroupNotSelector]
+    def not
+      UnitGroupNotSelector.new(self)
+    end
+
+    # @private
+    # Negative selector allowing unit group "ug.not." filter
+    class UnitGroupNotSelector < UnitGroup
+      attr_accessor :parent
+
+      def initialize(unit_group)
+        @parent = unit_group
+        super
+      end
+
+      # @private
+      # Does the opposite of selector and returns those values for parent
+      def select_type(*)
+        @parent.reject_type(*)
+      end
+
+      # Does the opposite of selector and returns those values for parent
+      def reject_type(*)
+        @parent.select_type(*)
+      end
+    end
+
+    # Returns a new UnitGroup containing all units matching attribute id(s)
+    # Multiple values work as an "AND" filter
+    # @example
+    #   # Single
+    #   ug.select_attribute(Api::Attribute::Structure) #=> <UnitGroup: ...>
+    #   ug.select_attribute(:Structure) #=> <UnitGroup: ...>
+    #   # Multiple - select mechanical flying units
+    #   ug.select_attribute([:Mechanical, :Flying]) #=> <UnitGroup: ...>
+    # @param attributes [Integer, Array<Integer>] one or an array of unit Api::UnitTypeId
+    # @return [UnitGroup]
+    def select_attribute(attributes)
+      cached("#{__method__}:#{attributes.hash}") do
+        attributes = [attributes] unless attributes.is_a? Array
+        attributes = attributes.map { |a| a.is_a?(Symbol) ? a : Api::Attribute.lookup(a) }
+        select do |unit|
+          attributes & unit.attributes == attributes
+        end
+      end
+    end
+
+    # Returns a new UnitGroup containing all units excluding attribute id(s)
+    # Multiple values work as an "AND" filter
+    # @example
+    #   # Single
+    #   ug.reject_attribute(Api::Attribute::Structure) #=> <UnitGroup: ...>
+    #   ug.reject_attribute(:Structure) #=> <UnitGroup: ...>
+    #   # Multiple - reject mechanical flying units
+    #   ug.reject_attribute(:Mechanical, :Flying) #=> <UnitGroup: ...>
+    # @param attributes [Integer, Array<Integer>] one or an array of unit Api::UnitTypeId
+    # @return [UnitGroup]
+    def reject_attribute(attributes)
+      cached("#{__method__}:#{attributes.hash}") do
+        attributes = [attributes] unless attributes.is_a? Array
+        attributes = attributes.map { |a| a.is_a?(Symbol) ? a : Api::Attribute.lookup(a) }
+        reject do |unit|
+          unit.attributes & attributes == attributes
+        end
+      end
+    end
+
+    # GENERICS ---
+
+    # Selects worker units
+    # @return [Sc2::UnitGroup] workers
+    def workers
+      select_type(TYPE_WORKER)
+    end
+
+    # Selects non army units workers. Generally run on Sc2::Player#units
+    # @example in the Player context
+    #   fighters = units.army
+    #   enemy_fighters = units.army
+    # @return [Sc2::UnitGroup] army
+    # @see #non_army_unit_type_ids to modify filters
+    def army
+      reject_type(non_army_unit_type_ids)
+    end
+
+    # Selects units with attribute Structure
+    # @return [Sc2::UnitGroup] structures
+    def structures
+      select_attribute(Api::Attribute::Structure)
+    end
+
+    # Contains an array non-army types
+    # Override to remove or add units you want units.army to exclude
+    # @example
+    #   # 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)
+    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
+
+    # Selects command posts (CC, OC, PF, Nexus, Hatch, Hive, Lair)
+    # Aliases are #hq and #townhalls
+    # @return [Sc2::UnitGroup] unit group of workers
+    def bases
+      select_type(TYPE_BASES)
+    end
+    alias_method :hq, :bases # short name
+    alias_method :townhalls, :bases # bad name
+
+    # Selects gas structures (refinery/extractor/assimilator)
+    # @return [UnitGroup] gas structures
+    def gas
+      select_type(TYPE_GAS_STRUCTURE)
+    end
+    alias_method :refineries, :gas
+    alias_method :extractors, :gas
+    alias_method :assimilators, :gas
+
+    # NEUTRAL ------------------------------------------
+
+    # Selects mineral fields
+    # @return [Sc2::UnitGroup] mineral fields
+    # @example
+    #   # Typically a Player selects via group @neutral
+    #   @neutral.minerals
+    def minerals
+      select_type(TYPE_MINERAL)
+    end
+
+    # Selects gas geysers
+    # @return [Sc2::UnitGroup] gas geysers
+    # @example
+    #   # Typically a Player selects via group @neutral
+    #   @neutral.geysers
+    def geysers
+      select_type(TYPE_GEYSER)
+    end
+
+    # Selects xel'naga watchtowers
+    # @return [Sc2::UnitGroup] watchtowers
+    # @example
+    #   # Typically a Player selects via group @neutral
+    #   @neutral.watchtowers
+    def watchtowers
+      select_type(Api::UnitTypeId::XELNAGATOWER)
+    end
+
+    # Reverse filters our minerals, geysers and towers to get what is hopefully debris
+    # @return [Sc2::UnitGroup] debris
+    # @example
+    #   # Typically a Player selects via group @neutral
+    #   @neutral.debris
+    def debris
+      reject_type(TYPE_REJECT_DEBRIS)
+    end
+
+    # ZERG ------------------------------------------
+    # Selects larva units
+    # @return [Sc2::UnitGroup] larva
+    def larva
+      select_type(Api::UnitTypeId::LARVA)
+    end
+    alias_method :larvae, :larva
+
+    # Selects queens
+    # @return [Sc2::UnitGroup] queens
+    def queens
+      select_type([Api::UnitTypeId::QUEEN, Api::UnitTypeId::QUEENBURROWED])
+    end
+
+    # Selects overlords
+    # @return [Sc2::UnitGroup]
+    def overlords
+      select_type([Api::UnitTypeId::OVERLORD, Api::UnitTypeId::OVERLORDCOCOON])
+    end
+
+    # 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
+    # @see #creep_tumors_burrowed for those ready to be spread
+    # @return [Sc2::UnitGroup] all tumors
+    def creep_tumors
+      select_type([Api::UnitTypeId::CREEPTUMORQUEEN, Api::UnitTypeId::CREEPTUMOR, Api::UnitTypeId::CREEPTUMORBURROWED])
+    end
+    alias_method :tumors, :creep_tumors
+
+    # 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.
+    # @return [Sc2::UnitGroup] burrowed tumors (with and without spread ability)
+    def creep_tumors_burrowed
+      select_type(Api::UnitTypeId::CREEPTUMORBURROWED)
+    end
+
+    # Protoss ---
+
+    # Selects pylons
+    # @return [Sc2::UnitGroup] pylons
+    def pylons
+      select_type(Api::UnitTypeId::PYLON)
+    end
+
+    # Selects warp gates (not gateways)
+    # @return [Sc2::UnitGroup] warp gates
+    def warpgates
+      select_type(Api::UnitTypeId::WARPGATE)
+    end
+
+    # Selects pylons and warp prisms in phasing mode
+    # @return [Sc2::UnitGroup] pylons annd warp prisms phasing
+    def warpables
+      select_type([Api::UnitTypeId::PYLON, Api::UnitTypeId::WARPPRISMPHASING])
+    end
+
+    # Geometric/Map ---
+
+    # 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
+    # @return [Boolean]
+    attr_accessor :use_kdtree
+
+    # Builds a kdtree if not already built and returns it
+    # @return [Kdtree]
+    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
+
+    # Returns an
+    # @param pos [Sc2::Position] unit.pos or a point of any kind
+    # @return [Sc2::UnitGroup, Api::Unit, nil] return group or single unit if amount is not supplied
+    def nearest_to(pos:, amount: nil)
+      return UnitGroup.new if !amount.nil? && amount.to_i <= 0
+
+      if use_kdtree
+        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
+
+    # Selects units which are in a particular circle
+    # @param point [Api::Point2D, Api::Point] center of circle
+    # @param radius [Float]
+    def select_in_circle(point:, radius:)
+      select { |unit| unit.in_circle?(point:, radius:) }
+    end
+  end
+end

data/lib/sc2ai/unit_group.rb

@@ -0,0 +1,277 @@
+# frozen_string_literal: true
+
+module Sc2
+  # A collection of Api::Unit, which acts as a hash of unit.tag => unit.
+  # Consider a UnitGroup a virtual Control Group.
+  # Most Hash operations like select/filter, reject, etc. are implemented to return a UnitGroup to to allow fluent group control
+  class UnitGroup
+    extend Forwardable
+    include Enumerable
+
+    # @!attribute units
+    # A hash of units by tag.
+    #   @return [Hash<Integer, Api::Unit>] Api::Unit.tag => Api::Unit
+    attr_accessor :units
+
+    # @param units [Api::Unit, Hash<Integer, Api::Unit>, Array<Api::Unit>, Sc2::UnitGroup, nil] default to be added.
+    # @return Sc2::UnitGroup new unit group
+    def initialize(units = nil)
+      @units = {}
+      case units
+      when Array, Google::Protobuf::RepeatedField
+        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
+
+    # @!macro [attach] def_delegators
+    #   @!method $2
+    #     Forwards to hash of #units.
+    #     @see Hash#$2
+    def_delegator :@units, :empty? # Returns whether there are no entries.
+    def_delegator :@units, :eql? # Returns whether a given object is equal to #units.
+    def_delegator :@units, :length # Returns the count of entries.
+    def_delegator :@units, :size # Returns the count of entries.
+
+    # @!macro [attach] def_delegators
+    #   @!method $2
+    #     Forwards to hash of #units.
+    #     @see Hash#$2
+    def_delegator :@units, :< # Returns whether #units is a proper subset of a given object.
+    def_delegator :@units, :<= # Returns whether #units is a subset of a given object.
+    def_delegator :@units, :== # Returns whether a given object is equal to #units.
+    def_delegator :@units, :> # Returns whether #units is a proper superset of a given object
+    def_delegator :@units, :>= # Returns whether #units is a proper superset of a given object.
+
+    # @!macro [attach] def_delegators
+    #   @!method $2
+    #     Forwards to hash of #units.
+    #     @see Hash#$2
+    def_delegator :@units, :[] # Returns the value associated with the given key, if found
+    def_delegator :@units, :keys # Returns an array containing all keys in #units.
+    def_delegator :@units, :values # Returns an array containing all values in #units.
+    def_delegator :@units, :values_at # Returns an array containing values for given tags in #units.
+
+    # @!macro [attach] def_delegators
+    #   @!method $2
+    #     Forwards to hash of #units.
+    #     @see Hash#$2
+    def_delegator :@units, :clear # Removes all entries from #units.
+    def_delegator :@units, :delete_if # Removes entries selected by a given block.
+    def_delegator :@units, :select! # Keep only those entries selected by a given block
+    def_delegator :@units, :filter! # Keep only those entries selected by a given block
+    def_delegator :@units, :keep_if # Keep only those entries selected by a given block
+    # def_delegator :@units, :compact! # Removes all +nil+-valued entries from #units.
+
+    # find_all, #filter, #select: Returns elements selected by the block.
+
+    def_delegator :@units, :reject! # Removes entries selected by a given block.
+    def_delegator :@units, :shift # Removes and returns the first entry.
+
+    def_delegator :@units, :to_a # Returns a new array of 2-element arrays; each nested array contains a key-value pair from #units
+    def_delegator :@units, :to_h # Returns {UnitGroup#units}
+    def_delegator :@units, :to_hash # Returns {UnitGroup#units}
+    def_delegator :@units, :to_proc # Returns a proc that maps a given key to its value.Returns a proc that maps a given key to its value.
+
+    # Gets the Unit at an index
+    # @return [Api::Unit]
+    def at(index)
+      @units[tags.at(index)]
+    end
+
+    # Calls the given block with each Api::Unit value
+    # @example
+    #   unit_group.each {|unit| puts unit.tag } #=> 1234 ...
+    #
+    #   unit_group.each do |unit|
+    #      puts unit.tag #=> 1234 ...
+    #   end
+    def each(&block)
+      @units.each_value(&block)
+    end
+
+    # Calls the given block with each key-value pair
+    # @return [self] a new unit group with items merged
+    # @example
+    #   unit_group.each {|tag, unit| puts "#{tag}: #{unit}"} #=> "12345: #<Api::Unit ...>"
+    #
+    #   unit_group.each do |tag, unit|
+    #      puts "#{tag}: #{unit}"} #=> "12345: #<Api::Unit ...>"
+    #   end
+    def each_with_tag(&block)
+      @units.each(&block)
+      self
+    end
+
+    # Checks whether this group contains a unit.
+    # @param unit [Api::Unit, Integer] a unit or a tag.
+    # @return [Boolean] A boolean indicating if the #units include? unit.
+    def contains?(unit)
+      tag = unit.is_a?(Api::Unit) ? unit.tag : unit
+      @units.include?(tag)
+    end
+
+    # Associates a given unit tag with a given unit.
+    # @see UnitGroup#add #add, which is easier to just pass an Api::Unit
+    def []=(unit_tag, unit)
+      return if unit_tag.nil? || unit.nil?
+      @units[unit_tag] = unit
+    end
+
+    # Adds a unit or units to the group.
+    # @param units [Api::Unit, Array<Api::Unit>, Sc2::UnitGroup]
+    # @return [self]
+    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
+
+    alias_method :push, :add
+
+    # Remove a another UnitGroup's units from ours or a singular Api::Unit either by object or Api::Unit#tag
+    # @param unit_group_unit_or_tag [Sc2::UnitGroup, Api::Unit, Integer, nil]
+    # @return [Hash<Integer, Api::Unit>, Api::Unit, nil] the removed item(s) or nil
+    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
+
+    alias_method :delete, :remove
+
+    # Creates a new unit group which is the result of the two being subtracted
+    # @param other_unit_group [UnitGroup]
+    # @return [UnitGroup] new unit group
+    def subtract(other_unit_group)
+      UnitGroup.new(@units.reject { |tag, _unit| other_unit_group.units.has_key?(tag) })
+    end
+
+    # Merges unit_group with our units and returns a new unit group
+    # @return [Sc2::UnitGroup] a new unit group with items merged
+    def merge(unit_group)
+      UnitGroup.new(@units.merge(unit_group))
+    end
+    alias_method :+, :merge
+
+    # Merges unit_group.units into self.units and returns self
+    # @return [self]
+    def merge!(unit_group)
+      @units.merge!(unit_group.units)
+      self
+    end
+
+    # Replaces the entire contents of #units with the contents of a given unit_group.
+    # Synonymous with self.units = unit_group.units
+    # @return [void]
+    def replace(unit_group)
+      @units = unit_group.units
+    end
+
+    # Returns a new UnitGroup object whose #units entries are those for which the block returns a truthy value
+    # @return [Sc2::UnitGroup] new unit group
+    # noinspection RubyMismatchedReturnType # UnitGroup acts as an array, so sig is ok.
+    def select
+      result = @units.select { |_tag, unit| yield unit }
+      UnitGroup.new(result)
+    end
+
+    alias_method :filter, :select
+
+    # Returns a new UnitGroup object whose entries are all those from #units for which the block returns false or nil
+    # @return [Sc2::UnitGroup] new unit group
+    # noinspection RubyMismatchedReturnType # UnitGroup acts as an array, so sig is ok.
+    def reject(&block)
+      result = @units.reject { |_tag, unit| yield unit }
+      UnitGroup.new(result)
+    end
+
+    # Returns a copy of self with units removed for specified tags.
+    # @return [Sc2::UnitGroup] new unit group
+    def except(...)
+      UnitGroup.new(@units.except(...))
+    end
+
+    # Returns a hash containing the entries for given tag(s).
+    # @return [Sc2::UnitGroup] new unit group
+    def slice(...)
+      UnitGroup.new(@units.slice(...))
+    end
+
+    # Selects a single random Unit without a parameter or an array of Units with a param, i.e. self.random(2)
+    # @return []
+    def sample(...)
+      @units.values.sample(...)
+    end
+    alias_method :random, :sample
+
+    # def select_or(*procs)
+    #   result = UnitGroup.new
+    #   procs.each do |proc|
+    #     selected = select(&proc)
+    #     result.merge!(selected) unless selected.nil?
+    #   end
+    #   result
+    # end
+
+    # Returns an array of unit tags
+    # @return [Array<Integer>] array of unit#tag
+    def tags
+      keys
+    end
+
+    class << self
+    end
+
+    private
+
+    # @private
+    # Caches a block based on key and current UnitGroup#units.hash
+    # If the hash changes (units are modified) the cache expires
+    # This allows lazy lookups which only fires if the units change
+    # Allows, i.e. Player#units.workers to fire only the first time it's called per frame
+    def cached(key)
+      if @_cache_hash[key] != @units.hash
+        @_cache_hash[key] = @units.hash
+        @_cache[key] = yield
+      end
+      @_cache[key]
+    end
+
+    attr_accessor :_cache_hash
+    attr_accessor :_cache
+  end
+end
+
+require_relative "unit_group/action_ext"
+require_relative "unit_group/filter_ext"

data/lib/sc2ai/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module Sc2
-  VERSION = "0.0.0.pre"
+  # gem version
+  VERSION = "0.0.3"
 end