upwords 0.1.1 → 0.2.1

data/lib/upwords/move.rb

@@ -1,59 +1,71 @@
+# Encapsulates a possible move that a player could submit in a single turn
+
 module Upwords
   class Move
     
+    # Initialized with a list of 2D arrays, each containing a position (row, col) and a letter
     def initialize(tiles = [])
       @shape = Shape.new(tiles.map {|(row, col), letter| [row, col]})
       @move = tiles.to_h
     end
 
-    # TODO: remove dict from word class
-    # TODO: move score and new word methods to board class?
+    # Calculate value of move
+    # Most of the word score calculate logic is in the Word class. However, this method
+    # will also add 20 points if the player uses all of their letters in the move
     def score(board, player)
       new_words(board).reduce(player.rack_capacity == @move.size ? 20 : 0) do |total, word|
         total += word.score
       end
     end
 
-    # TODO: Add the following legal move checks:
-    # - Move is not a simple pluralization? (e.g. Cat -> Cats is NOT a legal move)
+    # Check if a move is legal
     def legal?(board, dict, raise_exception = false)
       legal_shape?(board, raise_exception) && legal_words?(board, dict, raise_exception)
     end
 
+    # Check if a move has a legal shape
     def legal_shape?(board, raise_exception = false)
       @shape.legal?(board, raise_exception)
-    end
-
-    def can_play_letters?(board, raise_exception = false)
-      @move.all? do |(row, col), letter|
-        board.can_play_letter?(letter, row, col, raise_exception)
-      end
-    end
-
+    end   
+    
+    # Check if all words that result from move are legal
     # TODO: Add the following legal move checks:
-    # - Move is not a simple pluralization? (e.g. Cat -> Cats is NOT a legal move)
+    # TODO: - Move is not a simple pluralization? (e.g. Cat -> Cats is NOT a legal move)
     def legal_words?(board, dict, raise_exception = false)
 
       if can_play_letters?(board, raise_exception)    
         bad_words = self.new_illegal_words(board, dict)
         if bad_words.empty?
           return true
-        else
-          raise IllegalMove, "#{bad_words.join(', ')} #{bad_words.size==1 ? 'is not a legal word' : 'are not legal words'}!" if raise_exception
+        elsif raise_exception
+          raise IllegalMove, "#{bad_words.join(', ')} #{bad_words.size==1 ? 'is not a legal word' : 'are not legal words'}!" 
         end
       end
 
       return false
     end
 
+    # Check if entire move can be played on a board violating any board constraints, such as
+    # being out of bounds or exceeding the maximum stack height
+    def can_play_letters?(board, raise_exception = false)
+      @move.all? do |(row, col), letter|
+        board.can_play_letter?(letter, row, col, raise_exception)
+      end
+    end
+
+    # Check if a particular position (row, col) is covered by the move
     def position?(row, col)
       @move.key?([row, col])
     end
 
+    # Return the letter in position (row, col) of the move
     def [](row, col)
       @move[[row, col]]
     end
     
+    # Play move on board and return the board
+    # NOTE: this method mutates the boards! 
+    # TODO: consider adding the 'can_play_letters?' check?
     def play(board)
       @move.reduce(board) do |b, (posn, letter)| 
         b.play_letter(letter, *posn)
@@ -61,7 +73,8 @@ module Upwords
       end
     end
 
-    # TODO: consider move main subroutine to Shape class?
+    # Remove a previous move from the board and return the board (throws an exception if the move does not exist on the board)
+    # NOTE: this method mutates the boards! 
     def remove_from(board)
       if @move.any? {|(row, col), letter| board.top_letter(row, col) != letter}
         raise IllegalMove, "Move does not exist on board and therefore cannot be removed!"
@@ -73,23 +86,25 @@ module Upwords
       end
     end
 
