ruby2d 0.11.2 → 0.12.0

data/lib/ruby2d/rectangle.rb

@@ -1,18 +1,26 @@
+# frozen_string_literal: true
+
 # Ruby2D::Rectangle
 
 module Ruby2D
+  # A rectangle
   class Rectangle < Quad
-
-    def initialize(opts = {})
-      @x = opts[:x] || 0
-      @y = opts[:y] || 0
-      @z = opts[:z] || 0
-      @width = opts[:width] || 200
-      @height = opts[:height] || 100
-      self.color = opts[:color] || 'white'
-      self.color.opacity = opts[:opacity] if opts[:opacity]
-      update_coords(@x, @y, @width, @height)
-      add
+    # Create an rectangle
+    # @param [Numeric] x
+    # @param [Numeric] y
+    # @param [Numeric] width
+    # @param [Numeric] height
+    # @param [Numeric] z
+    # @param [String, Array] color A single colour or an array of exactly 4 colours
+    # @param [Numeric] opacity Opacity of the image when rendering
+    # @raise [ArgumentError] if an array of colours does not have 4 entries
+    def initialize(x: 0, y: 0, width: 200, height: 100, z: 0, color: nil, colour: nil, opacity: nil)
+      @width = width
+      @height = height
+      super(x1: @x = x, y1: @y = y,
+            x2: x + width, y2: y,
+            x3: x + width, y3: y + height,
+            x4: x, y4: y + height, z: z, color: color, colour: colour, opacity: opacity)
     end
 
     def x=(x)
@@ -29,37 +37,28 @@ module Ruby2D
       @y4 = y + @height
     end
 
-    def width=(w)
-      @width = w
-      update_coords(@x, @y, w, @height)
+    def width=(width)
+      @width = width
+      @x2 = @x1 + width
+      @x3 = @x1 + width
     end
 
-    def height=(h)
-      @height = h
-      update_coords(@x, @y, @width, h)
+    def height=(height)
+      @height = height
+      @y3 = @y1 + height
+      @y4 = @y1 + height
     end
 
-    def self.draw(opts = {})
-      ext_draw([
-        opts[:x]               , opts[:y]                , opts[:color][0][0], opts[:color][0][1], opts[:color][0][2], opts[:color][0][3],
-        opts[:x] + opts[:width], opts[:y]                , opts[:color][1][0], opts[:color][1][1], opts[:color][1][2], opts[:color][1][3],
-        opts[:x] + opts[:width], opts[:y] + opts[:height], opts[:color][2][0], opts[:color][2][1], opts[:color][2][2], opts[:color][2][3],
-        opts[:x]               , opts[:y] + opts[:height], opts[:color][3][0], opts[:color][3][1], opts[:color][3][2], opts[:color][3][3]
-      ])
+    def self.draw(x:, y:, width:, height:, color:)
+      super(x1: x, y1: y,
+            x2: x + width, y2: y,
+            x3: x + width, y3: y + height,
+            x4: x, y4: y + height, color: color)
     end
 
-    private
-
-    def update_coords(x, y, w, h)
-      @x1 = x
-      @y1 = y
-      @x2 = x + w
-      @y2 = y
-      @x3 = x + w
-      @y3 = y + h
-      @x4 = x
-      @y4 = y + h
+    def contains?(x, y)
+      # Override the check from Quad since this is faster
+      x >= @x && x <= (@x + @width) && y >= @y && y <= (@y + @height)
     end
-
   end
 end

data/lib/ruby2d/renderable.rb

@@ -1,8 +1,10 @@
+# frozen_string_literal: true
+
 # Ruby2D::Renderable
 
 module Ruby2D
+  # Base class for all renderable shapes
   module Renderable
-
     attr_reader :x, :y, :z, :width, :height, :color
 
     # Set the z position (depth) of the object
@@ -23,18 +25,17 @@ module Ruby2D
     end
 
     # Set the color value
