chess_cli 0.9.2

data/lib/console_game/chess/input/smith_notation.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module ConsoleGame
+  module Chess
+    # Module to parse Smith notation
+    module SmithNotation
+      # Smith Input Regexp pattern
+      # The first capture group is used to support move preview mode
+      # The second capture group is used to support direct move and place
+      SMITH_PATTERN = { gp1: "(?:[a-h][1-8])", gp2: "|(?:[a-h][1-8]){2}", promotion: "(?:[qrbn])" }.freeze
+
+      # Smith regexp pattern parser
+      SMITH_PARSER = /[a-z]\d*/
+
+      private
+
+      # == Smith notation ==
+
+      # Input validation when input scheme is set to Smith notation
+      # @param input [String] input value from prompt
+      # @return [Hash] a command pattern hash
+      def validate_smith(input)
+        case input.scan(SMITH_PARSER)
+        in [curr_pos] then { type: :preview_move, args: [curr_pos] }
+        in [curr_pos, new_pos] then { type: :direct_move, args: [curr_pos, new_pos] }
+        in [curr_pos, new_pos, notation] then { type: :direct_promote, args: [curr_pos, new_pos, notation] }
+        else { type: :invalid_input, args: [input] }
+        end
+      end
+
+      # == Utilities ==
+
+      # Smith Regexp pattern builder
+      # @return [String]
+      def regexp_smith = "#{SMITH_PATTERN.values.join('')}?"
+    end
+  end
+end

data/lib/console_game/chess/launcher.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative "game"
+
+module ConsoleGame
+  module Chess
+    # A wrapper to launch the game Chess
+    # @author Ancient Nimbus
+    module Launcher
+      # Load chess to app list
+      # @return [Hash]
+      def load_chess = { "chess" => method(:chess) }
+
+      # Run game: Chess
+      # @param game_manager [GameManager] expects ConsoleGame::GameManager object
+      # @return [Game]
+      def chess(game_manager) = Chess::Game.new(game_manager)
+    end
+  end
+end

data/lib/console_game/chess/level.rb

