osb 1.0.3 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dae3bb6b24e591176075dcfaeb67dc5e74c625c668e44dd91e8f35b660973222
-  data.tar.gz: 30a7304fe4b0c47a81d9a55ea0cc91d5e60775ab06f01aa85e4d76c46b241c0c
+  metadata.gz: 9ac326d1ca7ffd249550ff8762b4b8f1f3a56aad69dd567a5f4146938ae9ca70
+  data.tar.gz: e832ae17332a76d259c2813da3d5f602945bf9017f00080539042d7225caa029
 SHA512:
-  metadata.gz: 7fd1cc3edbf6bc0995eb04951ac640ca7d583130e36e46b8b9aa801cbbdbd040cbcd41f1b1ea2eff477361f9af39f7775487b80b65332737df0a7055830c877e
-  data.tar.gz: 3d4a452f5fdc3002e544d5ffc32542fa850f792dc01e19da19a32ae506da120fccfdf49d68c2c6d25534320d9406bdf575a67d63c1b1904a98878f26be9c1424
+  metadata.gz: 1620c4004ef265061b2060969b115d02c28d848dd9f99cf1f3ef9045d3a5ce809025266a1637dbf19c72201d9c56dd10f618af81a8fede0cfe7caf8fca53962f
+  data.tar.gz: af61c900d6ced4c4f19007a1b569e96fcd089f64e9f2f2a8503095746ad195c5334a0abd847ef98d8bc75558afb16f7bb874f9ad063b1213370d40ddc2962d7c

data/.yardopts

@@ -0,0 +1,3 @@
+--no-private
+-
+README.md

data/README.md

@@ -0,0 +1,64 @@
+# osb
+A simple osu! storyboard framework written in Ruby.
+
+## Installation
+
+Install with Gem:
+```sh
+gem install osb
+```
+
+## Usage
+
+Create a storyboard container:
+```rb
+require "osb"
+include Osb
+sb = Storyboard.new
+```
+
+Create a static image:
+```rb
+sp = Sprite.new(file_path: "test.png")
+```
+
+Describe what it does:
+```rb
+sp.fade(start_time: 1000, start_opacity: 1)
+sp.move(start_time: 2000, start_position: [320, 640], end_position: [100, 100])
+sp.scale(start_time: 100, end_time: 200, start_scale: 1, end_scale: 2)
+```
+
+Add it to the container:
+```rb
+sb << sp
+```
+
+Generate your storyboard file:
+```rb
+sb.generate("path/to/your_storyboard_file.osb")
+```
+
+osb also supports DSL syntax.
+
+```rb
+storyboard do
+  out_path "path/to/your_storyboard_file.osb"
+
+  sprite file_path: "test.png" do
+    fade start_time: 1000, start_opacity: 1
+    
+    move start_time: 2000, start_position: [320, 640], end_position: [100, 100]
+  end
+end
+```
+
+Full documentation is available at https://rubydoc.info/gems/osb/index.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/nanachi-code/osb-ruby.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/osb/animation.rb

@@ -3,7 +3,7 @@
 module Osb
   # A moving image.
   class Animation
-    # @api private
+    # @private
     attr_reader :commands, :layer
     include Commandable
 

data/lib/osb/assert.rb

@@ -1,20 +1,20 @@
 # frozen_string_literal: true
 
 module Osb
-  # @api private
+  # @private
   class TypeError < StandardError
   end
 
-  # @api private
+  # @private
   class InvalidValueError < StandardError
   end
 
-  # @api private
+  # @private
   module Internal
-    # @api private
+    # @private
     Boolean = [TrueClass, FalseClass]
 
-    # @api private
+    # @private
     class TypedArray
       # @param [Class] type
       def initialize(type)
@@ -30,16 +30,21 @@ module Osb
       end
     end
 
-    # @api private
+    # @private
     # @type [Hash{Class => Hash{Class => Object}}]
-    T = { Array => { Numeric => TypedArray.new(Numeric) } }
+    T = {
+      Array => {
+        Numeric => TypedArray.new(Numeric),
+        Integer => TypedArray.new(Integer)
+      }
+    }
 
     # Check if supplied argument is correctly typed.
     # @param [Object] arg
     # @param [BasicObject, Array, TypedArray] possible_types
     # @param [String] param_name
     # @return [void]
-    # @api private
+    # @private
     def self.assert_type!(arg, possible_types, param_name)
       if possible_types.is_a?(Array)
         valid =
