minigl 2.4.3 → 2.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 46eaeb260b03c9bcfbac716d7568b01c081d66760d71dc540ca9046050f7d89d
-  data.tar.gz: 3de3cd79bd21324af047f1705d641374e92c986ec0f02badf0a5fd9206f228e8
+  metadata.gz: 6078cf1c0aafd790460ec6b7723dff865c0a2e78a8359fd8734cd8a6a07aec60
+  data.tar.gz: 61be9170370e9b912a7c3a7087ca145de121f36b005abf62bfe193ca1dc29ec3
 SHA512:
-  metadata.gz: 33675d555bd833c359f548bff9c16ef95da819ecc084ecbc657c60016d5e3d18255cd19da03252b212e53bb8600a5a0c4c9f4ab4893261377a7f4f20a03d991b
-  data.tar.gz: 3f9ed35d874c81bca4544a42c7f6106c0f3b26ba69bf5bfcba59f201297588be32aa6a2f697f2ea4ffde846e8f46fd2d42c5bc68142ec925cf9f8cd6bc5542cf
+  metadata.gz: 68d1060caaf63cfe944a924b692c38680833a15fa49412060295904e630d8b73e5b6342abf4febf1ff6d9324e88f61e0a34fa5c9014e70b376cafa10402e0df5
+  data.tar.gz: ff9db71adca879e4ec8b7044c1864477befb45eff207cdd0dc2b1ff3d97d4f6f3f0255e1d61e6705293d7ab3d490c484543f40cd861545cf1936b5b09d2da590

data/README.md

@@ -10,6 +10,7 @@ It provides the following features:
   * UI (text, buttons, text fields, drop-down lists, progress bars)
   * Basic physics and collision checking
   * Animated objects
+  * Particle systems
 
 More functionalities are coming. Feel free to contribute! You can send feedback
 to victordavidsantos@gmail.com.
@@ -38,13 +39,17 @@ After installing the Gosu dependencies, you can just `gem install minigl`.
 
 ## Documentation
 
