Class: Sc2::Player::Bot

Inherits:
Sc2::Player show all
Includes:
Actions, Debug, Units
Defined in:
lib/sc2ai/player.rb

Overview

An object which interacts with an SC2 client and is game-aware.

Constant Summary

Constants included from Actions

Actions::COMBINABLE_ABILITIES

Constants inherited from Sc2::Player

IDENTIFIED_RACES

Instance Attribute Summary collapse

Attributes included from Debug

#debug_command_queue, #debug_commands_queue

Attributes included from Actions

#action_queue

Attributes included from Units

#all_seen_unit_tags, #all_units, #blips, #effects, #event_units_damaged, #event_units_destroyed, #neutral, #placeholders, #power_sources, #radar_rings, #structures, #units, #upgrades_completed

Attributes inherited from Sc2::Player

#IDENTIFIED_RACES, #ai_build, #api, #callbacks_defined, #difficulty, #enable_feature_layer, #interface_options, #name, #opponent_id, #race, #realtime, #step_count, #timer, #type

Attributes included from GameState

#chats_received, #data, #game_info, #game_loop, #observation, #result, #spent_minerals, #spent_supply, #spent_vespene, #status

Instance Method Summary collapse

Methods included from Debug

#debug_create_unit, #debug_draw_box, #debug_draw_line, #debug_draw_sphere, #debug_end_game, #debug_game_state, #debug_kill_unit, #debug_print, #debug_set_score, #debug_set_unit_value, #debug_test_process, #debug_text_screen, #debug_text_world, #debug_tile, #queue_debug_command

Methods included from Actions

#action, #action_chat, #action_raw_camera_move, #action_raw_toggle_autocast, #action_raw_unit_command, #action_spatial_camera_move, #action_spatial_unit_command, #action_spatial_unit_selection_point, #action_spatial_unit_selection_rect, #action_ui_cargo_panel_unload, #action_ui_control_group, #action_ui_multi_panel, #action_ui_production_panel_remove_from_queue, #action_ui_select_army, #action_ui_select_idle_worker, #action_ui_select_larva, #action_ui_select_warp_gates, #action_ui_toggle_autocast, #build, #queue_action, #research, #warp

Methods included from Units

#ability_data, #can_afford?, #can_afford_upgrade?, #subtract_cost, #tech_requirement_met?, #unit_ability_available?, #unit_data, #unit_group_from_tags, #unit_has_attribute?, #units_in_progress, #upgrade_completed?, #upgrade_data, #upgrade_in_progress?, #upgrades_in_progress

Methods inherited from Sc2::Player

#callback_defined?, #connect, #create_game, #disconnect, #join_game, #leave_game, #prepare_start, #quit, #race_unknown?, #refresh_game_info, #refresh_state, #requires_client?, #set_enemy, #set_race_for_random, #started, #step_forward

Methods included from GameState

#available_abilities, #common, #on_status_change

Methods included from Connection::StatusListener

#on_status_change

Constructor Details

#initialize(race:, name:) ⇒ Bot

Returns a new instance of Bot.



215
216
217
218
219
220
221
 
# File 'lib/sc2ai/player.rb', line 215

def initialize(race:, name:)
  super(race:, name:, type: Api::PlayerType::PARTICIPANT, difficulty: nil, ai_build: nil)
  @previous = Sc2::Player::PreviousState.new
  @geo = Sc2::Player::Geo.new(self)

  configure
end

Instance Attribute Details

#enemy ⇒ Sc2::Player::Enemy

Returns:



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

def enemy
  @enemy
end

#geo ⇒ Sc2::Player::Geo

Returns geo and map helper functions.

Returns:



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

def geo
  @geo
end

#previous ⇒ Sc2::Player::PreviousState

Returns the previous state of the game.

Returns:



209
210
211
 
# File 'lib/sc2ai/player.rb', line 209

def previous
  @previous
end

Instance Method Details

#configure ⇒ void

This method returns an undefined value.

Override to customize initialization Alias of before_join You can enable_feature_layer=true, set step_count, define

Examples:

def configure
  step_count = 4 # Update less frequently
  enable_feature_layer = true

end



233
234
 
# File 'lib/sc2ai/player.rb', line 233

def configure
end

#on_action_errors(errors) ⇒ void

This method returns an undefined value.

Called on step if errors are present. Equivalent of UI red text errors. Override to read action errors.

Parameters:



315
316
317
 
# File 'lib/sc2ai/player.rb', line 315

def on_action_errors(errors)
  # Sc2.logger.debug errors
end

#on_actions_performed(actions) ⇒ void

This method returns an undefined value.

Actions this player performed since the last Observation. Override to read actions successfully performed

Parameters:



323
324
325
 
# File 'lib/sc2ai/player.rb', line 323

def on_actions_performed(actions)
  # Sc2.logger.debug actions
end

#on_alerts(alerts) ⇒ void

This method returns an undefined value.

Callback when observation.alerts is populated Override to use alerts or read Player.observation.alerts

Examples:

alerts.each do |alert|
  case alert
  when :NUCLEAR_LAUNCH_DETECTED
    pp "TAKE COVER!"
  when :NYDUS_WORM_DETECTED
    pp "FIND THE WORM!"
  end
end

Parameters:

  • alerts (Array<Integer>) —

    array of Api::Alert::*

