rich_engine 0.0.0 → 0.1.0

data/lib/rich_engine/animation.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module RichEngine
+  # Plays a sequence of string frames (sprites) at a fixed frames-per-second.
+  #
+  # @example
+  #   frames = [
+  #     "A",
+  #     "B"
+  #   ]
+  #   anim = RichEngine::Animation.new(frames: frames, fps: 8, loop: true)
+  #
+  #   # Inside your Game loop:
+  #   anim.update(elapsed_time)
+  #   anim.draw(@canvas, x: 10, y: 2, fg: :yellow)
+  class Animation
+    # @return [Array<String>] the frame sprites, in playback order.
+    # @return [Integer] the index of the frame currently shown.
+    # @return [Integer, Float] the configured frames per second.
+    attr_reader :frames, :frame_index, :fps
+
+    # @return [Symbol, String, Array<Integer>, Integer] default foreground
+    #   color used when drawing.
+    attr_accessor :fg
+
+    # Builds an animation from a sequence of string frames.
+    #
+    # @param frames [Array<String>] each string is a frame; can be multi-line.
+    #   Spaces are transparent.
+    # @param fps [Integer, Float] how many frames per second to advance.
+    # @param loop [Boolean] if true, wrap to the first frame after the last;
+    #   otherwise stop at the last frame.
+    # @param fg [Symbol, String, Array<Integer>, Integer] default foreground
+    #   color when drawing.
+    # @example
+    #   anim = RichEngine::Animation.new(frames: ["A", "B"], fps: 8, loop: true)
+    def initialize(frames:, fps: 12, loop: true, fg: :white)
+      @frames = frames
+      @fps = fps
+      @loop = loop
+      @fg = fg
+      @frame_index = 0
+      @playing = true
+      @stepper = RichEngine::Timer.every(seconds: frame_interval)
+    end
+
+    # Changes playback speed at runtime.
+    #
+    # @param value [Integer, Float] the new frames per second.
+    # @return [Integer, Float] the assigned value.
+    def fps=(value)
+      @fps = value
+      @stepper.interval = frame_interval
+    end
+
+    # @return [Boolean] whether the animation wraps after the last frame.
+    def loop? = @loop
+
+    # @return [Boolean] whether the animation is currently advancing frames.
+    def playing? = @playing
+
+    # Stops playback and rewinds to the first frame.
+    #
+    # @return [void]
+    def stop!
+      @playing = false
+      reset!
+    end
+
+    # Pauses playback on the current frame.
+    #
+    # @return [void]
+    def pause!
+      @playing = false
+    end
+
+    # Resumes playback.
+    #
+    # @return [void]
+    def play!
+      @playing = true
+    end
+
+    # Rewinds to the first frame and restarts the frame timer.
+    #
+    # @return [void]
+    def reset!
+      @frame_index = 0
+      @stepper.interval = frame_interval
+    end
+
+    # @return [String] the frame string currently shown.
+    def current_frame
+      @frames[@frame_index]
+    end
+
+    # Advances the internal timer; call once per frame with the elapsed time.
+    #
+    # @param elapsed_time [Float] seconds since the last frame.
+    # @return [void]
+    def update(elapsed_time)
+      return unless @playing
+      return if @frames.size <= 1
+
+      @stepper.update(elapsed_time)
+      @stepper.when_ready { advance_frame }
+    end
+
+    # Renders the current frame to the canvas.
+    #
+    # @param canvas [RichEngine::Canvas] the canvas to draw on.
+    # @param x [Integer] left column to draw at.
+    # @param y [Integer] top row to draw at.
+    # @param fg [Symbol, String, Array<Integer>, Integer, nil] foreground
+    #   color; falls back to the animation's default when nil.
+    # @return [void]
+    def draw(canvas, x:, y:, fg: nil)
+      canvas.draw_sprite(current_frame, x: x, y: y, fg: fg || @fg)
+    end
+
+    private
+
+    def frame_interval
+      1.0 / @fps.to_f
+    end
+
+    def advance_frame
+      if @loop
+        @frame_index = (@frame_index + 1) % @frames.size
+      elsif @frame_index < @frames.size - 1
+        @frame_index += 1
+      else
+        @playing = false
+      end
+    end
+  end
+end