-    # TODO: handle exceptions when board cannot be updated with new move
-    # TODO: move score and new word methods to board class?
-    def new_words(board)
-      # HACK: update board with new move
-      words = (board.play_move(self).word_positions).select do |word_posns|
-        word_posns.any? {|row, col| position?(row, col)}
-        
-      end.map do |word_posns|
-        Word.new(word_posns, board)
+    # Return a list of new words that would result from playing this move on the board
+    def new_words(board, raise_exception = false)
+      if can_play_letters?(board, raise_exception) 
+        # HACK: update board with new move
+        words = (board.play_move(self).word_positions).select do |word_posns|
+          word_posns.any? {|row, col| position?(row, col)}
+          
+        end.map do |word_posns|
+          Word.new(word_posns, board)
+        end
+  
+        # HACK: remove move from board
+        remove_from(board)
+  
+        return words
       end
-
-      # HACK: remove move from board
-      remove_from(board)
-
-      words
     end
 
+    # Return a list of new words that are not legal that would result from playing this move on the board
     def new_illegal_words(board, dict)
       new_words(board).reject {|word| dict.legal_word?(word.to_s)}
     end

data/lib/upwords/move_manager.rb

@@ -11,15 +11,19 @@ module Upwords
     # --------------------------------
     # Player-Board Interaction Methods
     # --------------------------------
+
     def add(player, letter, row, col)
-      # TODO: remove the need for @pending_move.map
-      if (@pending_move.map {|m| m[0]}).include?([row, col])
+      if self.include?(row, col) 
         raise IllegalMove, "You can't stack on a space more than once in a single turn!"
       elsif
         @pending_move << player.play_letter(@board, letter, row, col)
       end
     end
 
+    def include?(row, col)
+      @pending_move.map {|m| m[0]}.include?([row, col])
+    end
+
     def undo_last(player)
       if @pending_move.empty?
         raise IllegalMove, "No moves to undo!"
@@ -44,7 +48,11 @@ module Upwords
       end
     end
 
-    # TODO: cache prev board in local variable...
+    # -------------------------------------
+    # Methods that require the game history
+    # -------------------------------------
+
+    # TODO: cache previous board in local variable...
     def pending_words
       prev_board = Board.build(@move_history, @board.size, @board.max_height)
       Move.new(@pending_move).new_words(prev_board)

data/lib/upwords/player.rb

@@ -1,7 +1,10 @@
+# Encapsules a player
+# Contains basic AI logic
+
 module Upwords
   class Player
 
-    attr_reader :name, :cpu
+    attr_reader :name
     attr_accessor :score, :last_turn
 
     def initialize(name, rack_capacity=7, cpu=false)
@@ -12,10 +15,6 @@ module Upwords
       @cpu = cpu
     end
 
-    def cpu?
-      @cpu
-    end
-
     def letters
       @rack.letters.dup
     end
@@ -39,6 +38,10 @@ module Upwords
     def take_letter(letter)
       @rack.add(letter)
     end
+    
+    # -------------------------------
+    # Game object interaction methods
+    # -------------------------------
 
     def take_from(board, row, col)
       if board.stack_height(row, col) == 0
@@ -74,84 +77,88 @@ module Upwords
       end
     end
     
-    # ----------------
-    # CPU Move Methods
-    # ----------------
+    # ---------------
+    # AI move methods
+    # ---------------
     
-    def straight_moves(board)
-      rows = board.num_rows
-      cols = board.num_columns
-      
-      # Get single-position moves
+    def cpu?
+      @cpu
+    end
+    
+    # Return a list of legal move shapes that player could make on board
+    def legal_move_shapes(board)
       one_space_moves = board.coordinates.map {|posn| [posn]}
       
-      # Get board positions grouped by rows
-      (0...rows).map do |row| 
-        (0...cols).map {|col| [row, col]}
+      # Collect board positions grouped by rows
+      (0...board.num_rows).map do |row| 
+        (0...board.num_columns).map {|col| [row, col]} 
         
-        # Get horizontal multi-position moves
+        # Collect all positions of all possible horizontal multi-position moves that player could make
       end.flat_map do |posns|
         (2..(letters.size)).flat_map {|sz| posns.combination(sz).to_a}
         
-        # Collect all possible straight moves 
+        # Collect all positions of all possible vertical and horizontal moves that player could make
       end.reduce(one_space_moves) do |all_moves, move|