@@ -75,7 +80,7 @@ module Osb
     # @param [BasicObject, Array, Range] possible_values
     # @param [String] param_name
     # @return [void]
-    # @api private
+    # @private
     def self.assert_value!(arg, possible_values, param_name)
       val =
         if arg.is_a?(String) && arg.empty?
@@ -113,7 +118,7 @@ module Osb
     # Ensure the file name extenstion is correct.
     # @param [String] file_name
     # @param [String, Array<String>] exts
-    # @api private
+    # @private
     def self.assert_file_name_ext!(file_name, exts)
       if exts.is_a?(Array)
         exts_ = exts.join("|")

data/lib/osb/background.rb

@@ -1,7 +1,9 @@
+# frozen_string_literal: true
+
 module Osb
   # Beatmap's background.
   class Background
-    # @api private
+    # @private
     attr_reader :command
 
     # @param [String] file_name location of the background image relative to the beatmap directory.

data/lib/osb/color.rb

@@ -11,36 +11,52 @@ module Osb
     # @attribute [rw] b
     #   @return Blue value.
 
-    # @param [Integer] r red value
+    # @param [Integer, String, Array<Integer>] r red value, a hex +String+, 
+    #   or an +Array+ of 3 +{Integer}+s.
     # @param [Integer] g green value
     # @param [Integer] b blue value
-    def initialize(r, g, b)
-      Internal.assert_type!(r, Integer, "r")
-      Internal.assert_value!(r, 0..255, "r")
+    def initialize(r, g = nil, b = nil)
+      Internal.assert_type!(
+        r,
+        [Integer, String, Internal::T[Array][Integer]],
+        "r"
+      )
+      if r.is_a?(Array)
+        if r.size != 3
+          raise InvalidValueError, "Must be an Array of 3 Integers."
+        end
+        @r = r[0]
+        @g = r[1]
+        @b = r[2]
+      elsif r.is_a?(String)
+        Color.from_hex(r)
+      else
+        Internal.assert_value!(r, 0..255, "r")
 
-      Internal.assert_type!(g, Integer, "g")
-      Internal.assert_value!(g, 0..255, "g")
+        Internal.assert_type!(g, Integer, "g")
+        Internal.assert_value!(g, 0..255, "g")
 
-      Internal.assert_type!(b, Integer, "b")
-      Internal.assert_value!(b, 0..255, "b")
+        Internal.assert_type!(b, Integer, "b")
+        Internal.assert_value!(b, 0..255, "b")
 
-      @r = r
-      @g = g
-      @b = b
+        @r = r
+        @g = g
+        @b = b
+      end
     end
 
     # Returns whether 2 colors are not equal.
     # @param [Color] color
     def !=(color)
       Internal.assert_type!(color, Color, "color")
-      
+
       color.r != self.r && color.g != self.g && color.b != self.b
     end
 
     # Converts an HSL color value to RGB.
-    # @param [Integer] h
-    # @param [Integer] s
-    # @param [Integer] l
+    # @param [Integer] hue
+    # @param [Integer] saturation
+    # @param [Integer] lightness
     # @return [Color]
     def self.from_hsl(h, s, l)
       Internal.assert_type!(h, Integer, "h")
@@ -70,7 +86,7 @@ module Osb
       Color.new((r * 255).round, (g * 255).round, (b * 255).round)
     end
 
-    # @api private
+    # @private
     # @param [Float] p
     # @param [Float] q
     # @param [Float] t_
@@ -84,7 +100,7 @@ module Osb
       return p
     end
 
-    # Create a Color object from hex string.
+    # Create a +{Color}+ object from hex string.
     # @param [String] hex
     # @return [Color]
     def self.from_hex(hex)
@@ -95,4 +111,23 @@ module Osb
       components.collect { |component| component.to_i(16) }
     end
   end
+
+  # Create a new rgb +{Color}+.
+  # @param [Integer, String, Array<Integer>] r red value, a hex +String+, 
+  #   or an +Array+ of 3 +{Integer}+s.
+  # @param [Integer] g green value
+  # @param [Integer] b blue value
+  # @return [Color]
+  def rgb(r, g = nil, b = nil)
+    Color.new(r, g, b)
+  end
+
+  # Create a new hsl +{Color}+.
+  # @param [Integer] hue
+  # @param [Integer] saturation
+  # @param [Integer] lightness
+  # @return [Color]
+  def hsl(h, s, l)
+    Color.from_hsl(h, s, l)
+  end
 end

