sc2ai 0.7.0 → 0.8.0

data/lib/sc2ai/player/actions.rb

@@ -2,6 +2,29 @@ module Sc2
   class Player
     # Holds action list and queues batch
     module Actions
+      COMBINABLE_ABILITIES = [
+        Api::AbilityId::MOVE,
+        Api::AbilityId::ATTACK,
+        Api::AbilityId::SCAN_MOVE,
+        Api::AbilityId::STOP,
+        Api::AbilityId::SMART,
+        Api::AbilityId::HOLDPOSITION,
+        Api::AbilityId::PATROL,
+        Api::AbilityId::HARVEST_GATHER,
+        Api::AbilityId::HARVEST_RETURN,
+        Api::AbilityId::EFFECT_REPAIR,
+        Api::AbilityId::LIFT,
+        Api::AbilityId::BURROWDOWN,
+        Api::AbilityId::BURROWUP,
+        Api::AbilityId::SIEGEMODE_SIEGEMODE,
+        Api::AbilityId::UNSIEGE_UNSIEGE,
+        Api::AbilityId::MORPH_LIBERATORAAMODE,
+        Api::AbilityId::EFFECT_STIM,
+        Api::AbilityId::MORPH_UPROOT,
+        Api::AbilityId::EFFECT_BLINK,
+        Api::AbilityId::MORPH_ARCHON
+      ]
+
       # Holds actions which will be queued off each time we step forward
       # @!attribute action_queue
       #   @return [Array<Api::Action>]
@@ -382,6 +405,7 @@ module Sc2
       # @return [Api::ResponseAction, nil]
       def perform_actions
         return nil if @action_queue.empty?
+        combine_similar_actions
 
         response_action = @api.action(@action_queue)
         if callback_defined?(:on_action_errors)
@@ -404,6 +428,37 @@ module Sc2
         response_action
       end
 
+      # @private
+      # Makes 10x unit moves to the same target turn into one action
+      # with many unit_tags
+      # @return [void]
+      private def combine_similar_actions
+        grouped_actions = @action_queue.group_by do |action|
+          unit_command = action&.action_raw&.unit_command
+          [unit_command.nil? || !!unit_command&.queue_command,
+            unit_command&.ability_id,
+            unit_command&.target_world_space_pos,
+            unit_command&.target_unit_tag]
+        end
+
+        grouped_actions.each do |key, dupe_actions|
+          # Don't merge if it's not a unit command
+          # or queue_command is true
+          # or the action is unique
+          next if key[0] || dupe_actions.size < 2
+          # Skip if not a combinable ability such as Attack or Move
+          next unless COMBINABLE_ABILITIES.include?(key[1])
+
+          new_action = dupe_actions.first.dup
+          unit_tags = dupe_actions.flat_map do |dupe_action|
+            dupe_action.action_raw.unit_command.unit_tags
+          end
+          new_action.action_raw.unit_command.unit_tags = unit_tags
+          @action_queue = @action_queue.difference(dupe_actions)
+          @action_queue.unshift(new_action)
+        end
+      end
+
       # Empties and resets @action_queue
       # @return [void]
       def clear_action_queue

data/lib/sc2ai/player/game_state.rb

@@ -9,6 +9,7 @@ module Sc2
       attr_accessor :status
 
       include Connection::StatusListener
+
       # Callback when game status changes
       def on_status_change(status)
         self.status = status

data/lib/sc2ai/player/geo.rb

@@ -347,14 +347,14 @@ module Sc2
 
       # Returns a parsed terrain_height from bot.game_info.start_raw.
       # Each value in [row][column] holds a float value which is the z height
-      # @return [::Numo::SFloat] Numo array
+      # @return [::Numo::DFloat] Numo array
       def parsed_terrain_height
         if @parsed_terrain_height.nil?
 
           image_data = bot.game_info.start_raw.terrain_height
           @parsed_terrain_height = Numo::UInt8
             .from_binary(image_data.data, [image_data.size.y, image_data.size.x])
-            .cast_to(Numo::SFloat)
+            .cast_to(Numo::DFloat)
 
           # Values are between -16 and +16. The api values is a float height compressed to rgb range (0-255) in that range of 32.
           # real_height = -16 + (value / 255) * 32