-    def color=(c)
-      @color = Color.new(c)
+    def color=(color)
+      @color = Color.new(color)
     end
 
     # Allow British English spelling of color
-    alias_method :colour, :color
-    alias_method :colour=, :color=
+    alias colour color
+    alias colour= color=
 
     # Add a contains method stub
     def contains?(x, y)
       x >= @x && x <= (@x + @width) && y >= @y && y <= (@y + @height)
     end
-
   end
 end

data/lib/ruby2d/sound.rb

@@ -1,19 +1,24 @@
+# frozen_string_literal: true
+
 # Ruby2D::Sound
 
 module Ruby2D
+  # Sounds are intended to be short samples, played without interruption, like an effect.
   class Sound
-
     attr_reader :path
-    attr_accessor :data
+    attr_accessor :loop, :data
+
+    #
+    # Load a sound from a file
+    # @param [String] path File to load the sound from
+    # @param [true, false] loop If +true+ playback will loop automatically, default is +false+
+    # @raise [Error] if file cannot be found or music could not be successfully loaded.
+    def initialize(path, loop: false)
+      raise Error, "Cannot find audio file `#{path}`" unless File.exist? path
 
-    def initialize(path)
-      unless File.exist? path
-        raise Error, "Cannot find audio file `#{path}`"
-      end
       @path = path
-      unless ext_init(@path)
-        raise Error, "Sound `#{@path}` cannot be created"
-      end
+      @loop = loop
+      raise Error, "Sound `#{@path}` cannot be created" unless ext_init(@path)
     end
 
     # Play the sound
@@ -21,6 +26,11 @@ module Ruby2D
       ext_play
     end
 
+    # Stop the sound
+    def stop
+      ext_stop
+    end
+
     # Returns the length in seconds
     def length
       ext_length
@@ -32,11 +42,9 @@ module Ruby2D
     end
 
     # Set the volume of the sound
-    def volume=(v)
+    def volume=(volume)
       # Clamp value to between 0-100
-      if v < 0 then v = 0 end
-      if v > 100 then v = 100 end
-      ext_set_volume(v)
+      ext_set_volume(volume.clamp(0, 100))
     end
 
     # Get the volume of the sound mixer
@@ -45,11 +53,9 @@ module Ruby2D
     end
 
     # Set the volume of the sound mixer
-    def self.mix_volume=(v)
+    def self.mix_volume=(volume)
       # Clamp value to between 0-100
-      if v < 0 then v = 0 end
-      if v > 100 then v = 100 end
-      ext_set_mix_volume(v)
+      ext_set_mix_volume(volume.clamp(0, 100))
     end
   end
 end

data/lib/ruby2d/sprite.rb

@@ -1,101 +1,85 @@
+# frozen_string_literal: true
+
 # Ruby2D::Sprite
 
 module Ruby2D
+  # Sprites are special images that can be used to create animations, kind of like a flip book.
+  # To create a sprite animation, first you’ll need an image which contains each frame of your animation.
   class Sprite
     include Renderable
 
     attr_reader :path
     attr_accessor :rotate, :loop, :clip_x, :clip_y, :clip_width, :clip_height, :data, :x, :y, :width, :height
 
