rich_engine 0.0.0 → 0.1.0

data/lib/rich_engine/string_colors.rb

@@ -1,183 +1,276 @@
 # frozen_string_literal: true
 
 module RichEngine
+  # A refinement that adds color and style methods to String, plus helpers
+  # for resolving color specs.
+  #
+  # Colors are emitted as 256-color (8-bit) escape sequences using only the
+  # theme-independent regions of the palette: the 6x6x6 color cube (16-231)
+  # and the grayscale ramp (232-255). Unlike the classic 16 ANSI colors,
+  # these render the same RGB values in every terminal.
+  #
+  # Anywhere a color is accepted, you can pass:
+  #
+  # - a named color (`Symbol`): `:red`, `:bright_cyan`, ... (see {PALETTE})
+  # - a hex string: `"#ff8800"` (also `"ff8800"` and shorthand `"#f80"`)
+  # - an RGB array: `[255, 136, 0]`
+  # - a raw 256-color index (`Integer`): `208`
+  #
+  # Hex and RGB values snap to the nearest color in the fixed 256-color
+  # palette.
+  #
+  # @example
+  #   using RichEngine::StringColors
+  #
+  #   "hello".fg(:red)            # named color
+  #   "hello".fg("#ff8800").bold  # custom color, chained with a style
+  #   "hello".bg([0, 0, 215])     # RGB background
   module StringColors
-    refine String do
-      def fg(color)
-        send(color)
-      end
-
-      def bg(color)
-        send("on_#{color}")
-      end
-
-      # Colors
-
-      def transparent
-        gsub(/./, " ")
-      end
-
-      def black
-        color(30)
-      end
-
-      def red
-        color(31)
-      end
-
-      def green
-        color(32)
-      end
-
-      def yellow
-        color(33)
-      end
-
-      def blue
-        color(34)
-      end
-
-      def magenta
-        color(35)
-      end
-
-      def cyan
-        color(36)
-      end
-
-      def white
-        color(37)
-      end
-
-      def bright_black
-        color(90)
+    # Named colors mapped to fixed color-cube/grayscale indices.
+    #
+    # @return [Hash{Symbol => Integer}]
+    PALETTE = {
+      black: 16,
+      red: 160,
+      green: 40,
+      yellow: 184,
+      orange: 208,
+      blue: 20,
+      magenta: 164,
+      cyan: 44,
+      white: 231,
+      dark_gray: 238,
+      dark_grey: 238,
+      gray: 244,
+      grey: 244,
+      light_gray: 188,
+      light_grey: 188,
+      bright_red: 196,
+      bright_green: 46,
+      bright_yellow: 226,
+      bright_blue: 21,
+      bright_magenta: 201,
+      bright_cyan: 51
+    }.freeze
+
+    # Channel intensities used by the 6x6x6 color cube.
+    #
+    # @return [Array<Integer>]
+    CUBE_LEVELS = [0, 95, 135, 175, 215, 255].freeze
+
+    # Resolves a color spec into a 256-color index.
+    #
+    # @example
+    #   index_for(:red)          # => 160 (named palette color)
+    #   index_for("#ff8800")     # => 208 (nearest cube color)
+    #   index_for([255, 136, 0]) # => 208 (nearest cube color)
+    #   index_for(208)           # => 208 (used as-is)
+    #
+    # @param color [Symbol, String, Array<Integer>, Integer] a color spec
+    # @return [Integer] an index into the 256-color palette
+    # @raise [ArgumentError] if the spec is not one of the supported types
+    # @raise [KeyError] if a named color is not in {PALETTE}
+    def self.index_for(color)
+      case color
+      when Symbol then PALETTE.fetch(color)
+      when Integer then color
+      when Array then rgb_to_index(*color)
+      when String then rgb_to_index(*hex_to_rgb(color))
+      else
+        raise ArgumentError, "invalid color: #{color.inspect}"
       end
+    end
 
-      def bright_red
-        color(91)
-      end
+    # Returns `:black` or `:white`, whichever has the higher WCAG contrast
+    # ratio against the given color, like CSS's `contrast-color()` function.
+    # Ties go to `:white`.
+    #
+    # @example Readable labels on a dynamic background
+    #   label_color = StringColors.contrast_color(bg_color)
+    #   canvas.write_string("Score", x: 0, y: 0, fg: label_color, bg: bg_color)
+    #
+    # @example
+    #   contrast_color(:yellow)   # => :black
+    #   contrast_color("#0000d7") # => :white
+    #
+    # @param color [Symbol, String, Array<Integer>, Integer] a color spec
+    #   (raw indices 0-15 raise, since their RGB values are theme-dependent)
+    # @return [Symbol] `:black` or `:white`
+    def self.contrast_color(color)
+      luminance = relative_luminance(rgb_for(color))
+      white_contrast = 1.05 / (luminance + 0.05)
+      black_contrast = (luminance + 0.05) / 0.05
+
+      (white_contrast >= black_contrast) ? :white : :black
+    end
 
