robot_wars 0.1.0

data/lib/robot_wars/action_parser.rb

@@ -0,0 +1,66 @@
+module RobotWars
+  # Parses a pilot's free-text reply into an Action, per the grammar a
+  # warrior's brain is instructed to answer in:
+  #
+  #   STAY
+  #   MOVE <north|northeast|east|southeast|south|southwest|west|northwest>
+  #   ATTACK <x>,<y> <points>
+  #   DEFEND <points>
+  #
+  # Anything that doesn't match becomes Action.invalid (RULES.md 21's
+  # solo-conflict penalty, via TurnResolver) rather than raising — a
+  # pilot's bad reply is a turn's mistake, not a crash.
+  # :reek:RepeatedConditional -- each parse_* method guards its own independent regex match; they only share a name.
+  class ActionParser
+    DIRECTIONS = {
+      "north" => Direction::NORTH, "northeast" => Direction::NORTHEAST,
+      "east" => Direction::EAST, "southeast" => Direction::SOUTHEAST,
+      "south" => Direction::SOUTH, "southwest" => Direction::SOUTHWEST,
+      "west" => Direction::WEST, "northwest" => Direction::NORTHWEST
+    }.freeze
+
+    MOVE_PATTERN   = /\bMOVE\s+(\w+)/i
+    ATTACK_PATTERN = /\bATTACK\s*\(?\s*(-?\d+)\s*,\s*(-?\d+)\s*\)?\s+(\d+)/i
+    DEFEND_PATTERN = /\bDEFEND\s+(\d+)/i
+    STAY_PATTERN   = /\bSTAY\b/i
+
+    def parse(text)
+      return Action.invalid if text.nil?
+
+      parse_move(text) || parse_attack(text) || parse_defend(text) || parse_stay(text) || Action.invalid
+    end
+
+    private
+
+    def parse_move(text)
+      match = MOVE_PATTERN.match(text)
+      return unless match
+
+      direction = DIRECTIONS[match[1].downcase]
+      direction && Action.move(direction)
+    end
+
+    def parse_attack(text)
+      match = ATTACK_PATTERN.match(text)
+      return unless match
+
+      points = match[3].to_i
+      return unless points.positive?
+
+      square = Position.new(x: match[1].to_i, y: match[2].to_i)
+      Action.attack(square: square, points: points)
+    end
+
+    def parse_defend(text)
+      match = DEFEND_PATTERN.match(text)
+      return unless match
+
+      points = match[1].to_i
+      points.positive? ? Action.defend(points: points) : nil
+    end
+
+    def parse_stay(text)
+      Action.stay if STAY_PATTERN.match?(text)
+    end
+  end
+end

data/lib/robot_wars/board.rb

@@ -0,0 +1,47 @@
+module RobotWars
+  # Board geometry only (RULES.md 1: bounded board; 2: size set at game
+  # start). Holds no robots or ownership — see OccupancyMap and Territory.
+  class Board
+    attr_reader :width, :height
+
+    def initialize(width:, height:)
+      raise ArgumentError, "width must be positive" unless width.positive?
+      raise ArgumentError, "height must be positive" unless height.positive?
+
+      @width = width
+      @height = height
+    end
+
+    def on_board?(position)
+      position.x.between?(0, width - 1) && position.y.between?(0, height - 1)
+    end
+
+    def neighbors_of(position)
+      position.neighbors.select { |neighbor| on_board?(neighbor) }
+    end
+
+    # :reek:NestedIterators -- a 2D grid walk is inherently two loops deep.
+    # :reek:UncommunicativeVariableName -- x and y ARE the communicative names for grid coordinates.
+    def each_position
+      return enum_for(:each_position) unless block_given?
+
+      (0...width).each do |x|
+        (0...height).each { |y| yield Position.new(x: x, y: y) }
+      end
+    end
+
+    def random_position(random: Random.new)
+      Position.new(x: random.rand(width), y: random.rand(height))
+    end
+
+    # `count` distinct squares (RULES.md 6: no two robots share a
+    # starting square).
+    # :reek:FeatureEnvy -- `squares` is a local snapshot of this board's own positions, not another object's data.
+    def sample_positions(count, random: Random.new)
+      squares = each_position.to_a
+      raise ArgumentError, "cannot place #{count} robots on #{squares.size} squares" if count > squares.size
+
+      squares.sample(count, random: random)
+    end
+  end
+end

data/lib/robot_wars/conflict_resolver.rb

