particlefx2d 0.3.0

data/lib/particlefx2d/emitter.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require_relative 'particle'
+
+module ParticleFX2D
+  #
+  # A particle effect emitter
+  #
+  class Emitter
+    attr_accessor :emission_rate, :particle_config
+
+    #
+    # Create a new particle emitter
+    #
+    # @param opts Options to configure the emitter as follows:
+    # - +quantity+ Number of total particles in the emitter's pool
+    # - +emission_rate+ Number of particles to emit per second
+    # - +particle_config+ Options are used to configure each particle when it is emitted, which are as follows:
+    #   - +x+ Initial x-axis position of emission
+    #   - +x_range+ optional range from which a random value is chosen to add to the initial +x+; default is 0
+    #   - +y+ Initial y-axis position of emission
+    #   - +y_range+ optional range from which a random value is chosen to add to the initial +y+; default is 0
+    #   - +start_color+ optional initial colour of the emitted particle. See `Particle` for default
+    #   - +end_color+ optional end colour of the particle by the end of its life. See `Particle` for default
+    #   - +start_scale+ optional initial size scale factor of the emitted particle relative to its +size+; default is 1
+    #   - +end_scale+ optional end size scale factor of the particle by the end of its life; default is 1
+    #   - +angle+  optional angle at which the particle is emitted, in degrees. See `Particle` for default
+    #   - +angle_range+ optional range from which a random value is chosen to add to the +angle+; default is 0
+    #   - +speed+  optional speed at which the particle is emitted, in pixels/s. See `Particle` for default
+    #   - +speed_range+ optional range from which a random value is chosen to add to the +speed+; default is 0
+    #   - +size+  optional size of the particle when emitted, in pixels. See `Particle` for default
+    #   - +size_range+ optional range from which a random value is chosen to add to the +size+; default is 0
+    #   - +gravity_x+ optional linear acceleration in pixels/second squared along the x axis, default is 0
+    #   - +gravity_y+ optional linear acceleration in pixels/second squared along the y axis, default is 0
+    #   - +radial_acceleration+ optional radial accelation in pixel/seconds squared, default is 0
+    #   - +tangential_acceleration+ optional tangential accelation in pixel/seconds squared, default is 0
+    #   - +life_time+ of each particle in seconds. See `Particle` for default
+    #   - +life_time_range+ optional range from which a random value is chosen to add to the +life_time+; default is 0
+    #
+    def initialize(opts = {})
+      @quantity = (opts[:quantity] || 128).to_i
+      @emission_rate = opts[:emission_rate].to_f
+      @emission = 0
+      @particle_config = opts[:particle_config]
+      @renderer_factory = opts[:renderer_factory]
+      setup_particle_pool
+    end
+
+    #
+    # Update the particle effect emission, called for each frame of the animation cycle.
+    #
+    # @param [Float] frame_time in seconds (essentially, 1 / fps)
+    #
+    def update(frame_time)
+      @renderer_factory.on_update_start
+      emit_particles frame_time
+      @active.each do |p|
+        p.update frame_time
+        free_particle p unless p.alive?
+      end
+      @renderer_factory.on_update_end
+    end
+
+    #
+    # Retrieve statistics about the emitter's current status
+    #
+    # @return A hash with the following properties:
+    # - +quantity+ The total number of particles in the emitter
+    # - +emission_rate+ The emission rate (particles per second)
+    # - +active+ The number of active particles
+    # - +unused+ The number of inactive particles in the pool
+    #
+    def stats
+      {
+        quantity: @quantity,
+        emission_rate: @emission_rate,
+        active: @active.count,
+        unused: @pool.count
+      }
+    end
+
+    private
+
+    # Initialize the particle pool; call once per emitter.
+    def setup_particle_pool
+      @active = []
+      @pool = []
+      @quantity.times do
+        p = Particle.new
+        renderer = @renderer_factory.renderer_for(p)
+        p.renderer! renderer
+        free_particle p
+      end
+    end
+
+    # For each update frame emit as many particles as specified by the emission rate.
+    # May emit less that the rate if there aren't enough particles in the pool
+    def emit_particles(frame_time)
+      return unless @emission_rate.positive?
+
+      rate = @emission_rate * frame_time
+      @emission += rate
+      while @active.count < @quantity && @emission > rate
+        new_particle
+        @emission -= 1
+      end
+    end
+
+    # Generate a value for a particle configuration range-based property.
+    #
+    # @return nil if no config with +prop_name+ is found
+    def config_range_value(prop_name, prop_range_name)
+      return nil unless @particle_config[prop_name.to_sym]
+
+      prop_range = @particle_config[prop_range_name.to_sym]
+      @particle_config[prop_name.to_sym] + (prop_range ? rand(prop_range) : 0)
+    end
+
+    # Retrieve a value for a particle configuration value-only property.
+    #
+    # @return nil if no config with +prop_name+ is found
+    def config_value(prop_name, prop_alt_name = nil)
+      @particle_config[prop_name.to_sym] || (@particle_config[prop_alt_name.to_sym] if prop_alt_name)
+    end
+
+    # Reset a particle based on the emitter's particle config.
+    # This is done before emitting a particle from the particle pool
+    def reset_particle(particle)
+      particle.reset! x: config_range_value(:x, :x_range),
+                      y: config_range_value(:y, :y_range),
+                      color: config_value(:start_color, :start_colour),
+                      end_color: config_value(:end_color, :end_colour),
+                      scale: config_value(:start_scale), end_scale: config_value(:end_scale),
+                      gravity_x: config_value(:gravity_x), gravity_y: config_value(:gravity_y),
+                      radial_acceleration: config_range_value(:radial_acceleration, :radial_acceleration_range),
+                      tangential_acceleration: config_range_value(:tangential_acceleration, :tangential_acceleration),
+                      size: config_range_value(:size, :size_range),
+                      speed: config_range_value(:speed, :speed_range),
+                      angle: config_range_value(:angle, :angle_range),
+                      life_time: config_range_value(:life_time, :life_time_range)
+    end
+
+    # Retrieve an unused particle from the pool, reset it,
+    # and show it's associated shape/peer
+    def new_particle
+      p = @pool.pop
+      return unless p
+
+      @active << p
+      reset_particle p
+      p.renderer&.show_particle(p)
+    end
+
+    # Return a particle back to the unused pool,
+    # and hide it's associated shape/peer
+    def free_particle(particle)
+      ix = @active.find_index particle
+      @active.delete_at ix unless ix.nil?
+      @pool.push particle
+      particle.renderer&.hide_particle(p)
+    end
+  end
+end

