boardgame_engine 0.1.1 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7129074317f7ea44e65ad18e5952e2401e47be99186e26dd42b0c083ebc91797
-  data.tar.gz: f87aebcb6502cbfd9d8ee04e60b775f1497e09527863f3f820a1edb202297330
+  metadata.gz: 8f3c14dd095359859bb7c6fb53b25e7c94ae18bb1b4e407d0e377797254930a6
+  data.tar.gz: 5ecf4d791871a327a1f2e2844cc21b5d0de4b23b001f478a8ef8ca89834bc803
 SHA512:
-  metadata.gz: 1c1ab01918757d936b1ee97cf8d75bbf19a300e71450b0c1896fcd9cdda0f804b25324b71ef01929d8d231f96ef7af15ec023690dc52d5a738e8b363da43c4f8
-  data.tar.gz: b10198cde214fe10e7a861a27419e6235b25a84ef1fac0992de66e0297668da8e3f600effaae0049c12a5343e761dccfb623594bc2621d40b24063e8b8d82cb0
+  metadata.gz: 8a8579be5461dda2d3e77a4c2fa50b92ff0a6d4179f960e2ce083261bbc5db6cfe05defa5f1e679e07576bd517d2296477666b86f4388be30030b8127a2ce5ef
+  data.tar.gz: afd22e1654d2ca4a66f648e96d08cfd9f52ba3c780d19d4352344214dd6b753ba85236f8e2b0bbf47ecce2c1bd272ac6c33ed6592c0a96838db3c0ea50b327c5

data/.rubocop.yml

@@ -1,13 +1,5 @@
 AllCops:
-  TargetRubyVersion: 3.1
-
-Style/StringLiterals:
-  Enabled: true
-  EnforcedStyle: double_quotes
-
-Style/StringLiteralsInInterpolation:
-  Enabled: true
-  EnforcedStyle: double_quotes
+  TargetRubyVersion: 3.0
 
 Layout/LineLength:
   Max: 120

data/Gemfile

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
-source "https://rubygems.org"
+source 'https://rubygems.org'
 
 # Specify your gem's dependencies in boardgame_engine.gemspec
 gemspec
 
-gem "rake", "~> 13.0"
+gem 'rake', '~> 13.0'
 
-gem "rubocop", "~> 1.21"
+gem 'rubocop', '~> 1.21'

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    boardgame_engine (0.1.0)
+    boardgame_engine (0.2.0)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -2,7 +2,7 @@
 
 A gem that provides a template for creating boardgames. It aims to streamline
 the process of making boardgames to be played on the terminal by providing a 
-variety of methods and classes.
+variety of classes and modules.
 
 ## Installation
 
@@ -15,8 +15,43 @@ If bundler is not being used to manage dependencies, install the gem by executin
     $ gem install boardgame_engine
 
 ## Usage
+### Initial Setup
+To start making your own boardgame using this gem, your game module needs at least two classes -
+a `Game` class inheriting from `Boardgame` and a `Board` class inheriting `Board`.
+`Game` captures the core gameplay loop/logic and the `Board` captures 
+interactions with the board.
 
-TODO: Write usage instructions here
+Depending on the game rules, select child modules from the `Games` and `Boards`
+and include it into the `Game` and `Board` class respectively.
+These modules will handle much of the game and board logic related to the
+game mechanic/rule.
+
+For example, if the turns in your game go in a cycle like 1 -> 2 -> 3 -> 1 -> 2 ...
+your `Game` class would look like
+```ruby
+class Game < BoardgameEngine::Game
+  include Games::CyclicalGame
+  NUM_PLAYERS = 3
+  ...
+end
+```
+Including this module makes it so that the `BoardgameEngine::Game#change_turn` 
+method automatically hands the turn over to the correct player.
+
+### Overriding
+At the current stage of the app, there are methods that necessarily must be
+overridden in the child class.
+`play_turn` must be implemented on _your_ `Game` class, and must contain what happens
+during a single turn (not a round, just a turn).
+
+Additionally, the limited number of modules mean that you will probably have to implement some
+methods on your own. I hope to reduce the number of these as the app matures.
+I left yard comments on all module methods, so hopefully overriding won't be too
+difficult.
+
+## Example Games
+Check out `connect4.rb` for a game built with rather minimal overrides and
+`chess.rb` for a game that makes heavy use of customization.
 
 ## Development
 