@@ -0,0 +1,32 @@
+module RobotWars
+  # Resolves a square conflict (RULES.md 13-16): one shared roll damages
+  # every robot present, and the highest remaining life wins the square.
+  # A tie counts as a loss for everyone.
+  class ConflictResolver
+    Result = Data.define(:winner, :losers, :roll)
+
+    def initialize(roll_generator: RollGenerator.new)
+      @roll_generator = roll_generator
+    end
+
+    def resolve(robots)
+      raise ArgumentError, "a conflict needs at least 2 robots" if robots.size < 2
+
+      roll = @roll_generator.roll
+      robots.each { |robot| robot.apply_damage(roll) }
+
+      winner = winner_of(robots)
+      losers = robots - Array(winner)
+
+      Result.new(winner: winner, losers: losers, roll: roll)
+    end
+
+    private
+
+    def winner_of(robots)
+      highest_life = robots.map(&:life).max
+      contenders = robots.select { |robot| robot.life == highest_life }
+      contenders.one? ? contenders.first : nil
+    end
+  end
+end

data/lib/robot_wars/direction.rb

@@ -0,0 +1,30 @@
+module RobotWars
+  # The 8 one-square move directions (RULES.md 9: a robot moves like a
+  # chess king).
+  # :reek:TooManyConstants -- 8 compass points plus their two lookup tables; the compass isn't getting bigger.
+  module Direction
+    OFFSETS = [
+      Position.new(x: 0, y: -1),
+      Position.new(x: 1, y: -1),
+      Position.new(x: 1, y: 0),
+      Position.new(x: 1, y: 1),
+      Position.new(x: 0, y: 1),
+      Position.new(x: -1, y: 1),
+      Position.new(x: -1, y: 0),
+      Position.new(x: -1, y: -1)
+    ].freeze
+
+    NORTH, NORTHEAST, EAST, SOUTHEAST, SOUTH, SOUTHWEST, WEST, NORTHWEST = OFFSETS
+
+    NAMES = {
+      NORTH => "north", NORTHEAST => "northeast",
+      EAST => "east", SOUTHEAST => "southeast",
+      SOUTH => "south", SOUTHWEST => "southwest",
+      WEST => "west", NORTHWEST => "northwest"
+    }.freeze
+
+    # The compass name of a direction offset, for showing a move to a
+    # human ("north"), or nil for a position that isn't a direction.
+    def self.name_of(offset) = NAMES[offset]
+  end
+end

data/lib/robot_wars/fixed_roll_generator.rb

@@ -0,0 +1,16 @@
+module RobotWars
+  # A queued, deterministic roll source for tests and seeded replays.
+  class FixedRollGenerator
+    Exhausted = Class.new(StandardError)
+
+    def initialize(rolls)
+      @rolls = rolls.dup
+    end
+
+    def roll
+      raise Exhausted, "no more fixed rolls queued" if @rolls.empty?
+
+      @rolls.shift
+    end
+  end
+end

data/lib/robot_wars/game.rb

@@ -0,0 +1,79 @@
+module RobotWars
+  # A full match: setup, one turn at a time, until it ends (rule 39).
+  class Game
+    attr_reader :board, :occupancy, :territory, :turn_number
+
+    def initialize(board:, roll_generator: RollGenerator.new, random: Random.new)
+      @board = board
+      @occupancy = OccupancyMap.new
+      @territory = Territory.new
+      @robots = []
+      @turn_number = 0
+      @turn_resolver = TurnResolver.new(
+        board: board, occupancy: @occupancy, territory: @territory,
+        roll_generator: roll_generator, random: random
+      )
+    end
+
+    # Places robots on distinct random squares (rule 6), each starting
+    # with `life` points (rule 5's 100 unless the match says otherwise).
+    def self.start(board:, robot_ids:, life: Robot::STARTING_LIFE, roll_generator: RollGenerator.new, random: Random.new)
+      game = new(board: board, roll_generator: roll_generator, random: random)
+      positions = board.sample_positions(robot_ids.size, random: random)
+
+      robot_ids.zip(positions).each { |id, position| game.add_robot(Robot.new(id: id, life: life), position) }
+      game
+    end
+
+    def add_robot(robot, position)
+      @occupancy.place(robot, position)
+      @robots << robot
+      self
+    end
+
+    def robots
+      @robots.dup
+    end
+
+    def robot(id)
+      @robots.find { |robot| robot.id == id }
+    end
+
+    def alive_robots
+      @robots.select(&:alive?)
+    end
+
+    def over?
+      alive_robots.size <= 1
+    end
+
+    def winner
+      over? ? alive_robots.first : nil
+    end
+
+    def tie?
+      over? && alive_robots.empty?
+    end
+
+    # actions: Hash{Robot => Action}, exactly one entry per living robot.
+    def play_turn(actions)
+      raise ArgumentError, "the game is already over" if over?
+
+      validate_actions!(actions)
+      @turn_number += 1
+
+      report = @turn_resolver.resolve!(actions)
+      @robots -= report.deaths
+      report
+    end
+
+    private
+
+    def validate_actions!(actions)
+      provided = actions.keys
+      return if (alive_robots - provided).empty? && (provided - alive_robots).empty?
+
+      raise ArgumentError, "expected exactly one action per living robot"
+    end
+  end
+end