-        all_moves << move << move.map {|posn| posn.rotate}
-      end
-    end
-    
-    # TODO: Strip out move filters and have the client provide them in a block
-    def legal_move_shapes(board, &filter) 
-      straight_moves(board).select(&filter)
-    end
-    
-    def standard_legal_shape_filter(board)
-      proc do |move_arr|
-        Shape.new(move_arr).legal?(board)
+        all_moves << move                           # Horizontal moves
+        all_moves << move.map {|posn| posn.rotate}  # Vertical moves
+        
+        # Filter out illegal move shapes  
+      end.select do |move_posns|
+        Shape.new(move_posns).legal?(board)
       end
     end
     
-    def legal_shape_letter_permutations(board, &filter)
+    # Return list of all possible letter permutations on legal move shapes that player could make on board
+    # Elements in the list will be in form of [(row, col), letter]
+    def legal_move_shapes_letter_permutations(board)
       # Cache result of letter permutation computation for each move size
-      letter_perms = Hash.new {|ps, sz| ps[sz] = letters.permutation(sz).to_a}
+      letter_perms = Hash.new {|perms, sz| perms[sz] = letters.permutation(sz).to_a}
       
-      legal_move_shapes(board, &filter).reduce([]) do |all_moves, move|
+      legal_move_shapes(board).reduce([]) do |all_moves, move|
         letter_perms[move.size].reduce(all_moves) do |move_perms, perm|
           move_perms << move.zip(perm)
         end
       end
     end
 
-    def cpu_move(board, dict, sample_size = 1000, min_score = 0)
-      all_possible_moves = (self.legal_shape_letter_permutations(board, &self.standard_legal_shape_filter(board)))      
-      all_possible_moves.shuffle!
-
+    # Execute a legal move based on a predefined strategy
+    #
+    # Basic strategy:
+    # - Find all legal move shapes and all possible letter permutations across those shapes (this computation is relatively quick)
+    # - Retun the highest score from permutation that do not produce in any illegal new words (this computation is slow...)
+    # - To speed up the above computation: 
+    #   + Only check a batch of permutations at a time (specified in 'batch_size' argument)
+    #   + After each batch, terminate the subroutine if it finds a score that is at least as high as the given 'min_score'
+    #   + Decrement the 'min_score' after each batch that does not terminate the subroutine to prevent endless searches
+    #
+    # TODO: refactor the the 'strategy' component out of this method, so different strategies can be swapped in and out
+    def cpu_move(board, dict, batch_size = 1000, min_score = 0)
+      possible_moves = self.legal_move_shapes_letter_permutations(board)      
+      possible_moves.shuffle!
+      
       top_score = 0
       top_score_move = nil
-
-      # TODO: write test for this method
+      
       while top_score_move.nil? || (top_score < min_score) do
-
-        ([sample_size, all_possible_moves.size].min).times do
-                    
-          move_arr = all_possible_moves.pop
+        
+        # Check if next batch contains any legal moves and save the top score
+        ([batch_size, possible_moves.size].min).times do
+          move_arr = possible_moves.pop
           move = Move.new(move_arr)
 
           if move.legal_words?(board, dict)
-
             move_score = move.score(board, self)
-
             if move_score >= top_score
               top_score = move_score
               top_score_move = move_arr
             end
-
           end
         end
-
+        
         # Decrement minimum required score after each cycle to help prevent long searches
         min_score = [(min_score - 1), 0].max
       end
-
+      
       top_score_move
     end
     

data/lib/upwords/shape.rb

@@ -1,3 +1,6 @@
+# Encapsulates the shape of a possible move that a player could submit in a single turn
+# Component of the Move class
+
 module Upwords
   class Shape
 
@@ -9,7 +12,7 @@ module Upwords
     end
 
     # Check if move creates a legal shape when added to a given board.
-    # All checks assume that the move in question has not been played yet.
+    # NOTE: All checks assume that the move in question has not been played on the board yet.
     def legal?(board, raise_exception = false)        
       if board.empty? && !in_middle_square?(board)
         raise IllegalMove, "You must play at least one letter in the middle 2x2 square!" if raise_exception
@@ -30,12 +33,16 @@ module Upwords
       return false
     end
 