@@ -26,4 +61,9 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/Forthoney/boardgame_engine.
+Bug reports are welcome on GitHub at https://github.com/Forthoney/boardgame_engine.
+I may not get to them quickly but it will be greatly helpful
+
+As the app is under heavy development I will not look deeply into actually 
+pulling pull requests (if there were to be any).
+I will definitely consider the ideas proposed in them, so they are still welcome.

data/Rakefile

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
-require "bundler/gem_tasks"
-require "rubocop/rake_task"
+require 'bundler/gem_tasks'
+require 'rubocop/rake_task'
 
 RuboCop::RakeTask.new
 

data/boardgame_engine.gemspec

@@ -1,22 +1,22 @@
 # frozen_string_literal: true
 
-require_relative "lib/boardgame_engine/version"
+require_relative 'lib/boardgame_engine/version'
 
 Gem::Specification.new do |spec|
-  spec.name = "boardgame_engine"
+  spec.name = 'boardgame_engine'
   spec.version = BoardgameEngine::VERSION
-  spec.authors = ["FortHoney"]
-  spec.email = ["castlehoneyjung@gmail.com"]
+  spec.authors = ['FortHoney']
+  spec.email = ['castlehoneyjung@gmail.com']
 
-  spec.summary = "A gem that makes digitizing/creating board games to be played on the terminal quick and easy."
-  spec.homepage = "https://github.com/Forthoney/boardgame_engine"
-  spec.required_ruby_version = ">= 2.7.0"
+  spec.summary = 'A gem that makes digitizing/creating board games to be played on the terminal quick and easy.'
+  spec.homepage = 'https://github.com/Forthoney/boardgame_engine'
+  spec.required_ruby_version = '>= 3.0.0'
 
   # spec.metadata["allowed_push_host"] = "TODO: Set to your gem server 'https://example.com'"
 
-  spec.metadata["homepage_uri"] = spec.homepage
-  spec.metadata["source_code_uri"] = "https://github.com/Forthoney/boardgame_engine"
-  spec.metadata["changelog_uri"] = "https://github.com/Forthoney/boardgame_engine/blob/main/CHANGELOG.md"
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = 'https://github.com/Forthoney/boardgame_engine'
+  spec.metadata['changelog_uri'] = 'https://github.com/Forthoney/boardgame_engine/blob/main/CHANGELOG.md'
 
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
@@ -25,11 +25,11 @@ Gem::Specification.new do |spec|
       (f == __FILE__) || f.match(%r{\A(?:(?:bin|test|spec|features)/|\.(?:git|travis|circleci)|appveyor)})
     end
   end
-  spec.bindir = "exe"
+  spec.bindir = 'exe'
   spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
-  spec.require_paths = ["lib"]
+  spec.require_paths = ['lib']
 
-  spec.add_development_dependency "rspec", "~> 3.2"
+  spec.add_development_dependency 'rspec', '~> 3.2'
 
   # For more information and examples about making a new gem, check out our
   # guide at: https://bundler.io/guides/creating_gem.html

data/lib/boardgame_engine/board_modules.rb