data/lib/robot_wars/game_rules.md

@@ -0,0 +1,44 @@
+You are a warrior in RobotWars — a turn-based, last-robot-standing
+game on a bounded 2D grid.
+
+Every turn you receive a sensing report: your position, your life
+total, the full map of currently owned squares and who owns them, and
+how many warriors remain. You can never see where any robot physically
+is — only territory reveals anything about rivals, and only where it's
+been claimed. If you attacked last turn, the report also tells you
+whether that attack was a HIT (a robot was on the square) or a MISS
+(the square was empty) — the one other clue you ever get about where
+rivals are.
+
+The rules, in brief:
+- 8-way movement, one square per turn, like a chess king. Moving costs
+  1 life; staying still gains 1 life.
+- An illegal move — off the board, or onto a square someone else
+  owns — is punished with a random hit and no movement.
+- Two ways to own a square: win a fight there, or occupy it for
+  3 consecutive turns. A square you own is yours alone — no one else
+  may ever enter it while you hold it.
+- Fighting for a contested square: a single shared random roll hits
+  everyone on it equally; whoever has the most life left afterward
+  wins and stays, everyone else is sent home (a tie sends everyone
+  home). Losing your way home can cascade into a second fight, and
+  losing twice in one turn gets you shoved onto a nearby empty
+  square — or killed outright if there isn't one.
+- Ranged attack: commit up to your current life as an attack's
+  strength against ANY square on the board. If a robot is standing
+  there, it loses that full amount. Attacking is free UNLESS the
+  target had committed to DEFEND — then you take their full defended
+  amount back as counter-fire, regardless of how much damage you
+  dealt. You can never be sure a square is undefended.
+- Defending: commits points that counter-hit every attacker that turn
+  for your full committed amount. If nobody attacks you, defending
+  still costs 1 life as a premium for bracing.
+- You die at 0 life, or by being crushed with nowhere to stand. A dead
+  warrior's territory is released.
+
+Respond with EXACTLY one line and nothing else, in one of these forms:
+
+STAY
+MOVE <north|northeast|east|southeast|south|southwest|west|northwest>
+ATTACK <x>,<y> <points>
+DEFEND <points>

data/lib/robot_wars/game_rules.rb

@@ -0,0 +1,12 @@
+module RobotWars
+  # The canonical rules-of-the-game recap, shipped with the gem
+  # (lib/robot_wars/game_rules.md) so every warrior everywhere plays by
+  # the same rules. bin/rwars hands it to each RobotLab robot as its
+  # system_prompt — warrior templates carry only their model choice and
+  # personality, never a rules retelling.
+  module GameRules
+    FILE = File.expand_path("game_rules.md", __dir__)
+
+    def self.text = File.read(FILE)
+  end
+end

data/lib/robot_wars/illegal_move_resolver.rb

@@ -0,0 +1,18 @@
+module RobotWars
+  # Resolves an illegal move attempt (RULES.md 21): a solo conflict
+  # against the board edge or a rival's owned square — a random hit,
+  # no movement.
+  class IllegalMoveResolver
+    Result = Data.define(:robot, :roll)
+
+    def initialize(roll_generator: RollGenerator.new)
+      @roll_generator = roll_generator
+    end
+
+    def resolve(robot)
+      roll = @roll_generator.roll
+      robot.apply_damage(roll)
+      Result.new(robot: robot, roll: roll)
+    end
+  end
+end

data/lib/robot_wars/llm_pilot.rb

