sc2ai 0.2.0 → 0.3.0

data/lib/sc2ai/connection/status_listener.rb

@@ -5,7 +5,7 @@ module Sc2
     # Callbacks when game status changes
     module StatusListener
       # Called when game status changes
-      # @param status [:launched, :in_game, :in_replay, :ended, :quit, :unknown] game state, i.e. :in_game, :ended, :launched
+      # @param status [:LAUNCHED, :IN_GAME, :IN_REPLAY, :ENDED, :QUIT, :UNKNOWN] game state, i.e. :IN_GAME, :ENDED, :LAUNCHED
       # noinspection
       def on_status_change(status)
         Sc2.logger.debug { "#{self.class}.#{__method__} #{status}" }

data/lib/sc2ai/connection.rb

@@ -138,7 +138,7 @@ module Sc2
 
     attr_writer :status, :listeners
 
-    # @return [HTTP::Endpoint] websocket url for establishing protobuf connection
+    # @return [::Async::HTTP::Endpoint] websocket url for establishing protobuf connection
     def endpoint
       Async::HTTP::Endpoint.parse("ws://#{@host}:#{@port}/sc2api")
     end

data/lib/sc2ai/local_play/client.rb

@@ -115,7 +115,7 @@ module Sc2
 
     # @!attribute task
     # The async task running Sc2. Used when interrupting.
-    # @return [Async::Task]
+    # @return [::Async::Task]
     attr_accessor :task
 
     # @private
@@ -151,7 +151,7 @@ module Sc2
 
     # @private
     # Reads bundled versions.json
-    # @return [JSON] contents of versions.json
+    # @return [Array] JSON contents of versions.json
     def versions_json
       JSON.load_file(Paths.gem_data_versions_path)
     end

data/lib/sc2ai/local_play/match.rb

@@ -72,6 +72,11 @@ module Sc2
             ClientManager.stop(player_index) # unless keep_clients_alive
           end
         end
+        # Here, Api players are busy Joining and we wait for map loads
+        # Let's use this time for quick housekeeping before the match
+        run_task.async do
+          Process.warmup
+        end
       rescue
         # no op - clean exit from game may cause ws disconnection error
       end.wait
@@ -116,7 +121,7 @@ module Sc2
     # Gets a Sc2 client from Sc2::ClientManager and connects them
     def connect_players
       # Depending on number of players, api has different ready states
-      ready_statuses = (api_players.size > 1) ? [:launched] : %i[launched ready]
+      ready_statuses = (api_players.size > 1) ? [:LAUNCHED] : %i[LAUNCHED READY]
 
       # For each player, attempt to connect and retry once after closing Sc2 in worst-case
       api_players.each_with_index do |player, i|
@@ -149,7 +154,7 @@ module Sc2
       api_players.each do |player|
         # Clean surrender locally. Lapizistik taught me bad things.
         def player.leave_game
-          debug_end_game(end_result: :Surrender)
+          debug_end_game(end_result: :SURRENDER)
         end
       end
     end

data/lib/sc2ai/paths.rb

@@ -12,19 +12,26 @@ module Sc2
   # Credit to Hannes, Sean and Burny for setting the standard
   class Paths
     # Platform name for Windows
+    # @return [String] "Windows"
     PF_WINDOWS = "Windows"
     # Platform name for WSL1
+    # @return [String] "WSL"
     PF_WSL1 = "WSL1"
     # Platform name for WSL2
+    # @return [String] "WSL2"
     PF_WSL2 = "WSL2"
     # Platform name macOS
+    # @return [String] "Darwin"
     PF_DARWIN = "Darwin"
     # Platform name Linux
+    # @return [String] "Linux"
     PF_LINUX = "Linux"
     # Platform name for Wine
+    # @return [String] "WineLinux"
     PF_WINE = "WineLinux"
 
     # Where within user directory to locate ExecuteInfo.txt
+    # @return [Hash<String, String>] PF_* => "/path/to/StarCraft II"
     BASE_DIR = {
       PF_WINDOWS => "C:/Program Files (x86)/StarCraft II",
       PF_WSL1 => "/mnt/c/Program Files (x86)/StarCraft II",
@@ -35,6 +42,7 @@ module Sc2
     }.freeze
 
     # Where within user directory to locate ExecuteInfo.txt
