rich_engine 0.0.0 → 0.1.0

data/lib/rich_engine/game.rb

@@ -4,8 +4,16 @@ require_relative "canvas"
 require_relative "io"
 
 module RichEngine
-  # Example:
+  # The base class for all games. Subclass it, implement the lifecycle hooks,
+  # and draw to `@canvas` each frame; the game loop, input, rendering, and
+  # frame pacing are handled for you.
   #
+  # The lifecycle hooks are the core public API:
+  # - {#on_create} runs once at start
+  # - {#on_update} runs every frame
+  # - {#on_destroy} runs when the game exits
+  #
+  # @example A minimal game that draws a title and quits on "q"
   #   class MyGame < RichEngine::Game
   #     def on_create
   #       @title = "My Awesome Game"
@@ -19,22 +27,44 @@ module RichEngine
   #   end
   #
   #   MyGame.play
-  #
   class Game
+    # Raised internally to break out of the game loop. Use {#quit!} instead of
+    # raising this directly.
+    #
+    # @api private
     class Exit < StandardError; end
 
-    def initialize(width, height)
+    # @param width [Integer] the screen width in characters
+    # @param height [Integer] the screen height in characters
+    # @param target_fps [Integer, nil] target frames per second; pass nil to
+    #   run uncapped without frame pacing
+    def initialize(width, height, target_fps: 60)
       @width = width
       @height = height
+      @target_fps = target_fps
+      @frame_budget = @target_fps ? 1.0 / @target_fps : nil
       @config = {screen_width: @width, screen_height: @height}
       @io = RichEngine::IO.new(width, height)
       @canvas = RichEngine::Canvas.new(width, height)
     end
 
-    def self.play(width: 50, height: 10)
-      new(width, height).play
+    # Builds a game and runs it. The convenient entry point for starting a
+    # game.
+    #
+    # @param width [Integer] the screen width in characters
+    # @param height [Integer] the screen height in characters
+    # @param target_fps [Integer, nil] target frames per second; pass nil to
+    #   run uncapped without frame pacing
+    # @return [void]
+    def self.play(width: 50, height: 10, target_fps: 60)
+      new(width, height, target_fps: target_fps).play
     end
 
+    # Runs the game: prepares the terminal, calls {#on_create}, then loops
+    # calling {#on_update} and rendering every frame until the game exits,
+    # finally calling {#on_destroy} and restoring the terminal.
+    #
+    # @return [void]
     def play
       prepare_screen
       on_create
@@ -56,23 +86,49 @@ module RichEngine
       restore_screen
     end
 
+    # Lifecycle hook called once before the game loop starts. Override it to
+    # set up initial state (instance variables, timers, canvas slots, etc.).
+    #
+    # @return [void]
     def on_create
     end
 
+    # Lifecycle hook called once per frame. Override it to update game state
+    # and draw to `@canvas`.
+    #
+    # @param _elapsed_time [Float] seconds elapsed since the last frame
+    # @param _key [Symbol, nil] the last key pressed (e.g. :q, :up, :space,
+    #   :esc), or nil if no key was pressed this frame
+    # @return [void]
     def on_update(_elapsed_time, _key)
     end
 
+    # Lifecycle hook called once after the game loop ends. Override it to tear
+    # down state or print a final message.
+    #
+    # @return [void]
     def on_destroy
     end
 
+    # Exits the game loop, triggering {#on_destroy} and terminal restore.
+    #
+    # @return [void]
+    # @raise [Exit] always, to unwind out of the loop
     def quit!
       raise Exit
     end
 
+    # Runs a single frame: reads input, calls {#on_update}, renders, and
+    # sleeps to honor the target FPS.
+    #
+    # @param elapsed_time [Float] seconds elapsed since the last frame
+    # @return [void]
+    # @api private
     def game_loop(elapsed_time)
       key = read_input
       on_update(elapsed_time, key)
       render
+      sleep_if_needed(elapsed_time)
     end
 
     private
@@ -96,6 +152,13 @@ module RichEngine
       @io.write(@canvas.canvas, use_caching: use_caching)
     end
 
+    def sleep_if_needed(elapsed_time)
+      return if @frame_budget.nil?
+
+      sleep_time = @frame_budget - elapsed_time
+      sleep(sleep_time) if sleep_time > 0
+    end
+
     def check_game_exit
       yield
     rescue Exit

data/lib/rich_engine/io.rb

@@ -2,17 +2,33 @@
 
 require "timeout"
 require "io/console"
+require "stringio"
 
 module RichEngine
+  # Internal plumbing that bridges {Game} and the terminal: it flushes the
+  # canvas to $stdout (with render caching) and reads non-blocking keyboard
+  # input, translating escape sequences into key symbols.
+  #
+  # @api private
   class IO
     Signal.trap("INT") { raise Game::Exit }
 
+    # @param width [Integer] the screen width in characters
+    # @param height [Integer] the screen height in characters
     def initialize(width, height)
       @screen_width = width
       @screen_height = height
       delete_cache
     end
 
+    # Renders the canvas to $stdout, skipping the write when the canvas is
+    # unchanged since the last frame.
+    #
+    # @param canvas [Array] the flat array of canvas cells to draw
+    # @param use_caching [Boolean] when false, the render cache is dropped so
+    #   the canvas is always redrawn
+    # @return [Symbol] :cache_hit when the frame was skipped, :cache_miss
+    #   otherwise
     def write(canvas, use_caching:)
       delete_cache unless use_caching
 
@@ -23,23 +39,30 @@ module RichEngine
       end
     end
 