data/lib/particlefx2d/particle.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+require_relative 'private/vector2'
+require_relative 'private/color'
+
+module ParticleFX2D
+  #
+  # A single 2D particle.
+  #
+  class Particle
+    attr_reader :x, :y, :color, :end_color, :velocity, :speed, :angle, :life, :size, :renderer,
+                :gravity_x, :gravity_y, :radial_accel, :tangent_accel, :scale, :end_scale
+
+    # @!visibility private
+    # Create a new particle
+    #
+    # @param opts Options describing the particle. See #reset! for alll the properties.
+    #
+    def initialize(opts = {})
+      reset!(opts)
+    end
+
+    #
+    # Used by the _Emitter_ when re-using particles from the particle pool.
+    #
+    # @param opts Options describing the particle as follows:
+    # - +x+ defaults to 0
+    # - +y+ defaults to 0
+    # - +color+ or +colour+ array of particle's color components [r, g, b, a]; default is _[0, 1.0, 0, 1.0]_ (green)
+    # - +end_color+ or +end_colour+ array of particle's end color [r, g, b, a]; default is _[1.0, 0, 0, 1.0]_ (red)
+    # - +angle+ in degrees; default is 0
+    # - +speed+ in pixels per second; default is 100
+    # - +life_time+ in seconds; default is 100.0
+    # - +size+ in pixels; default is 5
+    # - +scale+ relative to size, default is 1
+    # - +end_scale+ particle's end scale relative to size; default is +scale+
+    # - +gravity_x+ in pixels/second squared along the x axis, default is 0
+    # - +gravity_y+ in pixels/second squared along the y axis, default is 0
+    # - +radial_acceleration+ in pixel/seconds squared, default is 0
+    # - +tangential_acceleration+ in pixel/seconds squared, default is 0
+    #
+    def reset!(opts = {})
+      @initial_life = @life = value_from(opts, :life_time, default: 100).to_f
+      @initial_size = @size = value_from(opts, :size, default: 5)
+      @gravity = Private::Vector2.new value_from(opts, :gravity_x, default: 0),
+                                      value_from(opts, :gravity_y, default: 0)
+      # following may depend on initial life and size
+      reset_forces opts
+      reset_scale_from opts
+      reset_position_from opts
+      reset_color_from opts
+      reset_velocity_from opts
+    end
+
+    #
+    # Set the rendering peer for the particle.
+    #
+    # @param renderer The renderer must implement following methods:
+    # - +show_particle(p)+ The specified particle is visible.
+    # - +hide_particle(p)+ The specified particle is no longer visible.
+    # - +draw_particle(p)+ Render the specified particle; this method is called only if a particle is visible.
+    #
+    def renderer!(renderer)
+      @renderer = renderer
+    end
+
+    #
+    # Returns true if the particle is considered alive
+    #
+    def alive?
+      @life.positive?
+    end
+
+    #
+    # Used by the _Emitter_ to update the particle by +frame_time+ seconds.
+    #
+    # @param [Float] frame_time in seconds
+    #
+    def update(frame_time)
+      @life -= frame_time
+      return unless alive?
+
+      @scale += @delta_scale * frame_time
+      @size = @initial_size * @scale
+      @color.add!(@delta_color, each_times: frame_time)
+      update_forces
+      update_motion frame_time
+      @renderer&.draw_particle self
+    end
+
+    private
+
+    # Calculates the number of pixels the particle should move
+    # based on its velocity and force of acceleration. Called per axis.
+    def accelerated_velocity(velocity, force_per_frame)
+      velocity + (force_per_frame.abs2 / 2)
+    end
+
+    # Update the force of acceleration based on configured gravity, radial accel and
+    # tangential accel if applicable.
+    def update_forces
+      @forces.copy! @gravity
+      return @forces if (@radial_accel.zero? && @tangent_accel.zero?) || (@x == @initial_x && @y == @initial_y)
+
+      @radial.set!(@x, @y)
+             .subtract!(@initial_x, @initial_y)
+             .normalize!
+      @tangential.copy!(@radial)
+                 .cross!
+                 .times!(@tangent_accel)
+      @forces.add_vector!(@radial.times!(@radial_accel))
+             .add_vector!(@tangential)
+    end
+
+    # Update the motion for a frame of animation based on the updated forces and velocity
+    def update_motion(frame_time)
+      @forces.times!(frame_time)
+      @x += accelerated_velocity @velocity.x * frame_time, @forces.x
+      @y += accelerated_velocity @velocity.y * frame_time, @forces.y
+      @velocity.add_vector! @forces
+    end
+
+    # Initialize position from configuration options
+    def reset_position_from(opts)
+      @initial_x = @x = value_from(opts, :x, default: 0)
+      @initial_y = @y = value_from(opts, :y, default: 0)
+    end
+
+    # Initialize scale factors from configuration options
+    def reset_scale_from(opts)
+      @initial_scale = @scale = value_from(opts, :scale, default: 1).to_f
+      @end_scale = value_from(opts, :end_scale, default: @initial_scale).to_f
+      @delta_scale = (@end_scale - @initial_scale) / @initial_life
+    end
+
+    # Initialize colours from configuration options
+    def reset_color_from(opts)
+      @initial_color = Private::Color.new(value_from(opts, :color, alt_name: :colour) || [0, 1.0, 0, 1.0])
+      @end_color = value_from(opts, :end_color, alt_name: :end_colour, default: @initial_color)
+      @color = Private::Color.new(@initial_color)
+      @delta_color = Private::Color.new(@end_color).subtract!(@initial_color).divide_by!(@initial_life)
+    end
+
+    # Convenient method to extract value for a particle configuration property
+    # if present.
+    def value_from(opts, name, default: nil, alt_name: nil)
+      value = opts[name.to_sym]
+      value ||= opts[alt_name.to_sym] unless alt_name.nil?
+      value ||= default
+      value
+    end
+
+    # Initialize velocity from configuration options
+    def reset_velocity_from(opts)
+      @angle = value_from(opts, :angle, default: 0).to_f
+      @angle_in_radians = nil
+      @speed = value_from(opts, :speed, default: 100).to_f
+      @velocity ||= Private::Vector2.new
+      angle_rad = @angle * Math::PI / 180
+      @velocity.set! @speed * Math.cos(angle_rad),
+                     -@speed * Math.sin(angle_rad)
+    end
+
+    # Initialize forces from configuration options
+    def reset_forces(opts)
+      @radial ||= Private::Vector2.new
+      @tangential ||= Private::Vector2.new
+      @forces ||= Private::Vector2.new
+      @radial_accel = value_from(opts, :radial_acceleration, default: 0)
+      @tangent_accel = value_from(opts, :tangential_acceleration, default: 0)
+    end
+  end
+end