See Also:

  • Alert in sc2api.proto for options


341
342
 
# File 'lib/sc2ai/player.rb', line 341

def on_alerts(alerts)
end

#on_finish(result) ⇒ void

This method returns an undefined value.

Override to handle game result (:Victory/:Loss/:Tie) Called when game has ended with a result, i.e. result = :Victory

Examples:

def on_finish(result)
  if result == :VICTORY
    puts "Yay!"
  else
    puts "Lets try again!"
  end
end

Parameters:

  • result (Symbol) —

    Api::Result::VICTORY or Api::Result::DEFEAT or Api::Result::UNDECIDED



300
301
302
 
# File 'lib/sc2ai/player.rb', line 300

def on_finish(result)
  # Sc2.logger.debug { "#{self.class} on_finish" }
end

#on_parse_observation_unit(unit) ⇒ void

This method returns an undefined value.

Callback, on observation parse when iterating over every unit Can be useful for decorating additional properties on a unit before on_step A Sc2::Player should override this to decorate additional properties



360
361
 
# File 'lib/sc2ai/player.rb', line 360

def on_parse_observation_unit(unit)
end

#on_random_race_detected(race) ⇒ void

This method returns an undefined value.

Called when Random race is first detected. Override to handle race identification of random enemy.

Parameters:



308
309
 
# File 'lib/sc2ai/player.rb', line 308

def on_random_race_detected(race)
end

#on_start ⇒ void

This method returns an undefined value.

Override to perform steps before first on_step gets called. Current game_loop is 0 and @api is available



269
270
271
 
# File 'lib/sc2ai/player.rb', line 269

def on_start
  # Sc2.logger.debug { "#{self.class} on_start" }
end

#on_step ⇒ void

This method returns an undefined value.

Override to implement your own game logic. Gets called whenever the game moves forward.

Raises:

  • (NotImplementedError) 


276
277
278
279
280
281
282
283
284
 
# File 'lib/sc2ai/player.rb', line 276

def on_step
  return unless is_a? Bot

  raise NotImplementedError,
    "You are required to override #{__method__} in your Bot with: def #{__method__}"

  # Sc2.logger.debug { "#{self.class}.#{__method__}" }
  # Sc2.logger.debug "on_step"
end

#on_structure_completed(unit) ⇒ void

This method returns an undefined value.

Callback for structure building is completed Override to use in your bot class or use Player.

Parameters:



399
400
 
# File 'lib/sc2ai/player.rb', line 399

def on_structure_completed(unit)
end

#on_structure_started(unit) ⇒ void

This method returns an undefined value.

Callback for structure building began Override to use in your bot class.

Parameters:



392
393
 
# File 'lib/sc2ai/player.rb', line 392

def on_structure_started(unit)
end

#on_unit_created(unit) ⇒ void

This method returns an undefined value.

Callback for unit created. Override to use in your bot class.

Parameters:



376
377
 
# File 'lib/sc2ai/player.rb', line 376

def on_unit_created(unit)
end

#on_unit_damaged(unit, amount) ⇒ void

This method returns an undefined value.

Callback for unit (Unit/Structure) taking damage Override to use in your bot class or use Player.

Parameters:

  • unit (Api::Unit)
  • amount (Integer) —

    of damage



407
408
 
# File 'lib/sc2ai/player.rb', line 407

def on_unit_damaged(unit, amount)
end

#on_unit_destroyed(unit) ⇒ void

This method returns an undefined value.

Callback for unit destroyed. Tags might be found in ‘previous.all_units` This excludes unknown objects, like projectiles and only shows things the API has “seen” as a unit Override to use in your bot class or use Player.

Parameters:

See Also:

  • Units#units_destroyed


369
370
 
# File 'lib/sc2ai/player.rb', line 369

def on_unit_destroyed(unit)
end

#on_unit_type_changed(unit, previous_unit_type_id) ⇒ void

This method returns an undefined value.

Callback for unit type changing. To detect certain unit creations, you should use this method to watch morphs. Override to use in your bot class or use Player.

Parameters:

  • unit (Api::Unit)
  • previous_unit_type_id (Integer) —

    Api::UnitTypeId::*



385
386
 
# File 'lib/sc2ai/player.rb', line 385

def on_unit_type_changed(unit, previous_unit_type_id)
end

#on_upgrades_completed(upgrade_ids) ⇒ void

This method returns an undefined value.

Callback when upgrades are completed, multiple might finish on the same observation.

Parameters:

  • upgrade_ids (Array<Integer>) —

    Api::UpgradeId::*



347
348
 
# File 'lib/sc2ai/player.rb', line 347

def on_upgrades_completed(upgrade_ids)
end

#play ⇒ Integer

TODO: If this suffices for Bot and Observer, they should share this code. Initializes and refreshes game data and runs the game loop

Returns:

  • (Integer) —

    One of Api::Result::VICTORY, Api::Result::DEFEAT, Api::Result::TIE, Api::Result::UNDECIDED



239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
 
# File 'lib/sc2ai/player.rb', line 239

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

  # Step 1 to n
  loop do
    perform_actions
    perform_debug_commands unless Sc2.ladder?
    step_forward

    return @result unless @result.nil?
    break if @status != :IN_GAME
  end
end