robot_wars 0.1.0

data/lib/robot_wars/sensing_report.rb

@@ -0,0 +1,61 @@
+module RobotWars
+  # What one robot is told before it acts (RULES.md 33-35): its own
+  # position and life, and the full map of owned squares — never any
+  # other robot's position.
+  #
+  # Two details rule 35 leaves open are implemented here as defaults,
+  # not settled rules (see notes.md): the map names each square's owner
+  # rather than just distinguishing mine/theirs, and the report says how
+  # many warriors remain and who they are.
+  class SensingReport
+    # attack_outcome: :hit or :miss when the robot attacked last turn
+    # (see TurnResolver::Report#attack_outcome_for), nil otherwise —
+    # Battleship-style feedback, the one thing an attacker learns about
+    # where its rivals are.
+    def initialize(game:, robot:, attack_outcome: nil)
+      @game = game
+      @robot = robot
+      @attack_outcome = attack_outcome
+    end
+
+    def to_s
+      [
+        "Turn #{@game.turn_number + 1}.",
+        "Your position: #{position_text}. Your life: #{@robot.life}.",
+        attack_feedback_text,
+        ownership_text,
+        survivors_text
+      ].compact.join("\n") << "\n"
+    end
+
+    private
+
+    def attack_feedback_text
+      @attack_outcome && "Your attack last turn was a #{@attack_outcome.to_s.upcase}."
+    end
+
+    def position_text
+      position = @game.occupancy.position_of(@robot)
+      "(#{position.x},#{position.y})"
+    end
+
+    def ownership_text
+      owned = @game.territory.each_owned.to_a
+      return "No squares are owned yet." if owned.empty?
+
+      lines = owned.map { |square, owner| "  (#{square.x},#{square.y}) owned by #{owner.id}#{mine(owner)}" }
+      (["Owned squares:"] + lines).join("\n")
+    end
+
+    # :reek:ControlParameter -- comparing the owner against @robot is the method's entire purpose.
+    def mine(owner)
+      owner == @robot ? " (yours)" : ""
+    end
+
+    # :reek:FeatureEnvy -- `survivors` is a local snapshot formatted in place; there is nowhere better for it.
+    def survivors_text
+      survivors = @game.alive_robots
+      "#{survivors.size} warriors remain: #{survivors.map(&:id).join(', ')}."
+    end
+  end
+end

data/lib/robot_wars/territory.rb

@@ -0,0 +1,75 @@
+module RobotWars
+  # Square ownership (RULES.md 22-25). Ownership comes from conquest
+  # (#claim!, called by whoever resolves square conflicts) or from
+  # occupation (#tick!, three consecutive turns per rule 23), and is
+  # released when the owner dies (#release!).
+  class Territory
+    TURNS_TO_OWN_BY_OCCUPATION = 3
+
+    def initialize
+      @owner_by_position = {}
+      @streak_by_position = {}
+    end
+
+    def owner_of(position)
+      @owner_by_position[position]
+    end
+
+    def owned?(position)
+      @owner_by_position.key?(position)
+    end
+
+    def owned_by?(position, robot)
+      owner_of(position) == robot
+    end
+
+    def owned_by_other?(position, robot)
+      owned?(position) && !owned_by?(position, robot)
+    end
+
+    def claim!(position, robot)
+      @owner_by_position[position] = robot
+    end
+
+    def release!(robot)
+      @owner_by_position.delete_if { |_position, owner| owner == robot }
+    end
+
+    def each_owned(&block)
+      return enum_for(:each_owned) unless block
+
+      @owner_by_position.each_pair(&block)
+    end
+
+    # Advances every square's occupation streak from who is standing
+    # there this turn, claiming ownership on the 3rd consecutive turn.
+    # Returns the squares that BECAME owned on this tick as
+    # {position => robot} — squares the robot already owned don't
+    # reappear on later ticks.
+    def tick!(occupancy_map)
+      current_by_position = occupancy_map.each_occupied.to_h
+
+      stale_positions(current_by_position).each { |position| @streak_by_position.delete(position) }
+      current_by_position.filter_map { |position, robot| record_occupation(position, robot) }.to_h
+    end
+
+    private
+
+    def stale_positions(current_by_position)
+      @streak_by_position.keys.reject do |position|
+        current_by_position[position] == @streak_by_position[position].fetch(:robot)
+      end
+    end
+
+    # Advances the square's streak; returns [position, robot] when the
+    # occupation just turned into NEW ownership, nil otherwise.
+    def record_occupation(position, robot)
+      streak = (@streak_by_position[position] ||= { robot: robot, count: 0 })
+      streak[:count] += 1
+      return nil if streak.fetch(:count) < TURNS_TO_OWN_BY_OCCUPATION || owned_by?(position, robot)
+
+      claim!(position, robot)
+      [position, robot]
+    end
+  end
+end

