rich_engine 0.0.0 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 37c9f68ab1fdc4951d70810a301758262203c270d81855259c04920194f44e21
-  data.tar.gz: f2848e8b2cfb1e99437aa99d4622f16e077b68e8866815192731b2f74160d9d2
+  metadata.gz: 78e2cb0aa9a46a3a771739f12c82d372744b2425cf423bcf647807056bb26758
+  data.tar.gz: 1f0a91b2f173c9115e6573c76ea706e4bd644d56232e21da7360dab33d3b1e6f
 SHA512:
-  metadata.gz: '01282dcff859e81e0cd7ac4ad4b266e450d317826e521f63603481d2c51a62ea4227582297db1abe26e1bfd05c8172e11f94706656a05e25552eb26009b4dad0'
-  data.tar.gz: 929a78668eff88fce37a81e2df06d310dd305b54000175423e0f032195c074cc1d64372cefde49ab3a8e79090d5c41ab6e84408d8c446ba789ce4ad213e7b70f
+  metadata.gz: 4343141533689b538f7ea5fc87a2a281fc09915d260b6ef5f193b67dfa2d6f9f459ec4f22123a17d857212be9191e49fd926cc8a7248d3aa4fdb0f4e97638385
+  data.tar.gz: d198b768cd889f969ae6f27f47da48b3b2ec1990ef340e546e70dce6b2ecf98654e90b43567491799a21a8dfb7b184622656fa9ee2d109c867fdc276099a5ad5

data/.github/workflows/tests-and-linter.yml

@@ -11,18 +11,19 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        ruby: [2.6, 2.7, '3.0']
+        ruby: ['3.2', '3.3', '3.4']
 
     steps:
-      - uses: actions/checkout@v2
-      - name: Set up Ruby ${{ matrix.ruby }}
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - name: Set up Ruby
         uses: ruby/setup-ruby@v1
         with:
           ruby-version: ${{ matrix.ruby }}
-      - name: Build and test with Rake
-        run: |
-          gem install bundler
-          bundle install --jobs 4 --retry 3
-          bundle exec rake
+          bundler-cache: true
+      - name: Run tests
+        run: bundle exec rake
       - name: Linter
         run: bundle exec standardrb
+        continue-on-error: true

data/.gitignore

@@ -1 +1,7 @@
-coverage/
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/tmp/

data/.yardopts

@@ -0,0 +1,6 @@
+--markup markdown
+--no-private
+lib/**/*.rb
+-
+README.md
+LICENSE.txt

data/Gemfile

@@ -7,6 +7,7 @@ gemspec
 group :development do
   gem "standardrb"
   gem "solargraph"
+  gem "yard", require: false
 end
 
 group :test do

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    rich_engine (0.1.0)
+    rich_engine (0.0.0)
 
 GEM
   remote: https://rubygems.org/
@@ -22,7 +22,8 @@ GEM
     ffi (1.17.2-x86_64-darwin)
     ffi (1.17.2-x86_64-linux-gnu)
     ffi (1.17.2-x86_64-linux-musl)
-    formatador (1.1.0)
+    formatador (1.2.1)
+      reline
     guard (2.19.1)
       formatador (>= 0.2.4)
       listen (>= 2.7, < 4.0)
@@ -38,8 +39,9 @@ GEM
     guard-minitest (2.4.6)
       guard-compat (~> 1.2)
       minitest (>= 3.0)
+    io-console (0.8.1)
     jaro_winkler (1.6.1)
-    json (2.12.2)
+    json (2.15.1)
     kramdown (2.5.1)
       rexml (>= 3.3.9)
     kramdown-parser-gfm (1.1.0)
@@ -50,9 +52,9 @@ GEM
       rb-fsevent (~> 0.10, >= 0.10.3)
       rb-inotify (~> 0.9, >= 0.9.10)
     logger (1.7.0)
-    lumberjack (1.2.10)
+    lumberjack (1.4.2)
     method_source (1.1.0)
-    minitest (5.25.5)
+    minitest (5.26.0)
     minitest-focus (1.4.0)
       minitest (>= 4, < 6)
     minitest-reporters (1.7.1)
@@ -61,32 +63,32 @@ GEM
       minitest (>= 5.0)
       ruby-progressbar
     nenv (0.3.0)
