Module: Sc2::Player::Debug

Included in:
Bot
Defined in:
lib/sc2ai/player/debug.rb

Overview

WARNING! Debug methods will not be available on Ladder This provides debug helper functions for RequestDebug

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#debug_command_queueObject

Holds debug commands which will be queued off each time we step forward



11
12
13
# File 'lib/sc2ai/player/debug.rb', line 11

def debug_command_queue
  @debug_command_queue
end

#debug_commands_queueArray<Api::Action>

Returns:



11
# File 'lib/sc2ai/player/debug.rb', line 11

attr_accessor :debug_command_queue

Instance Method Details

#debug_create_unit(unit_type_id:, owner:, pos:, quantity: 1) ⇒ void

This method returns an undefined value.

Spawns a quantity of units under an owner at position given

Parameters:

  • unit_type_id (Integer)

    Api::UnitTypeId::*

  • owner (Integer)

    typically you are 1 and 2 is enemy (see @common.player_id)

  • pos (Api::Point2D)

    position in 2d

  • quantity (Integer) (defaults to: 1)

    default 1



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

def debug_create_unit(unit_type_id:, owner:, pos:, quantity: 1)
  queue_debug_command Api::DebugCommand.new(
    create_unit: Api::DebugCreateUnit.new(
      unit_type: unit_type_id,
      owner:,
      pos:,
      quantity:
    )
  )
end

#debug_draw_box(point:, radius: 0.5, color: nil) ⇒ void

Note:

Api::Color RGB is broken for this command. Will use min(r,b)

Note:

Z index is elevated 0.02 so the line is visible and doesn’t clip through terrain

This method returns an undefined value.

Draws a box around position xy at base of z. Good for structure boxing.

Examples:

# Draws a box on structure placement grid
debug_draw_box(point: unit.pos, radius: unit.footprint_radius)

Parameters:

  • point (Api::Point)
  • radius (Float) (defaults to: 0.5)

    default one tile wide, 1.0

  • color (Api::Color) (defaults to: nil)

    default white. min(r,b) is used for both r&b



119
120
121
122
123
124
125
126
127
128
129
130
131
# File 'lib/sc2ai/player/debug.rb', line 119

def debug_draw_box(point:, radius: 0.5, color: nil)
  queue_debug_command Api::DebugCommand.new(
    draw: Api::DebugDraw.new(
      boxes: [
        Api::DebugBox.new(
          min: Api::Point.new(x: point.x - radius, y: point.y - radius, z: point.z + 0.03),
          max: Api::Point.new(x: point.x + radius, y: point.y + radius, z: point.z + (radius * 2) + 0.03),
          color:
        )
      ]
    )
  )
end

#debug_draw_line(p0:, p1:, color: nil) ⇒ void

This method returns an undefined value.

Draws a line between two Api::Point’s for color

Parameters:



92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
# File 'lib/sc2ai/player/debug.rb', line 92

def debug_draw_line(p0:, p1:, color: nil)
  queue_debug_command Api::DebugCommand.new(
    draw: Api::DebugDraw.new(
      lines: [
        Api::DebugLine.new(
          color:,
          line: Api::Line.new(
            p0:,
            p1:
          )
        )
      ]
    )
  )
end

#debug_draw_sphere(point:, radius: 1.0, color: nil) ⇒ void

This method returns an undefined value.

Debug draws a sphere at position with a radius in color

Parameters:

  • point (Api::Point)
  • radius (Float) (defaults to: 1.0)

    default one tile wide, 1.0

  • color (Api::Color) (defaults to: nil)

    default white



138
139
140
141
142
143
144
145
146
147
148
149
150
# File 'lib/sc2ai/player/debug.rb', line 138

def debug_draw_sphere(point:, radius: 1.0, color: nil)
  queue_debug_command Api::DebugCommand.new(
    draw: Api::DebugDraw.new(
      spheres: [
        Api::DebugSphere.new(
          p: point,
          r: radius,
          color:
        )
      ]
    )
  )
end

#debug_end_game(end_result:) ⇒ void