@@ -400,7 +400,7 @@ module Sc2
       # Returns a parsed map_state.visibility from bot.observation.raw_data.
       # Each value in [row][column] holds one of three integers (0,1,2) to flag a vision type
       # @see #visibility for reading from this value
-      # @return [::Numo::SFloat] Numo array
+      # @return [::Numo::UInt8] Numo array
       def parsed_visibility_grid
         if @parsed_visibility_grid.nil?
           image_data = bot.observation.raw_data.map_state.visibility

data/lib/sc2ai/player/units.rb

@@ -44,7 +44,7 @@ module Sc2
       # Shorthand for observation.raw_data.player.upgrade_ids
       # @!attribute [r] upgrades_completed
       #   @return [Array<Integer>] a group of neutral units
-      def upgrades_completed = observation&.raw_data&.player&.upgrade_ids.to_a || [] # not a unit
+      def upgrades_completed = observation&.raw_data&.player&.upgrade_ids.to_a # not a unit
 
       # Returns true if this upgrade has finished researching
       # @return [Boolean]
@@ -170,7 +170,7 @@ module Sc2
 
       # @private
       # @!attribute all_seen_unit_tags
-      # Privately keep track of all seen Unit tags (excl structures) in order to detect new created units
+      # Privately keep track of all seen Unit tags in order to detect new created units
       attr_accessor :_all_seen_unit_tags
       private :_all_seen_unit_tags
 
@@ -188,14 +188,6 @@ module Sc2
       #   @return [Sc2::UnitGroup] group of dead units
       attr_accessor :event_units_destroyed
 
-      # TODO: Unit buff disabled, because it calls back too often (mineral in hand). Put back if useful
-      # @private
-      # Units (Unit/Structure) on which a new buff_ids appeared this frame
-      # See which buffs via: unit.buff_ids - unit.previous.buff_ids
-      # Read this on_step. Alternative to callback on_unit_buffed
-      # @!attribute event_units_destroyed
-      # attr_accessor :event_units_buffed
-
       # Returns static [Api::UnitTypeData] for a unit
       # @param unit [Integer,Api::Unit] Api::UnitTypeId or Api::Unit
       # @return [Api::UnitTypeData]
@@ -360,7 +352,6 @@ module Sc2
 
         # Event-driven unit groups as callback alternatives
         @event_units_damaged = UnitGroup.new
-        # @event_units_buffed = UnitGroup.new
 
         # Categorization of self/enemy, structure/unit ---
         own_alliance = self.own_alliance
@@ -470,7 +461,7 @@ module Sc2
           on_unit_type_changed(unit, previous_unit.unit_type)
         end
 
-        # Check if a unit type has changed
+        # Check if a unit has taken damage
         if unit.health < previous_unit.health || unit.shield < previous_unit.shield
           damage_amount = previous_unit.health - unit.health + previous_unit.shield - unit.shield
           @event_units_damaged.add(unit)

data/lib/sc2ai/player.rb

@@ -19,6 +19,7 @@ module Sc2
     # include Sc2::Connection::ConnectionListener
 
     extend Forwardable
+
     def_delegators :@api, :add_listener
 
     # Known races for detecting race on Api::Race::RANDOM or nil
@@ -72,6 +73,21 @@ module Sc2
     # @return [String] ladder matches will set an opponent id
     attr_accessor :opponent_id
 
+    # @!attribute timer
+    #   Keeps track of time spent in steps.
+    #   @see Sc2::StepTimer
+    #   @example
+    #     # Useful for step-time as on ladder
+    #     @timer.avg_step_time
+    #     # Recent steps time, updated periodically. Good for debug ui
+    #     @timer.avg_recent_step_time
+    #     # Step time between now and previous measure and how many steps
+    #     @timer.previous_on_step_time # Time we spent on step
+    #     @timer.previous_on_step_count # How many steps we took
+    #
+    #   @return [Sc2::StepTimer]
+    attr_accessor :timer
+
     # @param race [Integer] see {Api::Race}
     # @param name [String]
     # @param type [Integer] see {Api::PlayerType}
