rubysketch 0.9.5 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ff5b8ecc70091bc532c6ddcc047df2ffb396bd8552c18e4d77dbf6538e7ae5f9
-  data.tar.gz: cfe92a8493db486fc33212097b0675bd37524ebcc769d4d9cdc52b1c44d65558
+  metadata.gz: c4f8d3591f90ee825cf8f8c1d6379c7841d7a03e90c211fdb5be0ba378514e74
+  data.tar.gz: c82032ec68d87488fcf2036177ebd6aea6168e91c3d6e6de7508af17a0c9daf9
 SHA512:
-  metadata.gz: 52857a9f308b4951971d78d3818d804526652f1c764ec226de92e9e0eb48d334520f5eed4ca04353da4c8c6ad086de09bb704034844f2a49116b82ac22b1c673
-  data.tar.gz: 92bbaa51e072847f188f54ba79370dcf549e71b6bd78ac53b055b42e5b8087bf193196f999278c76347b79e9b210f4afdd0b50a2f8b7786bfbd54d6e5daabc68
+  metadata.gz: 9c3e94f02d383ff622f082058e8146dbf1b913e26b902f94c7a4dc6d46b95d3ab743a5b638cc48d50d13237689650d7e4db3a3312466bad7044ed76cd17af99a
+  data.tar.gz: ae869f7c81595a77724f02410b65eb5f638ccfaa77184572b5ad13ca990ea9a33fd256f240af578a1b06c4846fc72faa1e320e1b58df959090b8a98bb34d9958

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

@@ -26,8 +26,17 @@ jobs:
       - name: setup dependencies
         run: "ruby -I.github/workflows -rutils -e 'setup_dependencies'"
 
+      - name: packages
+        run: bundle exec rake packages
+
+      - name: setup zig
+        if: github.event.repository.name == 'reflex-terminal'
+        uses: mlugg/setup-zig@v2
+        with:
+          version: 0.16.0
+
       - name: test
-        run: bundle exec rake packages test
+        run: bundle exec rake test
 
       - name: create gem
         id: gem

data/.github/workflows/test.yml

@@ -27,6 +27,15 @@ jobs:
       - name: packages
         run: bundle exec rake verbose packages
 
+      - name: setup zig
+        if: github.event.repository.name == 'reflex-terminal'
+        uses: mlugg/setup-zig@v2
+        with:
+          version: 0.16.0
+
+      - name: vendor
+        run: bundle exec rake vendor
+
       - name: lib
         run: bundle exec rake verbose lib
 

data/ChangeLog.md

@@ -1,6 +1,19 @@
 # rubysketch ChangeLog
 
 
+## [v0.10.0] - 2026-08-04
+
+- [BREAKING] Remove the context: parameter from Sprite.new and SpriteWorld#createSprite
+- Add constraint mechanism backed by Reflex constraints
+- Add mouseOver/mouseOut blocks to Sprite, and Sprite#mouseOver to read the state
+- Add sprite(world) support to draw all sprites in a world
+- Add position/size methods to SpriteWorld
+- Deprecate addSprite/removeSprite array params in favor of to:/from: keywords
+- Reject adding a sprite to two worlds, or removing it from another world
+
+- Fix SpriteWorld#oy=
+
+
 ## [v0.9.5] - 2026-06-23
 
 - Add packager support with bin/rubysketch CLI

data/VERSION

@@ -1 +1 @@
-0.9.5
+0.10.0

data/bin/rubysketch

@@ -11,7 +11,7 @@ profile = Reflex::Packager::Profile.new(
   libraries:    %w[Xot Rucy Beeps Rays Reflex Processing RubySketch],
   extensions:   %w[beeps_ext rays_ext reflex_ext],
   config_files: %w[rubysketch.yml rubysketch.yaml],
-  template:     <<~RUBY)
+  templates:    {'main.rb': <<~MAIN, 'rubysketch.yml': <<~CONFIG})
     require 'rubysketch'
     using RubySketch
 