This method returns an undefined value.

Ends game with a specified result of either :SURRENDER or :DECLARE_VICTORY

Parameters:

  • end_result (Integer)

    either 1/2. Api::DebugEndGame::EndResult::SURRENDER or Api::DebugEndGame::EndResult::DECLARE_VICTORY



266
267
268
269
270
271
272
# File 'lib/sc2ai/player/debug.rb', line 266

def debug_end_game(end_result:)
  queue_debug_command Api::DebugCommand.new(
    end_game: Api::DebugEndGame.new(
      end_result:
    )
  )
end

#debug_game_state(command) ⇒ void

Parameters:

  • command (Integer)

    one of Api::DebugGameState::*



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

def debug_game_state(command)
  queue_debug_command Api::DebugCommand.new(
    game_state: command
  )
end

#debug_kill_unit(unit_tags:) ⇒ void

This method returns an undefined value.

Kills a target unit or unit tag

Parameters:

  • unit_tags (Integer, Array<Integer>)

    one or many unit tags to kill



229
230
231
232
233
234
235
236
# File 'lib/sc2ai/player/debug.rb', line 229

def debug_kill_unit(unit_tags:)
  unit_tags = [unit_tags] if unit_tags.is_a? Integer
  queue_debug_command Api::DebugCommand.new(
    kill_unit: Api::DebugKillUnit.new(
      tag: unit_tags
    )
  )
end

#debug_print(text, size: 14) ⇒ void

This method returns an undefined value.

Prints debug text top left corner

Parameters:

  • text (String)

    will respect newlines

  • size (Integer) (defaults to: 14)

    of font, default 14px



27
28
29
30
31
32
33
34
35
36
37
38
39
# File 'lib/sc2ai/player/debug.rb', line 27

def debug_print(text, size: 14)
  queue_debug_command Api::DebugCommand.new(
    draw: Api::DebugDraw.new(
      text: [
        Api::DebugText.new(
          text:,
          size:,
          virtual_pos: Api::Point.new(x: 0.01, y: 0.01) # unit or fixed position.
        )
      ]
    )
  )
end

#debug_set_score(score: 0.0) ⇒ Object

Useful only for single-player “curriculum” maps

Parameters:

  • score (Float) (defaults to: 0.0)

    sets the score



255
256
257
258
259
260
261
# File 'lib/sc2ai/player/debug.rb', line 255

def debug_set_score(score: 0.0)
  queue_debug_command Api::DebugCommand.new(
    score: Api::DebugSetScore.new(
      score:
    )
  )
end

#debug_set_unit_value(unit_tag:, unit_value:, value:) ⇒ void

This method returns an undefined value.

Sets unit_value Energy, Life or Shields for a specific unit tag to given value

Parameters:

  • unit_tag (Integer)
  • unit_value (Integer)

    1=Energy,2=Life,3=Shields one of Api::DebugSetUnitValue::UnitValue::*

  • value (Float)

    the value which the attribute will be set to



279
280
281
282
283
284
285
286
287
# File 'lib/sc2ai/player/debug.rb', line 279

def debug_set_unit_value(unit_tag:, unit_value:, value:)
  queue_debug_command Api::DebugCommand.new(
    unit_value: Api::DebugSetUnitValue.new(
      unit_tag:,
      unit_value:, # property
      value: # value
    )
  )
end

#debug_test_process(test:, delay_ms: 0) ⇒ void

This method returns an undefined value.

Hangs, crashes and exits the Sc2 client. DO NOT USE.

Parameters:

  • test (Integer)

    one of Api::DebugTestProcess::Test::CRASH, Api::DebugTestProcess::Test::HANG, Api::DebugTestProcess::Test::EXIT

  • delay_ms (Integer) (defaults to: 0)

    default 0, how long this test is delayed



243
244
245
246
247
248
249
250
# File 'lib/sc2ai/player/debug.rb', line 243

def debug_test_process(test:, delay_ms: 0)
  queue_debug_command Api::DebugCommand.new(
    test_process: Api::DebugTestProcess.new(
      test:,
      delay_ms:
    )
  )