data/lib/rich_engine/canvas/slot.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module RichEngine
+  class Canvas
+    # A sub-section of a parent Canvas. All drawing operations are translated by
+    # the slot's origin (x, y).
+    class Slot < Canvas
+      # @return [String, nil] the slot's background fill, or nil to inherit the
+      #   parent's
+      attr_reader :bg
+
+      # @param parent [RichEngine::Canvas] the canvas this slot draws onto
+      # @param x [Integer] the slot's left column on the parent canvas
+      # @param y [Integer] the slot's top row on the parent canvas
+      # @param width [Integer] the slot width
+      # @param height [Integer] the slot height
+      # @param bg [String, nil] the slot's background fill, or nil to inherit
+      #   the parent's
+      def initialize(parent, x, y, width, height, bg: nil)
+        @parent = parent
+        @offset_x = x
+        @offset_y = y
+        @width = width
+        @height = height
+        @bg = bg
+      end
+
+      # Read the cell at the slot-local (x, y), translated to parent space.
+      #
+      # @param x [Integer] the slot-local column
+      # @param y [Integer] the slot-local row
+      # @return [String, nil] the cell contents, or nil if out of the slot's
+      #   bounds
+      def [](x, y)
+        return nil if out_of_bounds?(x, y)
+        @parent[@offset_x + x, @offset_y + y]
+      end
+
+      # Write the cell at the slot-local (x, y), translated to parent space.
+      # Writes outside the slot are clipped.
+      #
+      # @param x [Integer] the slot-local column
+      # @param y [Integer] the slot-local row
+      # @param value [String] the cell contents to write
+      # @return [void]
+      def []=(x, y, value)
+        return if out_of_bounds?(x, y)
+        @parent[@offset_x + x, @offset_y + y] = value
+      end
+
+      # Clear the slot, filling it with its background (or the parent's if the
+      # slot has none).
+      #
+      # @return [void]
+      def clear
+        fill_char = @bg || @parent.bg
+        each_coord do |x, y|
+          self[x, y] = fill_char
+        end
+      end
+
+      # Change the slot's background fill character and clear the slot.
+      #
+      # @param bg [String] the new background fill character
+      # @return [void]
+      def bg=(bg)
+        @bg = bg
+        clear
+      end
+    end
+  end
+end

data/lib/rich_engine/canvas.rb

@@ -1,13 +1,23 @@
 # frozen_string_literal: true
 
 require_relative "string_colors"
+require_relative "canvas/slot"
 
 module RichEngine
+  # A 2D character grid that you draw to each frame, with colored text and
+  # shapes. Cells are stored row-major in a flat array.
   class Canvas
     using StringColors
 
-    attr_reader :canvas, :bg
+    # @return [Array<String>] the flat, row-major array of cell contents
+    # @return [String] the background fill character
+    # @return [Integer] the canvas width in characters
+    # @return [Integer] the canvas height in characters
+    attr_reader :canvas, :bg, :width, :height
 
+    # @param width [Integer] the canvas width in characters
+    # @param height [Integer] the canvas height in characters
+    # @param bg [String] the background fill character
     def initialize(width, height, bg: " ")
       @width = width
       @height = height
@@ -15,10 +25,18 @@ module RichEngine
       clear
     end
 
+    # The canvas dimensions as a [width, height] pair.
+    #
+    # @return [Array(Integer, Integer)] the width and height
     def dimensions
       [@width, @height]
     end
 
+    # Yield every (x, y) coordinate in the canvas.
+    #
+    # @yieldparam x [Integer] the column
+    # @yieldparam y [Integer] the row
+    # @return [void]
     def each_coord(&block)
       (0...@width).each do |x|
         (0...@height).each do |y|
@@ -27,27 +45,55 @@ module RichEngine
       end
     end
 
+    # Enumerate the canvas one row at a time.
+    #
+    # @return [Enumerator] an enumerator of rows, each an array of cells
     def rows
       @canvas.each_slice(@width)
     end
 
-    def draw_sprite(sprite, x: 0, y: 0, fg: :white)
+    # Draw a multi-line string as a sprite; spaces are treated as transparent
+    # and left untouched.
+    #
+    # @param sprite [String] the multi-line sprite to draw
+    # @param x [Integer] the left column to start drawing at
+    # @param y [Integer] the top row to start drawing at
+    # @param fg [Symbol, String, Array<Integer>, Integer] the foreground color
+    # @param bg [Symbol, String, Array<Integer>, Integer] the background color
+    # @return [void]
+    def draw_sprite(sprite, x: 0, y: 0, fg: :white, bg: :transparent)
       sprite.split("\n").each.with_index do |line, i|
         line.each_char.with_index do |char, j|
           next if char == " "
 