-      def bright_green
-        color(92)
+    # Resolves a color spec into `[r, g, b]` channel values.
+    #
+    # @api private
+    def self.rgb_for(color)
+      case color
+      when Symbol then index_to_rgb(PALETTE.fetch(color))
+      when Integer then index_to_rgb(color)
+      when Array then color
+      when String then hex_to_rgb(color)
+      else
+        raise ArgumentError, "invalid color: #{color.inspect}"
       end
+    end
 
-      def bright_yellow
-        color(93)
+    # Converts a 256-color index (16-255) back into `[r, g, b]` values.
+    #
+    # @api private
+    def self.index_to_rgb(index)
+      if index.between?(16, 231)
+        cube = index - 16
+        [cube / 36, (cube % 36) / 6, cube % 6].map { |level| CUBE_LEVELS[level] }
+      elsif index.between?(232, 255)
+        level = 8 + (10 * (index - 232))
+        [level, level, level]
+      else
+        raise ArgumentError, "color index #{index} is theme-dependent; use 16-255"
       end
+    end
 
-      def bright_blue
-        color(94)
+    # WCAG 2 relative luminance of an sRGB color, from 0.0 (black) to 1.0
+    # (white). See https://www.w3.org/TR/WCAG20/#relativeluminancedef
+    #
+    # @api private
+    def self.relative_luminance(rgb)
+      r, g, b = rgb.map do |channel|
+        value = channel / 255.0
+        (value <= 0.04045) ? value / 12.92 : ((value + 0.055) / 1.055)**2.4
       end
 
-      def bright_magenta
-        color(95)
-      end
+      (0.2126 * r) + (0.7152 * g) + (0.0722 * b)
+    end
 
-      def bright_cyan
-        color(96)
-      end
+    # Parses `"#rrggbb"`, `"rrggbb"`, or `"#rgb"` into `[r, g, b]` values.
+    #
+    # @api private
+    def self.hex_to_rgb(hex)
+      digits = hex.delete_prefix("#")
+      digits = digits.each_char.map { |c| c * 2 }.join if digits.length == 3
+      digits.scan(/../).map { |pair| pair.to_i(16) }
+    end
 
-      def bright_white
-        color(97)
+    # Snaps `[r, g, b]` values to the nearest cube/grayscale index.
+    #
+    # @api private
+    def self.rgb_to_index(red, green, blue)
+      if red == green && green == blue
+        gray_index(red)
+      else
+        r, g, b = [red, green, blue].map { |channel| nearest_cube_level(channel) }
+        16 + (36 * r) + (6 * g) + b
       end
+    end
 
-      # Background colors
+    # Index of the cube level (0-5) closest to the given channel value.
+    #
+    # @api private
+    def self.nearest_cube_level(channel)
+      CUBE_LEVELS.each_index.min_by { |i| (CUBE_LEVELS[i] - channel).abs }
+    end
 
-      def on_black
-        color(40)
-      end
+    # The grayscale ramp (232-255) covers intensities 8, 18, ... 238. Levels
+    # near the extremes snap to the cube's black (16) and white (231).
+    #
+    # @api private
+    def self.gray_index(level)
+      return 16 if level < 4
+      return 231 if level > 243
 
-      def on_red
-        color(41)
-      end
+      232 + ((level - 8) / 10.0).round.clamp(0, 23)
+    end
 
-      def on_green
-        color(42)
-      end
+    refine String do
+      # Colors the string's foreground.
+      #
+      # @example
+      #   "hello".fg(:red)
+      #   "hello".fg("#ff8800")
+      #
+      # @param color [Symbol, String, Array<Integer>, Integer] a color spec
+      #   (see {StringColors}); `:transparent` replaces the text with spaces
+      # @return [String] the string wrapped in escape sequences
+      def fg(color)
+        return transparent if color == :transparent
 
-      def on_yellow
-        color(43)
+        "\e[38;5;#{StringColors.index_for(color)}m#{self}\e[39m"
       end
 
-      def on_blue
-        color(44)
-      end
+      # Colors the string's background.
+      #
+      # @example
+      #   "hello".bg(:cyan)
+      #   "hello".bg("#222222")
+      #
+      # @param color [Symbol, String, Array<Integer>, Integer] a color spec
+      #   (see {StringColors}); `:transparent` keeps the terminal's default
+      #   background
+      # @return [String] the string wrapped in escape sequences
+      def bg(color)
+        return on_transparent if color == :transparent
 