-    nokogiri (1.18.8-aarch64-linux-gnu)
+    nokogiri (1.18.10-aarch64-linux-gnu)
       racc (~> 1.4)
-    nokogiri (1.18.8-aarch64-linux-musl)
+    nokogiri (1.18.10-aarch64-linux-musl)
       racc (~> 1.4)
-    nokogiri (1.18.8-arm-linux-gnu)
+    nokogiri (1.18.10-arm-linux-gnu)
       racc (~> 1.4)
-    nokogiri (1.18.8-arm-linux-musl)
+    nokogiri (1.18.10-arm-linux-musl)
       racc (~> 1.4)
-    nokogiri (1.18.8-arm64-darwin)
+    nokogiri (1.18.10-arm64-darwin)
       racc (~> 1.4)
-    nokogiri (1.18.8-x86_64-darwin)
+    nokogiri (1.18.10-x86_64-darwin)
       racc (~> 1.4)
-    nokogiri (1.18.8-x86_64-linux-gnu)
+    nokogiri (1.18.10-x86_64-linux-gnu)
       racc (~> 1.4)
-    nokogiri (1.18.8-x86_64-linux-musl)
+    nokogiri (1.18.10-x86_64-linux-musl)
       racc (~> 1.4)
     notiffany (0.1.3)
       nenv (~> 0.1)
       shellany (~> 0.0)
     observer (0.1.2)
-    ostruct (0.6.1)
+    ostruct (0.6.3)
     parallel (1.27.0)
-    parser (3.3.8.0)
+    parser (3.3.9.0)
       ast (~> 2.4.1)
       racc
-    prism (1.4.0)
+    prism (1.6.0)
     pry (0.15.2)
       coderay (~> 1.1)
       method_source (~> 1.0)
@@ -96,13 +98,15 @@ GEM
     rb-fsevent (0.11.2)
     rb-inotify (0.11.1)
       ffi (~> 1.0)
-    rbs (3.9.4)
+    rbs (3.9.5)
       logger
-    regexp_parser (2.10.0)
+    regexp_parser (2.11.3)
+    reline (0.6.2)
+      io-console (~> 0.5)
     reverse_markdown (3.0.0)
       nokogiri
-    rexml (3.4.1)
-    rubocop (1.75.8)
+    rexml (3.4.4)
+    rubocop (1.80.2)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
@@ -110,10 +114,10 @@ GEM
       parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 2.9.3, < 3.0)
-      rubocop-ast (>= 1.44.0, < 2.0)
+      rubocop-ast (>= 1.46.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 4.0)
-    rubocop-ast (1.44.1)
+    rubocop-ast (1.47.1)
       parser (>= 3.3.7.2)
       prism (~> 1.4)
     rubocop-performance (1.25.0)
@@ -126,9 +130,9 @@ GEM
       docile (~> 1.1)
       simplecov-html (~> 0.11)
       simplecov_json_formatter (~> 0.1)
-    simplecov-html (0.13.1)
+    simplecov-html (0.13.2)
     simplecov_json_formatter (0.1.4)
-    solargraph (0.54.5)
+    solargraph (0.57.0)
       backport (~> 1.2)
       benchmark (~> 0.4)
       bundler (~> 2.0)
@@ -140,17 +144,19 @@ GEM
       observer (~> 0.1)
       ostruct (~> 0.6)
       parser (~> 3.0)
-      rbs (~> 3.3)
+      prism (~> 1.4)
+      rbs (>= 3.6.1, <= 4.0.0.dev.4)
       reverse_markdown (~> 3.0)
-      rubocop (~> 1.38)
+      rubocop (~> 1.76)
       thor (~> 1.0)
       tilt (~> 2.0)
       yard (~> 0.9, >= 0.9.24)
+      yard-activesupport-concern (~> 0.0)
       yard-solargraph (~> 0.1)
-    standard (1.50.0)
+    standard (1.51.1)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.0)
-      rubocop (~> 1.75.5)
+      rubocop (~> 1.80.2)
       standard-custom (~> 1.0.0)
       standard-performance (~> 1.8)
     standard-custom (1.0.2)