-  * The library is 100% RDoc-documented [here](http://www.rubydoc.info/gems/minigl).
+  * The library is 100% RDoc-documented [here](https://www.rubydoc.info/gems/minigl).
   * The [wiki](https://github.com/victords/minigl/wiki) is a work in progress with tutorials and examples.
   * Test package and examples aren't complete!
 
-## Version 2.4.3
+## Version 2.5.0
 
-  * Fixed a collision checking bug in `Movement#move`.
+  * Added `Particles` (particle system) class. Run `test/particles_game.rb` to check its capabilities!
+
+### Version 2.5.1
+
+  Patch fixing the required Ruby version (>= 3.1).
 
 ## Contributing
 

data/lib/minigl/particles.rb

@@ -0,0 +1,313 @@
+module MiniGL
+  # A particle system.
+  class Particles
+    # Create a new particle system.
+    # Options:
+    # - x: x-coordinate of the origin of the particle system. If +source+ is
+    #   set, it has precedence.
+    # - y: y-coordinate of the origin of the particle system. If +source+ is
+    #   set, it has precedence.
+    # - source: if set, must be an object that responds to +x+ and +y+. The
+    #   position of the particle system will be updated to this object's
+    #   position on initialization and every time +update+ is called.
+    # - emission_interval (Integer|Range): interval in frames between each
+    #   particle emission. It can be a fixed value or a range, in which case
+    #   the interval will be a random value within that range (a new value
+    #   before each emission). Default: 10.
+    # - emission_rate (Integer|Range): how many particles will be emitted at a
+    #   time. It can be a fixed value or a range, in which case a random number
+    #   of particles in that range will be emitted each time. Default: 1.
+    # - duration (Integer): how many frames each particle will live. Default: 30.
+    # - shape (Symbol|nil): one of +:square+, +:triangle_up+, or
+    #   +:triangle_down+, to emit basic shapes (if the +img+ option is set, it
+    #   has precedence). Shape particles don't support rotation. Either this or
+    #   +img+ must be set.
+    # - img (Gosu::Image|nil): image of the particle, has precedence over
+    #   +shape+. Either this or +shape+ must be set.
+    # - scale (Numeric): fixed scale of each particle, ignored if +scale_change+
+    #   is set to a valid value. Default: 1.
+    # - scale_change (Symbol|nil): one of +:grow+, +:shrink+, or +:alternate+,
+    #   indicates how the scale of the particle will change over time. +:grow+
+    #   will cause the scale to change from +scale_min+ to +scale_max+;
+    #   +:shrink+ will cause the scale to change from +scale_max+ to
+    #   +scale_min+; +:alternate+ will cause the scale to first go from
+    #   +scale_min+ to +scale_max+, in <code>scale_inflection * duration</code>
+    #   frames, and then back to +scale_min+ in the remaining frames. All
+    #   changes are linear over time.
+    # - scale_min (Numeric): minimum scale, to be used together with
+    #   +scale_change+. Default: 0.
+    # - scale_max (Numeric): maximum scale, to be used together with
+    #   +scale_change+. Default: 1.
+    # - scale_inflection (Numeric): should be a number between 0 and 1, to be
+    #   used with +scale_change+ set to +:alternate+. Default: 0.5.
+    # - alpha (Numeric): fixed alpha of each particle, ignored if +alpha_change+
+    #   is set to a valid value. Default: 255.
+    # - alpha_change, alpha_min, alpha_max, alpha_inflection: behave the same
+    #   way as the corresponding properties for +scale+. Default +alpha_max+ is
+    #   255.
+    # - angle (Numeric|Range|nil): initial rotation angle of each particle in
+    #   degrees. Can be a fixed value or a range, in which case the initial
+    #   rotation will be a random value within that range. Default: nil (no
+    #   rotation).
+    # - rotation(Numeric|nil): how much each particle will rotate each frame,
+    #   in degrees. Default: nil (no rotation).
+    # - speed (Vector|Hash|nil): specifies how the particle will move each
+    #   frame. It can be a +Vector+, in which case the particle will move a
+    #   fixed amount (corresponding to the +x+ and +y+ values of the vector)
+    #   or a +Hash+ with +:x+ and +:y+ keys, in this case the value can be
+    #   fixed or a range, for random movement. Default: nil (no movement).
+    # - color (Integer): color to tint the particles, in the 0xRRGGBB format.
+    #   Default: 0xffffff (white, no tinting).
+    # - round_position (Boolean): only draw particles in integer positions.
+    #   Default: true.
+    def initialize(**options)
+      raise "Particles must have either a shape or an image!" if options[:shape].nil? && options[:img].nil?
+
+      @options = DEFAULT_OPTIONS.merge(options)
+      @x = @options[:source]&.x || @options[:x] || 0
+      @y = @options[:source]&.y || @options[:y] || 0
+
+      @particles = []
+      @emitting = false
+    end
+
+    # Starts emitting particles. This returns +self+, so you can create, start,
+    # and assign a particle system to a variable like this:
+    # <code>@p_system = Particles.new(...).start</code>
+    def start
+      set_emission_time
+      @timer = @emission_time
+      @emitting = true
+      self
+    end
+
+    # Stops emitting new particles. The existing particles will still be kept
+    # alive until they hit +duration+ frames.
+    def stop
+      @emitting = false
+    end
+
+    # Returns a boolean indicating whether this particle system is currently
+    # emitting particles.
+    def emitting?
+      @emitting
+    end
+
+    # Returns the current particle count.
+    def count
+      @particles.size
+    end
+
+    # Updates the particle system. This should be called in the +update+ loop
+    # of the game.
+    def update
+      @particles.each do |particle|
+        particle.update
+        @particles.delete(particle) if particle.dead?
+      end
+      return unless @emitting
+
+      if @options[:source]
+        @x = @options[:source].x
+        @y = @options[:source].y
+      end
+
+      @timer += 1
+      if @timer >= @emission_time
+        count = @options[:emission_rate].is_a?(Range) ? rand(@options[:emission_rate]) : @options[:emission_rate]
+        count.times do
+          x = @options[:area] ? @x + rand * @options[:area].x : @x + @options[:spread] * (rand - 0.5)
+          y = @options[:area] ? @y + rand * @options[:area].y : @y + @options[:spread] * (rand - 0.5)
+          @particles << Particle.new(x:,
+                                     y:,
+                                     duration: @options[:duration],
+                                     shape: @options[:shape],
+                                     img: @options[:img],
+                                     **@options.slice(*PARTICLE_OPTIONS))
+        end
+        set_emission_time
+        @timer = 0
+      end
+    end
+
+    # Draws the particles.
+    # Parameters:
+    # - map (Map|nil): a map whose camera will be used to determine the
+    #   position of particles in the screen.
+    # - z_index (Integer): z-index to draw the particles. Default: 0.
+    def draw(map = nil, z_index = 0)
+      @particles.each do |particle|
+        particle.draw(map, z_index)
+      end
+    end
+
+    private
+
+    # :nodoc:
+    DEFAULT_OPTIONS = {
+      x: 0,
+      y: 0,
+      source: nil,
+      emission_interval: 10,
+      emission_rate: 1,
+      duration: 30,
+      shape: nil,
+      img: nil,
+      spread: 0,
+      scale: 1,
+      scale_change: nil,
+      scale_min: 0,
+      scale_max: 1,
+      scale_inflection: 0.5,
+      alpha: 255,
+      alpha_change: nil,
+      alpha_min: 0,
+      alpha_max: 255,
+      alpha_inflection: 0.5,
+      angle: nil,
+      rotation: nil,
+      speed: nil,
+      color: 0xffffff,
+      round_position: true,
+    }.freeze
+
+    # :nodoc:
+    PARTICLE_OPTIONS = %i[
+      scale
+      scale_change
+      scale_min
+      scale_max
+      scale_inflection
+      alpha
+      alpha_change
+      alpha_min
+      alpha_max
+      alpha_inflection
+      angle
+      rotation
+      speed
+      color
+      round_position
+    ].freeze
+
+    def set_emission_time # :nodoc:
+      interval = @options[:emission_interval]
+      @emission_time = interval.is_a?(Range) ? rand(interval) : interval
+    end
+
+    class Particle # :nodoc:
+      def initialize(x:, y:, duration:, shape: nil, img: nil, **options)
+        @x = x
+        @y = y
+        @duration = duration
+        @shape = shape
+        @img = img
+        @options = DEFAULT_OPTIONS.slice(*PARTICLE_OPTIONS).merge(options)
+        @elapsed_time = 0
+
+        if @options[:angle].is_a?(Range)
+          @angle = rand(@options[:angle])
+        elsif @options[:angle].is_a?(Numeric)
+          @angle = @options[:angle]
+        end
+
+        if @options[:speed].is_a?(Hash)
+          speed_x = @options[:speed][:x].is_a?(Range) ? rand(@options[:speed][:x]) : (@options[:speed][:x] || 0)
+          speed_y = @options[:speed][:y].is_a?(Range) ? rand(@options[:speed][:y]) : (@options[:speed][:y] || 0)
+          @speed = Vector.new(speed_x, speed_y)
+        elsif @options[:speed].is_a?(Vector)
+          @speed = @options[:speed]
+        end
+
+        init_variable_property(:scale)
+        init_variable_property(:alpha)
+      end
+
+      def init_variable_property(name)
+        ivar_name = "@#{name}".to_sym
+        case @options["#{name}_change".to_sym]
+        when :grow, :alternate
+          instance_variable_set(ivar_name, @options["#{name}_min".to_sym])
+        when :shrink
+          instance_variable_set(ivar_name, @options["#{name}_max".to_sym])
+        else
+          instance_variable_set(ivar_name, @options[name.to_sym])
+        end
+      end
+
+      def update_variable_property(name)
+        ivar_name = "@#{name}".to_sym
+        min = @options["#{name}_min".to_sym]
+        max = @options["#{name}_max".to_sym]
+        case @options["#{name}_change".to_sym]
+        when :grow
+          instance_variable_set(ivar_name, min + (@elapsed_time.to_f / @duration) * (max - min))
+        when :shrink
+          instance_variable_set(ivar_name, max - (@elapsed_time.to_f / @duration) * (max - min))
+        when :alternate
+          inflection_point = (@options["#{name}_inflection".to_sym] * @duration).round
+          if @elapsed_time >= inflection_point
+            instance_variable_set(ivar_name, min + (@duration - @elapsed_time).to_f / (@duration - inflection_point) * (max - min))
+          else
+            instance_variable_set(ivar_name, min + (@elapsed_time.to_f / inflection_point) * (max - min))
+          end
+        end
+      end
+
+      def dead?
+        @elapsed_time >= @duration
+      end
+
+      def update
+        if @options[:rotation] && !@img.nil?
+          @angle = 0 if @angle.nil?
+          @angle += @options[:rotation]
+          @angle -= 360 if @angle >= 360
+        end
+
+        if @speed
+          @x += @speed.x
+          @y += @speed.y
+        end
+
+        update_variable_property(:scale) if @options[:scale_change]
+        if @options[:alpha_change]
+          update_variable_property(:alpha)
+          @alpha = @alpha.round
+        end
+
+        @elapsed_time += 1
+      end
+
+      def draw(map, z_index)
+        x = @x - (map&.cam&.x || 0)
+        y = @y - (map&.cam&.y || 0)
+        if @options[:round_position]
+          x = x.round
+          y = y.round
+        end
+        color = (@alpha << 24) | @options[:color]
+        if @img
+          if @angle
+            @img.draw_rot(x, y, z_index, @angle, 0.5, 0.5, @scale, @scale, color)
+          else
+            @img.draw(x - @img.width * @scale * 0.5, y - @img.height * @scale * 0.5, z_index, @scale, @scale, color)
+          end
+        else
+          case @shape
+          when :square
+            G.window.draw_rect(@x - @scale * 0.5, @y - @scale * 0.5, @scale, @scale, color, z_index)
+          when :triangle_up
+            G.window.draw_triangle(@x - @scale * 0.5, @y + @scale * 0.433, color,
+                                   @x + @scale * 0.5, @y + @scale * 0.433, color,
+                                   @x, @y - @scale * 0.433, color, z_index)
+          when :triangle_down
+            G.window.draw_triangle(@x - @scale * 0.5, @y - @scale * 0.433, color,
+                                   @x + @scale * 0.5, @y - @scale * 0.433, color,
+                                   @x, @y + @scale * 0.433, color, z_index)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/minigl.rb

@@ -3,3 +3,4 @@ require_relative 'minigl/map'
 require_relative 'minigl/text'
 require_relative 'minigl/forms'
 require_relative 'minigl/localization'
+require_relative 'minigl/particles'

data/test/particles_game.rb

@@ -0,0 +1,70 @@
+require_relative '../lib/minigl'
+
+include MiniGL
+
+class MyGame < GameWindow
+  class Source
+    attr_accessor :x, :y
+
+    def initialize(x, y)
+      @x = x
+      @y = y
+    end
+  end
+
+  def initialize
+    super(800, 600, false)
+    @source = Source.new(100, 100)
+    @particles_systems = [
+      Particles.new(
+        source: @source,
+        img: Res.img(:square),
+        duration: 30,
+        spread: 50,
+        emission_rate: 5,
+        color: 0x00ffff,
+        scale_change: :grow,
+        alpha_change: :shrink,
+        speed: { x: -1..1, y: -2..2 },
+        rotation: 1,
+        angle: 0..89
+      ),
+      Particles.new(
+        x: 400,
+        y: 100,
+        shape: :triangle_down,
+        spread: 50,
+        emission_interval: 8,
+        emission_rate: 1..3,
+        scale: 40,
+        color: 0xffff00,
+        alpha_change: :alternate,
+      ),
+    ]
+    @particles_systems.each(&:start)
+  end
+
+  def update
+    KB.update
+    @source.x -= 3 if KB.key_down?(Gosu::KB_LEFT)
+    @source.x += 3 if KB.key_down?(Gosu::KB_RIGHT)
+    @source.y -= 3 if KB.key_down?(Gosu::KB_UP)
+    @source.y += 3 if KB.key_down?(Gosu::KB_DOWN)
+
+    if KB.key_pressed?(Gosu::KB_SPACE)
+      if @particles_systems[1].emitting?
+        @particles_systems[1].stop
+      else
+        @particles_systems[1].start
+      end
+    end
+
+    @particles_systems.each(&:update)
+  end
+
+  def draw
+    @particles_systems.each(&:draw)
+  end
+end
+
+MyGame.new.show

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: minigl
 version: !ruby/object:Gem::Version
-  version: 2.4.3
+  version: 2.5.1
 platform: ruby
 authors:
 - Victor David Santos
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-03-30 00:00:00.000000000 Z
+date: 2023-10-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: gosu
@@ -46,6 +46,7 @@ files:
 - lib/minigl/localization.rb
 - lib/minigl/map.rb
 - lib/minigl/movement.rb
+- lib/minigl/particles.rb
 - lib/minigl/text.rb
 - test/collision.rb
 - test/data/font/font1.ttf
@@ -82,6 +83,7 @@ files:
 - test/map_tests.rb
 - test/mov_game.rb
 - test/movement_tests.rb
+- test/particles_game.rb
 - test/res_tests.rb
 - test/test.png
 - test/vector_tests.rb
@@ -97,14 +99,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.0'
+      version: '3.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.15
+rubygems_version: 3.4.10
 signing_key: 
 specification_version: 4
 summary: MiniGL
@@ -117,6 +119,7 @@ test_files:
 - test/map_tests.rb
 - test/mov_game.rb
 - test/movement_tests.rb
+- test/particles_game.rb
 - test/res_tests.rb
 - test/vector_tests.rb
 - test/test.png