data/lib/particlefx2d/private/color.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+#
+# 2D Particle Effects
+#
+module ParticleFX2D
+  # @!visibility private
+  module Private
+    # @!visibility private
+    #
+    # RGBA colour representation by its four components, for internal use only.
+    #
+    class Color
+      attr_accessor :r, :g, :b, :a
+
+      def initialize(other)
+        case other
+        when Array
+          @r = other[0].to_f
+          @g = other[1].to_f
+          @b = other[2].to_f
+          @a = other[3].to_f
+        else
+          @r = other.r
+          @g = other.g
+          @b = other.b
+          @a = other.a
+        end
+      end
+
+      alias opacity a
+      alias opacity= a=
+
+      def to_a
+        [@r, @g, @b, @a]
+      end
+
+      def subtract!(other)
+        case other
+        when Numeric
+          @r -= other
+          @g -= other
+          @b -= other
+          @a -= other
+        else
+          @r -= other.r
+          @g -= other.g
+          @b -= other.b
+          @a -= other.a
+        end
+        self
+      end
+
+      def add!(other, each_times: 1)
+        case other
+        when Numeric
+          value = other * each_times
+          @r += value
+          @g += value
+          @b += value
+          @a += value
+        else
+          @r += other.r * each_times
+          @g += other.g * each_times
+          @b += other.b * each_times
+          @a += other.a * each_times
+        end
+        self
+      end
+
+      def divide_by!(other)
+        case other
+        when Numeric
+          @r /= other
+          @g /= other
+          @b /= other
+          @a /= other
+        else
+          @r /= other.r
+          @g /= other.g
+          @b /= other.b
+          @a /= other.a
+        end
+        self
+      end
+    end
+  end
+end

