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.

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_units, #effects, #event_structures_completed, #event_structures_started, #event_units_created, #event_units_damaged, #event_units_type_changed, #neutral, #power_sources, #radar_rings, #structures, #units, #upgrades_completed

Attributes included from GameState

#chats_received, #data, #game_info, #game_info_loop, #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_unit_value, #debug_text_screen, #debug_text_world, #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?, #unit_data, #unit_group_from_tags, #unit_has_attribute?, #upgrade_data, #upgrade_in_progress?, #upgrades_in_progress

Methods included from GameState

#common, #game_info_stale?, #on_status_change

Methods included from Connection::StatusListener

#on_status_change

Constructor Details

#initialize(race:, name:) ⇒ Bot

Returns a new instance of Bot.



194
195
196
197
198
199
200
 
# File 'lib/sc2ai/player.rb', line 194

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

  configure
end

Instance Attribute Details

#enemy ⇒ Sc2::Player::Enemy

Returns:



184
185
186
 
# File 'lib/sc2ai/player.rb', line 184

def enemy
  @enemy
end

#geo ⇒ Sc2::Player::Geometry

Returns geo and map helper functions.

Returns:



192
193
194
 
# File 'lib/sc2ai/player.rb', line 192

def geo
  @geo
end

#previous ⇒ Sc2::Player::PreviousState

Returns the previous state of the game.

Returns:



188
189
190
 
# File 'lib/sc2ai/player.rb', line 188

def previous
  @previous
end

Instance Method Details

#configure ⇒ Object Also known as: before_join

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


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

def configure
end

#on_action_errors(errors) ⇒ Object

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

Parameters:

  • errors (Array<Api::ActionError>) 


285
286
287
 
# File 'lib/sc2ai/player.rb', line 285

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

#on_actions_performed(actions) ⇒ Object

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

Parameters:

  • actions (Array<Api::Action>) —

    a list of actions which were performed



292
293
294
 
# File 'lib/sc2ai/player.rb', line 292

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

#on_alerts(alerts) ⇒ Object

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

Examples:

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

Parameters:

  • alerts (Array<Integer>) —

    array of Api::Alert::*

See Also:

  • Alert in sc2api.proto for options


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

def on_alerts(alerts)
end

#on_finish(result) ⇒ Object

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::Victory::Defeat or Api::Result::Victory::Undecided



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

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

#on_parse_observation_unit(unit) ⇒ Object

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



326
327
 
# File 'lib/sc2ai/player.rb', line 326

def on_parse_observation_unit(unit)
end

#on_random_race_detected(race) ⇒ Object

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

Parameters:

  • race (Integer) —

    Api::Race::* excl *::Random



279
280
 
# File 'lib/sc2ai/player.rb', line 279

def on_random_race_detected(race)
end

#on_start ⇒ Object

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



243
244
245
 
# File 'lib/sc2ai/player.rb', line 243

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

#on_step ⇒ Object

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

Raises:

  • (NotImplementedError) 


249
250
251
252
253
254
255
256
257
 
# File 'lib/sc2ai/player.rb', line 249

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) ⇒ Object

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

Parameters:



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

def on_structure_completed(unit)
end

#on_structure_started(unit) ⇒ Object

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

Parameters:



354
355
 
# File 'lib/sc2ai/player.rb', line 354

def on_structure_started(unit)
end

#on_unit_created(unit) ⇒ Object

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

Parameters:



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

def on_unit_created(unit)
end

#on_unit_damaged(unit, amount) ⇒ Object

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

Parameters:

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

    of damage



367
368
 
# File 'lib/sc2ai/player.rb', line 367

def on_unit_damaged(unit, amount)
end

#on_unit_destroyed(unit) ⇒ Object

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.event_units_destroyed

Parameters:

See Also:

  • Units#units_destroyed


334
335
 
# File 'lib/sc2ai/player.rb', line 334

def on_unit_destroyed(unit)
end

#on_unit_type_changed(unit, previous_unit_type_id) ⇒ Object

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.event_structures_started

Parameters:

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

    Api::UnitTypeId::*



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

def on_unit_type_changed(unit, previous_unit_type_id)
end

#on_upgrades_completed(upgrade_ids) ⇒ Object

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

Parameters:

  • upgrade_ids (Array<Integer>) —

    Api::UpgradeId::*



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

def on_upgrades_completed(upgrade_ids)
end

#play ⇒ Api::Result::Victory, ...

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

Returns:

  • (Api::Result::Victory, Api::Result::Defeat, Api::Result::Tie, Api::Result::Undecided) —

    result



218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
 
# File 'lib/sc2ai/player.rb', line 218

def play
  # Step 0
  prepare_start
  refresh_state
  started

  # Callback before first step is taken
  on_start
  # Callback for step 0
  on_step

  # Step 1 to n
  loop do
    r = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
    perform_actions
    perform_debug_commands # TODO: Detect IS_LADDER? -> unless IS_LADDER?
    step_forward
    puts (::Process.clock_gettime(::Process::CLOCK_MONOTONIC) - r) * 1000
    return @result unless @result.nil?
    break if @status != :in_game
  end
end