@@ -161,12 +167,14 @@ GEM
       rubocop-performance (~> 1.25.0)
     standardrb (1.0.1)
       standard
-    thor (1.3.2)
-    tilt (2.6.0)
-    unicode-display_width (3.1.4)
-      unicode-emoji (~> 4.0, >= 4.0.4)
-    unicode-emoji (4.0.4)
+    thor (1.4.0)
+    tilt (2.6.1)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.1.0)
     yard (0.9.37)
+    yard-activesupport-concern (0.0.1)
+      yard (>= 0.8)
     yard-solargraph (0.1.0)
       yard (~> 0.9)
 
@@ -191,6 +199,7 @@ DEPENDENCIES
   simplecov
   solargraph
   standardrb
+  yard
 
 BUNDLED WITH
    2.6.8

data/README.md

@@ -1,40 +1,341 @@
 # RichEngine
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/rich_engine`. To experiment with that code, run `bin/console` for an interactive prompt.
+RichEngine is a tiny terminal game engine for Ruby. It gives you 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.
 
-TODO: Delete this and the text above, and describe your gem
+At its core, you subclass `RichEngine::Game`, implement a few lifecycle hooks,
+and draw to a `Canvas` each frame.
 
-## Installation
+This README is a tour. For method-by-method reference, see the
+[API docs](https://rubydoc.info/gems/rich_engine) (or run
+`bundle exec yard server` locally).
 
-Add this line to your application's Gemfile:
+## Quick start: build a simple game
+
+Below is a minimal, complete example showing how to:
+- create a game by subclassing `RichEngine::Game`
+- quit on a key press
+- draw text and shapes to the screen
+- use canvas slots to keep a bottom HUD separate from the playfield
+
+```ruby
+require "rich_engine"
+
+class MyGame < RichEngine::Game
+  using RichEngine::StringColors
+
+  TITLE = "Catch the Star"
+  PLAYER_CHAR = "@"
+  PLAYER_COLOR = :yellow
+  ITEM_COLORS = [:green, :magenta, :cyan]
+  ITEM_CHAR = "*"
+  HUD_HEIGHT = 3
+
+  def on_create
+    @score = 0
+    @player_x = 2
+    @player_y = field_height / 2
+    @timer = RichEngine::Cooldown.new(5.0)
+    @field = @canvas.slot(x: 0, y: 0, width: @width, height: field_height, bg: RichEngine::UI::Textures.solid.white)
+    @hud   = @canvas.slot(x: 0, y: field_height, width: @width, height: HUD_HEIGHT)
+    spawn_item
+  end
+
+  # elapsed_time: seconds since last frame (Float)
+  # key: last key pressed (Symbol) or nil
+  def on_update(elapsed_time, key)
+    quit! if key == :q || key == :esc
+
+    # Move player with arrow keys
+    case key
+    when :left  then @player_x -= 1
+    when :right then @player_x += 1
+    when :up    then @player_y -= 1
+    when :down  then @player_y += 1
+    end
+
+    # Keep player inside the game field (above the HUD)
+    @player_x = @player_x.clamp(0, @width - 1)
+    @player_y = @player_y.clamp(0, field_height - 1)
+
+    # Game over if time runs out
+    @timer.update(elapsed_time)
+    if @timer.finished?
+      @game_over = true
+      quit!
+    end
+
+    # Pick up item
+    if @player_x == @item_x && @player_y == @item_y
+      @score += 1
+      spawn_item
+      @timer.reset!
+    end
+
+    # rendering the frame
+    @canvas.clear
+
+    @field.write_string(ITEM_CHAR, x: @item_x, y: @item_y, fg: @item_color)
+    @field.write_string(PLAYER_CHAR, x: @player_x, y: @player_y, fg: PLAYER_COLOR)
+
+    @hud.write_string(TITLE, x: 0, y: 0, fg: :bright_cyan)
+    @hud.write_string("Score: #{@score}", x: 0, y: 1, fg: :bright_yellow)
+    @hud.write_string("Time: #{format('%.1f', @timer.get)}s", x: 0, y: 2, fg: :bright_green)
+  end
+
+  def on_destroy
+    puts(@game_over ? "Game over! Final score: #{@score}" : "Thanks for playing! Score: #{@score}")
+  end
+
+  private
+
+  def field_height
+    @height - HUD_HEIGHT
+  end
+
+  def spawn_item
+    @item_x = rand(@width)
+    @item_y = rand(field_height)
+    @item_color = ITEM_COLORS.sample
+  end
+end
+
+MyGame.play(width: 50, height: 12)
+```
+
+Notes
+- Hooks:
+  - `on_create` runs once at start
+  - `on_update(elapsed_time, key)` runs every frame
+  - `on_destroy` runs when the game exits.
+- Keys: letters are symbols (e.g., `:q`), plus arrows (`:up`, `:down`, `:left`, `:right`), `:space`, `:enter`, `:esc`, `:pg_up`, `:pg_down`, `:home`, `:end`.
+- Drawing: all drawing happens on `@canvas`, via `write_string`, `draw_rect`,
+  `draw_circle`, and `draw_sprite`. Call `@canvas.clear` each frame if you want
+  to redraw from scratch.
+- Rendering and frame pacing are handled for you:
+  - `Game` flushes the canvas after each frame
+  - `Game` auto-sleeps to hit your target FPS (60 by default, but configurable via `target_fps:` on `Game.play`)
+
+## Canvas slots (sub-canvases)
+
+Slots are sub-regions of a canvas that translate local coordinates and clip drawing automatically. Great for HUDs and side panels.
+
+```ruby
+canvas = RichEngine::Canvas.new(100, 40)
+hud = canvas.slot(x: 0, y: 35, width: 100, height: 5, bg: " ")
+hud.clear
+hud.write_string("Score: 10", x: 2, y: 1, fg: :bright_yellow)
+
+log = canvas.slot(x: 80, y: 0, width: 20, height: 35)
+log.write_string("Hello", x: 1, y: 1)  # writes to (81, 1) on the parent canvas
+```
+
+## Colors
+
+Colors are emitted as 256-color escape sequences using only the theme-independent
+regions of the palette, so they look the same in every terminal regardless of the
+user's color scheme. Anywhere a color is accepted (`fg:`, `bg:`, `color:`), you
+can pass:
+
+- a named color: `:red`, `:bright_cyan`, etc. (see `RichEngine::StringColors::PALETTE`)
+- a hex string: `"#ff8800"` (also `"ff8800"` and shorthand `"#f80"`)
+- an RGB array: `[255, 136, 0]`
+- a raw 256-color index: `208`
+
+Hex and RGB values snap to the nearest color in the fixed 256-color palette.
+Note: `write_string` treats arrays as per-character color cycles, so use hex
+strings for custom colors there.
+
+`RichEngine::StringColors.contrast_color(color)` returns `:black` or `:white`,
+whichever reads better on top of the given color (like CSS's `contrast-color()`
+function). Handy for labels on dynamic backgrounds.
+
+To color strings directly (outside of canvas methods), add
+`using RichEngine::StringColors` to your class and chain away:
+`"hello".fg(:red).bg("#222222").bold`.
+
+## Animations
+
+`RichEngine::Animation` plays a sequence of string frames (sprites) at a fixed
+frames-per-second. Each frame is a multi-line string; spaces are treated as
+transparency by `Canvas#draw_sprite`.
+
+```ruby
+# frozen_string_literal: true
+
+require "rich_engine"
+
+class AnimationExample < RichEngine::Game
+  def on_create
+    sprites = ["(•‿•)", "(•‿-)", "(-‿-)", "(-‿•)"]
+
+    @animation = RichEngine::Animation.new(
+      frames: sprites,
+      fps: 4,
+      loop: true,
+      fg: :bright_yellow
+    )
+  end
+
+  def on_update(elapsed_time, key)
+    quit! if key == :q
+
+    @animation.update(elapsed_time)
+
+    @canvas.clear
+    @animation.draw(@canvas, x: 0, y: 0)
+    @canvas.write_string("q: quit", x: 0, y: @config[:screen_height] - 1, fg: :black)
+  end
+end
+
+AnimationExample.play(width: 10, height: 3, target_fps: 30)
+```
+
+Playback is controlled with `play!`, `pause!`, `stop!`, `reset!`, and `fps=`.
+
+## Helpers you can use
+
+All helpers live under `RichEngine::...` and are independent utilities you can
+use inside your game code.
+
+### Timer
+
+Accumulates elapsed time; you drive it by calling `update(dt)` with the
+`elapsed_time` from `on_update`. `Timer.every(seconds:)` returns a small
+scheduler that fires a block at a fixed interval.
+
+```ruby
+tick = RichEngine::Timer.new
+
+def on_update(dt, _key)
+  tick.update(dt)
+  if tick.get > 2
+    # do something every ~2 seconds
+    tick.reset!
+  end
+end
+
+# Fixed interval
+spawn = RichEngine::Timer.every(seconds: 0.5)
+def on_update(dt, _key)
+  spawn.update(dt)
+  spawn.when_ready { spawn_enemy! }
+end
+```
+
+### Cooldown
+
+Track a fixed delay and check if it’s ready.
 
 ```ruby
-gem 'rich_engine'
+shoot_cd = RichEngine::Cooldown.new(0.25) # seconds
+
+def on_update(dt, key)
+  shoot_cd.update(dt)
+  if key == :space && shoot_cd.ready?
+    shoot!
+    shoot_cd.reset!
+  end
+end
 ```
 
