rubysketch 0.7.19 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b251469c4df4dae76cf96474b13d46c7e321b3f84702c0b4cb36a2724665f4d9
-  data.tar.gz: 48ee21b1e75820ebfff7345687fad5c835335fbb9771b571c640b6b8f4ad1fcc
+  metadata.gz: c2d5ce7e554264c501763b490d4ecec02cc7be17509bf44c4821c5b0d4083788
+  data.tar.gz: 8c1d4352f30dd6e5b7455f4d67892952f43594e02f35fc7a5a3e3832ecc77aa4
 SHA512:
-  metadata.gz: 30c4a2f0a8a8463df2bd403d9f7ad42fe1cc37cd1fb81c06b19a5d5d6cf3ebe1b445aa06e62af84097ab68e74c5d9fcafef122db07d0ce3bb47e447fb7815e62
-  data.tar.gz: 871090464a099b23a9aa1477acd5efe66c5e9739a2864749da2b4a469a58a0474ce8bbf71c7e17921e878ce850d4c027a275a20fcb55fd69a45bf43d88556ea3
+  metadata.gz: 9ecd190e2f06b9321e76cb74c2d8ffdbe42142430095f80837df1731fbf6c0539d3c89855e9b69e09d94d730d69379ebe8a3968916a55a5b4cafbaaa9b885697
+  data.tar.gz: 28a1bc912004c769b691804768c203a2cb98454d3f96accd63b536687797eba08432ec4bb2cfe2a27f7411b97a85317e6bfe959e7e389dde13331b2915f38034

data/.github/workflows/release-gem.yml

@@ -36,23 +36,9 @@ jobs:
           echo path=$(ruby -e 'print Dir.glob("*.gem").first') >> $GITHUB_OUTPUT
 
       - name: create github release
-        id: release
-        uses: actions/create-release@v1
         env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        with:
-          tag_name: ${{ github.ref }}
-          release_name: ${{ github.ref }}
-
-      - name: upload to github release
-        uses: actions/upload-release-asset@v1
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        with:
-          upload_url: ${{ steps.release.outputs.upload_url }}
-          asset_path: ./${{ steps.gem.outputs.path }}
-          asset_name:   ${{ steps.gem.outputs.path }}
-          asset_content_type: application/zip
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: ruby -I.github/workflows -rutils -e 'release(*ARGV)' ./${{ steps.gem.outputs.path }}
 
       - name: upload to rubygems
         env:

data/ChangeLog.md

@@ -1,6 +1,16 @@
 # rubysketch ChangeLog
 
 
+## [v0.8.0] - 2026-05-17
+
+- [BREAKING] Wheel Y delta now follows top-left origin convention (from reflex)
+
+- Expose MML class at top level and add example
+- Add RDoc to MML class
+- Rewrite README.md
+- CI: Migrate release-gem.yml from actions/create-release to gh release create
+
+
 ## [v0.7.19] - 2026-05-10
 
 - Support WebAssembly

data/README.md

@@ -21,20 +21,24 @@ Thanks for your support! 🙌
 
 ## 🚀 About
 