-          self[x + j, y + i] = char.fg(fg)
+          self[x + j, y + i] = char.fg(fg).bg(bg)
         end
       end
     end
 
+    # Write colored text at a position. Pass :center for x or y to center the
+    # text along that axis. A single color applies to every character; an array
+    # of colors cycles per character.
+    #
+    # @param str [String] the text to write
+    # @param x [Integer, Symbol] the left column, or :center to horizontally
+    #   center the text
+    # @param y [Integer, Symbol] the row, or :center to vertically center the
+    #   text
+    # @param fg [Symbol, String, Array<Integer>, Integer, Array] the foreground
+    #   color, or an array of color specs to cycle per character
+    # @param bg [Symbol, String, Array<Integer>, Integer, Array] the background
+    #   color, or an array of color specs to cycle per character
+    # @return [void]
+    # @example Cycle foreground colors per character
+    #   canvas.write_string("Hello", x: :center, y: 1, fg: [:red, :green, :blue])
     def write_string(str, x: 0, y: 0, fg: :white, bg: :transparent)
       if x == :center
         x = (@width - str.length) / 2
       end
 
       if y == :center
-        y = (@height - str.length) / 2
+        y = (@height - 1) / 2
       end
 
       fg = Array(fg).cycle
@@ -58,6 +104,15 @@ module RichEngine
       end
     end
 
+    # Draw a filled rectangle. Coordinates and sizes are rounded to integers.
+    #
+    # @param x [Integer] the left column
+    # @param y [Integer] the top row
+    # @param width [Integer] the rectangle width
+    # @param height [Integer] the rectangle height
+    # @param char [String] the character to fill with
+    # @param color [Symbol, String, Array<Integer>, Integer] the fill color
+    # @return [void]
     def draw_rect(x:, y:, width:, height:, char: "█", color: :white)
       x = x.round
       y = y.round
@@ -71,6 +126,15 @@ module RichEngine
       end
     end
 
+    # Draw a filled circle centered on (x, y). The center is rounded to
+    # integers.
+    #
+    # @param x [Integer] the center column
+    # @param y [Integer] the center row
+    # @param radius [Integer] the circle radius
+    # @param char [String] the character to fill with
+    # @param color [Symbol, String, Array<Integer>, Integer] the fill color
+    # @return [void]
     def draw_circle(x:, y:, radius:, char: "█", color: :white)
       x = x.round
       y = y.round
@@ -84,6 +148,11 @@ module RichEngine
       end
     end
 
+    # Whether the given coordinate falls outside the canvas.
+    #
+    # @param x [Integer] the column
+    # @param y [Integer] the row
+    # @return [Boolean] true if (x, y) is outside the canvas bounds
     def out_of_bounds?(x, y)
       return true if x < 0
       return true if x >= @width
@@ -93,6 +162,11 @@ module RichEngine
       false
     end
 
+    # Read the cell at (x, y). Coordinates are rounded to integers.
+    #
+    # @param x [Integer] the column
+    # @param y [Integer] the row
+    # @return [String, nil] the cell contents
     def [](x, y)
       x = x.round
       y = y.round
@@ -100,6 +174,13 @@ module RichEngine
       @canvas[at(x, y)]
     end
 
+    # Write a cell at (x, y), ignoring out-of-bounds writes. Coordinates are
+    # rounded to integers.
+    #
+    # @param x [Integer] the column
+    # @param y [Integer] the row
+    # @param value [String] the cell contents to write
+    # @return [void]
     def []=(x, y, value)
       x = x.round
       y = y.round
@@ -108,15 +189,39 @@ module RichEngine
       @canvas[at(x, y)] = value
     end
 
+    # Clear the entire canvas, resetting every cell to the background fill.
+    #
+    # @return [void]
     def clear
       @canvas = create_blank_canvas
     end
 
+    # Change the background fill character and clear the canvas.
+    #
+    # @param bg [String] the new background fill character
+    # @return [void]
     def bg=(bg)
       @bg = bg
       clear
     end
 