-    def initialize(path, opts = {})
-      # Sprite image file path
-      @path = path
-
-      # Initialize the sprite texture
-      @texture = Texture.new(*Image.load_image(@path))
-      @img_width = @texture.width
-      @img_height = @texture.height
+    # Create a sprite via single image or sprite-sheet.
+    # @param path [#to_s] The location of the file to load as an image.
+    # @param width [Numeric] The +width+ of drawn image, or default is width from image file
+    # @param height [Numeric] The +height+ of drawn image, or default is height from image file
+    # @param x [Numeric]
+    # @param y [Numeric]
+    # @param z [Numeric]
+    # @param rotate [Numeric] Angle, default is 0
+    # @param color [Numeric] (or +colour+) Tint the image when rendering
+    # @param opacity [Numeric] Opacity of the image when rendering
+    # @param show [Boolean] If +true+ the image is added to +Window+ automatically.
+    # @param loop [Boolean] Sets whether animations loop by default when played (can be overridden by +play+ method)
+    # @param time [Numeric] The default time in millisecond for each frame (unless overridden animation within frames)
+    # @param animations [Hash{String => Range}, Hash{String=>Array<Hash>}] Sprite sheet map to animations using
+    #                                                                      frame ranges or individual frames
+    # @param default [Numeric] The default initial frame for the sprite
+    # @param clip_x [Numeric]
+    # @param clip_x [Numeric]
+    # @param clip_width [Numeric]
+    # @param clip_height [Numeric]
+    def initialize(path, atlas: nil, show: true, width: nil, height: nil,
+                   x: 0, y: 0, z: 0, rotate: 0, color: nil, colour: nil, opacity: nil,
+                   loop: false, time: 300, animations: {}, default: 0,
+                   clip_x: 0, clip_y: 0, clip_width: nil, clip_height: nil)
+      @path = path.to_s
 
       # Coordinates, size, and rotation of the sprite
-      @x = opts[:x] || 0
-      @y = opts[:y] || 0
-      @z = opts[:z] || 0
-      @rotate = opts[:rotate] || 0
-      self.color = opts[:color] || 'white'
-      self.color.opacity = opts[:opacity] if opts[:opacity]
+      @x = x
+      @y = y
+      @z = z
+      @rotate = rotate
+      self.color = color || colour || 'white'
+      self.color.opacity = opacity unless opacity.nil?
+
+      # Dimensions
+      @width  = width
+      @height = height
 
       # Flipping status
       @flip = nil
 
       # Animation attributes
-      @start_time = 0.0
-      @loop = opts[:loop] || false
-      @frame_time = opts[:time] || 300
-      @animations = opts[:animations] || {}
-      @playing = false
-      @current_frame = opts[:default] || 0
-      @last_frame = 0
-      @done_proc = nil
-
-      # The clipping rectangle
-      @clip_x = opts[:clip_x] || 0
-      @clip_y = opts[:clip_y] || 0
-      @clip_width  = opts[:clip_width]  || @img_width
-      @clip_height = opts[:clip_height] || @img_height
-
-      # Dimensions
-      @width  = opts[:width]  || nil
-      @height = opts[:height] || nil
-
-      # Set the default animation
-      @animations[:default] = 0..(@img_width / @clip_width) - 1
+      @loop = loop
+      @frame_time = time
+      @animations = animations
+      @current_frame = default
 
-      # Set the sprite defaults
-      @defaults = {
-        animation:   @animations.first[0],
-        frame:       @current_frame,
-        frame_time:  @frame_time,
-        clip_x:      @clip_x,
-        clip_y:      @clip_y,
-        clip_width:  @clip_width,
-        clip_height: @clip_height,
-        loop:        @loop
-      }
+      _setup_texture_and_clip_box atlas, clip_x, clip_y, clip_width, clip_height
+      _setup_animation
 
       # Add the sprite to the window
-      unless opts[:show] == false then add end
+      add if show
     end
 
-    # Play an animation
-    def play(opts = {}, &done_proc)
-
-      animation = opts[:animation]
-      loop = opts[:loop]
-      flip = opts[:flip]
-
-      if !@playing || (animation != @playing_animation && animation != nil) || flip != @flip
-
+    # Start playing an animation
+    # @param animation [String] Name of the animation to play
+    # @param loop [Boolean] Set the animation to loop or not
+    # @param flip [nil, :vertical, :horizontal, :both] Direction to flip the sprite if desired
+    def play(animation: :default, loop: nil, flip: nil, &done_proc)
+      unless @playing && animation == @playing_animation && flip == @flip
         @playing = true
         @playing_animation = animation || :default