-**RubySketch** is a game engine based on the Processing API, designed for use with Ruby.
+**RubySketch** is a 2D game engine for Ruby. It takes the [Processing for CRuby](https://github.com/xord/processing) sketch loop — `setup` / `draw` / `mousePressed` / ... — and layers a game-oriented vocabulary on top of it: `Sprite`, world-based 2D physics (via Box2D), `Sound` and `MML` (Music Macro Language) for audio, animation timers (`animate`, `setInterval`, `setTimeout`), and a small library of easing curves.
 
-It provides a familiar environment for developers who are accustomed to Processing, enabling them to create games and interactive graphics with ease.
+## 📋 Requirements
 
-**RubySketch** combines the simplicity of the Processing API with the power of Ruby, making it a versatile tool for creative coding.
+- Ruby **3.0.0** or later
+- All the runtime requirements of [Reflex](https://github.com/xord/reflex) (Rays, Rucy, Xot, plus the platform GUI backend — AppKit / UIKit / Win32 / SDL2 — and OpenGL)
+- The dependent gems are installed automatically: `xot`, `rucy`, `beeps`, `rays`, `reflexion`, `processing`
+
+There is no native C/C++ extension in this gem; the heavy lifting is done by the underlying gems' extensions.
 
 ## 📦 Installation
 
 Add this line to your Gemfile:
 ```ruby
-$ gem 'rubysketch'
+gem 'rubysketch'
 ```
 
-Then, install gem:
+Then install:
 ```bash
 $ bundle install
 ```
@@ -44,6 +48,183 @@ Or install it directly:
 $ gem install rubysketch
 ```
 
+## 📚 What's Provided
+
+`require 'rubysketch'` and `using RubySketch` make the whole **Processing API** ([camelCase](https://github.com/xord/processing#-whats-provided)) plus the RubySketch additions available as top-level methods in your file. As with Processing, a window opens and the sketch runs automatically on file exit; you do not need an explicit `start` call.
+
+`using RubySketch(snake_case: true)` adds snake_case aliases (`create_sprite`, `set_interval`, ...) alongside the camelCase originals.
+
+### On top of Processing, RubySketch adds:
+
+#### Sprites — `RubySketch::Sprite`
+
+`createSprite` returns a `Sprite` whose position, size, angle, velocity, image, offset, pivot, shape, draw block, and per-sprite mouse events you can drive directly.
+
+| Capability                | API                                                                                |
+| ------------------------- | ---------------------------------------------------------------------------------- |
+| Position / size           | `pos`, `x`, `y`, `z`, `left`, `top`, `right`, `bottom`, `center`, `size`, `width`, `height` |
+| Motion                    | `velocity`, `vx`, `vy`, `angle`, `fixAngle`, `pivot`                                |
+| Appearance                | `image`, `offset` (texture offset), draw block                                      |
+| Physics                   | `dynamic = true`, `static = true`, `restitution`, `density`, `friction`, `shape`    |
+| Interaction               | `mousePressed`, `mouseReleased`, `mouseMoved`, `mouseDragged`, `mouseClicked` (per-sprite) |
+| Lifecycle                 | `update { ... }`, `draw { ... }`, `show`, `hide`, `capture = true/false`            |
+
+Sprites can be sorted by `z` and drawn in bulk via the top-level `sprite(*sprites)` call.
+
+#### 2D physics
+
+| API                              | Purpose                                              |
+| -------------------------------- | ---------------------------------------------------- |
+| `gravity(x, y)` / `gravity(vec)` | Set the gravity of the active world                  |
+| `Sprite#shape =`                 | Box2D fixture shape (rect, ellipse, polygon)         |
+
+#### Sound
+
+| API                              | Purpose                                              |
+| -------------------------------- | ---------------------------------------------------- |
+| `loadSound(path)`                | Load a sample (WAV / AIFF / ...) into a `RubySketch::Sound` |
+| `Sound#play(gain:)`              | Play; returns a handle exposing `stop`, `playing?`, `seconds` |
+| `Sound#stop`                     | Stop all instances                                   |
+
+#### Music Macro Language (MML)
+
+A tiny MML compiler (`RubySketch::MML`) that turns a string like `"t120 l4 cdefgab>c"` into a `RubySketch::Sound`.
+
+- `MML.compile(str, streaming = false)` — compile and return a `Sound` you can play later.
+- `MML.play(str)` — shortcut for `compile(str).play`.
+
+#### Animation and timers
+
+| API                                   | Purpose                                                                          |
+| ------------------------------------- | -------------------------------------------------------------------------------- |
+| `setTimeout(seconds) { ... }`         | Run a block once after a delay; returns an id usable with `clearTimer`           |
+| `setInterval(seconds, now:) { ... }`  | Run a block every N seconds                                                      |
+| `clearTimer(id)`                      | Cancel a timer                                                                   |
+| `animate(seconds, easing:) { ... }`   | Drive a block from 0.0 to 1.0 over time, optionally with an easing curve         |
+| `animateValue(seconds, from:, to:, easing:) { ... }` | Same but yields the interpolated value                                 |
+
+Easing names: `linear`, `sineIn` / `sineOut` / `sineInOut`, `quadIn` / ... / `cubicIn` / ..., `expoIn` / `expoOut` / `expoInOut`, `circIn` / ..., `backIn` / `backOut` / `backInOut`, `elasticIn` / `elasticOut` / `elasticInOut`, `bounceIn` / `bounceOut` / `bounceInOut`. See `lib/rubysketch/easings.rb`.
+
+#### MIDI input (forwarded from Reflex)
+
+`notePressed`, `noteReleased`, `controlChange` blocks; `noteNumber`, `noteFrequency`, `noteVelocity`, `controllerIndex`, `controllerValue` accessors during a callback.
+
+#### Miscellaneous
+
+- `vibrate` (mobile)
+- `Vector`, `Image`, `WheelEvent` — re-exported from Processing for convenience
+
+## 💡 Usage
+
+### Hello, RubySketch
+
+```ruby
+require 'rubysketch'
+using RubySketch
+
+draw do
+  background 0
+  textSize 30
+  text 'hello, rubysketch!', 10, 100
+end
+```
+
+### Sprites and per-sprite input
+
+```ruby
+require 'rubysketch'
+using RubySketch
+
+player = createSprite 200, 200, 40, 40
+player.image = loadImage 'player.png'
+
+player.update do
+  player.x += 2 if keyIsDown(RIGHT)
+  player.x -= 2 if keyIsDown(LEFT)
+end
+
+player.mouseClicked do
+  player.z += 10              # bring forward on click
+end
+
+draw do
+  background 30
+  sprite player
+end
+```
+
+### 2D physics
+
+```ruby
+require 'rubysketch'
+using RubySketch
+
+noStroke
+gravity 0, 1000              # pixels / s^2 downward
+
+ground  = createSprite 0, height - 10, width, 10   # static by default
+sprites = []
+
+draw do
+  background 100
+  sprite ground, *sprites
+end
+
+mousePressed do
+  sp             = createSprite mouseX + rand, mouseY + rand,
+                                shape: Circle.new(0, 0, 20)
+  sp.dynamic     = true
+  sp.restitution = 0.5
+  sprites << sp
+end
+```
+
+### Sound and MML
+
+```ruby
+require 'rubysketch'
+using RubySketch
+
+bgm = loadSound 'bgm.wav'
+
+setup do
+  bgm.play(gain: 0.6)
+end
+
+# play an MML phrase on every click
+mousePressed do
+  RubySketch::MML.play 't140 l8 ccggaag4 ffeeddc4'
+end
+```
+
+### Animation with easing
+
+```ruby
+require 'rubysketch'
+using RubySketch
+
+x = 0
+animateValue(2.0, from: 0, to: width, easing: :elasticOut) {|v| x = v }
+
+draw do
+  background 0
+  fill 1
+  ellipse x, height / 2, 40, 40
+end
+```
+
+See [`examples/`](./examples) for `hello.rb`, `sprite.rb`, `physics.rb`, and `toon.rb`.
+
+## 🛠️ Development
+
+```bash
+$ rake test    # run the test suite
+$ rake doc     # generate YARD docs
+$ rake         # default tasks
+```
+
+In the [`xord/all`](https://github.com/xord/all) monorepo you can scope by module, e.g. `rake rubysketch test`.
+
 ## 📜 License
 
 **RubySketch** is licensed under the MIT License.

data/VERSION

@@ -1 +1 @@
-0.7.19
+0.8.0

data/examples/mml.rb

@@ -0,0 +1,10 @@
+%w[xot rucy beeps rays reflex processing rubysketch]
+  .map  {|s| File.expand_path "../../#{s}/lib", __dir__}
+  .each {|s| $:.unshift s if !$:.include?(s) && File.directory?(s)}
+
+require 'rubysketch'
+using RubySketch
+
+mouseClicked do
+  MML.play('cdefgab>c')
+end

data/lib/rubysketch/all.rb

@@ -18,8 +18,7 @@ require 'rubysketch/helper'
 require 'rubysketch/sprite'
 require 'rubysketch/shape'
 require 'rubysketch/sound'
+require 'rubysketch/mml'
 require 'rubysketch/easings'
 require 'rubysketch/graphics_context'
 require 'rubysketch/context'
-
-require 'rubysketch/mml'

data/lib/rubysketch/context.rb

@@ -9,6 +9,7 @@ module RubySketch
     SpriteWorld = RubySketch::SpriteWorld
     Circle      = RubySketch::Circle
     Sound       = RubySketch::Sound
+    MML         = RubySketch::MML
 
     # @private
     def initialize(window)

data/lib/rubysketch/mml.rb

@@ -1,20 +1,32 @@
 module RubySketch
 
 
+  # MML (Music Macro Language) compiler.
+  #
   class MML
 
+    # Oscillator tone types selectable with the `@N` command.
+    #
     TONES = %i[
       sine triangle square sawtooth pulse12_5 pulse25 noise
     ].freeze
 
     class << self
 
+      # Compile MML string into a sound.
+      #
+      # @param [String]  str       MML string
+      # @param [Boolean] streaming if true, creates a streaming sound
+      #
+      # @return [Sound] sound object
+      #
       def compile(str, streaming = false)
-        seq, duration = compile! str
+        seq, duration = compile__! str
         Sound.new Beeps::Sound.new(seq, streaming ? 0 : duration)
       end
 
-      def compile!(str)
+      # @private
+      def compile__!(str)
         scanner = StringScanner.new expandLoops__ str.gsub(/[;%].*(?:\n|$)/, '')
         seq     = Beeps::Sequencer.new
         note    = Note__.new
@@ -87,6 +99,12 @@ module RubySketch
         return seq, note.time
       end
 
+      # Compile and play MML string.
+      #
+      # @param [String] str MML string
+      #
+      # @return [nil] nil
+      #
       def play(str)
         compile(str).play
       end

data/rubysketch.gemspec

@@ -25,12 +25,12 @@ Gem::Specification.new do |s|
   s.platform              = Gem::Platform::RUBY
   s.required_ruby_version = '>= 3.0.0'
 
-  s.add_dependency 'xot',        '~> 0.3.12'
-  s.add_dependency 'rucy',       '~> 0.3.12'
-  s.add_dependency 'beeps',      '~> 0.3.12'
-  s.add_dependency 'rays',       '~> 0.3.12'
-  s.add_dependency 'reflexion',  '~> 0.3.15'
-  s.add_dependency 'processing', '~> 1.1.18'
+  s.add_dependency 'xot',        '~> 0.3.13'
+  s.add_dependency 'rucy',       '~> 0.3.13'
+  s.add_dependency 'beeps',      '~> 0.3.13'
+  s.add_dependency 'rays',       '~> 0.3.13'
+  s.add_dependency 'reflexion',  '~> 0.4.0'
+  s.add_dependency 'processing', '~> 1.2.0'
 
   s.files            = `git ls-files`.split $/
   s.test_files       = s.files.grep %r{^(test|spec|features)/}

data/test/test_mml.rb

@@ -4,7 +4,7 @@ require_relative 'helper'
 class TestMML < Test::Unit::TestCase
 
   def compile(str)
-    RubySketch::MML.compile! str
+    RubySketch::MML.compile__! str
   end
 
   def procs(str, klass = nil)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rubysketch
 version: !ruby/object:Gem::Version
-  version: 0.7.19
+  version: 0.8.0
 platform: ruby
 authors:
 - xordog
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-09 00:00:00.000000000 Z
+date: 2026-05-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: xot
@@ -16,84 +16,84 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.3.12
+        version: 0.3.13
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.3.12
+        version: 0.3.13
 - !ruby/object:Gem::Dependency
   name: rucy
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.3.12
+        version: 0.3.13
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.3.12
+        version: 0.3.13
 - !ruby/object:Gem::Dependency
   name: beeps
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.3.12
+        version: 0.3.13
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.3.12
+        version: 0.3.13
 - !ruby/object:Gem::Dependency
   name: rays
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.3.12
+        version: 0.3.13
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.3.12
+        version: 0.3.13
 - !ruby/object:Gem::Dependency
   name: reflexion
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.3.15
+        version: 0.4.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.3.15
+        version: 0.4.0
 - !ruby/object:Gem::Dependency
   name: processing
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.1.18
+        version: 1.2.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.1.18
+        version: 1.2.0
 description: A game engine based on the Processing API.
 email: xordog@gmail.com
 executables: []
@@ -117,6 +117,7 @@ files:
 - RubySketch.podspec
 - VERSION
 - examples/hello.rb
+- examples/mml.rb
 - examples/physics.rb
 - examples/sprite.rb
 - examples/toon.rb