data/lib/particlefx2d/private/vector2.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module ParticleFX2D
+  # @!visibility private
+  module Private
+    # @!visibility private
+    #
+    # A 2D vector, for internal use only
+    #
+    class Vector2
+      attr_reader :x, :y
+
+      def self.copy(vector)
+        Vector.new(vector.x, vector.y)
+      end
+
+      def initialize(x = 0, y = 0)
+        @x = x
+        @y = y
+      end
+
+      def set!(x, y)
+        @x = x
+        @y = y
+        self
+      end
+
+      def copy!(other)
+        @x = other.x
+        @y = other.y
+        self
+      end
+
+      def add!(x, y)
+        @x += x
+        @y += y
+        self
+      end
+
+      def subtract!(x, y)
+        @x -= x
+        @y -= y
+        self
+      end
+
+      def times!(value)
+        @x *= value
+        @y *= value
+        self
+      end
+
+      def divide_by!(value)
+        @x /= value
+        @y /= value
+        self
+      end
+
+      def add_vector!(other)
+        @x += other.x
+        @y += other.y
+        self
+      end
+
+      def minus_vector!(other)
+        @x -= other.x
+        @y -= other.y
+        self
+      end
+
+      def magnitude
+        Math.sqrt(@x.abs2 + @y.abs2)
+      end
+
+      def cross!
+        set! @y, -@x
+      end
+
+      def normalize!
+        mag = magnitude
+        mag = Float::INFINITY if mag.zero?
+        divide_by! mag
+      end
+    end
+  end
+end

data/lib/particlefx2d/renderer.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module ParticleFX2D
+  # Defines a particle renderer. Depending on the graphics system used to
+  # render the particle effects, you can implement either one single renderer per
+  # emitter that does the drawing implement a renderer per particle.
+  module Renderer
+    # Factory method to provide a renderer for a particle. Called once per particle.
+    # The particle system does not care if the factory returns a shared renderer for all the
+    # particles or if it returns one per particle. Each particle will be associated with the
+    # renderer.
+    def self.for(_particle)
+      raise StandardError('unimplemented')
+    end
+
+    # instance methods per Renderer
+
+    # Notifies the renderer that a particle is visible.
+    def show_particle(_particle)
+      raise StandardError('unimplemented')
+    end
+
+    # Notifies the renderer that a particle is hidden.
+    def hide_particle(_particle)
+      raise StandardError('unimplemented')
+    end
+
+    # Requests the render to draw the particle (or update the particle's rendering
+    # peer with the particle's visual attributes.)
+    def draw_particle(_particle)
+      raise StandardError('unimplemented')
+    end
+  end
+end