+    # Reads a single keypress without blocking, decoding multi-byte escape
+    # sequences (arrows, page keys, etc.) into key symbols.
+    #
+    # @return [Symbol, nil] the key pressed (e.g. :q, :up, :space, :esc), or
+    #   nil if no input was waiting
     def read_async
-      key = $stdin.read_nonblock(2)
-      _c1, c2 = key.chars
-
-      if c2 && csi?(key)
-        c3, c4 = $stdin.read_nonblock(2).chars
-
-        if digit?(c3)
-          symbolize_key("#{key}#{c3}#{c4}")
+      $stdin.raw do |io|
+        key = $stdin.read_nonblock(2)
+        _c1, c2 = key.chars
+
+        if c2 && csi?(key)
+          c3, c4 = $stdin.read_nonblock(2).chars
+
+          if digit?(c3)
+            symbolize_key("#{key}#{c3}#{c4}")
+          else
+            symbolize_key("#{key}#{c3}")
+          end
         else
-          symbolize_key("#{key}#{c3}")
+          symbolize_key(key)
         end
-      else
-        symbolize_key(key)
+      rescue ::IO::WaitReadable
+        nil
       end
-    rescue ::IO::WaitReadable
-      nil
     end
 
     private
@@ -52,13 +75,13 @@ module RichEngine
       return :cache_hit if canvas == @canvas_cache
 
       yield
-      @canvas_cache = canvas
+      @canvas_cache = canvas.dup # Snapshot by value; the game may mutate the array in place
 
       :cache_miss
     end
 
     def build_output(canvas)
-      output = +""
+      output = StringIO.new
 
       i = 0
       while i < canvas_size
@@ -67,7 +90,7 @@ module RichEngine
         i += @screen_width
       end
 
-      output
+      output.string
     end
 
     def canvas_size

data/lib/rich_engine/matrix.rb

@@ -1,27 +1,60 @@
 # frozen_string_literal: true
 
 module RichEngine
+  # A simple 2D grid utility backed by nested arrays, with convenience methods
+  # for indexing, iterating, mapping, zipping, and filling regions.
+  #
+  # @example
+  #   grid = RichEngine::Matrix.new(width: 10, height: 5, fill_with: 0)
+  #   grid[2, 3] = 1
+  #   grid.fill(x: 0..2, y: 0..1, with: 9)
   class Matrix
     # TODO: implement Enumerable
 
+    # @return [Array<Array>] the backing nested array of rows
     attr_accessor :vec
 
+    # Builds a matrix of the given dimensions, filling every cell with
+    # +fill_with+.
+    #
+    # @param width [Integer] the number of columns
+    # @param height [Integer] the number of rows
+    # @param fill_with [Object] the initial value for every cell
     def initialize(width: 1, height: 1, fill_with: nil)
       @vec = Array.new(width) { Array.new(height) { fill_with } }
     end
 
+    # Reads the value at the given coordinates.
+    #
+    # @param x [Integer] the column index
+    # @param y [Integer] the row index
+    # @return [Object] the value at +(x, y)+
     def [](x, y)
       @vec[x][y]
     end
 
+    # Writes a value at the given coordinates.
+    #
+    # @param x [Integer] the column index
+    # @param y [Integer] the row index
+    # @param value [Object] the value to store
+    # @return [Object] the stored value
     def []=(x, y, value)
       @vec[x][y] = value
     end
 
+    # Whether any cell matches the given block.
+    #
+    # @yield [cell] each cell in the matrix
+    # @return [Boolean] true if the block returns truthy for any cell
     def any?(&block)
       @vec.any? { |row| row.any?(&block) }
     end
 
+    # Iterates over every cell in row-major order.
+    #
+    # @yield [tile] each cell value
+    # @return [void]
     def each
       @vec.each do |row|
         row.each do |tile|
@@ -30,12 +63,21 @@ module RichEngine
       end
     end
 
+    # Maps every cell through the block, returning a nested array of results.
+    #
+    # @yield [value] each cell value
+    # @return [Array<Array>] a nested array of mapped values
     def map(&block)
       @vec.map do |row|
         row.map { |value| block.call(value) }
       end
     end
 
+    # Pairs each cell with the cell at the same coordinates in +other+.
+    #
+    # @param other [Matrix] another matrix of the same dimensions
+    # @return [Matrix] a new matrix whose cells are +[self_value, other_value]+
+    #   pairs
     def zip(other)
       new_matrix = Matrix.new
       new_matrix.vec = @vec.map.with_index do |row, i|
@@ -45,6 +87,11 @@ module RichEngine
       new_matrix
     end
 
+    # Iterates over every cell along with its column and row indexes.
+    #
+    # @yield [tile, i, j] each cell value with its column index +i+ and row
+    #   index +j+
+    # @return [void]
     def each_with_indexes
       @vec.each_with_index do |row, i|
         row.each_with_index do |tile, j|
@@ -53,6 +100,16 @@ module RichEngine
       end
     end
 
+    # Fills a cell or region with a value. +x+ and +y+ may each be a single
+    # index or any object responding to +each+ (e.g. a Range), so regions can
+    # be filled in one call.
+    #
+    # @param x [Integer, #each] the column index or range of columns
+    # @param y [Integer, #each] the row index or range of rows
+    # @param with [Object] the value to write
+    # @return [void]
+    # @example Fill a region
+    #   grid.fill(x: 0..2, y: 0..1, with: 9)
     def fill(x:, y:, with:)
       xs = Iterable(x)
       ys = Iterable(y)