data/lib/robot_wars/turn_resolver.rb

@@ -0,0 +1,265 @@
+module RobotWars
+  # Runs one full turn end to end (RULES.md rule 40): the movement
+  # economy, square conflicts — including cascading return conflicts and
+  # displacement-or-death — ranged combat, death processing, and
+  # occupation-streak ticking.
+  #
+  # A returning loser (rule 17) is sent to the square it started the
+  # turn on. Two cases the rules leave implicit are resolved here and
+  # flagged for confirmation (see notes.md): a robot that never left its
+  # square (its "origin" IS the square it just lost) has nowhere
+  # meaningful to return to, so it goes straight to displacement rather
+  # than re-fighting the robot that just beat it; and each robot's own
+  # defeat count (not a per-event count) is what caps a chain at two
+  # losses, so displacing a robot only starts THAT robot's own count.
+  class TurnResolver
+    Report = Data.define(:deaths, :ranged_effects, :conflicts, :solo_conflicts, :claims) do
+      # Battleship-style feedback for an attacker: :hit when this
+      # robot's attack this turn found a robot on the target square,
+      # :miss when it found the square empty, nil when it didn't attack.
+      # Counter-fire and unchallenged-defense effects don't count — they
+      # aren't the robot's own shot.
+      # :reek:ControlParameter -- `robot` is the query subject being looked up, not a behavior switch.
+      # :reek:FeatureEnvy -- `effect` is the block's own search variable; there is no better home for a Report query.
+      def attack_outcome_for(robot)
+        ranged_effects.find { |effect| effect.source == robot && %i[hit miss].include?(effect.kind) }&.kind
+      end
+
+      # The squares this robot NEWLY came to own this turn — by conquest
+      # or by completing a 3-turn occupation streak. Squares it already
+      # owned are never repeated.
+      def claimed_squares_for(robot)
+        claims.select { |claim| claim.robot == robot }.map(&:square)
+      end
+    end
+
+    # One square becoming newly owned during the turn (rules 22-23).
+    Claim = Data.define(:robot, :square)
+
+    # One resolved square conflict (rules 13-16), kept on the Report so a
+    # match transcript can say what happened, not just the resulting life
+    # totals. `winner` is nil on a tie.
+    Conflict = Data.define(:square, :robots, :roll, :winner, :losers) do
+      def to_s
+        outcome = winner ? "#{winner.id} takes the square" : "tie, everyone loses"
+        "conflict at (#{square.x},#{square.y}): #{robots.map(&:id).join(' vs ')} — roll #{roll}, #{outcome}"
+      end
+    end
+
+    # One rule 21 solo conflict — an invalid action or illegal move
+    # punished with a random hit and no movement.
+    SoloConflict = Data.define(:robot, :roll) do
+      def to_s = "solo conflict: #{robot.id} — roll #{roll}, no movement"
+    end
+
+    # :reek:ControlParameter -- `x || Default.new` is an injectable-collaborator fallback, not behavior selection.
+    def initialize(board:, occupancy:, territory:, roll_generator: RollGenerator.new, random: Random.new,
+                   move_resolver: nil, conflict_resolver: nil, illegal_move_resolver: nil)
+      @board = board
+      @occupancy = occupancy
+      @territory = territory
+      @random = random
+      @move_resolver = move_resolver || MoveResolver.new(board: board, territory: territory)
+      @conflict_resolver = conflict_resolver || ConflictResolver.new(roll_generator: roll_generator)
+      @illegal_move_resolver = illegal_move_resolver || IllegalMoveResolver.new(roll_generator: roll_generator)
+      @conflicts = []
+      @solo_conflicts = []
+      @claims = []
+    end
+
+    # actions: Hash{Robot => Action}, exactly one entry per living robot
+    # on the board (rule 8).
+    # :reek:TooManyStatements -- the rule 40 turn sequence, one linear step per phase; splitting it would hide the order.
+    def resolve!(actions)
+      reset_turn_log
+      origins = actions.keys.to_h { |robot| [robot, @occupancy.position_of(robot)] }
+
+      destinations = apply_movement_economy(actions)
+      settled, eliminated = resolve_square_conflicts(destinations, origins)
+      commit_occupancy(settled)
+
+      ranged_effects = resolve_ranged_combat(actions)
+      deaths = process_deaths(eliminated)
+
+      @territory.tick!(@occupancy).each { |square, robot| @claims << Claim.new(robot: robot, square: square) }
+
+      Report.new(deaths: deaths, ranged_effects: ranged_effects,
+                 conflicts: @conflicts, solo_conflicts: @solo_conflicts, claims: @claims)
+    end
+
+    private
+
+    # The per-turn event log the Report is built from, emptied at the
+    # top of every resolve!.
+    def reset_turn_log
+      @conflicts = []
+      @solo_conflicts = []
+      @claims = []
+    end
+
+    # --- Movement and the life-point economy (rules 9-11, 21) ---------
+
+    def apply_movement_economy(actions)
+      actions.to_h { |robot, action| [robot, intended_square(robot, action)] }
+    end
+
+    # :reek:FeatureEnvy -- dispatching on the action's type is this method's whole job; the Action is pure data.
+    def intended_square(robot, action)
+      origin = @occupancy.position_of(robot)
+      return resolve_move(robot, origin, action.direction) if action.move?
+
+      if action.invalid?
+        punish_solo_conflict(robot)
+      elsif action.stay?
+        robot.heal(1)
+      end
+
+      origin
+    end
+
+    def resolve_move(robot, origin, direction)
+      result = @move_resolver.resolve(robot, origin, direction)
+      unless result.legal
+        punish_solo_conflict(robot)
+        return origin
+      end
+
+      robot.apply_damage(1)
+      result.destination
+    end
+
+    def punish_solo_conflict(robot)
+      result = @illegal_move_resolver.resolve(robot)
+      @solo_conflicts << SoloConflict.new(robot: robot, roll: result.roll)
+    end
+
+    # --- Square conflicts, cascading returns, displacement (13-20) ----
+
+    # :reek:TooManyStatements -- initial-conflict pass plus the cascading-return queue drain belong together (rules 13-20).
+    def resolve_square_conflicts(destinations, origins)
+      settled = {}
+      eliminated = []
+      defeats = Hash.new(0)
+      queue = []
+
+      groups_by_square(destinations).each { |square, contenders| settle(square, contenders, settled, defeats, queue) }
+
+      until queue.empty?
+        robot, lost_at = queue.shift.values_at(:robot, :lost_at)
+        return_home(robot, lost_at, origins, settled, defeats, eliminated, queue)
+      end
+
+      [settled, eliminated]
+    end
+
+    def groups_by_square(destinations)
+      groups = Hash.new { |hash, square| hash[square] = [] }
+      destinations.each { |robot, square| groups[square] << robot }
+      groups
+    end
+
+    # Resolves one square's contenders: the sole robot, or the winner of
+    # a conflict, settles there and (on conquest) claims it; every loser
+    # is queued to attempt its own return.
+    # :reek:TooManyStatements -- fight, log, settle-or-vacate, queue losers: one linear pass per contested square.
+    def settle(square, contenders, settled, defeats, queue)
+      if contenders.one?
+        settled[square] = contenders.first
+        return
+      end
+
+      @conflict_resolver.resolve(contenders) => { winner:, losers:, roll: }
+      @conflicts << Conflict.new(square: square, robots: contenders, roll: roll,
+                                 winner: winner, losers: losers)
+
+      if winner
+        settled[square] = winner
+        record_conquest(square, winner)
+      else
+        settled.delete(square)
+      end
+
+      losers.each do |loser|
+        defeats[loser] += 1
+        queue << { robot: loser, lost_at: square }
+      end
+    end
+
+    # A conquest is always NEW ownership — no robot can legally enter a
+    # square someone else owns (and displacement avoids them too), so a
+    # conflict never happens on a square its winner already holds.
+    def record_conquest(square, winner)
+      @territory.claim!(square, winner)
+      @claims << Claim.new(robot: winner, square: square)
+    end
+
+    # :reek:LongParameterList -- the cascade's working state (origins/settled/defeats/eliminated/queue) is one
+    # turn's transient data; promoting it to ivars or a context object would outlive its single resolve! pass.
+    def return_home(robot, lost_at, origins, settled, defeats, eliminated, queue)
+      home = origins[robot]
+
+      if home == lost_at || defeats[robot] >= 2
+        displace_or_eliminate(robot, lost_at, settled, eliminated)
+        return
+      end
+
+      occupant = settled[home]
+      if occupant.nil?
+        settled[home] = robot
+        return
+      end
+
+      settle(home, [robot, occupant], settled, defeats, queue)
+    end
+
+    def displace_or_eliminate(robot, near, settled, eliminated)
+      candidates = @board.neighbors_of(near).reject do |square|
+        settled.key?(square) || @territory.owned_by_other?(square, robot)
+      end
+
+      if candidates.empty?
+        robot.eliminate!
+        eliminated << robot
+      else
+        settled[candidates.sample(random: @random)] = robot
+      end
+    end
+
+    def commit_occupancy(settled)
+      @occupancy.each_occupied.to_a.each { |square, _robot| @occupancy.vacate(square) }
+      settled.each { |square, robot| @occupancy.place(robot, square) }
+    end
+
+    # --- Ranged combat (26-32) -----------------------------------------
+
+    def resolve_ranged_combat(actions)
+      attacks = actions.filter_map { |robot, action| build_attack(robot, action) if action.attack? }
+      defenses = actions.filter_map { |robot, action| build_defense(robot, action) if action.defend? }
+
+      RangedCombatResolver.new(occupancy_map: @occupancy).resolve(attacks: attacks, defenses: defenses)
+    end
+
+    def build_attack(robot, action)
+      RangedCombatResolver::AttackOrder.new(attacker: robot, square: action.square, points: action.points)
+    end
+
+    def build_defense(robot, action)
+      RangedCombatResolver::DefendOrder.new(defender: robot, points: action.points)
+    end
+
+    # --- Death processing (25, 36-38) -----------------------------------
+
+    def process_deaths(already_eliminated)
+      newly_dead = @occupancy.each_occupied.to_a.filter_map { |_square, robot| robot if robot.dead? }
+      deaths = (already_eliminated + newly_dead).uniq
+
+      deaths.each do |robot|
+        position = @occupancy.position_of(robot)
+        @occupancy.vacate(position) if position
+        @territory.release!(robot)
+      end
+
+      deaths
+    end
+  end
+end