-        frames = @animations[@playing_animation]
-        flip_sprite(flip)
         @done_proc = done_proc
 
-        case frames
-        # When animation is a range, play through frames horizontally
-        when Range
-          @first_frame   = frames.first || @defaults[:frame]
-          @current_frame = frames.first || @defaults[:frame]
-          @last_frame    = frames.last
-        # When array...
-        when Array
-          @first_frame   = 0
-          @current_frame = 0
-          @last_frame    = frames.length - 1
-        end
+        flip_sprite(flip)
+        _reset_playing_animation
 
-        # Set looping
-        @loop = loop == true || @defaults[:loop] ? true : false
+        loop = @defaults[:loop] if loop.nil?
+        @loop = loop ? true : false
 
         set_frame
         restart_time
@@ -105,22 +89,22 @@ module Ruby2D
 
     # Stop the current animation and set to the default frame
     def stop(animation = nil)
-      if !animation || animation == @playing_animation
-        @playing = false
-        @playing_animation = @defaults[:animation]
-        @current_frame = @defaults[:frame]
-        set_frame
-      end
+      return unless !animation || animation == @playing_animation
+
+      @playing = false
+      @playing_animation = @defaults[:animation]
+      @current_frame = @defaults[:frame]
+      set_frame
     end
 
     # Flip the sprite
+    # @param flip [nil, :vertical, :horizontal, :both] Direction to flip the sprite if desired
     def flip_sprite(flip)
-
       # The sprite width and height must be set for it to be flipped correctly
       if (!@width || !@height) && flip
         raise Error,
-         "Sprite width and height must be set in order to flip; " +
-         "occured playing animation `:#{@playing_animation}` with image `#{@path}`"
+              "Sprite width/height required to flip; occured playing animation `:#{@playing_animation}`
+               with image `#{@path}`"
       end
 
       @flip = flip
@@ -142,12 +126,7 @@ module Ruby2D
         reset_clipping_rect
         @clip_x = @current_frame * @clip_width
       when Array
-        f = frames[@current_frame]
-        @clip_x      = f[:x]      || @defaults[:clip_x]
-        @clip_y      = f[:y]      || @defaults[:clip_y]
-        @clip_width  = f[:width]  || @defaults[:clip_width]
-        @clip_height = f[:height] || @defaults[:clip_height]
-        @frame_time  = f[:time]   || @defaults[:frame_time]
+        _set_explicit_frame frames[@current_frame]
       end
     end
 
@@ -163,75 +142,137 @@ module Ruby2D
 
     # Update the sprite animation, called by `render`
     def update
-      if @playing
+      return unless @playing
 
-        # Advance the frame
-        unless elapsed_time <= (@frame_time || @defaults[:frame_time])
-          @current_frame += 1
-          restart_time
-        end
+      # Advance the frame
+      unless elapsed_time <= (@frame_time || @defaults[:frame_time])
+        @current_frame += 1
+        restart_time
+      end
 
-        # Reset to the starting frame if all frames played
-        if @current_frame > @last_frame
-          @current_frame = @first_frame
-          unless @loop
-            # Stop animation and play block, if provided
-            stop
-            if @done_proc
-              # allow proc to make nested `play/do` calls to sequence multiple
-              # animations by clearing `@done_proc` before the call
-              kept_done_proc = @done_proc
-              @done_proc = nil
-              kept_done_proc.call
-            end
+      # Reset to the starting frame if all frames played
+      if @current_frame > @last_frame
+        @current_frame = @first_frame
+        unless @loop
+          # Stop animation and play block, if provided
+          stop
+          if @done_proc
+            # allow proc to make nested `play/do` calls to sequence multiple
+            # animations by clearing `@done_proc` before the call
+            kept_done_proc = @done_proc
+            @done_proc = nil
+            kept_done_proc.call
           end
         end
-
-        set_frame
       end
+
+      set_frame
     end
 