+    # Define a logical sub-region of this canvas that translates local
+    # coordinates into the parent canvas space and clips drawing to the region.
+    #
+    # @param x [Integer] the region's left column on the parent canvas
+    # @param y [Integer] the region's top row on the parent canvas
+    # @param width [Integer] the region width
+    # @param height [Integer] the region height
+    # @param bg [String, nil] the slot's background fill, or nil to inherit the
+    #   parent's
+    # @return [RichEngine::Canvas::Slot] the sub-region canvas
+    # @example
+    #   log = canvas.slot(x: 80, y: 0, width: 20, height: 10)
+    #   log.write_string("Hello", x: 1, y: 1)  # => writes at (81, 1)
+    def slot(x:, y:, width:, height:, bg: nil)
+      Slot.new(self, x, y, width, height, bg: bg)
+    end
+
     private
 
     def at(x, y)

data/lib/rich_engine/chance.rb

@@ -1,7 +1,17 @@
 # frozen_string_literal: true
 
 module RichEngine
+  # Random helpers for probability checks.
   module Chance
+    # Returns true with the given probability.
+    #
+    # @param value [Integer, Float] a probability as a fraction (0.2) or as a
+    #   percentage (20); values greater than 1 are treated as percentages.
+    # @param rand_gen [#call] a generator returning a float in [0, 1).
+    # @return [Boolean] whether the chance succeeded.
+    # @example
+    #   RichEngine::Chance.of(0.2) # 20% chance
+    #   RichEngine::Chance.of(20)  # also 20% (percent form)
     def self.of(value, rand_gen: method(:rand))
       percent = if value > 1
         value / 100.0
@@ -12,6 +22,13 @@ module RichEngine
       rand_gen.call < percent
     end
 
+    # Returns true with a one-in-+value+ probability.
+    #
+    # @param value [Integer, Float] the denominator of the odds.
+    # @param rand_gen [#call] a generator returning a float in [0, 1).
+    # @return [Boolean] whether the chance succeeded.
+    # @example
+    #   RichEngine::Chance.of_one_in(10) # 1 in 10 chance
     def self.of_one_in(value, rand_gen: method(:rand))
       of(1 / value.to_f, rand_gen: rand_gen)
     end

data/lib/rich_engine/cooldown.rb

@@ -1,26 +1,45 @@
 # frozen_string_literal: true
 
 module RichEngine
+  # Tracks a fixed delay and reports when it has elapsed.
+  #
+  # @example
+  #   shoot_cd = RichEngine::Cooldown.new(0.25) # seconds
+  #   shoot_cd.update(dt)
+  #   if shoot_cd.ready?
+  #     shoot!
+  #     shoot_cd.reset!
+  #   end
   class Cooldown
+    # @param target_time [Integer, Float] the cooldown duration in seconds.
     def initialize(target_time)
-      @timer = 0
       @target_time = target_time
+      @timer = target_time
     end
 
+    # Counts down by the elapsed time.
+    #
+    # @param dt [Float] seconds since the last frame.
+    # @return [Float] the remaining time.
     def update(dt)
-      @timer += dt
+      @timer -= dt
     end
 
+    # @return [Float] the remaining time in seconds (negative once finished).
     def get
       @timer
     end
 
+    # Restarts the cooldown at its full duration.
+    #
+    # @return [Integer, Float] the reset remaining time.
     def reset!
-      @timer = 0
+      @timer = @target_time
     end
 
+    # @return [Boolean] whether the cooldown has elapsed.
     def finished?
-      @timer >= @target_time
+      @timer <= 0
     end
     alias_method :ready?, :finished?
   end

data/lib/rich_engine/enum/mixin.rb

@@ -1,11 +1,45 @@
 module RichEngine
   class Enum
+    # Adds enum support to a class. Include it, then declare enums with
+    # {ClassMethods#enum} to get a class-level enum accessor and an
+    # instance-level reader that resolves the instance variable into an
+    # {Enum::Value}.
+    #
+    # @example
+    #   class Player
+    #     include RichEngine::Enum::Mixin
+    #     enum :state, {idle: 0, running: 1, paused: 2}
+    #
+    #     def initialize
+    #       @state = :idle
+    #     end
+    #   end
+    #
+    #   Player.states          #=> RichEngine::Enum
+    #   Player.new.state.idle? #=> true
     module Mixin
+      # Extends the including class with {ClassMethods}.
+      #
+      # @param base [Class] the class including this module
+      # @return [void]
       def self.included(base)
         base.extend ClassMethods
       end
 
+      # Class-level methods made available by including {Mixin}.
       module ClassMethods