@@ -217,59 +233,31 @@ module Sc2
       def configure
       end
 
-      alias_method :before_join, :configure
-
       # TODO: If this suffices for Bot and Observer, they should share this code.
       # Initializes and refreshes game data and runs the game loop
       # @return [Integer] One of Api::Result::VICTORY, Api::Result::DEFEAT, Api::Result::TIE, Api::Result::UNDECIDED
       def play
+        @timer = StepTimer.new(self)
+
         # Step 0
         prepare_start
         refresh_state
         started
 
+        @timer.update
+
         # Callback before first step is taken
         on_start
+
         # Callback for step 0
         on_step
 
-        # Local play prints out avg times
-        unless Sc2.ladder?
-          running_avg_step_times = []
-          average_runtime = 0.0
-        end
-
-        puts ""
-
         # Step 1 to n
-        i = 0
         loop do
-          if i >= 5
-            i = 0
-          end
-          r = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
           perform_actions
           perform_debug_commands unless Sc2.ladder?
           step_forward
 
-          unless Sc2.ladder?
-            time_delta = (::Process.clock_gettime(::Process::CLOCK_MONOTONIC) - r) * 1000
-            step_delta = game_loop - @previous.game_loop
-            # running_avg_step_times.shift if running_avg_step_times.size == 5
-            running_avg_step_times << [time_delta, step_delta]
-
-            if i == 0
-              sum_t, sum_s = running_avg_step_times.each_with_object([0, 0]) do |n, total|
-                total[0] += n[0]
-                total[1] += n[1]
-              end
-              average_runtime = sum_t / sum_s
-              running_avg_step_times.clear
-            end
-            print "\e[2K#{step_delta} Step(s) Took (ms): #{"%.2f" % time_delta} | Avg (ms/frame): #{"%.2f" % average_runtime}\n\e[1A\r"
-          end
-
-          i += 1
           return @result unless @result.nil?
           break if @status != :IN_GAME
         end
@@ -587,6 +575,7 @@ module Sc2
       end
 
       refresh_state
+      @timer.update # Runtimes calc
       on_step if @result.nil?
     end
 
@@ -595,7 +584,6 @@ module Sc2
     # @return [void]
     # TODO: After cleaning up all the comments, review whether this is too heavy or not. #perf #clean
     def refresh_state
-      # Process.clock_gettime(Process::CLOCK_MONOTONIC)
       step_to_loop = @realtime ? game_loop + @step_count : nil
       response_observation = @api.observation(game_loop: step_to_loop)
       return if response_observation.nil?
@@ -622,8 +610,7 @@ module Sc2
 
       # First game-loop: set enemy and our race if random
       if enemy.nil?
-        # Finish game_info load immediately, because we need it's info
-        game_info
+        # Finish game_info load immediately, because we need its info
         set_enemy
         set_race_for_random if race == Api::Race::RANDOM
       end

data/lib/sc2ai/ports.rb

@@ -113,7 +113,8 @@ module Sc2
       end
 
       # Will bind tcp port and return port if successful
-      # if port is zero, it will return random port bound to
+      # when port is zero, it will return random port bound to
+      # @param port [Integer]
       # @return [Integer, Boolean] port if bind succeeds, false on failure
       def bind(port)
         socket = ::Socket.new(:AF_INET, :SOCK_STREAM, 0)
@@ -130,8 +131,19 @@ module Sc2
 
   # A port configuration for a Match which allows generating Api::PortSet
   class PortConfig
-    attr_reader :start_port, :server_port_set, :client_port_sets
-
+    # @!attribute start_port
+    #   @return [Integer]
+    attr_reader :start_port
+    # @!attribute server_port_set
+    #   @return [Array<Integer>]
+    attr_reader :server_port_set
+    # @!attribute client_port_sets
+    #   @return [Array<Integer>]
+    attr_reader :client_port_sets
+
+    # @param [Integer] start_port
+    # @param [Integer] num_players
+    # @param [Array<Integer>] ports
     def initialize(start_port:, num_players:, ports: [])
       @start_port = start_port
       @server_port_set = nil