@@ -21,9 +21,13 @@ profile = Reflex::Packager::Profile.new(
 
     draw do
       background 100
-      fill 255, 0, 0
-      ellipse width / 2, height / 2, 100, 100
+      text 'hello, world!', 100, 100
     end
-  RUBY
+  MAIN
+    name: {{name}}
+    version: 1.0.0
+    #bundle_id: org.xord.rubysketch.example.{{name_id}}
+    #icon: icon.png
+  CONFIG
 
 Reflex::Packager::CLI.new(profile).run ARGV.dup

data/examples/constraint.rb

@@ -0,0 +1,89 @@
+%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
+
+
+def setup()
+  noStroke
+  gravity 0, 1000
+
+  $statics = [
+    createSprite(0, height - 10, width, 10),
+    createSprite(0,          0, 10, height),
+    createSprite(width - 10, 0, 10, height)
+  ]
+  walls = $statics[1..]
+  $balls = []
+
+  # pendulum: snap the hanging ball to the anchor
+  pivot  = anchor 100, 100
+  weight = ball   170, 100, 30
+  pivot.snap weight
+
+  # motored arm: half a turn per second
+  hinge = anchor 250, 100
+  arm   = ball   250, 140, 20
+  hinge.snap arm, motor: PI
+
+  # spring chain: balls linked with springs
+  prev = anchor 400, 60
+  4.times do |i|
+    node = ball 400, 100 + i * 40, 20
+    node.link prev, spring: 4, damping: 0.5, collide: true
+    prev = node
+  end
+
+  # car: each tire rides on the body with a wheel constraint -- a vertical
+  # suspension spring and a drive motor, reversed whenever the body bumps
+  # into a wall
+  body = createSprite 60, height - 80, 60, 14
+  body.dynamic = true
+  axles = [10, 50].map do |x|
+    tire = ball 50 + x, height - 60, 18
+    tire.pin(9, 9).wheel body.pin(x, 12),
+      axis: [0, 1], spring: 6, damping: 0.7, motor: TWO_PI
+  end
+  body.contact do |o|
+    axles.each {|a| a.motor = -a.motor} if walls.include?(o)
+  end
+  $car = body
+
+  # chaser: follows the mouse pointer with a soft spring
+  chaser = ball 100, 300, 24
+  chaser.gravityScale = 0
+  chaser.sensor       = true # do not bump the pendulum
+  $chase = chaser.chase [100, 300], spring: 2, damping: 0.7
+end
+
+def draw()
+  background 0
+
+  $chase.target = [mouseX, mouseY]
+
+  fill 200
+  sprite *$statics
+  fill 240, 240, 240
+  sprite $car
+  fill 150, 240, 150
+  sprite *$balls
+
+  textSize 16
+  fill 255, 200, 150
+  text "#{frameRate.to_i} FPS - the ball chases the mouse pointer", 20, 30
+end
+
+def ball(x, y, size)
+  sp = createSprite x, y, shape: Circle.new(0, 0, size)
+  sp.dynamic = true
+  $balls << sp
+  sp
+end
+
+def anchor(x, y)
+  sp = createSprite x, y, 10, 10 # static by default
+  $statics << sp
+  sp
+end

data/lib/rubysketch/all.rb

@@ -18,6 +18,8 @@ require 'rubysketch/window'
 
 require 'rubysketch/sprite'
 require 'rubysketch/shape'
+require 'rubysketch/pin'
+require 'rubysketch/constraint'
 require 'rubysketch/sound'
 require 'rubysketch/mml'
 require 'rubysketch/easings'

data/lib/rubysketch/constraint.rb

@@ -0,0 +1,422 @@
+module RubySketch
+
+
+  # Constrains the motion of sprites.
+  # Constraints are created with Sprite#snap, #link, #wheel and #chase
+  # (or the same verbs on Sprite#pin), not with new.
+  #
+  class Constraint
+
+    include Xot::Setter
+
+    # @private
+    def initialize(constraint)
+      @constraint__ = constraint
+    end
+
+    # Removes the constraint permanently.
+    #
+    # @return [Constraint] self
+    #
+    def remove()
+      @constraint__.remove
+      self
+    end
+
+    # Sets the spring stiffness in hertz.
+    #
+    # @param [Numeric, nil] hertz stiffness, or nil to make it rigid
+    #
+    # @return [Numeric, nil] hertz
+    #
+    def spring=(hertz)
+      @constraint__.spring = hertz
+    end
+
+    # Returns the spring stiffness in hertz.
+    #
+    # @return [Numeric, nil] hertz, or nil if the constraint is rigid
+    #
+    def spring()
+      @constraint__.spring
+    end
+
+    # Sets the spring damping ratio.
+    #
+    # @param [Numeric] ratio 0 (no damping) to 1 (critical damping)
+    #
+    # @return [Numeric] damping ratio
+    #
+    def damping=(ratio)
+      @constraint__.damping = ratio
+    end
+
+    # Returns the spring damping ratio.
+    #
+    # @return [Numeric] damping ratio
+    #
+    def damping()
+      @constraint__.damping
+    end
+
+    # Sets whether the constrained sprites collide with each other.
+    #
+    # @param [Boolean] bool collide or not
+    #
+    # @return [Boolean] collide or not
+    #
+    def collide=(bool)
+      @constraint__.collide = bool
+    end
+
+    # Returns whether the constrained sprites collide with each other.
+    #
+    # @return [Boolean] collide or not
+    #
+    def collide?()
+      @constraint__.collide?
+    end
+
+    # Sets the maximum force (or torque) that drives the constraint.
+    #
+    # @param [Numeric, nil] force
+    #  maximum force, or nil for the default strength.
+    #  0 makes the drive powerless
+    #
+    # @return [Numeric, nil] force
+    #
+    def force=(force)
+      @constraint__.force = force
+    end
+
+    # Returns the maximum force that drives the constraint.
+    #
+    # @return [Numeric, nil] force, or nil for the default strength
+    #
+    def force()
+      @constraint__.force
+    end
+
+    universal_accessor :spring, :damping, :force, collide: {reader: :collide?}
+
+    # Returns whether the constraint is active in a physics world.
+    #
+    # @return [Boolean] active or not
+    #
+    def active?()
+      @constraint__.active?
+    end
+
+    # Returns whether the constraint was removed.
+    #
+    # @return [Boolean] removed or not
+    #
+    def removed?()
+      @constraint__.removed?
+    end
+
+    # Returns the sprites the constraint is fastened to.
+    #
+    # @return [Array<Sprite, nil>] nil for a world anchor
+    #
+    def sprites()
+      @sprites__ ||= @constraint__.views.map {_1&.sprite}.freeze
+    end
+
+    # @private
+    def ==(o)
+      o.is_a?(Constraint) && @constraint__ == o.getInternal__
+    end
+
+    alias eql? ==
+
+    # @private
+    def hash()
+      @constraint__.hash
+    end
+
+    # @private
+    def getInternal__()
+      @constraint__
+    end
+
+    # @private
+    def self.wrap__(constraint)
+      klass =
+        case constraint
+        when Reflex::SnapConstraint  then SnapConstraint
+        when Reflex::LinkConstraint  then LinkConstraint
+        when Reflex::WheelConstraint then WheelConstraint
+        when Reflex::ChaseConstraint then ChaseConstraint
+        else raise ArgumentError, "unknown constraint type: #{constraint.class}"
+        end
+      klass.new constraint
+    end
+
+    private
+
+    def getContext__()
+      sprites.first&.getContext__ || Processing.context
+    end
+
+    def toDegrees__(angle)
+      getContext__.toDegrees__ angle
+    end
+
+    def fromDegrees__(degrees)
+      getContext__.fromDegrees__ degrees
+    end
+
+  end# Constraint
+
+
+  # Snaps two points together like a hinge.
+  #
+  class SnapConstraint < Constraint
+
+    # Sets the range of the relative rotation angle.
+    #
+    # @param [Range, Numeric, nil] angle
+    #  radians or degrees depending on angleMode().
+    #  nil rotates freely, 0 fixes the rotation
+    #
+    # @return [Range, Numeric, nil] angle
+    #
+    def angle=(angle)
+      @constraint__.angle =
+        case angle
+        when Range   then Range.new toDegrees__(angle.begin), toDegrees__(angle.end)
+        when Numeric then toDegrees__ angle
+        else              angle
+        end
+    end
+
+    # Returns the range of the relative rotation angle.
+    #
+    # @return [Range, nil] radians or degrees depending on angleMode()
+    #
+    def angle()
+      angle = @constraint__.angle
+      angle ? Range.new(fromDegrees__(angle.begin), fromDegrees__(angle.end)) : nil
+    end
+
+    # Sets the motor speed that drives the relative rotation.
+    #
+    # @param [Numeric, nil] speed
+    #  angular velocity per second, radians or degrees depending on
+    #  angleMode(). nil stops the motor
+    #
+    # @return [Numeric, nil] speed
+    #
+    def motor=(speed)
+      @constraint__.motor = speed && toDegrees__(speed)
+    end
+
+    # Returns the motor speed.
+    #
+    # @return [Numeric, nil] angular velocity per second
+    #
+    def motor()
+      speed = @constraint__.motor
+      speed && fromDegrees__(speed)
+    end
+
+    universal_accessor :angle, :motor
+
+  end# SnapConstraint
+
+
+  # Keeps two points apart at a distance, or slides them along an axis
+  # like a rail.
+  #
+  class LinkConstraint < Constraint
+
+    # Sets the axis to slide along.
+    # With an axis, the separation is measured along it instead of
+    # radially, and the relative rotation is locked like a rail.
+    #
+    # @param [Vector, Array<Numeric>, nil] axis
+    #  direction in the target local space, or nil to link radially
+    #
+    # @return [Vector, Array<Numeric>, nil] axis
+    #
+    def axis=(axis)
+      @constraint__.axis = RubySketch.unwrap__ axis
+    end
+
+    # Returns the axis to slide along.
+    #
+    # @return [Vector, nil] axis, or nil for a radial link
+    #
+    def axis()
+      @constraint__.axis&.toVector
+    end
+
+    # Sets the distance to keep.
+    #
+    # @param [Numeric] distance distance in pixels
+    #
+    # @return [Numeric] distance
+    #
+    def distance=(distance)
+      @constraint__.distance = distance
+    end
+
+    # Returns the distance to keep.
+    #
+    # @return [Numeric] distance in pixels
+    #
+    def distance()
+      @constraint__.distance
+    end
+
+    # Returns the current distance between the two points.
+    #
+    # @return [Numeric] distance in pixels, or 0 if not active in a world
+    #
+    def currentDistance()
+      @constraint__.current_distance
+    end
+
+    # Sets the range of the separation.
+    #
+    # @param [Range, Numeric, nil] range
+    #  distance range like a rope, or the translation range along the axis
+    #
+    # @return [Range, Numeric, nil] range
+    #
+    def range=(range)
+      @constraint__.range = range
+    end
+
+    # Returns the range of the separation.
+    #
+    # @return [Range, nil] separation range
+    #
+    def range()
+      @constraint__.range
+    end
+
+    # Sets the motor speed that drives the separation.
+    #
+    # @param [Numeric, nil] speed speed in pixels per second, or nil to stop
+    #
+    # @return [Numeric, nil] speed
+    #
+    def motor=(speed)
+      @constraint__.motor = speed
+    end
+
+    # Returns the motor speed.
+    #
+    # @return [Numeric, nil] speed in pixels per second
+    #
+    def motor()
+      @constraint__.motor
+    end
+
+    universal_accessor :axis, :distance, :range, :motor
+
+    alias dist= distance=
+    alias dist  distance
+
+  end# LinkConstraint
+
+
+  # Rides on the target like a wheel: slides along an axis for the
+  # suspension while spinning freely.
+  #
+  class WheelConstraint < Constraint
+
+    # Sets the axis to slide along for the suspension.
+    #
+    # @param [Vector, Array<Numeric>] axis direction in the target local space
+    #
+    # @return [Vector, Array<Numeric>] axis
+    #
+    def axis=(axis)
+      @constraint__.axis = RubySketch.unwrap__ axis
+    end
+
+    # Returns the axis to slide along.
+    #
+    # @return [Vector] axis
+    #
+    def axis()
+      @constraint__.axis&.toVector
+    end
+
+    # Sets the range of the translation along the axis.
+    #
+    # @param [Range, Numeric, nil] range translation range in pixels
+    #
+    # @return [Range, Numeric, nil] range
+    #
+    def range=(range)
+      @constraint__.range = range
+    end
+
+    # Returns the range of the translation along the axis.
+    #
+    # @return [Range, nil] translation range
+    #
+    def range()
+      @constraint__.range
+    end
+
+    # Sets the motor speed that spins the wheel.
+    #
+    # @param [Numeric, nil] speed
+    #  angular velocity per second, radians or degrees depending on
+    #  angleMode(). nil stops the motor
+    #
+    # @return [Numeric, nil] speed
+    #
+    def motor=(speed)
+      @constraint__.motor = speed && toDegrees__(speed)
+    end
+
+    # Returns the motor speed.
+    #
+    # @return [Numeric, nil] angular velocity per second
+    #
+    def motor()
+      speed = @constraint__.motor
+      speed && fromDegrees__(speed)
+    end
+
+    universal_accessor :axis, :range, :motor
+
+  end# WheelConstraint
+
+
+  # Moves a point toward the target every frame.
+  #
+  class ChaseConstraint < Constraint
+
+    # Sets the target to chase.
+    #
+    # @param [Sprite, Pin, Vector, Array<Numeric>, nil] target
+    #  the center of a sprite, a pin, or a point in the world.
+    #  nil chases nothing
+    #
+    # @return [Sprite, Pin, Vector, Array<Numeric>, nil] target
+    #
+    def target=(target)
+      @constraint__.target = RubySketch.unwrap__ target
+    end
+
+    # Returns the target to chase.
+    #
+    # @return [Pin] the target pin
+    #
+    def target()
+      Pin.new nil, pin__: @constraint__.target
+    end
+
+    universal_accessor :target
+
+  end# ChaseConstraint
+
+
+end# RubySketch

data/lib/rubysketch/context.rb

@@ -265,29 +265,29 @@ module RubySketch
     # @return [Sprite] the new sprite object
     #
     def createSprite(*args, **kwargs)
-      @world__.createSprite(*args, context: self, **kwargs)
+      @world__.createSprite(*args, **kwargs)
     end
 
     # Adds sprite to the physics engine.
     #
-    # @param [Array]  array user array to store the sprite
     # @param [Sprite] sprite sprite object
+    # @param [Array]  to     user array to store the sprite
     #
     # @return [Sprite] the added sprite
     #
-    def addSprite(array = nil, sprite)
-      @world__.addSprite array, sprite
+    def addSprite(...)
+      @world__.addSprite(...)
     end
 
     # Removes sprite from the physics engine.
     #
-    # @param [Array]  array user array to remove the sprite
     # @param [Sprite] sprite sprite object
+    # @param [Array]  from   user array to remove the sprite
     #
     # @return [Sprite] the removed sprite
     #
-    def removeSprite(array = nil, sprite)
-      @world__.removeSprite array, sprite
+    def removeSprite(...)
+      @world__.removeSprite(...)
     end
 
     alias drawSprite sprite
@@ -307,7 +307,11 @@ module RubySketch
     # @return [SpriteWorld] first added world
     #
     def addWorld(*worlds)
-      worlds.each {@window__.add_overlay _1.getInternal__}
+      raise ArgumentError if worlds.any? {_1.getContext__}
+      worlds.each do |world|
+        @window__.add_overlay world.getInternal__
+        world.attached__
+      end
       worlds.first
     end
 
@@ -318,7 +322,11 @@ module RubySketch
     # @return [SpriteWorld] first removed world
     #
     def removeWorld(*worlds)
-      worlds.each {@window__.remove_overlay _1.getInternal__}
+      raise ArgumentError if worlds.any? {_1.getContext__ != self}
+      worlds.each do |world|
+        @window__.remove_overlay world.getInternal__
+        world.detached__
+      end
       worlds.first
     end
 

data/lib/rubysketch/extension.rb

@@ -7,7 +7,7 @@ module RubySketch
     module_function
 
     def name(downcase = false)
-      super().split('::')[-2].then {|s|
+      super().split('::')[..-2].join.then {|s|
         downcase ? s.downcase : s
       }
     end

data/lib/rubysketch/helper.rb

@@ -4,3 +4,13 @@ class Rays::Point
     Processing::Vector.new x, y, z
   end
 end
+
+
+module RubySketch
+
+  # @private
+  def self.unwrap__(arg)
+    arg.respond_to?(:getInternal__) ? arg.getInternal__ : arg
+  end
+
+end# RubySketch