@@ -0,0 +1,17 @@
+module RobotWars
+  # A warrior's brain: an LLM-backed decision-maker built from a human's
+  # prompt template. `llm_robot` is anything answering `#run(message)`
+  # with a result that answers `#reply` — a RobotLab::Robot in practice,
+  # but never required by name, so tests can hand it a plain double.
+  class LLMPilot
+    def initialize(llm_robot:, parser: ActionParser.new)
+      @llm_robot = llm_robot
+      @parser = parser
+    end
+
+    def decide(report)
+      reply = @llm_robot.run(report).reply
+      @parser.parse(reply)
+    end
+  end
+end

data/lib/robot_wars/model_spec.rb

@@ -0,0 +1,39 @@
+require "yaml"
+
+module RobotWars
+  # A warrior's LLM designation: "<provider>/<model id>" — the pattern of
+  # the `model:` front matter field in warrior templates and of the rwars
+  # --model option. The first "/" splits the RubyLLM provider name from
+  # the model id (which may itself contain slashes, as OpenRouter-style
+  # ids do). A bare id with no "/" names no provider and leaves that
+  # choice to RubyLLM's model registry.
+  ModelSpec = Data.define(:provider, :model) do
+    # Parse a "<provider>/<model id>" string.
+    #
+    # @param text [String, nil]
+    # @return [ModelSpec, nil] nil when text is nil or blank
+    def self.parse(text)
+      text = text.to_s.strip
+      return nil if text.empty?
+
+      provider, _, model = text.partition("/")
+      return new(provider: nil, model: provider) if model.empty?
+      return new(provider: nil, model: model) if provider.empty?
+
+      new(provider: provider.to_sym, model: model)
+    end
+
+    # Read a warrior template's YAML front matter and parse its `model:`
+    # field.
+    #
+    # @param path [String] path to a warrior *.md template
+    # @return [ModelSpec, nil] nil when the template names no model
+    def self.from_template(path)
+      matched = File.read(path).match(/\A---\s*\n(.*?)\n---\s*(\n|\z)/m)
+      return nil unless matched
+
+      front_matter = YAML.safe_load(matched[1])
+      parse(front_matter.is_a?(Hash) ? front_matter["model"] : nil)
+    end
+  end
+end

data/lib/robot_wars/move_resolver.rb

@@ -0,0 +1,30 @@
+module RobotWars
+  # Determines a move's destination and legality (RULES.md 9 and 21).
+  # Board boundaries and rival ownership make a destination illegal;
+  # another robot simply standing there does not — that's a conflict,
+  # not an illegal move.
+  class MoveResolver
+    Result = Data.define(:legal, :destination)
+
+    def initialize(board:, territory:)
+      @board = board
+      @territory = territory
+    end
+
+    def resolve(robot, origin, direction)
+      destination = origin + direction
+
+      if legal_destination?(destination, robot)
+        Result.new(legal: true, destination: destination)
+      else
+        Result.new(legal: false, destination: origin)
+      end
+    end
+
+    private
+
+    def legal_destination?(destination, robot)
+      @board.on_board?(destination) && !@territory.owned_by_other?(destination, robot)
+    end
+  end
+end

data/lib/robot_wars/occupancy_map.rb

@@ -0,0 +1,45 @@
+module RobotWars
+  # Where each living robot stands right now (RULES.md 4: one robot per
+  # square). Pure position bookkeeping — combat and ownership live in
+  # ConflictResolver and Territory.
+  class OccupancyMap
+    def initialize
+      @robot_by_position = {}
+    end
+
+    def place(robot, position)
+      raise ArgumentError, "#{position} is already occupied" if occupied?(position)
+
+      @robot_by_position[position] = robot
+    end
+
+    def vacate(position)
+      @robot_by_position.delete(position)
+    end
+
+    def move(robot, from:, to:)
+      raise ArgumentError, "#{robot} is not at #{from}" unless robot_at(from).equal?(robot)
+
+      vacate(from)
+      place(robot, to)
+    end
+
+    def robot_at(position)
+      @robot_by_position[position]
+    end
+
+    def occupied?(position)
+      @robot_by_position.key?(position)
+    end
+
+    def position_of(robot)
+      @robot_by_position.key(robot)
+    end
+
+    def each_occupied(&block)
+      return enum_for(:each_occupied) unless block
+
+      @robot_by_position.each_pair(&block)
+    end
+  end
+end

data/lib/robot_wars/position.rb