data/lib/osb/commandable.rb

@@ -4,21 +4,21 @@ module Osb
   module Internal
     # @param [Integer] time
     # @return [void]
-    # @api private
+    # @private
     def self.raise_if_invalid_start_time!(time)
       Internal.assert_type!(time, Integer, "start_time")
     end
 
     # @param [Integer] time
     # @return [void]
-    # @api private
+    # @private
     def self.raise_if_invalid_end_time!(time)
       Internal.assert_type!(time, Integer, "end_time")
     end
 
     # @param [Integer] easing
     # @return [void]
-    # @api private
+    # @private
     def self.raise_if_invalid_easing!(easing)
       Internal.assert_type!(easing, Integer, "easing")
       Internal.assert_value!(easing, Easing::ALL, "easing")
@@ -26,10 +26,12 @@ module Osb
   end
 
   module Commandable
+    # @private
     private def tab_level
       @is_in_trigger ? 2 : 1
     end
 
+    # @private
     private def raise_if_trigger_called!
       if @trigger_called
         raise RuntimeError, "Do not add commands after #trigger is called."
@@ -42,6 +44,7 @@ module Osb
     # @param [Integer] easing
     # @param [Numeric] start_opacity
     # @param [Numeric] end_opacity
+    # @return [void]
     def fade(
       start_time:,
       end_time: start_time,
@@ -71,6 +74,7 @@ module Osb
     # @param [Integer] easing
     # @param [Osb::Vector2, Array<Numeric>] start_position
     # @param [Osb::Vector2, Array<Numeric>] end_position
+    # @return [void]
     def move(
       start_time:,
       end_time: start_time,
@@ -84,12 +88,12 @@ module Osb
       Internal.raise_if_invalid_easing!(easing)
       Internal.assert_type!(
         start_position,
-        [Osb::Vector2, T[Array][Numeric]],
+        [Osb::Vector2, Internal::T[Array][Numeric]],
         "start_position"
       )
       Internal.assert_type!(
         end_position,
-        [Osb::Vector2, T[Array][Numeric]],
+        [Osb::Vector2, Internal::T[Array][Numeric]],
         "end_position"
       )
       if start_position.is_a?(Array)
@@ -100,8 +104,9 @@ module Osb
       tabs = " " * self.tab_level
       command =
         "#{tabs}M,#{start_time},#{end_time},#{start_position.x},#{start_position.y}"
-      command += ",#{end_position.x},#{end_position.y}" if end_position !=
-        start_position
+      if end_position != start_position
+        command += ",#{end_position.x},#{end_position.y}"
+      end
       @commands << command
     end
 
@@ -111,6 +116,7 @@ module Osb
     # @param [Integer] easing
     # @param [Numeric] start_x
     # @param [Numeric] end_x
+    # @return [void]
     def move_x(
       start_time:,
       end_time: start_time,
@@ -138,6 +144,7 @@ module Osb
     # @param [Integer] easing
     # @param [Numeric] start_y
     # @param [Numeric] end_y
+    # @return [void]
     def move_y(
       start_time:,
       end_time: start_time,
@@ -167,6 +174,7 @@ module Osb
     # @param [Integer] easing
     # @param [Numeric, Osb::Vector2, Array<Numeric>] start_scale
     # @param [Numeric, Osb::Vector2, Array<Numeric>] end_scale
+    # @return [void]
     def scale(
       start_time:,
       end_time: start_time,
@@ -180,12 +188,12 @@ module Osb
       Internal.raise_if_invalid_easing!(easing)
       Internal.assert_type!(
         start_scale,
-        [Numeric, T[Array][Numeric], Osb::Vector2],
+        [Numeric, Internal::T[Array][Numeric], Osb::Vector2],
         "start_scale"
       )
       Internal.assert_type!(
         end_scale,
-        [Numeric, T[Array][Numeric], Osb::Vector2],
+        [Numeric, Internal::T[Array][Numeric], Osb::Vector2],
         "end_scale"
       )
 
@@ -207,7 +215,6 @@ module Osb
         end
 
         start_scale = Osb::Vector2.new(start_scale) if start_scale.is_a?(Array)
-
         end_scale = Osb::Vector2.new(end_scale) if end_scale.is_a?(Array)
 
         command =
@@ -223,6 +230,7 @@ module Osb
     # @param [Integer] easing
     # @param [Float] start_angle start angle in radians.
     # @param [Float] end_angle end angle in radians.
+    # @return [void]
     def rotate(
       start_time:,
       end_time: start_time,
@@ -248,8 +256,9 @@ module Osb
     # @param [Integer] start_time
     # @param [Integer] end_time
     # @param [Integer] easing
-    # @param [Osb::Color] start_color
-    # @param [Osb::Color] end_color
+    # @param [Osb::Color, Array<Integer>] start_color
+    # @param [Osb::Color,  Array<Integer>] end_color
+    # @return [void]
     def color(
       start_time:,
       end_time: start_time,
@@ -261,8 +270,19 @@ module Osb
       Internal.raise_if_invalid_start_time!(start_time)
       Internal.raise_if_invalid_end_time!(end_time)
       Internal.raise_if_invalid_easing!(easing)
-      Internal.assert_type!(start_color, Osb::Color, "start_color")
-      Internal.assert_type!(end_color, Osb::Color, "end_color")
+      Internal.assert_type!(
+        start_color,
+        [Osb::Color, Internal::T[Array][Integer]],
+        "start_color"
+      )
+      Internal.assert_type!(
+        end_color,
+        [Osb::Color, Internal::T[Array][Integer]],
+        "end_color"
+      )
+
+      start_color = Color.new(start_color) if start_color.is_a?(Array)
+      end_color = Color.new(end_color) if end_color.is_a?(Array)
 
       end_time = "" if start_time == end_time
       tabs = " " * self.tab_level
@@ -279,6 +299,7 @@ module Osb
     # @param [Integer] end_time
     # @param [Boolean] horizontally
     # @param [Boolean] vertically
+    # @return [void]
     def flip(start_time:, end_time:, horizontally: true, vertically: false)
       self.raise_if_trigger_called!
       Internal.raise_if_invalid_start_time!(start_time)
@@ -304,6 +325,7 @@ module Osb
     # Use additive-color blending instead of alpha-blending.
     # @param [Integer] start_time
     # @param [Integer] end_time
+    # @return [void]
     def additive_color_blending(start_time:, end_time:)
       self.raise_if_trigger_called!
       Internal.raise_if_invalid_start_time!(start_time)
@@ -338,7 +360,8 @@ module Osb
     # @param [String] on indicates the trigger condition. It can be "Failing" or "Passing".
     # @param [Integer] start_time the timestamp at which the trigger becomes valid.
     # @param [Integer] end_time the timestamp at which the trigger stops being valid.
-    def trigger(on:, start_time:, end_time:)
+    # @return [void]
+    def trigger(on:, start_time:, end_time:, &blk)
       self.raise_if_trigger_called!
       Internal.raise_if_invalid_start_time!(start_time)
       Internal.raise_if_invalid_end_time!(end_time)

data/lib/osb/dsl/commands.rb

@@ -0,0 +1,252 @@
+# frozen_string_literal: true
+
+module Osb
+  # @private
+  def current_object
+    return @sprite if @sprite
+    return @animation if @animation
+    return nil
+  end
+
+  # @private
+  def raise_unless_inside_object!
+    self.raise_unless_inside_storyboard!
+    unless self.current_object
+      raise RuntimeError,
+            "Do not call this method outside of a sprite/animation context."
+    end
+  end
+
+  # Change the opacity of the object (how transparent it is).
+  # @param [Integer] start_time
+  # @param [Integer] end_time
+  # @param [Integer] easing
+  # @param [Numeric] start_opacity
+  # @param [Numeric] end_opacity
+  # @return [void]
+  def fade(
+    start_time:,
+    end_time: start_time,
+    easing: Easing::Linear,
+    start_opacity:,
+    end_opacity: start_opacity
+  )
+    self.raise_unless_inside_object!
+    self.current_object.fade(
+      start_time: start_time,
+      end_time: end_time,
+      easing: easing,
+      start_opacity: start_opacity,
+      end_opacity: end_opacity
+    )
+  end
+
+  # Move the object to a new position in the play area.
+  # @param [Integer] start_time
+  # @param [Integer] end_time
+  # @param [Integer] easing
+  # @param [Osb::Vector2, Array<Numeric>] start_position
+  # @param [Osb::Vector2, Array<Numeric>] end_position
+  # @return [void]
+  def move(
+    start_time:,
+    end_time: start_time,
+    easing: Easing::Linear,
+    start_position:,
+    end_position: start_position
+  )
+    self.raise_unless_inside_object!
+    self.current_object.move(
+      start_time: start_time,
+      end_time: end_time,
+      easing: easing,
+      start_position: start_position,
+      end_position: end_position
+    )
+  end
+
+  # Move the object along the x axis.
+  # @param [Integer] start_time
+  # @param [Integer] end_time
+  # @param [Integer] easing
+  # @param [Numeric] start_x
+  # @param [Numeric] end_x
+  # @return [void]
+  def move_x(
+    start_time:,
+    end_time: start_time,
+    easing: Easing::Linear,
+    start_x:,
+    end_x: start_x
+  )
+    self.raise_unless_inside_object!
+    self.current_object.move_x(
+      start_time: start_time,
+      end_time: end_time,
+      easing: easing,
+      start_x: start_x,
+      end_x: end_x
+    )
+  end
+
+  # Move the object along the y axis.
+  # @param [Integer] start_time
+  # @param [Integer] end_time
+  # @param [Integer] easing
+  # @param [Numeric] start_y
+  # @param [Numeric] end_y
+  # @return [void]
+  def move_y(
+    start_time:,
+    end_time: start_time,
+    easing: Easing::Linear,
+    start_y:,
+    end_y: start_y
+  )
+    self.raise_unless_inside_object!
+    self.current_object.move_x(
+      start_time: start_time,
+      end_time: end_time,
+      easing: easing,
+      start_y: start_y,
+      end_y: end_y
+    )
+  end
+
+  # Change the size of the object relative to its original size. Will scale
+  # seperatedly if given +Osb::Vector2+s or +Array<Numeric>+s. The scaling is
+  # affected by the object's origin
+  # @param [Integer] start_time
+  # @param [Integer] end_time
+  # @param [Integer] easing
+  # @param [Numeric, Osb::Vector2, Array<Numeric>] start_scale
+  # @param [Numeric, Osb::Vector2, Array<Numeric>] end_scale
+  # @return [void]
+  def scale(
+    start_time:,
+    end_time: start_time,
+    easing: Easing::Linear,
+    start_scale:,
+    end_scale: start_scale
+  )
+    self.raise_unless_inside_object!
+    self.current_object.scale(
+      start_time: start_time,
+      end_time: end_time,
+      easing: easing,
+      start_scale: start_scale,
+      end_scale: end_scale
+    )
+  end
+
+  # Rotate the object around its origin.
+  # @param [Integer] start_time
+  # @param [Integer] end_time
+  # @param [Integer] easing
+  # @param [Float] start_angle start angle in radians.
+  # @param [Float] end_angle end angle in radians.
+  # @return [void]
+  def rotate(
+    start_time:,
+    end_time: start_time,
+    easing: Easing::Linear,
+    start_angle:,
+    end_angle: start_angle
+  )
+    self.raise_unless_inside_object!
+    self.current_object.rotate(
+      start_time: start_time,
+      end_time: end_time,
+      easing: easing,
+      start_angle: start_angle,
+      end_angle: end_angle
+    )
+  end
+
+  # The virtual light source colour on the object. The colours of the pixels on the object are determined subtractively.
+  # @param [Integer] start_time
+  # @param [Integer] end_time
+  # @param [Integer] easing
+  # @param [Osb::Color, Array<Integer>] start_color
+  # @param [Osb::Color,  Array<Integer>] end_color
+  # @return [void]
+  def color(
+    start_time:,
+    end_time: start_time,
+    easing: Easing::Linear,
+    start_color:,
+    end_color: start_color
+  )
+    self.raise_unless_inside_object!
+    self.current_object.color(
+      start_time: start_time,
+      end_time: end_time,
+      easing: easing,
+      start_color: start_color,
+      end_color: end_color
+    )
+  end
+
+  # Flip the object horizontally or vertically.
+  # @param [Integer] start_time
+  # @param [Integer] end_time
+  # @param [Boolean] horizontally
+  # @param [Boolean] vertically
+  # @return [void]
+  def flip(start_time:, end_time:, horizontally: true, vertically: false)
+    self.raise_unless_inside_object!
+    self.current_object.flip(
+      start_time: start_time,
+      end_time: end_time,
+      horizontally: horizontally,
+      vertically: vertically
+    )
+  end
+
+  # Use additive-color blending instead of alpha-blending.
+  # @param [Integer] start_time
+  # @param [Integer] end_time
+  # @return [void]
+  def additive_color_blending(start_time:, end_time:)
+    self.raise_unless_inside_object!
+    self.current_object.additive_color_blending(
+      start_time: start_time,
+      end_time: end_time
+    )
+  end
+
+  # Add a group of commands on a specific condition.
+  # `#trigger` can only be called on an empty object declaration (no commands).
+  # Pass a block to this method call to specify which commands to run if
+  # the condition is met.
+  #
+  # @example
+  #   img.trigger(on: "Passing", start_time: 0, end_time: 1000) do
+  #     img.fade(start_time: 0, start_opacity: 0.5)
+  #   end
+  #
+  # In addition to the "implicit" player feedback via the separate
+  # Pass/Fail layers, you can use one of several Trigger conditions
+  # to cause a series of events to happen whenever that condition is
+  # fulfilled within a certain time period.
+  # Note that `start_time` and `end_time` of any commands called inside
+  # the block become relative to the `start_time` and `end_time` of the
+  # `#trigger` command.
+  #
+  # While osu! supports trigger on hitsounds playing, we decided to not
+  # include it in because it is unreliable/unpredictable.
+  #
+  # @param [String] on indicates the trigger condition. It can be "Failing" or "Passing".
+  # @param [Integer] start_time the timestamp at which the trigger becomes valid.
+  # @param [Integer] end_time the timestamp at which the trigger stops being valid.
+  # @return [void]
+  def trigger(on:, start_time:, end_time:, &blk)
+    self.raise_unless_inside_object!
+    self.current_object.trigger(
+      on: on,
+      start_time: start_time,
+      end_time: end_time,
+      &blk
+    )
+  end
+end

data/lib/osb/dsl/object.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module Osb
+  # @private
+  def raise_unless_inside_storyboard!
+    unless @storyboard
+      raise RuntimeError,
+            "Do not call this method outside of a storyboard context."
+    end
+  end
+
+  # Set the output directory of this storyboard.
+  # @param [String] path path to .osb or .osu file
+  def out_path(path)
+    self.raise_unless_inside_storyboard!
+    @out_path = path
+  end
+
+  # Create an osu! storyboard.
+  # @return [void]
+  def storyboard
+    if @storyboard
+      raise RuntimeError,
+            "Cannot create a new storyboard inside another storyboard."
+    end
+    @storyboard = Storyboard.new
+    yield
+    raise RuntimeError, "Output path is not set." unless @out_path
+    @storyboard.generate(@out_path)
+    @storyboard = nil
+  end
+
+  # Create a still image.
+  # @param [String] layer the layer the object appears on.
+  # @param [String] origin where on the image should osu! consider that image's origin (coordinate) to be.
+  # @param [String] file_path filename of the image.
+  # @param [Osb::Vector2, nil] initial_position where the object should be by default.
+  # @return [void]
+  def sprite(
+    layer: Layer::Background,
+    origin: Origin::Center,
+    file_path:,
+    initial_position: nil
+  )
+    self.raise_unless_inside_storyboard!
+
+    if @sprite || @animation
+      raise RuntimeError,
+            "Cannot create a new sprite inside another sprite/animation."
+    end
+    @sprite =
+      Sprite.new(
+        layer: layer,
+        origin: origin,
+        file_path: file_path,
+        initial_position: initial_position
+      )
+    @storyboard << @sprite
+    yield
+    @sprite = nil
+  end
+
+  # Group multiple objects for clarity.
+  # @return [void]
+  def group(name: nil)
+  end
+
+  # Create a moving image.
+  # @param [String] layer the layer the object appears on.
+  # @param [String] origin where on the image should osu! consider that image's origin (coordinate) to be.
+  # @param [String] file_path filename of the image.
+  # @param [Vector2, nil] initial_position where the object should be by default.
+  # @param [Integer] frame_count how many frames the animation has.
+  # @param [Integer] frame_delay how many milliseconds should be in between each frame.
+  # @param [Boolean] repeat if the animation should loop or not.
+  # @return [void]
+  def animation(
+    layer: Osb::Layer::Background,
+    origin: Osb::Origin::Center,
+    file_path:,
+    initial_position: nil,
+    frame_count:,
+    frame_delay:,
+    repeat: false
+  )
+    self.raise_unless_inside_storyboard!
+
+    if @sprite || @animation
+      raise RuntimeError,
+            "Cannot create a new animation inside another animation/animation."
+    end
+    @animation =
+      Animation.new(
+        layer: layer,
+        origin: origin,
+        file_path: file_path,
+        initial_position: initial_position,
+        frame_count: frame_count,
+        frame_delay: frame_delay,
+        repeat: repeat
+      )
+    @storyboard << @animation
+    yield
+    @animation = nil
+  end
+
+  # Set the background image for the beatmap.
+  # @param [String] file_name location of the background image relative to the beatmap directory.
+  # @return [void]
+  def background(file_path:)
+    self.raise_unless_inside_storyboard!
+
+    @storyboard << Background.new(file_path: file_path)
+  end
+
+  # Set the video for the beatmap.
+  # @param [String] file_name location of the video file relative to the beatmap directory.
+  # @param [Integer] start_time when the video starts.
+  # @return [void]
+  def video(file_path:, start_time:)
+    self.raise_unless_inside_storyboard!
+
+    @storyboard << Video.new(file_path: file_path, start_time: start_time)
+  end
+
+  # Add an audio sample to the storyboard.
+  # @param [Integer] time the timestamp that the sound should start playing.
+  # @param [String] layer the layer you want the sound to be on.
+  # @param [String] file_path filename of the audio.
+  # @param [Integer] volume indicate the relative loudness of the sound.
+  def sample(time:, layer:, file_path:, volume: 100)
+    self.raise_unless_inside_storyboard!
+
+    @storyboard << Sample.new(
+      time: time,
+      layer: layer,
+      file_path: file_path,
+      volume: volume
+    )
+  end
+end

data/lib/osb/integer.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 class Integer
   # Does nothing. Just a way to tell people it's represented in milliseconds.
   # @return [Integer]

data/lib/osb/numeric.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 class Numeric
   # The degrees method is used to convert from degrees to radians.
   # @return [Float]

data/lib/osb/sample.rb

@@ -1,6 +1,9 @@
+# frozen_string_literal: true
+
 module Osb
+  # Audio sample.
   class Sample
-    # @api private
+    # @private
     attr_reader :command
 
     # @param [Integer] time the timestamp that the sound should start playing.

data/lib/osb/sprite.rb

@@ -3,7 +3,7 @@
 module Osb
   # A still image.
   class Sprite
-    # @api private
+    # @private
     attr_reader :commands, :layer
     include Commandable
 

data/lib/osb/storyboard.rb

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
 module Osb
-  # @api private
+  # @private
   module Internal
-    # @api private
+    # @private
     class LayerManager
       attr_reader :background,
                   :foreground,
@@ -71,7 +71,7 @@ module Osb
   # +Osb::Storyboard+ object, but we recommend you to split the project into multiple
   # +Osb::Group+ so it will be easier to manage.
   class Group
-    # @api private
+    # @private
     attr_reader :layers
 
     def initialize
@@ -115,11 +115,11 @@ module Osb
     end
   end
 
-  # Represent a osu! storyboard. Each sprite or animation can be added directly
+  # Represent an osu! storyboard. Each sprite or animation can be added directly
   # to the storyboard instance, or through an intermediate group. A group can
   # have multiple nested groups in itself.
   class Storyboard
-    # @api private
+    # @private
     attr_reader :layers
 
     def initialize

data/lib/osb/vector2.rb

@@ -10,14 +10,16 @@ module Osb
     #   @return y coordinate of this vector
 
     # @param [Numeric, Array<Numeric>] x
-    #   x coordinate of this +Vector2+, or an +Array+ of 2 numbers.
-    # @param [Numeric] y y coordinate of this +Vector2+
+    #   x coordinate of this +{Vector2}+, or an +Array+ of 2 numbers.
+    # @param [Numeric] y y coordinate of this +{Vector2}+
     def initialize(x = 0, y = 0)
       Internal.assert_type!(x, [Numeric, Internal::T[Array][Numeric]], "x")
       Internal.assert_type!(y, Numeric, "y")
 
       if x.is_a?(Array)
-        raise InvalidValueError, "Must be an Array of 2 Numeric values." if x.size != 2
+        if x.size != 2
+          raise InvalidValueError, "Must be an Array of 2 Numeric values."
+        end
         @x = x[0]
         @y = x[1]
       else
@@ -26,7 +28,7 @@ module Osb
       end
     end
 
-    # Add another +Vector2+ to this one.
+    # Add another +{Vector2}+ to this one.
     # @param [Vector2] vector
     # @return [Vector2]
     def +(vector)
@@ -34,7 +36,7 @@ module Osb
       Vector2.new(self.x + vector.x, self.y + vector.y)
     end
 
-    # Subtract another +Vector2+ from this one.
+    # Subtract another +{Vector2}+ from this one.
     # @param [Vector2] vector
     # @return [Vector2]
     def -(vector)
@@ -42,7 +44,7 @@ module Osb
       Vector2.new(self.x - vector.x, self.y - vector.y)
     end
 
-    # Returns whether two +Vector2+ are equal within tolerance
+    # Returns whether two +{Vector2}+ are equal within tolerance
     # @param [Vector2] vector
     # @return [Boolean]
     def ==(vector)
@@ -50,14 +52,14 @@ module Osb
       Math.fuzzy_equal(self.x, vector.x) && Math.fuzzy_equal(self.y, vector.y)
     end
 
-    # Returns whether two +Vector2+ are not equal within tolerance
+    # Returns whether two +{Vector2}+ are not equal within tolerance
     # @param [Vector2] vector
     # @return [Boolean]
     def !=(vector)
       !(self == vector)
     end
 
-    # Makes a copy of this +Vector2+.
+    # Makes a copy of this +{Vector2}+.
     # @return [Vector2]
     def clone
       Vector2.new(self.x, self.y)
@@ -69,16 +71,24 @@ module Osb
       [self.x, self.y]
     end
 
-    # Returns a string representation of this +Vector2+.
+    # Returns a string representation of this +{Vector2}+.
     # @return [String]
     def to_s
       self.to_a.to_s
     end
 
-    # Returns the length of this +Vector2+.
+    # Returns the length of this +{Vector2}+.
     # @return [Float]
     def length
       Math.sqrt(self.x**2 + self.y**2)
     end
   end
+
+  # Create a +{Vector2}+.
+  # @param [Numeric, Array<Numeric>] x
+  #   x coordinate of this +{Vector2}+, or an +Array+ of 2 numbers.
+  # @param [Numeric] y y coordinate of this +{Vector2}+
+  def vec2(x = 0, y = 0)
+    Vector2.new(x, y)
+  end
 end

data/lib/osb/video.rb

@@ -1,14 +1,14 @@
 module Osb
-  # A video.
+  # Background video.
   class Video
-    # @api private
+    # @private
     attr_reader :commands, :layer
 
-    # @param [String] file_path location of the background image relative to the beatmap directory.
+    # @param [String] file_path location of the video file relative to the beatmap directory.
     # @param [Integer] start_time when the video starts.
     def initialize(file_path:, start_time:)
       Internal.assert_type!(file_path, String, "file_path")
-      Internal.assert_file_name_ext!(file_path, %w[png jpg jpeg])
+      Internal.assert_file_name_ext!(file_path, "mp4")
       Internal.assert_type!(start_time, Integer, "start_time")
 
       @command = "1,#{start_time},\"#{file_path}\""

data/lib/osb.rb

@@ -16,7 +16,12 @@ require_relative "osb/sample"
 require_relative "osb/video"
 require_relative "osb/background"
 require_relative "osb/storyboard"
+require_relative "osb/dsl/object"
+require_relative "osb/dsl/commands"
 
 module Osb
-  VERSION = "1.0.3"
+  VERSION = "1.1.0"
 end
+
+# Extend the main object with the DSL commands.
+extend Osb

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: osb
 version: !ruby/object:Gem::Version
-  version: 1.0.3
+  version: 1.1.1
 platform: ruby
 authors:
 - Dinh Vu
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-08-19 00:00:00.000000000 Z
+date: 2023-08-23 00:00:00.000000000 Z
 dependencies: []
 description: A simple framework for building osu! storyboard.
 email: dinhvu2509@gmail.com
@@ -16,12 +16,16 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".yardopts"
+- README.md
 - lib/osb.rb
 - lib/osb/animation.rb
 - lib/osb/assert.rb
 - lib/osb/background.rb
 - lib/osb/color.rb
 - lib/osb/commandable.rb
+- lib/osb/dsl/commands.rb
+- lib/osb/dsl/object.rb
 - lib/osb/enums/easing.rb
 - lib/osb/enums/layer.rb
 - lib/osb/enums/origin.rb
@@ -52,7 +56,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.6
+rubygems_version: 3.4.18
 signing_key:
 specification_version: 4
 summary: osu! storyboard framework