end

#debug_text_screen(text, left_percent: 1.0, top_percent: 1.0, color: nil, size: 14) ⇒ void

This method returns an undefined value.

Prints text on screen from top and left

Parameters:

  • text (String)

    will respect newlines

  • left_percent (Numeric) (defaults to: 1.0)

    range 0..100. percent from left of screen

  • top_percent (Numeric) (defaults to: 1.0)

    range 0..100. percent from top of screen

  • color (Api::Color) (defaults to: nil)

    default white

  • size (Integer) (defaults to: 14)

    of font, default 14px



48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
# File 'lib/sc2ai/player/debug.rb', line 48

def debug_text_screen(text, left_percent: 1.0, top_percent: 1.0, color: nil, size: 14)
  queue_debug_command Api::DebugCommand.new(
    draw: Api::DebugDraw.new(
      text: [
        Api::DebugText.new(
          text:,
          virtual_pos: Api::Point.new(
            x: left_percent.to_f / 100,
            y: top_percent.to_f / 100
          ),
          color:,
          size:
        )
      ]
    )
  )
end

#debug_text_world(text, point:, color: nil, size: 14) ⇒ void

This method returns an undefined value.

Prints text on screen at 3d world position

Parameters:

  • text (String)

    will respect newlines

  • point (Api::Point)

    point in the world, i.e. unit.pos

  • color (Api::Color) (defaults to: nil)

    default white

  • size (Integer) (defaults to: 14)

    of font, default 14px



72
73
74
75
76
77
78
79
80
81
82
83
84
85
# File 'lib/sc2ai/player/debug.rb', line 72

def debug_text_world(text, point:, color: nil, size: 14)
  queue_debug_command Api::DebugCommand.new(
    draw: Api::DebugDraw.new(
      text: [
        Api::DebugText.new(
          text:,
          world_pos: point,
          color:,
          size:
        )
      ]
    )
  )
end

#debug_tile(pos = nil, x: nil, y: nil, color: nil, indent: 0.05) ⇒ Object

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

Examples:

debug_tile(x: 12.3, y: 4.56, color: Api::Color.new(r: 255, g: 0, b: 0))
debug_tile(some_unit)
debug_tile(some_unit.pos)

Parameters:

  • pos (Api::Unit, Sc2::Position) (defaults to: nil)
  • x (Float, Integer) (defaults to: nil)
  • y (Float, Integer) (defaults to: nil)
  • color (Api::Color) (defaults to: nil)
  • indent (Float) (defaults to: 0.05)

    default 0.05. should be lower than < 1.0



164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
# File 'lib/sc2ai/player/debug.rb', line 164

def debug_tile(pos = nil, x: nil, y: nil, color: nil, indent: 0.05)
  if pos.is_a?(Api::Unit)
    x = pos.pos.x.floor
    y = pos.pos.y.floor
  elsif pos.is_a?(Sc2::Position)
    x = pos.x.floor
    y = pos.y.floor
  end

  # Raise above floor to prevent texture clipping
  z = geo.terrain_height(x:, y:).to_f + 0.1
  tl = Api::Point[x + indent, y + 1.0 - indent, z]
  bl = Api::Point[x + indent, y + indent, z]
  br = Api::Point[x + 1.0 - indent, y + indent, z]
  tr = Api::Point[x + 1.0 - indent, y + 1.0 - indent, z]

  debug_draw_line(p0: tl, p1: bl, color:)
  debug_draw_line(p0: bl, p1: br, color:)
  debug_draw_line(p0: br, p1: tr, color:)
  debug_draw_line(p0: tr, p1: tl, color:)
end

#queue_debug_command(debug_command) ⇒ void

This method returns an undefined value.

Queues debug command for performing later

Parameters:



16
17
18
19
# File 'lib/sc2ai/player/debug.rb', line 16

def queue_debug_command(debug_command)
  @debug_command_queue ||= []
  @debug_command_queue << debug_command
end