data/lib/particlefx2d/renderer_factory.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative 'renderer'
+
+module ParticleFX2D
+  # Defines a RendererFactory. Each emitter should have it's own
+  # factory which is called once per particle to create a Renderer.
+  # It is possible for a factory to
+  # * EITHER return the same Renderer for all particles and handle the drawing for the particles;
+  # * OR return a renderer per particle.
+  module RendererFactory
+    # Return a particle renderer.
+    #
+    # @return [Renderer] for each particle
+    def renderer_for(_particle)
+      raise StandardError('unimplemented')
+    end
+
+    #
+    # Called once per update cycle by the emitter to let the factory know that
+    # all the particles are about to be updated and redrawn.
+    # A shared renderer factory can use this to clear the underlying surface, for example.
+    # A per-particle renderer factory can ignore this method as by default it does nothing.
+    def on_update_start
+      # Does nothing by default.
+    end
+
+    #
+    # Called once per update cycle by the emitter to let the factory know that
+    # an update cycle is complete.
+    # A shared renderer factory can use this to commit the changes made, for example.
+    # A per-particle renderer factory can ignore this method as by default it does nothing.
+    def on_update_end
+      # Does nothing by default.
+    end
+  end
+end

data/lib/particlefx2d/ruby2d/canvas_renderer_factory.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require_relative '../renderer_factory'
+
+module ParticleFX2D
+  module Ruby2D
+    # A shared surface renderer that uses Ruby2D's _Canvas_ to draw into. This is both
+    # a factory and the renderer/
+    #
+    # This approach uses the same renderer for all particles in an emitter.
+    class CanvasRendererFactory
+      include ParticleFX2D::RendererFactory
+      include ParticleFX2D::Renderer
+
+      # ----- Factory
+
+      # Instantiate a shape renderer factory.
+      #
+      # @param [Ruby2D::Canvas] canvas The partice effects will be drawn into this canvas. Disable auto-update for
+      #                                the Canvas so that each attempt to draw into it will not cause a texture update.
+      def initialize(canvas)
+        @canvas = canvas
+      end
+
+      # Return a particle renderer.
+      #
+      # @return [Renderer] for each particle
+      def renderer_for(_particle)
+        self
+      end
+
+      # Clear the canvas before the next update cycle
+      def on_update_start
+        @canvas.draw_rectangle(x: 0, y: 0,
+                               width: @canvas.width, height: @canvas.height,
+                               color: [0, 0, 0, 0])
+      end
+
+      # Update the canvas at the end of the next update cycle
+      def on_update_end
+        @canvas.update
+      end
+
+      # ----- Renderer
+
+      # Show the particle. Used when a particle is activated.
+      def show_particle(_particle); end
+
+      # Hide the particle. Used when a particle is deactivated.
+      def hide_particle(_particle); end
+
+      # Updates the shape's properties; no explicit drawing needed.
+      def draw_particle(particle)
+        size = particle.size
+        x = particle.x - (size / 2)
+        y = particle.y - (size / 2)
+        @canvas.draw_rectangle(x: x, y: y,
+                               width: size, height: size,
+                               color: particle.color.to_a)
+      end
+    end
+  end
+end

data/lib/particlefx2d/ruby2d/particle_circle.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative 'shape_renderer'
+
+module ParticleFX2D
+  module Ruby2D
+    #
+    # A particle shape that is based on the Ruby2D _Circle_ shape.
+    class ParticleCircle < ::Ruby2D::Circle
+      include ShapeRenderer
+
+      # Called by the emitter for each particle that it manages. Creates an instance
+      # of _ParticleCircle_ intialized with the particle's position, size and colour.
+      #
+      # @param [ParticleFX2D::Particle] particle
+      #
+      def self.for(particle)
+        s = ParticleCircle.new x: particle.x, y: particle.y,
+                               radius: particle.size / 2
+        s.color! particle.color
+        s.remove
+        s
+      end
+
+      # Sets the circle's position using the incoming centre coordinates.
+      def center!(centre_x, centre_y)
+        self.x = centre_x
+        self.y = centre_y
+      end
+
+      # Sets the radius using the particle size and calls #super
+      def draw_particle(particle)
+        self.radius = particle.size / 2
+        super
+      end
+    end
+  end
+end