data/lib/sc2ai/protocol/extensions/position.rb

@@ -5,6 +5,14 @@ module Sc2
     # Tolerance for floating-point comparisons.
     TOLERANCE = 1e-9
 
+    # Returns self.
+    # If you're ever unsure if you have a Unit or Position in hand,
+    # this method allows safely calling `unknown_target.pos` to return a position.
+    # @example
+    #   target.pos
+    # @return [Sc2::Position]
+    def pos = self
+
     # Basic operations
 
     # Loose equality matches on floats x and y.
@@ -70,10 +78,12 @@ module Sc2
       dup.random_offset!(offset)
     end
 
-    # Changes this point's x and y by the supplied offset
+    # Randomly change this point's x and y by the supplied offset.
+    # i.e. offset=2 can adjust x and y by any number in range -2..2
+    # @param offset [Float]
     # @return [Sc2::Position] self
     def random_offset!(offset)
-      offset = offset.to_f
+      offset = offset.to_f.abs
       range = -offset..offset
       offset!(rand(range), rand(range))
       self
@@ -136,6 +146,7 @@ module Sc2
 
     # Linear interpolation between this point and another for scale
     # Finds a point on a line between two points at % along the way. 0.0 returns self,  1.0 returns other, 0.5 is halfway.
+    # @param other [Sc2::Position]
     # @param scale [Float] a value between 0.0..1.0
     # @return [Api::Point2D]
     def lerp(other, scale)
@@ -214,12 +225,13 @@ module Sc2
 
     # Returns [x,y] array tuple where floats are cast to ints
     # Useful when trying to find the tile which something is on
-    # @return [Array<Integer, Integer>
+    # @return [Array<Integer, Integer>]
     def to_atile
       [x.to_i, y.to_i]
     end
 
     # @private
+    # @return [String]
     def to_s
       "#<#{self.class} x=#{x} y=#{y}>"
     end

data/lib/sc2ai/protocol/extensions/unit.rb

@@ -39,9 +39,50 @@ module Api
       new_unit = @bot.all_units[tag]
       return false if new_unit.nil? || new_unit == self
 
-      method(:initialize).parameters.each do |_, entry|
-        send(:"#{entry.name}=", new_unit.send(entry))
-      end
+      self.display_type = new_unit.display_type
+      self.alliance = new_unit.alliance
+      self.tag = new_unit.tag
+      self.unit_type = new_unit.unit_type
+      self.owner = new_unit.owner
+      self.pos = new_unit.pos
+      self.facing = new_unit.facing
+      self.radius = new_unit.radius
+      self.build_progress = new_unit.build_progress
+      self.cloak = new_unit.cloak
+      self.buff_ids = new_unit.buff_ids
+      self.detect_range = new_unit.detect_range
+      self.radar_range = new_unit.radar_range
+      self.is_selected = new_unit.is_selected
+      self.is_on_screen = new_unit.is_on_screen
+      self.is_blip = new_unit.is_blip
+      self.is_powered = new_unit.is_powered
+      self.is_active = new_unit.is_active
+      self.attack_upgrade_level = new_unit.attack_upgrade_level
+      self.armor_upgrade_level = new_unit.armor_upgrade_level
+      self.shield_upgrade_level = new_unit.shield_upgrade_level
+      self.health = new_unit.health
+      self.health_max = new_unit.health_max
+      self.shield = new_unit.shield
+      self.shield_max = new_unit.shield_max
+      self.energy = new_unit.energy
+      self.energy_max = new_unit.energy_max
+      self.mineral_contents = new_unit.mineral_contents
+      self.vespene_contents = new_unit.vespene_contents
+      self.is_flying = new_unit.is_flying
+      self.is_burrowed = new_unit.is_burrowed
+      self.is_hallucination = new_unit.is_hallucination
+      self.orders = new_unit.orders
+      self.add_on_tag = new_unit.add_on_tag
+      self.passengers = new_unit.passengers
+      self.cargo_space_taken = new_unit.cargo_space_taken
+      self.cargo_space_max = new_unit.cargo_space_max
+      self.assigned_harvesters = new_unit.assigned_harvesters
+      self.ideal_harvesters = new_unit.ideal_harvesters
+      self.weapon_cooldown = new_unit.weapon_cooldown
+      self.engaged_target_tag = new_unit.engaged_target_tag
+      self.buff_duration_remain = new_unit.buff_duration_remain
+      self.buff_duration_max = new_unit.buff_duration_max
+      self.rally_targets = new_unit.rally_targets
 
       true
     end