-    def draw(opts = {})
+    # @param width [Numeric] The +width+ of drawn image
+    # @param height [Numeric] The +height+ of drawn image
+    # @param x [Numeric]
+    # @param y [Numeric]
+    # @param rotate [Numeric] Angle, default is 0
+    # @param color [Numeric] (or +colour+) Tint the image when rendering
+    # @param clip_x [Numeric]
+    # @param clip_x [Numeric]
+    # @param clip_width [Numeric]
+    # @param clip_height [Numeric]
+    def draw(x:, y:, width: (@width || @clip_width), height: (@height || @clip_height), rotate: @rotate,
+             clip_x: @clip_x, clip_y: @clip_y, clip_width: @clip_width, clip_height: @clip_height,
+             color: [1.0, 1.0, 1.0, 1.0])
+
       Window.render_ready_check
+      render(x: x, y: y, width: width, height: height, color: Color.new(color), rotate: rotate, crop: {
+               x: clip_x,
+               y: clip_y,
+               width: clip_width,
+               height: clip_height,
+               image_width: @img_width,
+               image_height: @img_height
+             })
+    end
+
+    private
+
+    def render(x: @x, y: @y, width: (@width || @clip_width), height: (@height || @clip_height),
+               color: @color, rotate: @rotate, flip: @flip,
+               crop: {
+                 x: @clip_x,
+                 y: @clip_y,
+                 width: @clip_width,
+                 height: @clip_height,
+                 image_width: @img_width,
+                 image_height: @img_height
+               })
+      update
+      vertices = Vertices.new(x, y, width, height, rotate, crop: crop, flip: flip)
+      @texture.draw vertices.coordinates, vertices.texture_coordinates, color
+    end
 
-      opts[:width] = opts[:width] || (@width || @clip_width)
-      opts[:height] = opts[:height] || (@height || @clip_height)
-      opts[:rotate] = opts[:rotate] || @rotate
-      opts[:clip_x] = opts[:clip_x] || @clip_x
-      opts[:clip_y] = opts[:clip_y] || @clip_y
-      opts[:clip_width] = opts[:clip_width] || @clip_width
-      opts[:clip_height] = opts[:clip_height] || @clip_height
-      unless opts[:color]
-        opts[:color] = [1.0, 1.0, 1.0, 1.0]
+    # Reset the playing animation to the first frame
+    def _reset_playing_animation
+      frames = @animations[@playing_animation]
+      case frames
+      # When animation is a range, play through frames horizontally
+      when Range
+        @first_frame   = frames.first || @defaults[:frame]
+        @current_frame = frames.first || @defaults[:frame]
+        @last_frame    = frames.last
+      # When array...
+      when Array
+        @first_frame   = 0
+        @current_frame = 0
+        @last_frame    = frames.length - 1
       end
+    end
 
-      render(x: opts[:x], y: opts[:y], width: opts[:width], height: opts[:height], color: Color.new(color), rotate: opts[:rotate], crop: {
-        x: opts[:clip_x],
-        y: opts[:clip_y],
-        width: opts[:clip_width],
-        height: opts[:clip_height],
-        image_width: @img_width,
-        image_height: @img_height,
-      })
+    # Set the current frame based on the region/portion of image
+    def _set_explicit_frame(frame)
+      @clip_x      = frame[:x]      || @defaults[:clip_x]
+      @clip_y      = frame[:y]      || @defaults[:clip_y]
+      @clip_width  = frame[:width]  || @defaults[:clip_width]
+      @clip_height = frame[:height] || @defaults[:clip_height]
+      @frame_time  = frame[:time]   || @defaults[:frame_time]
     end
 
-    private
+    # initialize texture and clipping, called by constructor
+    def _setup_texture_and_clip_box(atlas, clip_x, clip_y, clip_width, clip_height)
+      # Initialize the sprite texture
+      # Consider input pixmap atlas if supplied to load image file
+      @texture = Image.load_image_as_texture @path, atlas: atlas
+      @img_width = @texture.width
+      @img_height = @texture.height
 