+    # Check if move shape completely covers any existing word on the board
     def covering_moves?(board)
       (board.word_positions).any? do |word_posns|
         positions >= word_posns
       end
     end
     
+    # Check if all empty spaces in the rows and columns spanned by the move shape are covered by a previously-played tile on board
+    # For example, if the move shape = [1,1] [1,2] [1,4], then this method returns 'true' if the board has a tile at position [1,3]
+    # and 'false' if it does not.
     def gaps_covered_by?(board)
       row_range.all? do |row|
         col_range.all? do |col|
@@ -44,15 +51,17 @@ module Upwords
       end
     end
        
+    # Check if at least one position within the move shape is adjacent to or overlapping any tile on the board
     def touching?(board)
       @positions.any? do |row, col|
-        # Are any positions overlapping or adjacent to a non-empty board space 
         [[0, 0], [1, 0], [-1, 0], [0, 1], [0, -1]].any? do |dr, dc|
           board.nonempty_space?(row + dr, col + dc)
         end
       end
     end
 
+    # Check if at least one position within the move shape is within the middle 2x2 square on the board
+    # This check is only performed at the beginning of the game
     def in_middle_square?(board)
       board.middle_square.any? do |posn|
         @positions.include?(posn)

data/lib/upwords/ui.rb

@@ -0,0 +1,360 @@
+module Upwords
+  class UI
+
+    def initialize(game, row_height = 1, col_width = 4)
+      # Game and drawing variables
+      @game = game
+      @rows = game.board.num_rows
+      @cols = game.board.num_columns
+      @row_height = row_height
+      @col_width = col_width
+      @rack_visible = false
+
+      # Configure Curses and initialize screen
+      Curses.noecho
+      Curses.curs_set(2)  # Blinking cursor
+      Curses.init_screen
+      Curses.start_color
+
+      # Initialize colors
+      Curses.init_pair(RED, Curses::COLOR_RED, Curses::COLOR_BLACK) # Red on black background
+      Curses.init_pair(YELLOW, Curses::COLOR_YELLOW, Curses::COLOR_BLACK) # Yellow on black background
+
+      # Initialize main window and game loop
+      begin
+        @win = Curses.stdscr
+        @win.keypad=(true)
+
+        add_players
+        @game.all_refill_racks
+
+        @win.setpos(*letter_pos(*@game.cursor.pos))
+        draw_update_loop
+      ensure
+        Curses.close_screen
+      end      
+    end
+
+    # ==================================
+    # Main methods: draw and input loops
+    # ==================================
+
+    def draw_update_loop
+      draw_grid
+      draw_controls
+
+      while @game.running? do
+        @rack_visible = false
+        draw_player_info
+        draw_message "#{@game.current_player.name}'s turn"
+
+        # CPU move subroutine
+        if @game.current_player.cpu?
+          draw_message "#{@game.current_player.name} is thinking..."
+          @game.cpu_move
+          draw_letters
+          draw_stack_heights
+          draw_player_info 
+        # Read key inputs then update cursor and window
+        else
+          while read_key do
+            @win.setpos(*letter_pos(*@game.cursor.pos))
+            draw_letters
+            draw_stack_heights
+            draw_player_info 
+          end
+        end
+        
+        # Game over subroutine
+        if @game.game_over?
+          draw_player_info 
+          get_game_result
+        end
+
+      end
+    end
+
+    # If read_key returns 'false', then current iteration of the input loop ends
+    def read_key
+      case (key = @win.getch)      
+      when 'Q'
+        if draw_confirm("Are you sure you want to exit the game? (y/n)")
+          @game.exit_game 
+          return false
+        end
+      when DELETE
+        @game.undo_last
+        draw_message(@game.standard_message) # TODO: factor this method
+      when Curses::Key::UP
+        @game.cursor.up
+      when Curses::Key::DOWN
+        @game.cursor.down
+      when Curses::Key::LEFT
+        @game.cursor.left
+      when Curses::Key::RIGHT
+        @game.cursor.right
+      when SPACE
+        @rack_visible = !@rack_visible
+      when ENTER
+        if draw_confirm("Are you sure you wanted to submit? (y/n)")  
+          @game.submit_moves
+          return false
+        end
+      when '+'
+        draw_message("Pick a letter to swap")
+        letter = @win.getch
+        if letter =~ /[[:alpha:]]/ && draw_confirm("Swap '#{letter}' for a new letter? (y/n)")
+          @game.swap_letter(letter)
+          return false
+        else
+          draw_message("'#{letter}' is not a valid letter")
+        end
+      when '-'
+        if draw_confirm("Are you sure you wanted to skip your turn? (y/n)")  
+          @game.skip_turn
+          return false
+        end
+      when /[[:alpha:]]/
+        @game.play_letter(key)
+        draw_message(@game.standard_message)
+      end
+      
+      return true
+
+    rescue IllegalMove => exception
+      draw_confirm("#{exception.message} (press any key to continue...)")
+      return true 
+    end
+
+    # =============================
+    # Subroutines in draw loop
+    # =============================    
+
+    # Select the maximum number of players, then add players and select if they humans or computers
+    # TODO: refactor this method
+    def add_players
+      @win.setpos(0, 0)
+      Curses.echo
+      @win.keypad=(false) 
+      
+      num_players = 0
+      
+      # Select how many players will be in the game
+      # TODO: Add a command-line flag to allow players to skip this step
+      until (1..@game.max_players).include?(num_players.to_i) do
+        @win.addstr("How many players will play? (1-#{@game.max_players})\n")
+        num_players = @win.getstr
+        
+        @win.addstr("Invalid selection\n") if !(1..@game.max_players).include?(num_players.to_i)
+        @win.addstr("\n")
+
+        # Refresh screen if lines go beyond terminal window   
+        clear_terminal if @win.cury >= @win.maxy - 1
+      end
+
+      # Name each player and choose if they are humans or computers
+      # TODO: Add a command-line flag to set this
+      (1..num_players.to_i).each do |idx|
+        @win.addstr("What is Player #{idx}'s name? (Press enter to submit...)\n")
+
+        name = @win.getstr
+        name = (name =~ /[[:alpha:]]/ ? name : sprintf('Player %d', idx))
+        @win.addstr("\nIs #{name} a computer? (y/n)\n")
+        
+        cpu = @win.getstr
+        @game.add_player(name, rack_capacity=7, cpu.upcase == "Y")
+        @win.addstr("\n")        
+
+        # Refresh screen if lines go beyond terminal window
+        clear_terminal if @win.cury >= @win.maxy - 1
+      end
+    ensure
+      Curses.noecho
+      @win.keypad=(true) 
+    end
+    
+    def get_game_result
+      draw_confirm("The game is over. Press any key to continue to see who won...")
+      
+      top_score = @game.get_top_score
+      winners = @game.get_winners
+      
+      if winners.size == 1 
+        draw_confirm "And the winner is... #{winners.first} with #{top_score} points!"
+      else
+        draw_confirm "We have a tie! #{winners.join(', ')} all win with #{top_score} points!"
+      end
+      
+      @game.exit_game
+    end
+
+    # =============================
+    # Draw individual game elements
+    # =============================
+
+    def draw_message(text)
+      write_str(*message_pos, text, clear_below=true)
+    end
+
+    def clear_message
+      draw_message("")
+    end
+
+    def draw_player_info
+      draw_wrapper do
+        py, px = player_info_pos
+        
+        # Draw rack for current player only          
+        write_str(py, px, "#{@game.current_player.name}'s letters:", clear_right=true)
+        write_str(py+1, px, "[#{@game.current_player.show_rack(masked=!@rack_visible)}]", clear_right=true)
+
+        @game.players.each_with_index do |p, i|
+          write_str(py+i+3, px, sprintf("%s %-13s %4d", p == @game.current_player ? "->" : "  ", "#{p.name}:", p.score), clear_right=true)
+        end
+      end
+    end
+
+    # TODO: make confirmation options more clear
+    def draw_confirm(text) 
+      draw_message("#{text}")
+      reply = (@win.getch.to_s).upcase == "Y"
+      clear_message
+      return reply
+    end
+
+    def draw_grid
+      draw_wrapper do
+        # create a list containing each line of the board string
+        divider = [nil, ["-" * @col_width] * @cols, nil].flatten.join("+")
+        spaces = [nil, [" " * @col_width] * @cols, nil].flatten.join("|")
+        lines = ([divider] * (@rows + 1)).zip([spaces] * @rows).flatten
+
+        # concatenate board lines and draw in a sub-window on the terminal
+        @win.setpos(0, 0)
+        @win.addstr(lines.join("\n"))
+      end
+    end
+
+    def draw_controls
+      draw_wrapper do
+        y, x = controls_info_pos
+        ["----------------------",
+         "|      Controls      |",
+         "----------------------",
+         "Show Letters   [SPACE]",
+         "Undo Last Move [DEL]",
+         "Submit Move    [ENTER]",
+         "Swap Letter    [+]",
+         "Skip Turn      [-]",
+         "Quit Game      [SHIFT+Q]",
+         "Force Quit     [CTRL+Z]"      # TODO: technically this only works for unix shells...
+        ].each_with_index do |line, i|
+          @win.setpos(y+i, x)
+          @win.addstr(line)
+        end
+      end
+    end
+
+    def draw_letters
+      board = @game.board
+
+      draw_for_each_cell do |row, col|
+        @win.setpos(*letter_pos(row, col))
+        
+        # HACK: removes yellow highlighting from 'Qu'
+        letter = "#{board.top_letter(row, col)}  "[0..1] 
+
+        if @game.pending_position?(row, col)
+          Curses.attron(Curses.color_pair(YELLOW)) { @win.addstr(letter) }
+        else
+          @win.addstr(letter)      
+        end  
+      end
+    end
+
+    def draw_stack_heights
+      board = @game.board
+
+      draw_for_each_cell do |row, col|        
+        @win.setpos(*stack_height_pos(row, col))
+
+        case (height = board.stack_height(row, col))
+        when 0
+          @win.addstr("-")
+        when board.max_height
+          Curses.attron(Curses.color_pair(RED)) { @win.addstr(height.to_s) }
+        else
+          @win.addstr(height.to_s)
+        end
+      end
+    end
+
+    private
+  
+    # ======================================
+    # Get positions of various game elements
+    # ======================================
+
+    def letter_pos(row, col)
+      [(row * (@row_height + 1)) + 1, (col * (@col_width + 1)) + 2] # TODO: magic nums are offsets 
+    end
+
+    def stack_height_pos(row, col)
+      [(row * (@row_height + 1)) + 2, (col * (@col_width + 1)) + @col_width] # TODO: magic nums are offsets
+    end
+
+    def message_pos
+      [@rows * (@row_height + 1) + 2, 0] # TODO: magic nums are offsets
+    end
+
+    def player_info_pos
+      [1, @cols * (@col_width + 1) + 4] # TODO: magic_nums are offsets
+    end
+
+    def controls_info_pos
+      y, x = player_info_pos
+      return [y + (@rows * (@row_height + 1)) / 2, x] # TODO: magic_nums are offsets
+    end
+
+    # ======================
+    # Drawing helper methods
+    # ======================
+
+    # Execute draw operation in block and reset cursors and refresh afterwards
+    def draw_wrapper(&block)
+      cury, curx = @win.cury, @win.curx
+      
+      yield block if block_given? 
+      
+      @win.setpos(cury, curx)
+      @win.refresh
+    end
+
+    def draw_for_each_cell(&block)
+      draw_wrapper do
+        (0...@rows).each do |row|
+          (0...@cols).each { |col| block.call(row, col)}
+        end
+      end
+    end
+
+    # Write text to position (y, x) of the terminal
+    # Optionally, delete all text to the right or all lines below before writing text
+    def write_str(y, x, text, clear_right = false, clear_below = false)
+      draw_wrapper do
+        @win.setpos(y, x)
+        draw_wrapper { @win.addstr(" " * (@win.maxx - @win.curx)) } if clear_right
+        draw_wrapper { (@win.maxy - @win.cury + 1).times { @win.deleteln } } if clear_below
+        draw_wrapper { @win.addstr(text) }
+      end
+    end
+
+    def clear_terminal
+      @win.clear
+      @win.refresh
+      @win.setpos(0, 0)
+    end
+
+  end
+end
+