@@ -157,6 +198,24 @@ module Api
       energy == energy_max
     end
 
+    # Returns whether this is a melee (non-ranged) attacker
+    # Archon isn't melee; 3 range
+    # Hellbat is melee, but Hellion isn't melee; 5 range
+    # Roach isn't melee; just an attack animation when nearby
+    # @!attribute [r] is_melee?
+    #   @return [Boolean] melee unit (non-ranged attacker)
+    def is_melee?
+      Sc2::UnitGroup::TYPE_MELEE.include?(unit_type)
+    end
+
+    # Returns ranged attack units
+    # @see Sc2::UnitGroup::TYPE_RANGE
+    # @!attribute [r] is_ranged?
+    #   @return [Boolean] if reasonably considered a ranged attacker
+    def is_ranged?
+      Sc2::UnitGroup::TYPE_RANGE.include?(unit_type)
+    end
+
     # Some overrides to allow question mark references to boolean properties
 
     # @!attribute [r] is_flying?
@@ -593,7 +652,7 @@ module Api
         Api::UnitTypeId::STARPORTREACTOR
       end
 
-      build(unit_type_id: unit_type_id, target: target_for_addon_placement, queue_command:)
+      build(unit_type_id: unit_type_id, target:, queue_command:)
     end
 
     # For Terran builds a tech lab add-on on the current structure
@@ -607,21 +666,7 @@ module Api
       when Api::UnitTypeId::STARPORT, Api::UnitTypeId::STARPORTFLYING
         Api::UnitTypeId::STARPORTTECHLAB
       end
-      build(unit_type_id: unit_type_id, target: target_for_addon_placement, queue_command:)
-    end
-
-    private def target_for_addon_placement
-      # Attempts to auto-move left if not placeable
-      x = pos.x.floor
-      y = pos.y.floor
-      if !bot.geo.placeable?(x: x + 3, y: y - 1) ||
-          !bot.geo.placeable?(x: x + 3, y: y) ||
-          !bot.geo.placeable?(x: x + 2, y: y - 1) ||
-          !bot.geo.placeable?(x: x + 2, y: y)
-        return Api::Point2D[pos.x - 1, pos.y]
-      end
-
-      nil
+      build(unit_type_id: unit_type_id, target:, queue_command:)
     end
 
     # PROTOSS Convenience functions ---

data/lib/sc2ai/step_timer.rb