+        # Declares an enum on the class. Defines a class method returning the
+        # {Enum} (named after +enum_name+) and an instance method (named
+        # +name+) that reads the +@name+ instance variable and returns the
+        # matching {Enum::Value}.
+        #
+        # @param name [Symbol] the name of the enum and instance reader; the
+        #   value is read from the +@name+ instance variable
+        # @param enum_options [Array, Hash] the enum options, as accepted by
+        #   {Enum#initialize}
+        # @param enum_name [String] the name of the class-level enum accessor;
+        #   defaults to the pluralized +name+
+        # @return [void]
         def enum(name, enum_options, enum_name: "#{name}s")
           define_singleton_method(enum_name) do
             Enum.new(name, enum_options)

data/lib/rich_engine/enum/value.rb

@@ -1,10 +1,28 @@
 module RichEngine
   class Enum
+    # A single selected option of an {Enum}. Values are comparable (by their
+    # underlying option value) and expose a query method per option, e.g.
+    # +#idle?+. Only values from the same enum can be compared or are equal.
+    #
+    # @example
+    #   state = RichEngine::Enum.new(:state, {idle: 0, running: 1})
+    #   value = state.running
+    #   value.running? #=> true
+    #   value.value    #=> 1
     class Value
       include Comparable
 
+      # @return [Enum] the enum this value belongs to
+      # @return [Symbol] the selected option
       attr_reader :enum, :selected
 
+      # Builds a value for a selected option and defines a query method per
+      # option (e.g. +#idle?+).
+      #
+      # @param enum [Enum] the enum this value belongs to
+      # @param selected [Symbol] the selected option; must be a valid option of
+      #   +enum+
+      # @raise [ArgumentError] if +selected+ is not an option of +enum+
       def initialize(enum:, selected:)
         @enum = enum
         @selected = selected
@@ -15,16 +33,29 @@ module RichEngine
         freeze
       end
 
+      # The underlying value of the selected option.
+      #
+      # @return [Object] the value mapped to the selected option
       def value
         @enum[@selected]
       end
 
+      # Compares two values from the same enum by their underlying values.
+      #
+      # @param other [Value] another value from the same enum
+      # @return [Integer] -1, 0, or 1
+      # @raise [ArgumentError] if +other+ belongs to a different enum
       def <=>(other)
         raise ArgumentError, "Can't compare values from different enums" if enum != other.enum
 
         value <=> other.value
       end
 
+      # Two values are equal when they come from the same enum and have the
+      # same selected option.
+      #
+      # @param other [Object] the object to compare against
+      # @return [Boolean] whether the values are equal
       def ==(other)
         return @enum == other.enum && selected == other.selected if other.is_a? self.class
 

data/lib/rich_engine/enum.rb

@@ -1,10 +1,29 @@
-require_relative "./enum/value"
-require_relative "./enum/mixin"
+require_relative "enum/value"
+require_relative "enum/mixin"
 
 module RichEngine
+  # An ergonomic, comparable enum with query methods. Options may be given as an
+  # array (auto-indexed from 0) or as a hash mapping each option to its value. A
+  # reader method is defined for every option that returns an {Enum::Value}.
+  #
+  # @example Array of options (auto-indexed)
+  #   colors = RichEngine::Enum.new(:colors, [:red, :green, :blue])
+  #   colors.options #=> {red: 0, green: 1, blue: 2}
+  #   colors.red.value #=> 0
+  #
+  # @example Hash of options with explicit values
+  #   state = RichEngine::Enum.new(:state, {idle: 0, running: 1, paused: 2})
+  #   state.running > state.idle #=> true
   class Enum
+    # @return [Symbol] the name of the enum
+    # @return [Hash] the options as a hash mapping each option to its value
     attr_reader :name, :options
 
+    # Builds an enum and defines a reader method for each option.
+    #
+    # @param name [Symbol] the name of the enum
+    # @param options [Array, Hash] option names; an array is auto-indexed from
+    #   0, a hash maps each option name to its value
     def initialize(name, options)
       @name = name
       @options = if options.respond_to? :each_pair
@@ -22,6 +41,11 @@ module RichEngine
       freeze
     end
 
+    # Looks up the value of an option.
+    #
+    # @param option [Symbol] the option name
+    # @return [Object] the value mapped to that option
+    # @raise [KeyError] if the option is unknown
     def [](option)
       @options.fetch(option)
     end