-    def render(x: @x, y: @y, width: (@width || @clip_width), height: (@height || @clip_height) , color: @color, rotate: @rotate, flip: @flip, crop: {
-      x: @clip_x,
-      y: @clip_y,
-      width: @clip_width,
-      height: @clip_height,
-      image_width: @img_width,
-      image_height: @img_height,
-    })
-      update
+      # The clipping rectangle
+      @clip_x = clip_x
+      @clip_y = clip_y
+      @clip_width  = clip_width  || @img_width
+      @clip_height = clip_height || @img_height
+    end
 
-      vertices = Vertices.new(x, y, width, height, rotate, crop: crop, flip: flip)
+    # initialize animation, called by constructor
+    def _setup_animation
+      @start_time = 0.0
+      @playing = false
+      @last_frame = 0
+      @done_proc = nil
+
+      # Set the default animation
+      @animations[:default] = 0..(@img_width / @clip_width) - 1
 
-      @texture.draw(
-        vertices.coordinates, vertices.texture_coordinates, color
-      )
+      # Set the sprite defaults
+      @defaults = {
+        animation: @animations.first[0],
+        frame: @current_frame,
+        frame_time: @frame_time,
+        clip_x: @clip_x,
+        clip_y: @clip_y,
+        clip_width: @clip_width,
+        clip_height: @clip_height,
+        loop: @loop
+      }
     end
   end
 end

data/lib/ruby2d/square.rb

@@ -1,37 +1,38 @@
+# frozen_string_literal: true
+
 # Ruby2D::Square
 
 module Ruby2D
+  # A square
   class Square < Rectangle
-
     attr_reader :size
 
-    def initialize(opts = {})
-      @x = opts[:x] || 0
-      @y = opts[:y] || 0
-      @z = opts[:z] || 0
-      @width = @height = @size = opts[:size] || 100
-      self.color = opts[:color] || 'white'
-      self.color.opacity = opts[:opacity] if opts[:opacity]
-      update_coords(@x, @y, @size, @size)
-      add
+    # Create an square
+    # @param [Numeric] x
+    # @param [Numeric] y
+    # @param [Numeric] size is width and height
+    # @param [Numeric] z
+    # @param [String, Array] color A single colour or an array of exactly 4 colours
+    # @param [Numeric] opacity Opacity of the image when rendering
+    # @raise [ArgumentError] if an array of colours does not have 4 entries
+    def initialize(x: 0, y: 0, size: 100, z: 0, color: nil, colour: nil, opacity: nil)
+      @size = size
+      super(x: x, y: y, width: size, height: size, z: z,
+            color: color, colour: colour, opacity: opacity)
     end
 
     # Set the size of the square
-    def size=(s)
-      self.width = self.height = @size = s
+    def size=(size)
+      self.width = self.height = @size = size
     end
 
-    def self.draw(opts = {})
-      ext_draw([
-        opts[:x]              , opts[:y]              , opts[:color][0][0], opts[:color][0][1], opts[:color][0][2], opts[:color][0][3],
-        opts[:x] + opts[:size], opts[:y]              , opts[:color][1][0], opts[:color][1][1], opts[:color][1][2], opts[:color][1][3],
-        opts[:x] + opts[:size], opts[:y] + opts[:size], opts[:color][2][0], opts[:color][2][1], opts[:color][2][2], opts[:color][2][3],
-        opts[:x]              , opts[:y] + opts[:size], opts[:color][3][0], opts[:color][3][1], opts[:color][3][2], opts[:color][3][3]
-      ])
+    def self.draw(x:, y:, size:, color:)
+      super(x: x, y: y,
+            width: size, height: size,
+            color: color)
     end
 
     # Make the inherited width and height attribute accessors private
     private :width=, :height=
-
   end
 end