data/lib/robot_wars/version.rb

@@ -0,0 +1,3 @@
+module RobotWars
+  VERSION = "0.1.0".freeze
+end

data/lib/robot_wars/warrior.rb

@@ -0,0 +1,22 @@
+module RobotWars
+  # Pairs a game-state Robot with whatever decides its actions each turn.
+  # Game only ever needs the Action that comes out the other end, so the
+  # pilot can be an LLMPilot, a scripted proc, or eventually a human —
+  # anything answering #decide(report).
+  class Warrior
+    attr_reader :robot, :pilot
+
+    def initialize(robot:, pilot:)
+      @robot = robot
+      @pilot = pilot
+    end
+
+    def id
+      robot.id
+    end
+
+    def decide(report)
+      pilot.decide(report)
+    end
+  end
+end

data/lib/robot_wars.rb

@@ -0,0 +1,29 @@
+require "robot_lab"
+
+require_relative "robot_wars/version"
+require_relative "robot_wars/position"
+require_relative "robot_wars/direction"
+require_relative "robot_wars/board"
+require_relative "robot_wars/roll_generator"
+require_relative "robot_wars/fixed_roll_generator"
+require_relative "robot_wars/robot"
+require_relative "robot_wars/action"
+require_relative "robot_wars/occupancy_map"
+require_relative "robot_wars/territory"
+require_relative "robot_wars/move_resolver"
+require_relative "robot_wars/conflict_resolver"
+require_relative "robot_wars/illegal_move_resolver"
+require_relative "robot_wars/ranged_combat_resolver"
+require_relative "robot_wars/turn_resolver"
+require_relative "robot_wars/game"
+require_relative "robot_wars/action_parser"
+require_relative "robot_wars/model_spec"
+require_relative "robot_wars/game_rules"
+require_relative "robot_wars/sensing_report"
+require_relative "robot_wars/warrior"
+require_relative "robot_wars/llm_pilot"
+
+module RobotWars
+  # Raised for RobotWars-specific misuse.
+  class Error < StandardError; end
+end