-      def on_magenta
-        color(45)
+        "\e[48;5;#{StringColors.index_for(color)}m#{self}\e[49m"
       end
 
-      def on_cyan
-        color(46)
-      end
+      # Colors
 
-      def on_gray
-        color(47)
+      # Replaces every character with a space.
+      #
+      # @return [String]
+      def transparent
+        gsub(/./, " ")
       end
 
+      # Renders the string on the terminal's default background.
+      #
+      # @return [String]
       def on_transparent
-        color(49)
+        "\e[49m#{self}\e[49m"
       end
 
-      def on_bright_black
-        color(100)
-      end
-
-      def on_bright_red
-        color(101)
-      end
-
-      def on_bright_green
-        color(102)
-      end
-
-      def on_bright_yellow
-        color(103)
-      end
-
-      def on_bright_blue
-        color(104)
-      end
-
-      def on_bright_magenta
-        color(105)
-      end
-
-      def on_bright_cyan
-        color(106)
-      end
-
-      def on_bright_white
-        color(107)
+      # @!macro [attach] palette_color
+      #   @!method $1
+      #     Colors the foreground `$1` (equivalent to `fg(:$1)`).
+      #     @return [String]
+      #   @!method on_$1
+      #     Colors the background `$1` (equivalent to `bg(:$1)`).
+      #     @return [String]
+      PALETTE.each_key do |name|
+        define_method(name) { fg(name) }
+        define_method("on_#{name}") { bg(name) }
       end
 
       # STYLES
 
+      # @return [String] the string styled bold
       def bold
         "\e[1m#{self}\e[22m"
       end
 
+      # @return [String] the string styled italic
       def italic
         "\e[3m#{self}\e[23m"
       end
 
+      # @return [String] the string underlined
       def underline
         "\e[4m#{self}\e[24m"
       end
 
+      # @return [String] the string styled blinking
       def blink
         "\e[5m#{self}\e[25m"
       end
 
+      # @return [String] the string with foreground and background swapped
       def reverse_color
         "\e[7m#{self}\e[27m"
       end
-
-      private
-
-      def color(n)
-        "\e[#{n}m#{self}\e[0m"
-      end
     end
   end
 end

data/lib/rich_engine/terminal/cursor.rb

@@ -2,17 +2,32 @@
 
 module RichEngine
   module Terminal
+    # Internal plumbing for controlling the terminal cursor: visibility and
+    # positioning.
+    #
+    # @api private
     module Cursor
       extend self
 
+      # Hides the cursor.
+      #
+      # @return [void]
       def hide
         system("tput civis")
       end
 
+      # Shows the cursor.
+      #
+      # @return [void]
       def display
         system("tput cnorm")
       end
 
+      # Moves the cursor to the given screen position.
+      #
+      # @param x [Integer] the column to move to
+      # @param y [Integer] the row to move to
+      # @return [void]
       def goto(x, y)
         $stdout.goto(x, y)
       end

data/lib/rich_engine/terminal.rb

@@ -3,25 +3,44 @@
 require_relative "terminal/cursor"
 
 module RichEngine
+  # Internal plumbing used by {Game} to prepare and restore the terminal:
+  # clearing the screen, toggling cursor visibility, and toggling input echo.
+  #
+  # @api private
   module Terminal
     module_function
 
+    # Clears the screen.
+    #
+    # @return [void]
     def clear
       $stdout.clear_screen
     end
 
+    # Hides the terminal cursor.
+    #
+    # @return [void]
     def hide_cursor
       Cursor.hide
     end
 
+    # Shows the terminal cursor.
+    #
+    # @return [void]
     def display_cursor
       Cursor.display
     end
 
+    # Stops typed characters from being echoed to the screen.
+    #
+    # @return [void]
     def disable_echo
       $stdin.echo = false
     end
 
+    # Resumes echoing typed characters to the screen.
+    #
+    # @return [void]
     def enable_echo
       $stdin.echo = true
     end

data/lib/rich_engine/timer/every.rb

@@ -2,13 +2,20 @@
 
 module RichEngine
   class Timer
+    # A scheduler that fires at a fixed interval, created via {Timer.every}.
     class Every
+      # @param interval [Integer, Float] seconds between firings.
       def initialize(interval)
         @interval = interval
         @ready = false
         @timer = Timer.new
       end
 
+      # Accumulates elapsed time and marks the scheduler ready once the
+      # interval is reached.
+      #
+      # @param elapsed_time [Float] seconds since the last frame.
+      # @return [void]
       def update(elapsed_time)
         @timer.update(elapsed_time)
 
@@ -17,6 +24,10 @@ module RichEngine
         end
       end
 
+      # Runs the block and resets the timer when the interval has elapsed.
+      #
+      # @yield called once each time the interval is reached.
+      # @return [void]
       def when_ready(&block)
         if @ready
           block.call