+    # @return [Hash<String, String>] PF_* => "/path/to/ExecuteInfo.txt"
     EXEC_INFO_PATH = {
       PF_WINDOWS => "Documents/StarCraft II/ExecuteInfo.txt",
       PF_WSL1 => "Documents/StarCraft II/ExecuteInfo.txt",
@@ -45,6 +53,7 @@ module Sc2
     }.freeze
 
     # Path helper for finding executable
+    # @return [Hash<String, String>] PF_* => "SC2_binary.exe"
     BIN_PATH = {
       PF_WINDOWS => "SC2_x64.exe",
       PF_WSL1 => "SC2_x64.exe",
@@ -56,6 +65,7 @@ module Sc2
 
     # Working directory sub-folder per platform.
     # Used when spawning client process on some platforms.
+    # @return [Hash<String, String>] PF_* => "Directory"
     WORKING_DIR = {
       PF_WINDOWS => "Support64",
       PF_WSL1 => "Support64",
@@ -74,7 +84,7 @@ module Sc2
 
       # Bucketed platform names follows convention
       # Uses ENV['SC2PF'] if configured. This is the only way to set "WineLinux"
-      # @return ["Windows","WSL1","WSL2","Darwin","Linux","WineLinux"] string platform name
+      # @return [String] string platform name
       def platform
         return ENV.fetch("SC2PF", nil) unless ENV["SC2PF"].to_s.strip.empty?
 
@@ -252,7 +262,7 @@ module Sc2
       end
 
       # Loads version data
-      # @return [JSON] versions.json
+      # @return [Array] versions.json
       def version_json
         JSON.load_file(Pathname(__dir__.to_s).join("../data/versions.json"))
       end

data/lib/sc2ai/player/actions.rb

@@ -148,8 +148,8 @@ module Sc2
 
       # Issues spatial unit command. Target is either target_screen_coord or target_minimap_coord.
       # @param ability_id [Api::AbilityId]
-      # @param target_screen_coord [Api::Point2I]
-      # @param target_minimap_coord [Api::Point2I]
+      # @param target_screen_coord [Api::PointI]
+      # @param target_minimap_coord [Api::PointI]
       # @param queue_command [Boolean] shift+command
       # @return [void]
       def action_spatial_unit_command(ability_id:, target_screen_coord: nil, target_minimap_coord: nil, queue_command: false)
@@ -166,7 +166,7 @@ module Sc2
       end
 
       # Simulates a click on the minimap to move the camera.
-      # @param center_minimap [Api::Point2I]
+      # @param center_minimap [Api::PointI]
       # @return [void]
       #
       def action_spatial_camera_move(center_minimap:)
@@ -182,10 +182,10 @@ module Sc2
       # Issues spatial unit select point command. Target is either target_screen_coord or target_minimap_coord.
       # @param type [Integer] 1,2,3,4 = Api::ActionSpatialUnitSelectionPoint::Type::*
       #   enum Type {
-      #     Select = 1;         // Equivalent to normal click. Changes selection to unit.
-      #     Toggle = 2;         // Equivalent to shift+click. Toggle selection of unit.
-      #     AllType = 3;        // Equivalent to control+click. Selects all units of a given type.
-      #     AddAllType = 4;     // Equivalent to shift+control+click. Selects all units of a given type.
+      #     SELECT = 1;         // EQUIVALENT TO NORMAL CLICK. CHANGES SELECTION TO UNIT.
+      #     TOGGLE = 2;         // EQUIVALENT TO SHIFT+CLICK. TOGGLE SELECTION OF UNIT.
+      #     ALL_TYPE = 3;        // EQUIVALENT TO CONTROL+CLICK. SELECTS ALL UNITS OF A GIVEN TYPE.
+      #     ADD_ALL_TYPE = 4;     // EQUIVALENT TO SHIFT+CONTROL+CLICK. SELECTS ALL UNITS OF A GIVEN TYPE.
       #   }
       # @param selection_screen_coord [Api::PointI]
       # @return [void]
@@ -221,11 +221,11 @@ module Sc2
       # Populated if Feature Layer or Render interface is enabled.
       # @param action [Integer] 1-5 = Api::ActionControlGroup::ControlGroupAction::*
       #   enum ControlGroupAction {
-      #     Recall = 1;             // Equivalent to number hotkey. Replaces current selection with control group.
-      #     Set = 2;                // Equivalent to Control + number hotkey. Sets control group to current selection.
-      #     Append = 3;             // Equivalent to Shift + number hotkey. Adds current selection into control group.
-      #     SetAndSteal = 4;        // Equivalent to Control + Alt + number hotkey. Sets control group to current selection. Units are removed from other control groups.
-      #     AppendAndSteal = 5;     // Equivalent to Shift + Alt + number hotkey. Adds current selection into control group. Units are removed from other control groups.
+      #     RECALL = 1;             // EQUIVALENT TO NUMBER HOTKEY. REPLACES CURRENT SELECTION WITH CONTROL GROUP.
+      #     SET = 2;                // EQUIVALENT TO CONTROL + NUMBER HOTKEY. SETS CONTROL GROUP TO CURRENT SELECTION.
+      #     APPEND = 3;             // EQUIVALENT TO SHIFT + NUMBER HOTKEY. ADDS CURRENT SELECTION INTO CONTROL GROUP.
+      #     SET_AND_STEAL = 4;        // EQUIVALENT TO CONTROL + ALT + NUMBER HOTKEY. SETS CONTROL GROUP TO CURRENT SELECTION. UNITS ARE REMOVED FROM OTHER CONTROL GROUPS.
+      #     APPEND_AND_STEAL = 5;     // EQUIVALENT TO SHIFT + ALT + NUMBER HOTKEY. ADDS CURRENT SELECTION INTO CONTROL GROUP. UNITS ARE REMOVED FROM OTHER CONTROL GROUPS.
       #   }
       # @param control_group_index [Integer] 0-9
       # @return [void]
@@ -280,10 +280,10 @@ module Sc2
       # @param type [Integer] 1-4 = Api::ActionSelectIdleWorker::Type::*
       #
       #   enum Type {
-      #     Set = 1;        // Equivalent to click with no modifiers. Replaces selection with single idle worker.
-      #     Add = 2;        // Equivalent to shift+click. Adds single idle worker to current selection.
-      #     All = 3;        // Equivalent to control+click. Selects all idle workers.
-      #     AddAll = 4;     // Equivalent to shift+control+click. Adds all idle workers to current selection.
+      #     SET = 1;        // EQUIVALENT TO CLICK WITH NO MODIFIERS. REPLACES SELECTION WITH SINGLE IDLE WORKER.
+      #     ADD = 2;        // EQUIVALENT TO SHIFT+CLICK. ADDS SINGLE IDLE WORKER TO CURRENT SELECTION.
+      #     ALL = 3;        // EQUIVALENT TO CONTROL+CLICK. SELECTS ALL IDLE WORKERS.
+      #     ADD_ALL = 4;     // EQUIVALENT TO SHIFT+CONTROL+CLICK. ADDS ALL IDLE WORKERS TO CURRENT SELECTION.
       #   }
       def action_ui_select_idle_worker(type:)
         queue_action Api::Action.new(
@@ -299,15 +299,15 @@ module Sc2
       # @param type [Integer] 1-4 = Api::ActionMultiPanel::Type::*
       # @param unit_index [Integer] n'th unit on panel
       #   enum Type {
-      #     SingleSelect = 1;         // Click on icon
-      #     DeselectUnit = 2;         // Shift Click on icon
-      #     SelectAllOfType = 3;      // Control Click on icon.
-      #     DeselectAllOfType = 4;    // Control+Shift Click on icon.
+      #       SINGLE_SELECT = 1;         // CLICK ON ICON
+      #       DESELECT_UNIT = 2;         // SHIFT CLICK ON ICON
+      #       SELECT_ALL_OF_TYPE = 3;      // CONTROL CLICK ON ICON.
+      #       DESELECT_ALL_OF_TYPE = 4;    // CONTROL+SHIFT CLICK ON ICON.
+      #   }
+      #   message ActionMultiPanel {
+      #     optional Type type = 1;
+      #     optional int32 unit_index = 2;
       #   }
-      # message ActionMultiPanel {
-      #   optional Type type = 1;
-      #   optional int32 unit_index = 2;
-      # }
       def action_ui_multi_panel(type:, unit_index:)
         queue_action Api::Action.new(
           action_ui: Api::ActionUI.new(
@@ -359,8 +359,8 @@ module Sc2
 
       # Send a chat message
       # @param message [String] to send
-      # @param channel [Integer] 1-2, default:Team  Api::ActionChat::Channel::Broadcast = 1, Api::ActionChat::Channel::Team = 2
-      def action_chat(message, channel: Api::ActionChat::Channel::Team)
+      # @param channel [Integer] 1-2, default:TEAM  Api::ActionChat::Channel::BROADCAST = 1, Api::ActionChat::Channel::TEAM = 2
+      def action_chat(message, channel: Api::ActionChat::Channel::TEAM)
         queue_action Api::Action.new(
           action_chat: Api::ActionChat.new(
             channel: channel,
@@ -371,24 +371,43 @@ module Sc2
 
       private
 
+      # @private
+      # Clears action errors. The list should be empty before we
+      # do build the errors from our batch action of this step
+      def clear_action_errors
+        @action_errors = []
+      end
+
       # Sends actions via api and flushes action_queue
+      # @return [Api::ResponseAction, nil]
       def perform_actions
-        # request_actions = []
-        # @action_queue.each do |queue_type, actions|
-        #   request_actions.push(actions)
-        # end
-
-        @api.action(@action_queue) unless @action_queue.empty?
+        return nil if @action_queue.empty?
+
+        response_action = @api.action(@action_queue)
+        if callback_defined?(:on_action_errors)
+          # Clear action errors
+          clear_action_errors
+          # Loop over every executed action response
+          response_action.result.each_with_index do |action_result, i|
+            next if action_result == Api::ActionResult::SUCCESS
+            executed_action = @action_queue[i]
+            next unless [Api::ActionRaw, Api::ActionUI].include?(executed_action.action_type) # undetectable Api::ActionSpatial,
+
+            @action_errors << Api::ActionError.new(
+              unit_tag: executed_action.unit_tags.first,
+              ability_id: executed_action.ability_id,
+              result: action_result
+            )
+          end
+        end
         clear_action_queue
+        response_action
       end
 
       # Empties and resets @action_queue
       # @return [void]
       def clear_action_queue
         @action_queue = []
-        # TYPES.each do |type|
-        #   @action_queue[type] = []
-        # end
       end
 
       # Returns an array of unit tags from a variety of sources

data/lib/sc2ai/player/debug.rb

@@ -22,7 +22,7 @@ module Sc2
 
       # Prints debug text top left corner
       # @param text [String] will respect newlines
-      # @param size [Size] of font, default 14px
+      # @param size [Integer] of font, default 14px
       # @return [void]
       def debug_print(text, size: 14)
         queue_debug_command Api::DebugCommand.new(
@@ -43,7 +43,7 @@ module Sc2
       # @param left_percent [Numeric] range 0..100. percent from left of screen
       # @param top_percent [Numeric] range 0..100. percent from top of screen
       # @param color [Api::Color] default white
-      # @param size [Size] of font, default 14px
+      # @param size [Integer] of font, default 14px
       # @return [void]
       def debug_text_screen(text, left_percent: 1.0, top_percent: 1.0, color: nil, size: 14)
         queue_debug_command Api::DebugCommand.new(
@@ -67,7 +67,7 @@ module Sc2
       # @param text [String] will respect newlines
       # @param point [Api::Point] point in the world, i.e. unit.pos
       # @param color [Api::Color] default white
-      # @param size [Size] of font, default 14px
+      # @param size [Integer] of font, default 14px
       # @return [void]
       def debug_text_world(text, point:, color: nil, size: 14)
         queue_debug_command Api::DebugCommand.new(
@@ -152,7 +152,7 @@ module Sc2
       # Renders a block on the floor, drawn by 4 lines
       # Pass in either a pos (Position/Unit) or exact x * y coordinates
       # Optional indentation adds padding on borders inward
-      # @param pos [Api::Unit, Api::Position]
+      # @param pos [Api::Unit, Sc2::Position]
       # @param x [Float, Integer]
       # @param y [Float, Integer]
       # @param color [Api::Color]
@@ -166,8 +166,8 @@ module Sc2
           x = pos.pos.x.floor
           y = pos.pos.y.floor
         elsif pos.is_a?(Sc2::Position)
-          x = pos.pos.x.floor
-          y = pos.pos.y.floor
+          x = pos.x.floor
+          y = pos.y.floor
         end
 
         # Raise above floor to prevent texture clipping
@@ -187,18 +187,18 @@ module Sc2
 
       # @param command [Integer] one of Api::DebugGameState::*
       # Possible values:
-      #  Api::DebugGameState::Show_map
-      #  Api::DebugGameState::Control_enemy
-      #  Api::DebugGameState::Food
-      #  Api::DebugGameState::Free
-      #  Api::DebugGameState::All_resources
-      #  Api::DebugGameState::God
-      #  Api::DebugGameState::Minerals
-      #  Api::DebugGameState::Gas
-      #  Api::DebugGameState::Cooldown
-      #  Api::DebugGameState::Tech_tree
-      #  Api::DebugGameState::Upgrade
-      #  Api::DebugGameState::Fast_build
+      #  Api::DebugGameState::SHOW_MAP
+      #  Api::DebugGameState::CONTROL_ENEMY
+      #  Api::DebugGameState::FOOD
+      #  Api::DebugGameState::FREE
+      #  Api::DebugGameState::ALL_RESOURCES
+      #  Api::DebugGameState::GOD
+      #  Api::DebugGameState::MINERALS
+      #  Api::DebugGameState::GAS
+      #  Api::DebugGameState::COOLDOWN
+      #  Api::DebugGameState::TECH_TREE
+      #  Api::DebugGameState::UPGRADE
+      #  Api::DebugGameState::FAST_BUILD
       # @return [void]
       def debug_game_state(command)
         queue_debug_command Api::DebugCommand.new(
@@ -237,7 +237,7 @@ module Sc2
 
       # @private
       # Hangs, crashes and exits the Sc2 client. DO NOT USE.
-      # @param test [Integer] one of Api::DebugTestProcess::Test::Crash, Api::DebugTestProcess::Test::Hang, Api::DebugTestProcess::Test::Exit
+      # @param test [Integer] one of Api::DebugTestProcess::Test::CRASH, Api::DebugTestProcess::Test::HANG, Api::DebugTestProcess::Test::EXIT
       # @param delay_ms [Integer] default 0, how long this test is delayed
       # @return [void]
       def debug_test_process(test:, delay_ms: 0)
@@ -260,8 +260,8 @@ module Sc2
         )
       end
 
-      # Ends game with a specified result of either Surrender or DeclareVictory
-      # @param end_result [Integer] either 1/2.  Api::DebugEndGame::EndResult::Surrender or Api::DebugEndGame::EndResult::DeclareVictory
+      # Ends game with a specified result of either :SURRENDER or :DECLARE_VICTORY
+      # @param end_result [Integer] either 1/2.  Api::DebugEndGame::EndResult::SURRENDER or Api::DebugEndGame::EndResult::DECLARE_VICTORY
       # @return [void]
       def debug_end_game(end_result:)
         queue_debug_command Api::DebugCommand.new(

data/lib/sc2ai/player/game_state.rb

@@ -5,7 +5,7 @@ module Sc2
     # Holds game state
     module GameState
       # @!attribute status
-      #   @return [:launched, :in_game, :in_replay, :ended, :quit, :unknown] status
+      #   @return [:LAUNCHED, :IN_GAME, :IN_REPLAY, :ENDED, :QUIT, :UNKNOWN] status
       attr_accessor :status
 
       include Connection::StatusListener
@@ -27,10 +27,16 @@ module Sc2
       # Access useful game information. Used in parsed pathing grid, terrain height, placement grid.
       # Holds Api::ResponseGameInfo::#start_locations.
       # @return [Api::ResponseGameInfo]
-      attr_reader :game_info
+      def game_info
+        if @game_info_task&.running?
+          @game_info_task&.wait
+          @game_info_task = nil
+        end
+        @game_info
+      end
 
       def game_info=(new_info)
-        @game_info_loop = game_loop || 0
+        @game_info_loop = game_loop
         @game_info = new_info
       end
 
@@ -40,19 +46,6 @@ module Sc2
       # @return [Integer]
       attr_accessor :game_info_loop
 
-      # Determines if your game_info will be refreshed at this moment
-      # Has a hard-capped refresh of only ever 4 steps
-      # In general game_info is only refreshed Player::Bot reads from pathing_grid or placement_grid
-      # @return [Boolean]
-      def game_info_stale?
-        return true if game_info_loop.nil? || game_info.nil?
-        return false if game_info_loop == game_loop
-
-        # Note: No minimum step count set anymore
-        # We can do something like, only updating every 2+ frames:
-        game_info_loop + 4 <= game_loop
-      end
-
       # @!attribute data
       #   @return [Api::ResponseData]
       attr_accessor :data
@@ -141,14 +134,14 @@ module Sc2
           player_id: 0,
           minerals: 50,
           vespene: 0,
-          food_cap: ((race == Api::Race::Zerg) ? 14 : 15),
+          food_cap: ((race == Api::Race::ZERG) ? 14 : 15),
           food_used: 12,
           food_army: 0,
           food_workers: 12,
           idle_worker_count: 0,
           army_count: 0,
           warp_gate_count: 0,
-          larva_count: ((race == Api::Race::Zerg) ? 3 : 0)
+          larva_count: ((race == Api::Race::ZERG) ? 3 : 0)
         )
       end