@@ -0,0 +1,13 @@
+module RobotWars
+  # A single square's coordinates. Values only — no board-bounds checking
+  # here; see Board#on_board?.
+  Position = Data.define(:x, :y) do
+    def +(other)
+      Position.new(x: x + other.x, y: y + other.y)
+    end
+
+    def neighbors
+      Direction::OFFSETS.map { |offset| self + offset }
+    end
+  end
+end

data/lib/robot_wars/ranged_combat_resolver.rb

@@ -0,0 +1,59 @@
+module RobotWars
+  # Resolves ranged combat for one turn (RULES.md 26-32): attacks land
+  # on whoever occupies the target square, defense is counter-fire
+  # rather than a shield, and a defender nobody shot at still pays a
+  # 1-point premium.
+  class RangedCombatResolver
+    AttackOrder = Data.define(:attacker, :square, :points)
+    DefendOrder = Data.define(:defender, :points)
+    Effect = Data.define(:kind, :robot, :amount, :source)
+
+    def initialize(occupancy_map:)
+      @occupancy_map = occupancy_map
+    end
+
+    def resolve(attacks:, defenses:)
+      defense_by_defender = defenses.to_h { |defense| [defense.defender, defense] }
+      attacked_defenders = []
+
+      effects = attacks.flat_map { |attack| resolve_attack(attack, defense_by_defender, attacked_defenders) }
+      effects + unchallenged_effects(defenses, attacked_defenders)
+    end
+
+    private
+
+    # :reek:FeatureEnvy -- an AttackOrder is pure data; resolving it needs this resolver's occupancy map and defense table.
+    def resolve_attack(attack, defense_by_defender, attacked_defenders)
+      target = @occupancy_map.robot_at(attack.square)
+      return [miss(attack)] unless target
+
+      target.apply_damage(attack.points)
+      effects = [Effect.new(kind: :hit, robot: target, amount: attack.points, source: attack.attacker)]
+
+      defense = defense_by_defender[target]
+      return effects unless defense
+
+      attacked_defenders << defense.defender
+      effects << counter_fire(attack.attacker, defense)
+    end
+
+    def miss(attack)
+      Effect.new(kind: :miss, robot: nil, amount: attack.points, source: attack.attacker)
+    end
+
+    def counter_fire(attacker, defense)
+      attacker.apply_damage(defense.points)
+      Effect.new(kind: :counter_fire, robot: attacker, amount: defense.points, source: defense.defender)
+    end
+
+    def unchallenged_effects(defenses, attacked_defenders)
+      defenses.reject { |defense| attacked_defenders.include?(defense.defender) }
+              .map { |defense| unchallenged(defense) }
+    end
+
+    def unchallenged(defense)
+      defense.defender.apply_damage(1)
+      Effect.new(kind: :unchallenged, robot: defense.defender, amount: 1, source: nil)
+    end
+  end
+end

data/lib/robot_wars/robot.rb

@@ -0,0 +1,49 @@
+module RobotWars
+  # A player in the game. Life-point bookkeeping only (RULES.md 5, 10,
+  # 11, 12, 36) — position, ownership, and actions live elsewhere so
+  # each piece of state can be tested on its own.
+  class Robot
+    STARTING_LIFE = 100
+
+    attr_reader :id, :life
+
+    def initialize(id:, life: STARTING_LIFE)
+      @id = id
+      @life = life
+      @eliminated = false
+    end
+
+    def alive?
+      !@eliminated && life.positive?
+    end
+
+    def dead?
+      !alive?
+    end
+
+    # Death by displacement (RULES.md 37) — a separate cause from life
+    # reaching 0 or less (rule 36), so the life total is left as-is.
+    def eliminate!
+      @eliminated = true
+      self
+    end
+
+    def apply_damage(amount)
+      raise ArgumentError, "amount must not be negative" if amount.negative?
+
+      @life -= amount
+      self
+    end
+
+    def heal(amount)
+      raise ArgumentError, "amount must not be negative" if amount.negative?
+
+      @life += amount
+      self
+    end
+
+    def to_s
+      "##{id} (#{life} life)"
+    end
+  end
+end

data/lib/robot_wars/roll_generator.rb

@@ -0,0 +1,15 @@
+module RobotWars
+  # The shared conflict roll (RULES.md 14 and 21): one random number,
+  # 1 to 10.
+  class RollGenerator
+    RANGE = (1..10)
+
+    def initialize(random: Random.new)
+      @random = random
+    end
+
+    def roll
+      @random.rand(RANGE)
+    end
+  end
+end