-And then execute:
+### Chance (random helpers)
 
-    $ bundle install
+```ruby
+RichEngine::Chance.of(0.2)   # 20% chance
+RichEngine::Chance.of(20)    # also 20% (percent form)
+RichEngine::Chance.of_one_in(10) # 1 in 10 chance
+```
 
-Or install it yourself as:
+### Enum and Enum::Mixin
 
-    $ gem install rich_engine
+Create ergonomic, comparable enums with query methods.
 
-## Usage
+```ruby
+# Standalone enum
+STATE = RichEngine::Enum.new(:state, {idle: 0, running: 1, paused: 2})
+STATE.idle.value        #=> 0
+STATE.running > STATE.idle #=> true
+
+# In a class via Mixin
+class Player
+  include RichEngine::Enum::Mixin
+  enum :state, {idle: 0, running: 1, paused: 2}
 
-TODO: Write usage instructions here
+  def initialize
+    @state = :idle
+  end
 
-## Development
+  def update
+    if state.running?
+      # ...
+    end
+  end
+end
+```
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+### Matrix (2D grid)
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+A simple 2D matrix utility with convenience methods.
+
+```ruby
+grid = RichEngine::Matrix.new(width: 10, height: 5, fill_with: 0)
+grid[2, 3] = 1
 
-## Contributing
+grid.each { |cell| puts cell }
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/rich_engine.
+# Fill regions
+grid.fill(x: 0..2, y: 0..1, with: 9)
 
+# Zip two matrices into pairs
+other = RichEngine::Matrix.new(width: 10, height: 5, fill_with: :a)
+pairs = grid.zip(other) # => matrix of [left, right]
+```
+
+### UI::Textures
+
+Convenience glyphs for shading and blocky fills: `solid` (█), the shades
+(▓ ▒ ░), half blocks, and friends.
+
+```ruby
+@canvas.draw_rect(x: 10, y: 6, width: 8, height: 2, char: RichEngine::UI::Textures.solid, color: :magenta)
+```
+
+## Examples
+
+See the `examples/` folder for more complete samples:
+- `timer.rb` — using timers and intervals
+- `noise.rb` — colorful random output
+- `background.rb` — background fill and drawing
+- `grains_of_sand.rb` — simple cellular-like simulation
+- `command_line_fps.rb` — a raycasting FPS with a radar and target practice
+
+## Install and run locally (optional)
+
+Add to a Gemfile, then bundle:
+
+```ruby
+gem "rich_engine"
+```
+
+```sh
+bundle install
+```
+
+Or install directly:
+
+```sh
+gem install rich_engine
+```
+
+Then run one of the examples:
+
+```sh
+ruby examples/timer.rb
+```
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+MIT

data/examples/background.rb

@@ -73,7 +73,7 @@ class Cloud
   def initialize(x: -rand(5..300))
     @x = x
     @y = rand(0..4)
-    @color = [:white, :bright_white].sample
+    @color = [:light_gray, :white].sample
     @sprite = cloud_sprites.sample
     @speed = rand(1..10)
   end