@@ -0,0 +1,262 @@
+# frozen_string_literal: true
+
+# Module for different board types
+module Boards
+  # Boards laid out in grid format
+  module Grid
+    # Print a visual representation of the board
+    #
+    # @param [Boolean] show_row whether to show row labels
+    # @param [Boolean] show_col whether to show column labels
+    #
+    # @return [void]
+    def display(show_row: false, show_col: false)
+      if show_row
+        @board.each_with_index { |row, idx| puts("#{idx} " + format_row(row)) }
+      else
+        @board.each { |row| puts format_row(row) }
+      end
+
+      return unless show_col
+
+      column_spacer = show_row ? '  ' : ''
+      puts format_col_numbering(column_spacer)
+    end
+
+    # Accessor for getting piece at a location on the board
+    #
+    # @param [Array<Integer, Integer>] location the coordinates on the grid to
+    # get the piece from
+    #
+    # @return [Piece] the piece at the location
+    def get_piece_at(location)
+      row, col = location
+      @board.dig(row, col)
+    end
+
+    # Setter for setting a piece at a location on the board
+    #
+    # @param [Array<Integer, Integer>] location <description>
+    # @param [Piece] piece the piece to place down
+    #
+    # @return [void]
+    def set_piece_at(location, piece)
+      row, col = location
+      @board[row][col] = piece
+    end
+
+    # Check whether the given input refers to a valid location on the board,
+    # regardless of placement of other pieces, rules, etc
+    #
+    # @param [String] input the user input
+    # @param [Boolean] only_row optional arg for only allowing user to specify
+    # row
+    # @param [Boolean] only_col optional arg for only allowing user to specify
+    # col
+    #
+    # @return [Boolean] true if the input can be parsed into a location on the
+    # board, false otherwise
+    def valid_board_input?(input, only_row: false, only_col: false)
+      if only_row || only_col
+        input.match?(/[0-#{@board.length - 1}]/)
+      else
+        input.match?(/[0-#{@board.length - 1}], [0-#{@board[0].length - 1}]$/)
+      end
+    end
+
+    # Check whether there exists a clear diagonal path from start to a
+    # destination
+    #
+    # @param [Array<Integer, Integer>] start_location the start location
+    # @param [Array<Integer, Integer>] end_location the intended destination
+    #
+    # @return [Boolean] true if there exists an unblocked path to destination
+    def clear_diag_path?(start_location, end_location)
+      row, col = start_location
+      end_row, end_col = end_location
+
+      ((end_row - row).abs == (end_col - col).abs) \
+      && clear_path?(row, col, end_row, end_col, board)
+    end
+
+    # Check whether there exists an unblocked horizontal path from start to
+    # a destination
+    #
+    # @param [Array<Integer, Integer>] start_location the start location
+    # @param [Array<Integer, Integer>] end_location the intended destination
+    #
+    # @return [Boolean] true if there exists an unblocked path to destination
+    def clear_horz_path?(start_location, end_location)
+      row, col = start_location
+      end_row, end_col = end_location
+
+      (end_row == row) && clear_path?(row, col, end_row, end_col, board)
+    end
+
+    # Check whether there exists an unblocked vertical path from start to
+    # a destination
+    #
+    # @param [Array<Integer, Integer>] start_location the start location
+    # @param [Array<Integer, Integer>] end_location the intended destination
+    #
+    # @return [Boolean] true if there exists an unblocked path to destination
+    def clear_vert_path?(start_location, end_location)
+      row, col = start_location
+      end_row, end_col = end_location
+
+      (end_col == col) && clear_path?(row, col, end_row, end_col, board)
+    end
+
+    # Parse an input from the user that has a corresponding board location. This
+    # must be used in after valid_board_input? has confirmed the input is in
+    # the correct format
+    #
+    # @param [String] input a valid
+    #
+    # @return [Array<Integer, Integer>]
+    def parse_input(input)
+      input.split(',').map(&:to_i)
+    end
+
+    # Make a 2D Array representing the board
+    #
+    # @param [Integer] row the number of rows
+    # @param [Integer] col the number of columns
+    #
+    # @return [Array<Array>] A 2D Array
+    def generate_board(row, col)
+      Array.new(row) { Array.new(col) { nil } }
+    end
+
+    # Check whether there are consecutive pieces on the board
+    #
+    # @param [Integer] num the number of consecutive pieces to check for.
+    # @param [Boolean] row check for row-wise consecutive pieces
+    # @param [Boolean] col check for column-wise consecutive pieces
+    # @param [Boolean] diagonal check for diagonally consecutive pieces
+    #
+    # @return [Boolean] true if any specified directins have num number of
+    # consecutive pieces
+    def consecutive?(num, row: true, col: true, diagonal: true)
+      configs = []
+      configs << @board if row
+      configs << @board.transpose if col
+      configs << align_diagonal(@board) << align_diagonal(@board.transpose) if diagonal
+
+      configs.each do |board|
+        board.each { |array| return true if row_consecutive?(num, array) }
+      end
+      false
+    end
+
+    private
+
+    # calculates the location of the next cell in the sequence of cells from a
+    # given start location and an end location
+    #
+    # @param [Integer] row
+    # @param [Integer] col
+    # @param [Integer] end_row
+    # @param [Integer] end_col
+    #
+    # @return [Array<Integer, Integer>] the next cell in the sequence of cells
+    def next_cell(row, col, end_row, end_col)
+      row_move = 0
+      col_move = 0
+
+      col_move = (end_col - col) / (end_col - col).abs if end_col != col
+      row_move = (end_row - row) / (end_row - row).abs if end_row != row
+
+      [row + row_move, col + col_move]
+    end
+
+    # Given a linear path, check whether there exists an unblocked path.
+    # It msut be checked beforehand that the path is indeed linear
+    #
+    # @param [Integer] row
+    # @param [Integer] col
+    # @param [Integer] end_row
+    # @param [Integer] end_col
+    #
+    # @return [Boolean] true if there exists a clear path
+    def clear_path?(row, col, end_row, end_col)
+      current_tile = get_piece_at([row, col])
+
+      if (row == end_row) && (col == end_col)
+        current_tile.nil? || (current_tile.owner != @owner)
+      elsif current_tile.nil? || current_tile.equal?(self)
+        next_row, next_col = next_cell(row, col, end_row, end_col)
+        clear_path?(next_row, next_col, end_row, end_col)
+      else
+        false
+      end
+    end
+
+    # Check a single row for consecutive pieces
+    #
+    # @param [Integer] num the number of consecutive pieces to check for
+    # @param [Array] array the row to check in
+    #
+    # @return [Boolean] true if there are at least num number of consecutive
+    # elements
+    def row_consecutive?(num, array)
+      chunked_elems = array.chunk { |elem| elem }
+      elem_counts = chunked_elems.map { |elem, elems| [elem, elems.length] }
+      elem_counts.any? { |elem, count| count >= num && elem }
+    end
+
+    # Align the diagonals of a board. Must be called once on the original board
+    # and once more on the transposed board to check for both directions of
+    # diagonals
+    #
+    # @param [Array<Array>] board the board to align
+    #
+    # @return [Array<Array>] new board with the diagonals aligned
+    def align_diagonal(board)
+      board.map.with_index do |row, idx|
+        left_filler = Array.new(board.length - 1 - idx, nil)
+        right_filler = Array.new(idx, nil)
+        left_filler + row + right_filler
+      end
+    end
+
+    # Format a single row for String representation
+    #
+    # @param [Array] row the row to turn into a String
+    #
+    # @return [String] a String representation of the row
+    def format_row(row)
+      row.map { |elem| "[#{elem.nil? ? ' ' : elem}]" }.join
+    end
+
+    # Format the column numbering of a board
+    #
+    # @param [String] column_spacer the spacer to use between the indices
+    #
+    # @return [String] a String representation of the row
+    def format_col_numbering(column_spacer)
+      @board[0].each_index.reduce(column_spacer) { |str, idx| str + " #{idx} " }
+    end
+  end
+
+  # Boards with movable pieces
+  module MovablePiece
+    # Move a piece from at a start location to an end location. Should be called
+    # after checking that the movement is valid board and game logic wise.
+    #
+    # @param [<Type>] start_location the starting location of the piece
+    # @param [<Type>] end_location the destination of the piece
+    # @param [<Type>] set_start_to what to place at the start location. defaults
+    # to nil
+    #
+    # @return [Piece] the piece at the destination
+    def move_piece(start_location, end_location, set_start_to: nil)
+      piece = get_piece_at(start_location)
+      set_piece_at(start_location, set_start_to)
+      destination_piece = get_piece_at(end_location)
+      set_piece_at(end_location, piece)
+
+      destination_piece
+    end
+  end
+end

data/lib/boardgame_engine/boardgame.rb

@@ -2,145 +2,167 @@
 
 # All classes in this script are intended to be abstract, meaning they should
 # not be called on their own.
-
 module BoardgameEngine
-  # Class representing a physical board comprised of a grid in a board game. It
-  # acts as both the View and Model if the project were to be compared to a MVC
-  # model. It plays both roles as the board in a board game not only stores data,
-  # but also IS the data that must be shown to the players.
-  class Board
-    attr_reader :board
-
-    def initialize(row, col)
-      @board = Array.new(row) { Array.new(col) { nil } }
-    end
-
-    def display(show_row: false, show_col: false)
-      if show_row
-        @board.each_with_index { |row, idx| puts("#{idx} " + format_row(row)) }
-      else
-        @board.each { |row| puts format_row(row) }
-      end
-      return unless show_col
-
-      column_spacer = show_row ? "  " : ""
-      puts(@board[0].each_index.reduce(column_spacer) do |str, idx|
-        str + " #{idx} "
-      end)
-    end
-
-    def move_piece(start_row, start_col, end_row, end_col)
-      piece = @board[start_row][start_col]
-      @board[start_row][start_col] = nil
-      destination = @board[end_row][end_col]
-      @board[end_row][end_col] = piece
-
-      destination
-    end
-
-    private
-
-    def format_row(row)
-      row.map { |elem| "[#{elem.nil? ? " " : elem}]" }.join
-    end
-
-    def spot_playable?(piece, row, col)
-      piece.possible_moves.include? [row, col]
-    end
-  end
-
   # Class representing a player in a game
   class Player
     attr_reader :name
 
+    # Creates a player object with the given name
+    #
+    # @param [String] name the name of the player
     def initialize(name)
       @name = name
     end
 
+    # String representation of player
+    #
+    # @return [String] the name of the player
     def to_s
       @name.to_s
     end
   end
 
-  # Class for running a board game.
-  class Boardgame
+  # Class representing the game loop. It contains the tutorial sequence and
+  # information about the core gameplay loop
+  class Game
+    PLAY_INSTRUCTIONS = ''
     EXIT_INSTRUCTIONS ||= "Try a sample input or input 'back' to leave the " \
     "tutorial. Type in 'exit' anytime to exit the game fully"
+    GAME_NAME = 'Boardgame'
+    NUM_PLAYERS = 2
+
+    # Begins a round of the Game
+    #
+    # @param [Boolean] do_onboarding optional argument on whether to do
+    # onboarding
+    #
+    # @return [void]
+    def self.start(do_onboarding: true)
+      names = []
+      self::NUM_PLAYERS.times do |i|
+        puts "What is Player #{i}'s name?"
+        names.push(gets.chomp)
+      end
 
-    def initialize(board, instructions, name1 = "Player 1", name2 = "Player 2")
-      @player1 = Player.new(name1)
-      @player2 = Player.new(name2)
-      @board = setup_board(board)
-      @instructions = instructions
-      @winner = nil
-    end
-
-    def self.play(do_onboarding: true)
-      puts "What is Player 1's name?"
-      player1 = gets.chomp
-      puts "What is Player 2's name?"
-      player2 = gets.chomp
-      @game = new(player1, player2)
+      @game = new(names)
 
       puts "Welcome to #{@game}!"
       @game.onboarding if do_onboarding
       puts "Starting #{@game}..."
-      @game.start
-    end
-
-    def to_s(game_name = "boardgame")
-      "#{game_name} between #{@player1} and #{@player2}"
+      @game.play
     end
 
+    # Execute onboarding sequence where the player is asked if they want a
+    # tutorial
+    #
+    # @return [void]
     def onboarding
       puts "Would you like a tutorial on how to play on this program? \n(y, n)"
+
       case gets.chomp
-      when "y"
+      when 'y'
         tutorial
-      when "n"
-        puts "Skipping tutorial"
+      when 'n'
+        puts 'Skipping Tutorial'
       else
         puts 'Please answer either "y" or "n"'
         onboarding
       end
     end
 
-    def tutorial
-      puts @instructions + Boardgame::EXIT_INSTRUCTIONS
-      input = gets.chomp
-      until input == "back"
-        exit if input == "exit"
-        puts valid_input?(input) ? "Valid input!" : "Invalid input"
-        input = gets.chomp
-      end
-    end
-
-    def start(turn = @player1)
+    # Play the game
+    #
+    # @param [Player] turn the player who is going first
+    #
+    # @return [void]
+    def play(turn = @players[0])
       @turn = turn
       @board.display
       until @winner
         play_turn
         @board.display
+        change_turn
       end
       puts "#{@winner} wins!"
     end
 
+    # String representation of the game
+    #
+    # @return [String] <description>
+    def to_s
+      "#{self.class::GAME_NAME} between #{@players.join(', ')}"
+    end
+
     protected
 
-    def proper_format_input(special_commands = [])
+    # Constructor for a board game. Kept private so that an object of just class
+    # BoardGame cannot be instantiated without being inherited. It essentially
+    # keeps it as an abstract class
+    #
+    # @param [Board] board the board to play on
+    # @param [Array<String>] names the names of the players
+    def initialize(board, names)
+      @players = names.map { |name| Player.new name }
+      @board = setup_board(board)
+      @winner = nil
+    end
+
+    # Run tutorial for the game
+    def tutorial
+      puts self.class::PLAY_INSTRUCTIONS + self.class::EXIT_INSTRUCTIONS
+      input = gets.chomp
+      until input == 'back'
+        exit if input == 'exit'
+        puts @board.valid_board_input?(input) ? 'Valid input' : 'Invalid input'
+        input = gets.chomp
+      end
+    end
+
+    # Prompts a user for a board input until a proper input is received
+    #
+    # @param [Array<String>] special_commands a list of commands that are not
+    # valid board input but are valid commands like "back"
+    #
+    # @return [String] a valid input
+    def get_valid_board_input(special_commands = [])
       input = gets.chomp
-      until valid_input?(input)
-        exit if input == "exit"
-        return input if special_commands.include?(input)
 
-        puts "Input is in the wrong format or out of bounds. Try again"
+      until @board.valid_board_input?(input) || special_commands.include?(input)
+        exit if input == 'exit'
+
+        puts 'Invalid input. Try again'
         input = gets.chomp
       end
+
       input
     end
 
+    # Setup the board
+    #
+    # @param [Class] board the class of the board to be used in the game
+    #
+    # @return [Board] a new board
     def setup_board(board)
       board.new
     end
   end
+
+  class Piece
+    attr_accessor :status
+    attr_reader :owner
+
+    def initialize(owner, name)
+      @status = 'alive'
+      @owner = owner
+      @name = name
+    end
+
+    def kill(other)
+      other.status = 'dead'
+    end
+
+    def to_s
+      @name.to_s
+    end
+  end
 end