@@ -0,0 +1,276 @@
+# frozen_string_literal: true
+
+require_relative "game"
+require_relative "board"
+require_relative "logics/piece_analysis"
+require_relative "logics/piece_lookup"
+require_relative "logics/endgame_logic"
+require_relative "logics/moves_simulation"
+require_relative "pieces/king"
+require_relative "pieces/queen"
+require_relative "pieces/bishop"
+require_relative "pieces/knight"
+require_relative "pieces/rook"
+require_relative "pieces/pawn"
+require_relative "utilities/fen_import"
+require_relative "utilities/fen_export"
+require_relative "utilities/chess_utils"
+
+module ConsoleGame
+  module Chess
+    # The Level class handles the core game loop of the game Chess
+    # @author Ancient Nimbus
+    class Level
+      include ChessUtils
+
+      # @!attribute [r] w_player
+      #   @return [ChessPlayer, ChessComputer]
+      # @!attribute [r] b_player
+      #   @return [ChessPlayer, ChessComputer]
+      # @!attribute [r] kings
+      #   @return [Hash{Symbol => King}]
+      attr_accessor :fen_data, :white_turn, :turn_data, :active_piece, :en_passant, :player, :half_move, :full_move,
+                    :game_ended, :event_msgs
+      attr_reader :controller, :w_player, :b_player, :session, :board, :kings, :castling_states, :threats_map,
+                  :usable_pieces, :opponent
+
+      # @param input [ChessInput]``
+      # @param sides [Hash]
+      #   @option sides [ChessPlayer, ChessComputer] :white Player who plays as White
+      #   @option sides [ChessPlayer, ChessComputer] :black Player who plays as Black
+      # @param session [Hash] current session
+      # @param fen_import [String] expects a valid FEN string
+      def initialize(input, sides, session, fen_import = nil)
+        @controller = input
+        @w_player, @b_player = sides.values
+        @session = session
+        @board = Board.new(self)
+        controller.link_level(self)
+        @fen_data = fen_import.nil? ? parse_fen : parse_fen(fen_import)
+      end
+
+      # == Flow ==
+
+      # Start level
+      def open_level
+        init_level
+        play_chess until game_ended
+      end
+
+      # == Board Logic ==
+
+      # Actions to perform when player input is valid
+      # @param print_turn [Boolean] print board if is it set to true
+      # @return [Boolean] true if the operation is a success
+      def refresh(print_turn: true)
+        @piece_lookup = nil
+        update_board_state
+        game_end_check
+        add_check_marker
+        board.print_turn(event_msgs) if print_turn || game_ended
+      end
+
+      # Board state refresher
+      def update_board_state = board_analysis.each { |var, v| instance_variable_set("@#{var}", v) }
+
+      # Simulate next move - Find good moves
+      # @param piece [ChessPiece] expects a ChessPiece object
+      # @return [nil, Array<Integer>] good moves
+      # @see MovesSimulation #simulate_next_moves
+      def simulate_next_moves(piece) = piece.nil? ? nil : MovesSimulation.simulate_next_moves(self, piece)
+
+      # == Game Logic ==
+
+      # Pawn specific: Present a list of option when player can promote a pawn
+      def promote_opts = player.indirect_promote
+
+      # Reset En Passant status when it is not used at the following turn
+      def reset_en_passant
+        return if en_passant.nil? || active_piece == en_passant[0]
+
+        self.en_passant = nil if active_piece.curr_pos != en_passant[1]
+      end
+
+      # == Utilities ==
+
+      # Create new piece lookup service
+      # @return [PieceLookup]
+      def piece_lookup = @piece_lookup ||= PieceLookup.new(self)
+
+      # Fetch a single chess piece
+      # @see PieceLookup #fetch_piece
+      def fetch_piece(...) = piece_lookup.fetch_piece(...)
+
+      # Fetch a group of pieces notation from turn_data based on algebraic notation
+      # @see PieceLookup #group_fetch
+      def group_fetch(...) = piece_lookup.group_fetch(...)
+
+      # Grab all pieces, only whites or only blacks
+      # @see PieceLookup #fetch_all
+      def fetch_all(...) = piece_lookup.fetch_all(...)
+
+      # Lookup a piece based on its possible move position
+      # @see PieceLookup #reverse_lookup
+      def reverse_lookup(...) = piece_lookup.reverse_lookup(...)
+
+      # Loading message
+      # @param msg [String] message
+      # @param time [Integer] wait time
+      def loading_msg(msg, time: 2) = board.loading_msg(msg, time:)
+
+      # == Export ==
+
+      # Update session moves record
+      def update_session_moves
+        move_pairs = build_move_pairs(*all_moves)
+        rebuild_moves_record(move_pairs)
+      end
+
+      # Check for end game condition
+      # @return [Hash, nil] if it is hash message the game will end.
+      # @see EndgameLogic #game_end_check
+      def game_end_check
+        case EndgameLogic.game_end_check(self)
+        in nil then self.game_ended = false
+        in { draw: type } then handle_result(type:)
+        in { checkmate: side } then handle_result(type: "checkmate", side:)
+        end
+      end
+
+      private
+
+      # Initialise the chessboard
+      def init_level
+        @kings = PieceAnalysis.bw_nil_hash
+        @threats_map, @usable_pieces = Array.new(2) { PieceAnalysis.bw_arr_hash }
+        @event_msgs = []
+        fen_data.each { |field, v| instance_variable_set("@#{field}", v) }
+        set_current_player
+        update_board_state
+        refresh(print_turn: false)
+        greet_player
+      end
+
+      # greet player on load, message should change depending on load state
+      def greet_player
+        keypath = full_move == 1 ? "session.new" : "session.load"
+        event_msgs.push(board.s(keypath, {
+                                  event: [session[:event].sub("Status", "| Status:"), "gold"], p1: player.name
+                                }))
+      end
+
+      # Pre-turn flow
+      def pre_turn
+        save_turn
+        set_current_player
+        player.link_level(self)
+        refresh
+      end
+
+      # Main Game Loop
+      def play_chess
+        pre_turn
+        return if game_ended
+
+        player_action
+
+        # Post turn
+        self.white_turn = !white_turn
+      end
+
+      # Player action flow
+      def player_action
+        board.print_msg(board.s("level.turn", { player: player.name }), pre: "⠗ ")
+        player.is_a?(ChessComputer) ? player.play_turn : controller.turn_action(player)
+      end
+
+      # Set player side
+      # @return [ChessPlayer, ChessComputer]
+      def set_current_player
+        @player, @opponent = white_turn ? [w_player, b_player] : [b_player, w_player]
+      end
+
+      # Generate all possible move and send it to board analysis
+      # @see PieceAnalysis #board_analysis
+      # @return [Hash]
+      def board_analysis = PieceAnalysis.board_analysis(fetch_all.each(&:query_moves))
+
+      # == Endgame Logics ==
+
+      # Handle checkmate and draw event
+      # @param type [String] grounds of draw
+      # @param side [Symbol, nil] player side
+      # @return [Boolean]
+      def handle_result(type:, side: nil)
+        update_event_status(type:)
+        save_turn
+        winner = session[opposite_of(side)]
+        kings[side].color = "#CC0000" if type == "checkmate"
+        event_msgs << board.s("level.endgame.#{type}", { win_player: [winner, "gold"] })
+        @game_ended = true
+      end
+
+      # Update event state
+      def update_event_status(type:) = session[:event].sub!(board.s("status.ongoing"), board.s("status.#{type}"))
+
+      # Add checked or checkmate marker to opponent's last move
+      def add_check_marker
+        side = player.side
+        return unless kings[side].checked
+
+        last_move = opponent.moves_history[-1]
+        return if last_move.nil? || last_move.match?(/\A[a-zA-Z1-8]*[+#]\z/)
+
+        marker = game_ended ? "#" : "+"
+        opponent.moves_history[-1] = last_move + marker
+      end
+
+      # == Data Handling ==
+
+      # Parse FEN string data and convert this to usable internal data hash
+      # @param fen_import [String, nil] expects a complete FEN string
+      # @return [Hash<Hash>] FEN data hash for internal use
+      # @see FenImport #parse_fen
+      def parse_fen(fen_import = nil) = FenImport.parse_fen(self, fen_import)
+
+      # Convert internal data to FEN friendly string
+      # @return [String] fen string
+      # @see FenExport #to_fen
+      def to_fen = FenExport.to_fen(self)
+
+      # Save turn handling
+      def save_turn
+        save_player_move
+        @full_move = calculate_full_move
+        fen_str = to_fen
+        session[:fens].push(fen_str) if session.fetch(:fens)[-1] != fen_str
+        controller.save(mute: true)
+      end
+
+      # Save player move to session
+      def save_player_move
+        key = player.side == w_sym ? :white_moves : :black_moves
+        last_move = player.moves_history.last
+        session[key] << last_move unless last_move.nil? || session[key].last == last_move
+      end
+
+      # Calculate the full move
+      # @return [Integer]
+      def calculate_full_move = session[:black_moves].size + 1
+
+      # Rebuild session moves record
+      def rebuild_moves_record(move_pairs)
+        session[:moves] = {}
+        move_pairs.each_with_index { |pair, i| session[:moves][i + 1] = pair }
+      end
+
+      # Fetch moves history from both player
+      # @return [Array<Array<String>>]
+      def all_moves = [w_player, b_player].map(&:moves_history)
+
+      # Build a nested array of move pairs
+      # @return [Array<Array<String>>] move_pair
+      def build_move_pairs(w_moves, b_moves) = w_moves.zip(b_moves).reject { |turn| turn.include?(nil) }
+    end
+  end
+end

data/lib/console_game/chess/logics/display.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+require "paint"
+require_relative "../../../nimbus_file_utils/nimbus_file_utils"
+
+module ConsoleGame
+  module Chess
+    # Display module for the game Chess in Console Game
+    module Display
+      include ::NimbusFileUtils
+      # Default design for the chessboard
+      # Board padding is added as an UX enhancement, with 80 character width as design blueprint.
+      # Standard board padding is set to 23, while large board is set to 7.
+      BOARD = { size: 8, turn_data: Array.new(8) { [" "] }, file: [*"a".."h"], std_tile: 3, h: "═", decors: %w[◆ ◇],
+                head_l: "╔═══╦", head_r: "╦═══╗", sep_l: "╠═══╬", sep_r: "╬═══╣", tail_l: "╚═══╩", tail_r: "╩═══╝",
+                side: ->(v) { "║ #{v} ║" }, b_size_s: [1, 23], b_size_l: [2, 7] }.freeze
+
+      # Default design for chess pieces
+      PIECES = { k: { name: "King", notation: "K", style1: "♚", style2: "♔" },
+                 q: { name: "Queen", notation: "Q", style1: "♛", style2: "♕" },
+                 r: { name: "Rook", notation: "R", style1: "♜", style2: "♖" },
+                 b: { name: "Bishop", notation: "B", style1: "♝", style2: "♗" },
+                 n: { name: "Knight", notation: "N", style1: "♞", style2: "♘" },
+                 p: { name: "Pawn", notation: "P", style1: "♟", style2: "♙" } }.freeze
+
+      # Default theme
+      # Note on other good options: bg: %w[#ada493 #847b6a], black: "#A52A2A", white: "#F0FFFF"
+      THEME = {
+        classic: { bg: %w[#cdaa7d #8b5742], black: "#000000", white: "#f0ffff", icon: "◇", highlight: "#00ff7f" },
+        navy: { bg: %w[#cdaa7d #8b5742], black: "#191970", white: "#f0ffff", icon: "◇", highlight: "#00ff7f" }
+      }.freeze
+
+      # Message Syntax highlight
+      MSG_HIGHLIGHT = {
+        std: { type: "cyan", alg_pos: "gold" }
+      }.freeze
+
+      # Override: s
+      # Retrieves a localized string and perform String interpolation and paint text if needed.
+      # @param key_path [String] textfile keypath
+      # @param subs [Hash] `{ demo: ["some text", :red] }`
+      # @param paint_str [Array<Symbol, String, nil>]
+      # @param extname [String]
+      # @return [String] the translated and interpolated string
+      def s(key_path, subs = {}, paint_str: %i[default default], extname: ".yml")
+        super("app.chess.#{key_path}", subs, paint_str:, extname:)
+      end
+
+      private
+
+      # Build the chessboard
+      # @param turn_data [Array<Array<ChessPiece, String>>] expects an 8 by 8 array, each represents a whole rank
+      # @param side [Symbol] :white or :black, this will flip the board
+      # @param colors [Array<Symbol, String>] Expects contrasting background colour
+      # @param size [Integer] padding size
+      # @param show_r [Boolean] print ranks on the side?
+      # @return [Array<String>] a complete board with head and tail
+      def build_board(turn_data = BOARD[:turn_data], side: :white, colors: THEME[:classic][:bg], size: 1, show_r: true)
+        tile_w = to_quadratic(size)
+        # main
+        board = build_main(turn_data, side: side, colors: colors, tile_w: tile_w, size: size, show_r: show_r)
+        # Set board decorator
+        board_decors = BOARD[:decors]
+        head_side, tail_side = side == :black ? board_decors : board_decors.reverse
+        # Insert head
+        board.unshift(frame(:head, side: side, tile_w: tile_w, show_r: show_r, label: head_side))
+        # Push tail
+        board.push(frame(:tail, side: side, tile_w: tile_w, show_r: show_r, label: tail_side))
+        # Return flatten
+        board.flatten
+      end
+
+      # Rank formatter
+      # @param rank_num [Integer] rank number
+      # @param row_data [Array<ChessPiece, String>] expects a 1-element(reprinting) or n-elements array(In order)
+      # @param colors [Array<Symbol, String, nil>] Expects contrasting background colour
+      # @param tile_w [Integer] width of each tile
+      # @param show_r [Boolean] print ranks on the side?
+      # @param label [String] override the print rank value with custom string
+      # @return [Array<String>] a complete row of a specific rank within the board
+      def format_row(rank_num, row_data, colors: THEME[:classic][:bg], tile_w: BOARD[:std_tile], show_r: false,
+                     label: "", flipped: false)
+        arr = []
+        # Light background colour, dark background colour
+        bg1, bg2 = pattern_order(rank_num, colors: colors)
+        # Build individual tile
+        BOARD[:size].times { |i| arr << paint_tile(row_data[i % row_data.size], tile_w, i.even? ? bg1 : bg2) }
+        # Build side borders
+        label = rank_num if label.empty?
+        border = [BOARD[:side].call(show_r ? label : " ")]
+        add_borders(arr, border, flipped: flipped)
+      end
+
+      # Return a formatted row with borders
+      def add_borders(arr_data, border, flipped: false)
+        formatted_row = border.concat(arr_data, border)
+        formatted_row.reverse! if flipped
+        [formatted_row.join("")]
+      end
+
+      # Build the main section of the chessboard
+      # @param turn_data [Array<Array>] expects an array with n elements, each represents a single row
+      # @param side [Symbol] :white or :black, this will flip the board
+      # @param colors [Array<Symbol, String>] Expects contrasting background colour
+      # @param tile_w [Integer] width of each tile
+      # @param size [Integer] padding size
+      # @param show_r [Boolean] print ranks on the side?
+      def build_main(turn_data, side: :white, colors: THEME[:classic][:bg], tile_w: BOARD[:std_tile], size: 1,
+                     show_r: true)
+        board = []
+        flip = true if side == :black
+        turn_data.each_with_index do |row, i|
+          rank_num = i + 1
+          rank_row = format_row(rank_num, row, colors: colors, tile_w: tile_w, show_r: show_r, flipped: flip)
+          buffer_row = [format_row(rank_num, [" "], colors: colors, tile_w: tile_w, flipped: flip)] * (size - 1)
+          board << buffer_row.concat(rank_row, buffer_row)
+        end
+        flip ? board : board.reverse
+      end
+
+      # Helper: Build the head and tail section of the chessboard
+      # @param section [Symbol] :head or :tail
+      # @param tile_w [Integer] width of each tile
+      # @param show_r [Boolean] print ranks on the side?
+      # @param label [String] override the print rank value with custom string
+      # @return [Array<String>] the top or bottom section of the board
+      def frame(section = :head, side: :white, tile_w: BOARD[:std_tile], show_r: true, label: "")
+        row_values = show_r ? BOARD[:file] : [label]
+        flip = true if side == :black
+        ends_l, ends_r = section == :head ? %i[head_l head_r] : %i[tail_l tail_r]
+
+        arr = [border(BOARD[ends_l], BOARD[ends_r], tile_w, BOARD[:h])]
+        arr << format_row(0, row_values, colors: [nil, nil], tile_w: tile_w, show_r: true, label: label, flipped: flip)
+        arr << border(BOARD[:sep_l], BOARD[:sep_r], tile_w, BOARD[:h])
+
+        section == :head ? arr : arr.reverse
+      end
+
+      # Helper: Build horizontal border
+      # @param left [String] left padding
+      # @param right [String] right padding
+      # @param length [Integer] times of repetition
+      # @param value [String] value to be repeated
+      def border(left, right, length, value) = "#{left}#{value.center(length * BOARD[:size], value)}#{right}"
+
+      # Helper: Determine the checker order of a specific rank
+      # @param rank_num [Integer] rank number
+      # @param colors [Array<Symbol, String>] Expects contrasting background colour
+      # @return [Array<Symbol, String>] colour values
+      def pattern_order(rank_num, colors: THEME[:classic][:bg]) = rank_num.even? ? colors : colors.reverse
+
+      # Helper: Paint tile
+      # @param item [ChessPiece, Hash, String] item
+      # @param tile_w [Integer] width within each tile
+      # @param bg_color [Symbol, String] expects a colour value
+      # @return [String] coloured string
+      def paint_tile(item, tile_w, bg_color)
+        str, color, bg = case item
+                         when ChessPiece then [item.icon, item.color, bg_color]
+                         when Hash then [item[:icon], item[:highlight], bg_color]
+                         when String then [item, :default, bg_color]
+                         end
+        Paint[str.center(tile_w), color, bg]
+      end
+
+      # Helper: Quadratic expression to maintain tile shape, based on n^2-n+1
+      # @param size [Integer] padding size
+      # @return [Integer] total width of each tile
+      def to_quadratic(size) = (size + 1)**2 - (size + 1) + 1
+
+      # Convert a 1D array to 2D array based on bound's row value
+      # @param flat_arr [Array]
+      # @param bound [Array<Integer>] `[row, col]`
+      # @return [Array] nested array
+      def to_matrix(flat_arr, bound: [BOARD[:size], BOARD[:size]])
+        nested_arr = []
+        flat_arr.each_slice(bound[0]) { |row| nested_arr.push(row) }
+        nested_arr
+      end
+    end
+  end
+end

data/lib/console_game/chess/logics/endgame_logic.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module ConsoleGame
+  module Chess
+    # The EndgameLogic class defines the various logics to determine whether the game is a draw or checkmates
+    # @author Ancient Nimbus
+    class EndgameLogic
+      # Check for end game condition
+      # @return [Hash, nil]
+      def self.game_end_check(...) = new(...).game_end_check
+
+      # @!attribute [r] level
+      #   @return [Level] current level
+      # @!attribute [r] player
+      #   @return [ChessPlayer, ChessComputer] player of the current turn
+      # @!attribute [r] side
+      #   @return [Symbol] side of the current player
+      # @!attribute [r] usable_pieces
+      #   @return [Hash] all usable pieces from both sides
+      # @!attribute [r] threats_map
+      #   @return [Hash] all threats affecting both sides
+      # @!attribute [r] half_move
+      #   @return [Integer] half move clock value
+      # @!attribute [r] fen_records
+      #   @return [Hash<String>] fen session history
+      # @!attribute [r] kings
+      #   @return [Hash<King>] all kings as hash
+      attr_reader :level, :player, :side, :usable_pieces, :threats_map, :half_move, :fen_records, :kings
+
+      # @param level [Level] expects a Chess::Level class object
+      def initialize(level)
+        @level = level
+        @player = level.player
+        @side = player.side
+        @usable_pieces = level.usable_pieces
+        @threats_map = level.threats_map
+        @half_move = level.half_move
+        @fen_records = level.session[:fens]
+        @kings = level.kings
+      end
+
+      # Check for end game condition
+      # @return [Hash, nil]
+      def game_end_check
+        condition = draw?
+        return condition unless condition.nil?
+
+        condition = any_checkmate?
+        return condition unless condition.nil?
+
+        nil
+      end
+
+      private
+
+      # == Checkmate ==
+
+      # End game if either side achieved a checkmate
+      # @return [Hash, nil] return a message if either side is checkmate
+      def any_checkmate?
+        fallen_king = kings.values.select(&:checkmate?)
+        fallen_king.empty? ? nil : { checkmate: fallen_king.first.side }
+      end
+
+      # == Rules for Draw ==
+
+      # End game if is it a draw
+      # @return [Hash, nil] the game is a draw when true
+      def draw? = [stalemate?, fifty_move?, threefold_repetition?, insufficient_material?(*last_four)].compact.first
+
+      # Game is a stalemate
+      # @return [Hash, nil] returns a message if it is a draw
+      def stalemate? = usable_pieces[side].empty? && threats_map[side].empty? ? { draw: "stalemate" } : nil
+
+      # Game is a draw due to Fifty-move rule
+      # @return [Hash, nil] returns a message if it is a draw
+      def fifty_move? = half_move >= 100 ? { draw: "fifty_move" } : nil
+
+      # Game is a draw due to Threefold Repetition
+      # @return [Hash, nil] returns a message if it is a draw
+      def threefold_repetition?
+        return nil unless fen_records.size > 10
+
+        sectioned_fen_records = fen_records.last(100).map { |fen| fen.split(" ")[0...-2].join(" ") }
+        sectioned_fen_records.count(sectioned_fen_records.last) >= 3 ? { draw: "threefold" } : nil
+      end
+
+      # Game is a draw due to insufficient material
+      # @see https://support.chess.com/en/articles/8705277-what-does-insufficient-mating-material-mean
+      # @param remaining_pieces [Array<ChessPiece>]
+      # @param remaining_notations [Array<String>]
+      # @return [Hash, nil] returns a message if it is a draw
+      def insufficient_material?(remaining_pieces, remaining_notations)
+        return nil if remaining_pieces.nil? || remaining_notations.nil?
+        return nil unless bishops_insufficient_material?(remaining_pieces)
+
+        insufficient_patterns = %w[KK KBK KKN KBKB KNKN]
+        return nil unless insufficient_patterns.any? { |combo| combo.chars.sort == remaining_notations.sort }
+
+        { draw: "insufficient" }
+      end
+
+      # Determine the minimum qualifying requirement to enter the #insufficient_material? flow
+      # @return [Array<nil>, Array<Array<ChessPiece>, Array<String>>]
+      def last_four
+        pieces = usable_pieces.values
+        pieces.sum(&:size) > 4 ? [nil, nil] : level.group_fetch(pieces)
+      end
+
+      # Insufficient material helper: check if two bishops are from the same side or on the same color tile
+      # @param pieces [Array<ChessPiece>] remaining ChessPiece
+      # @return [Boolean] continue insufficient material flow
+      def bishops_insufficient_material?(pieces)
+        bishops = pieces.select { |piece| piece.is_a?(Bishop) }
+        return true if bishops.size <= 1
+        return false if bishops.size > 2
+
+        bishop1, bishop2 = bishops
+        return false if bishop1.side == bishop2.side
+
+        b1_ord, b2_ord = bishops.map { |bishop| bishop.file.ord + bishop.rank.to_i }
+        b1_ord == b2_ord
+      end
+    end
+  end
+end