@@ -0,0 +1,134 @@
+module Sc2
+  # Tracks various metrics about your step time performance.
+  class StepTimer
+    TRUNCATED_TIME_RANGE = 0..999.99
+    HEALTHY_STEP_TIME_MS = (1000.0 / 22.4)
+    private_constant :TRUNCATED_TIME_RANGE, :HEALTHY_STEP_TIME_MS
+
+    # @!attribute [r] avg_real_time
+    # @return [Float] Realtime average time per step in ms. Includes SC2 wait time
+    attr_reader :avg_real_time
+
+    # @!attribute [r] avg_step_time
+    # @return [Float] Total average time per step in ms. "Ladder Time" as measured by aiarena
+    attr_reader :avg_step_time
+
+    # @!attribute [r] recent_average
+    # @return [Float] Running average time per step in ms for recent couple of steps
+    attr_accessor :avg_recent_step_time
+
+    # @!attribute [r] previous_on_step_time
+    # @return [Float] Previous on_step took this amount of ms to run
+    attr_reader :previous_on_step_time
+
+    # @!attribute [r] previous_on_step_count
+    # @return [Integer] Number of frames which passed previous on_step
+    attr_reader :previous_on_step_count
+
+    # @private
+    private attr_accessor :bot
+    # @private
+    private attr_accessor :previous_external_time, :previous_update_time
+    # @private
+    private attr_accessor :recent_sum_time, :recent_sum_steps, :recent_update_counter
+
+    # @private
+    # @param bot [Sc2::Player]
+    def initialize(bot)
+      @bot = bot
+
+      # Tracking vars
+      @previous_external_time = @bot.api.external_time
+      @previous_update_time = Process.clock_gettime(Process::CLOCK_MONOTONIC, :float_millisecond)
+      @recent_update_counter = 0
+      @recent_sum_steps = 0
+      @recent_sum_time = 0.0
+      @total_step_time = 0.0
+      @total_real_time = 0.0
+
+      # Output vars
+      @avg_real_time = 0.0
+      @avg_step_time = 0.0
+      @avg_recent_step_time = 0.0
+      @previous_on_step_time = 0.0
+      @previous_on_step_count = 0
+    end
+
+    # How much time we have left in this step, to be healthy
+    def allowance
+      return 0.0 if @bot.realtime
+      time_passed = Process.clock_gettime(Process::CLOCK_MONOTONIC, :float_millisecond) - @previous_update_time
+      external_delta = @bot.api.external_time - @previous_external_time
+      (HEALTHY_STEP_TIME_MS * @bot.step_count) - (time_passed - external_delta)
+    end
+
+    # A one-line string summary of all tracked times
+    # @return [String]
+    def summary
+      "AVG Real: #{format_time(@avg_real_time)} | " \
+        "AVG Total: #{format_time(@avg_step_time)} | " \
+        "AVG Recent: #{format_time(@avg_recent_step_time)} | " \
+        "Previous #{@previous_on_step_count} Step(s): #{format_time(@previous_on_step_time)} (ms)"
+    end
+
+    # A hash containing :avg_real_time, :avg_step_time, :avg_recent_step_time, :previous_on_step_count, :previous_on_step_time
+    # @return [Hash]
+    def to_h
+      {
+        avg_real_time: avg_real_time,
+        avg_step_time: avg_step_time,
+        avg_recent_step_time: avg_recent_step_time,
+        previous_on_step_count: previous_on_step_count,
+        previous_on_step_time: previous_on_step_time
+      }
+    end
+
+    def update
+      # Number of steps which have passed
+      step_delta = @bot.game_loop - @bot.previous.game_loop
+
+      # Time spent waiting for SC2 is not counted on ladder
+      external_time = @bot.api.external_time
+      external_delta = external_time - @previous_external_time
+      @previous_external_time = external_time
+
+      # Start calculating...
+      now = Process.clock_gettime(Process::CLOCK_MONOTONIC, :float_millisecond)
+
+      time_delta = now - @previous_update_time
+      @previous_update_time = now
+
+      # Update real time
+      @total_real_time += time_delta
+
+      # Update step time (excl external)
+      time_delta -= external_delta
+      @total_step_time += time_delta
+
+      # Write public values...
+      @previous_on_step_time = time_delta
+      @previous_on_step_count = step_delta
+      @avg_real_time = @total_real_time / (@bot.game_loop + 1)
+      @avg_step_time = @total_step_time / (@bot.game_loop + 1)
+
+      @recent_sum_time += time_delta
+      @recent_sum_steps += step_delta
+      if @recent_update_counter >= 11
+        @avg_recent_step_time = @recent_sum_time / @recent_sum_steps
+
+        @recent_sum_time = 0.0
+        @recent_sum_steps = 0
+        @recent_update_counter = 0
+      end
+      @recent_update_counter += 1
+    end
+
+    private
+
+    # @private
+    # @return [String] time with ansi colour coded
+    def format_time(time)
+      "%5.2f" % time.clamp(TRUNCATED_TIME_RANGE)
+    end
+  end
+end

data/lib/sc2ai/unit_group/action_ext.rb

@@ -7,7 +7,7 @@ module Sc2
     # Returns nil if units are empty, so use safety operator bot&.method(...)
     # @return [Sc2::Player, nil] player with active connection
     def bot
-      first&.bot
+      @bot ||= first&.bot
     end
 
     # Performs action on all units in this group