@@ -24,6 +35,10 @@ module RichEngine
         end
       end
 
+      # Changes the firing interval and resets the timer.
+      #
+      # @param interval [Integer, Float] the new interval in seconds.
+      # @return [void]
       def interval=(interval)
         @interval = interval
         reset!

data/lib/rich_engine/timer.rb

@@ -1,7 +1,16 @@
 # frozen_string_literal: true
 
 module RichEngine
+  # Accumulates elapsed time; drive it by calling {#update} each frame.
   class Timer
+    # Returns a small scheduler that fires a block at a fixed interval.
+    #
+    # @param seconds [Integer, Float] the interval between firings.
+    # @return [RichEngine::Timer::Every] the interval scheduler.
+    # @example
+    #   spawn = RichEngine::Timer.every(seconds: 0.5)
+    #   spawn.update(dt)
+    #   spawn.when_ready { spawn_enemy! }
     def self.every(seconds: 1, &block)
       Every.new(seconds)
     end
@@ -10,14 +19,22 @@ module RichEngine
       @timer = 0
     end
 
+    # Adds the elapsed time to the accumulated total.
+    #
+    # @param dt [Float] seconds since the last frame.
+    # @return [Float] the new accumulated time.
     def update(dt)
       @timer += dt
     end
 
+    # @return [Float] the accumulated time in seconds.
     def get
       @timer
     end
 
+    # Resets the accumulated time back to zero.
+    #
+    # @return [Integer] zero.
     def reset!
       @timer = 0
     end

data/lib/rich_engine/ui/textures.rb

@@ -1,44 +1,76 @@
 module RichEngine
+  # Reusable UI building blocks for games.
   module UI
+    # Convenience glyphs for shading and blocky fills.
     module Textures
       extend self
 
+      # The empty glyph (space).
+      #
+      # @return [String] " "
       def empty
         " "
       end
 
+      # The solid block glyph.
+      #
+      # @return [String] "█"
       def solid
         "█"
       end
 
+      # The light shade glyph.
+      #
+      # @return [String] "▓"
       def light_shade
         "▓"
       end
 
+      # The medium shade glyph.
+      #
+      # @return [String] "▒"
       def medium_shade
         "▒"
       end
 
+      # The dark shade glyph.
+      #
+      # @return [String] "░"
       def dark_shade
         "░"
       end
 
+      # The upper half block glyph.
+      #
+      # @return [String] "▀"
       def top_half
         "▀"
       end
 
+      # The lower half block glyph.
+      #
+      # @return [String] "▄"
       def bottom_half
         "▄"
       end
 
+      # The left half block glyph.
+      #
+      # @return [String] "▌"
       def left_half
         "▌"
       end
 
+      # The right half block glyph.
+      #
+      # @return [String] "▐"
       def right_half
         "▐"
       end
 
+      # The plaid (half-shade diagonal) glyph.
+      #
+      # @return [String] "▞"
       def plaid
         "▞"
       end

data/lib/rich_engine/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module RichEngine
-  VERSION = "0.0.0"
+  # The current gem version.
+  VERSION = "0.1.0"
 end

data/lib/rich_engine.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "rich_engine/animation"
 require_relative "rich_engine/canvas"
 require_relative "rich_engine/chance"
 require_relative "rich_engine/cooldown"
@@ -13,5 +14,12 @@ require_relative "rich_engine/timer/every"
 require_relative "rich_engine/ui/textures"
 require_relative "rich_engine/version"
 
+# A tiny terminal game engine for Ruby. It provides a simple game loop, a 2D
+# character canvas with colors, non-blocking keyboard input, and a handful of
+# helpers (timers, cooldowns, RNG, enums, matrices) so you can ship playful
+# ASCII games quickly.
+#
+# At its core, you subclass {RichEngine::Game}, implement a few lifecycle hooks,
+# and draw to a {RichEngine::Canvas} each frame.
 module RichEngine
 end

data/mise.toml

@@ -1,2 +1,2 @@
 [tools]
-ruby = "3.4.6"
+ruby = "3.2"

data/rich_engine.gemspec

@@ -11,7 +11,7 @@ Gem::Specification.new do |spec|
   spec.summary = "A Ruby engine for terminal games."
   spec.homepage = "https://github.com/MatheusRich/rich_engine"
   spec.license = "MIT"
-  spec.required_ruby_version = Gem::Requirement.new(">= 2.3.0")
+  spec.required_ruby_version = Gem::Requirement.new(">= 3.2.0")
 
   spec.metadata["homepage_uri"] = spec.homepage
   # spec.metadata["source_code_uri"] = "TODO: Put your gem's public repo URL here."