data/sig/robot_wars.rbs

@@ -0,0 +1,6 @@
+module RobotWars
+  VERSION: String
+
+  class Error < StandardError
+  end
+end

metadata

@@ -0,0 +1,100 @@
+--- !ruby/object:Gem::Specification
+name: robot_wars
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Dewayne VanHoozer
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: robot_lab
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+description: 'A turn-based game built on the RobotLab framework: each robot occupies
+  a square on a 2D grid, all robots move simultaneously each turn, conflicts are resolved
+  between turns, and the last robot remaining wins.'
+email:
+- dvanhoozer@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".envrc"
+- ".loki"
+- ".rubocop.yml"
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- RULES.md
+- Rakefile
+- docs/game_board.svg
+- examples/01_random_match.rb
+- examples/warriors/opportunist.md
+- examples/warriors/oppressor.md
+- examples/warriors/sentinel.md
+- examples/warriors/wanderer.md
+- examples/warriors/warmonger.md
+- lib/robot_wars.rb
+- lib/robot_wars/action.rb
+- lib/robot_wars/action_parser.rb
+- lib/robot_wars/board.rb
+- lib/robot_wars/conflict_resolver.rb
+- lib/robot_wars/direction.rb
+- lib/robot_wars/fixed_roll_generator.rb
+- lib/robot_wars/game.rb
+- lib/robot_wars/game_rules.md
+- lib/robot_wars/game_rules.rb
+- lib/robot_wars/illegal_move_resolver.rb
+- lib/robot_wars/llm_pilot.rb
+- lib/robot_wars/model_spec.rb
+- lib/robot_wars/move_resolver.rb
+- lib/robot_wars/occupancy_map.rb
+- lib/robot_wars/position.rb
+- lib/robot_wars/ranged_combat_resolver.rb
+- lib/robot_wars/robot.rb
+- lib/robot_wars/roll_generator.rb
+- lib/robot_wars/sensing_report.rb
+- lib/robot_wars/territory.rb
+- lib/robot_wars/turn_resolver.rb
+- lib/robot_wars/version.rb
+- lib/robot_wars/warrior.rb
+- sig/robot_wars.rbs
+homepage: https://github.com/MadBomber/robot_wars
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/MadBomber/robot_wars
+  source_code_uri: https://github.com/MadBomber/robot_wars
+  changelog_uri: https://github.com/MadBomber/robot_wars/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: Turn-based last-robot-standing game for RobotLab robots on a 2D grid board.
+test_files: []