osb 1.0.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: dae3bb6b24e591176075dcfaeb67dc5e74c625c668e44dd91e8f35b660973222
+  data.tar.gz: 30a7304fe4b0c47a81d9a55ea0cc91d5e60775ab06f01aa85e4d76c46b241c0c
+SHA512:
+  metadata.gz: 7fd1cc3edbf6bc0995eb04951ac640ca7d583130e36e46b8b9aa801cbbdbd040cbcd41f1b1ea2eff477361f9af39f7775487b80b65332737df0a7055830c877e
+  data.tar.gz: 3d4a452f5fdc3002e544d5ffc32542fa850f792dc01e19da19a32ae506da120fccfdf49d68c2c6d25534320d9406bdf575a67d63c1b1904a98878f26be9c1424

data/lib/osb/animation.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Osb
+  # A moving image.
+  class Animation
+    # @api private
+    attr_reader :commands, :layer
+    include Commandable
+
+    # @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.
+    def initialize(
+      layer: Osb::Layer::Background,
+      origin: Osb::Origin::Center,
+      file_path:,
+      initial_position: nil,
+      frame_count:,
+      frame_delay:,
+      repeat: false
+    )
+      Internal.assert_type!(layer, String, "layer")
+      Internal.assert_value!(layer, Osb::Layer::ALL, "layer")
+
+      Internal.assert_type!(origin, String, "origin")
+      Internal.assert_value!(origin, Osb::Origin::ALL, "origin")
+
+      Internal.assert_type!(file_path, String, "file_path")
+      Internal.assert_file_name_ext!(file_path, %w[png jpg jpeg])
+      if initial_position
+        Internal.assert_type!(initial_position, Vector2, "initial_position")
+      end
+
+      Internal.assert_type!(frame_count, Integer, "frame_count")
+      Internal.assert_type!(frame_delay, Integer, "frame_delay")
+      Internal.assert_type!(repeat, Internal::Boolean, "repeat")
+
+      @layer = layer
+
+      first_command = "Animation,#{layer},#{origin},\"#{file_path}\""
+      if initial_position
+        first_command += ",#{initial_position.x},#{initial_position.y}"
+      else
+        first_command += ",,"
+      end
+      first_command += ",#{frame_count}"
+      first_command += ",#{frame_delay}"
+      looptype = repeat ? "LoopForever" : "LoopOnce"
+      first_command += ",#{type}" if repeat
+      # @type [Array<String>]
+      @commands = [first_command]
+    end
+  end
+end

data/lib/osb/assert.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module Osb
+  # @api private
+  class TypeError < StandardError
+  end
+
+  # @api private
+  class InvalidValueError < StandardError
+  end
+
+  # @api private
+  module Internal
+    # @api private
+    Boolean = [TrueClass, FalseClass]
+
+    # @api private
+    class TypedArray
+      # @param [Class] type
+      def initialize(type)
+        @type = type
+      end
+
+      def name
+        "Array<#{@type.name}>"
+      end
+
+      def valid?(object)
+        object.is_a?(Array) && object.all? { |value| value.is_a?(@type) }
+      end
+    end
+
+    # @api private
+    # @type [Hash{Class => Hash{Class => Object}}]
+    T = { Array => { Numeric => TypedArray.new(Numeric) } }
+
+    # Check if supplied argument is correctly typed.
+    # @param [Object] arg
+    # @param [BasicObject, Array, TypedArray] possible_types
+    # @param [String] param_name
+    # @return [void]
+    # @api private
+    def self.assert_type!(arg, possible_types, param_name)
+      if possible_types.is_a?(Array)
+        valid =
+          possible_types.any? do |type|
+            type.is_a?(TypedArray) ? type.valid?(arg) : arg.is_a?(type)
+          end
+        unless valid
+          accepted_types = possible_types.map { |type| type.name }.join(" or ")
+
+          raise TypeError,
+                "Parameter #{param_name} expects type #{accepted_types}, " +
+                  "got type #{arg.class.name} instead."
+        end
+      elsif possible_types.is_a?(TypedArray)
+        valid = possible_types.valid?(arg)
+        unless valid
+          raise TypeError,
+                "Parameter #{param_name} expects type Array<#{possible_types.type.name}>, " +
+                  "got type #{arg.class.name} instead."
+        end
+      else
+        type = possible_types
+        unless arg.is_a?(type)
+          raise TypeError,
+                "Parameter #{param_name} expects type #{type.name}, " +
+                  "got type #{arg.class.name} instead."
+        end
+      end
+    end
+
+    # Ensures the supplied argument is correct.
+    # @param [Object] arg
+    # @param [BasicObject, Array, Range] possible_values
+    # @param [String] param_name
+    # @return [void]
+    # @api private
+    def self.assert_value!(arg, possible_values, param_name)
+      val =
+        if arg.is_a?(String) && arg.empty?
+          "an empty string"
+        else
+          arg
+        end
+
+      if possible_values.is_a?(Array)
+        valid = possible_values.any? { |value| arg == value }
+        unless valid
+          accepted_values = possible_values.join(" or ")
+
+          raise InvalidValueError,
+                "Parameter #{param_name} expects #{accepted_values}, " +
+                  "got #{val} instead."
+        end
+      elsif possible_values.is_a?(Range)
+        valid = arg >= possible_values.min && arg <= possible_values.max
+        unless valid
+          raise InvalidValueError,
+                "Parameter #{param_name} expects value within " +
+                  "#{possible_values.min} to #{possible_values.max}, " +
+                  "got #{val} instead."
+        end
+      else
+        unless arg == possible_values
+          raise InvalidValueError,
+                "Parameter #{param_name} expects #{possible_values}, " +
+                  "got #{val} instead."
+        end
+      end
+    end
+
+    # Ensure the file name extenstion is correct.
+    # @param [String] file_name
+    # @param [String, Array<String>] exts
+    # @api private
+    def self.assert_file_name_ext!(file_name, exts)
+      if exts.is_a?(Array)
+        exts_ = exts.join("|")
+        exts__ = exts.join(" or ")
+        unless /[\w\s\d]+\.(#{exts_})/.match(file_name)
+          raise InvalidValueError, "File name must end with #{exts__}"
+        end
+      else
+        unless /[\w\s\d]+\.#{exts}/.match(file_name)
+          raise InvalidValueError, "File name must end with #{exts}"
+        end
+      end
+    end
+  end
+end

data/lib/osb/background.rb

@@ -0,0 +1,14 @@
+module Osb
+  # Beatmap's background.
+  class Background
+    # @api private
+    attr_reader :command
+
+    # @param [String] file_name location of the background image relative to the beatmap directory.
+    def initialize(file_path:)
+      Internal.assert_type!(file_path, String, "file_path")
+      Internal.assert_file_name_ext!(file_path, %w[png jpg jpeg])
+      @command = "0,0,\"#{file_path}\""
+    end
+  end
+end

data/lib/osb/color.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Osb
+  # Represents an RGB color.
+  class Color
+    attr_accessor :r, :g, :b
+    # @attribute [rw] r
+    #   @return Red value.
+    # @attribute [rw] g
+    #   @return Green value.
+    # @attribute [rw] b
+    #   @return Blue value.
+
+    # @param [Integer] r red value
+    # @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")
+
+      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")
+
+      @r = r
+      @g = g
+      @b = b
+    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
+    # @return [Color]
+    def self.from_hsl(h, s, l)
+      Internal.assert_type!(h, Integer, "h")
+      Internal.assert_type!(s, Integer, "s")
+      Internal.assert_type!(l, Integer, "l")
+
+      h = h / 360.0
+      s = s / 100.0
+      l = l / 100.0
+
+      r = 0.0
+      g = 0.0
+      b = 0.0
+
+      if s == 0.0
+        r = l.to_f
+        g = l.to_f
+        b = l.to_f
+      else
+        q = l < 0.5 ? l * (1 + s) : l + s - l * s
+        p = 2 * l - q
+        r = hue_to_rgb(p, q, h + 1 / 3.0)
+        g = hue_to_rgb(p, q, h)
+        b = hue_to_rgb(p, q, h - 1 / 3.0)
+      end
+
+      Color.new((r * 255).round, (g * 255).round, (b * 255).round)
+    end
+
+    # @api private
+    # @param [Float] p
+    # @param [Float] q
+    # @param [Float] t_
+    # @return [Float]
+    def self.hue_to_rgb(p, q, t_)
+      t = t_ + 1 if t_ < 0
+      t = t_ - 1 if t_ > 1
+      return(p + (q - p) * 6 * t) if t < 1 / 6.0
+      return q if t < 1 / 2.0
+      return(p + (q - p) * (2 / 3.0 - t) * 6) if t < 2 / 3.0
+      return p
+    end
+
+    # Create a Color object from hex string.
+    # @param [String] hex
+    # @return [Color]
+    def self.from_hex(hex)
+      Internal.assert_type!(hex, String, "hex")
+
+      hex.gsub!("#", "")
+      components = hex.scan(/.{2}/)
+      components.collect { |component| component.to_i(16) }
+    end
+  end
+end

data/lib/osb/commandable.rb

@@ -0,0 +1,373 @@
+# frozen_string_literal: true
+
+module Osb
+  module Internal
+    # @param [Integer] time
+    # @return [void]
+    # @api private
+    def self.raise_if_invalid_start_time!(time)
+      Internal.assert_type!(time, Integer, "start_time")
+    end
+
+    # @param [Integer] time
+    # @return [void]
+    # @api private
+    def self.raise_if_invalid_end_time!(time)
+      Internal.assert_type!(time, Integer, "end_time")
+    end
+
+    # @param [Integer] easing
+    # @return [void]
+    # @api private
+    def self.raise_if_invalid_easing!(easing)
+      Internal.assert_type!(easing, Integer, "easing")
+      Internal.assert_value!(easing, Easing::ALL, "easing")
+    end
+  end
+
+  module Commandable
+    private def tab_level
+      @is_in_trigger ? 2 : 1
+    end
+
+    private def raise_if_trigger_called!
+      if @trigger_called
+        raise RuntimeError, "Do not add commands after #trigger is called."
+      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
+    def fade(
+      start_time:,
+      end_time: start_time,
+      easing: Easing::Linear,
+      start_opacity:,
+      end_opacity: start_opacity
+    )
+      self.raise_if_trigger_called!
+      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_opacity, Numeric, "start_opacity")
+      Internal.assert_type!(end_opacity, Numeric, "end_opacity")
+      Internal.assert_value!(start_opacity, 0..1, "start_opacity")
+      Internal.assert_value!(end_opacity, 0..1, "end_opacity")
+
+      end_time = "" if start_time == end_time
+      tabs = " " * self.tab_level
+      command = "#{tabs}F,#{start_time},#{end_time},#{start_opacity}"
+      command += ",#{end_opacity}" if end_opacity != start_opacity
+      @commands << command
+    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
+    def move(
+      start_time:,
+      end_time: start_time,
+      easing: Easing::Linear,
+      start_position:,
+      end_position: start_position
+    )
+      self.raise_if_trigger_called!
+      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_position,
+        [Osb::Vector2, T[Array][Numeric]],
+        "start_position"
+      )
+      Internal.assert_type!(
+        end_position,
+        [Osb::Vector2, T[Array][Numeric]],
+        "end_position"
+      )
+      if start_position.is_a?(Array)
+        start_position = Osb::Vector2.new(start_position)
+      end
+      end_position = Osb::Vector2.new(end_position) if end_position.is_a?(Array)
+      end_time = "" if start_time == end_time
+      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
+      @commands << command
+    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
+    def move_x(
+      start_time:,
+      end_time: start_time,
+      easing: Easing::Linear,
+      start_x:,
+      end_x: start_x
+    )
+      self.raise_if_trigger_called!
+      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_x, Numeric, "start_x")
+      Internal.assert_type!(end_x, Numeric, "end_x")
+
+      end_time = "" if start_time == end_time
+      tabs = " " * self.tab_level
+      command = "#{tabs}MX,#{start_time},#{end_time},#{start_x}"
+      command += ",#{end_x}" if end_x
+      @commands << command
+    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
+    def move_y(
+      start_time:,
+      end_time: start_time,
+      easing: Easing::Linear,
+      start_y:,
+      end_y: start_y
+    )
+      self.raise_if_trigger_called!
+      Internal.raise_if_invalid_start_time!(start_time)
+      Internal.raise_if_invalid_end_time!(end_time) if end_time
+      Internal.raise_if_invalid_easing!(easing)
+      Internal.assert_type!(start_y, Numeric, "start_y")
+      Internal.assert_type!(end_y, Numeric, "end_y")
+
+      end_time = "" if start_time == end_time
+      tabs = " " * self.tab_level
+      command = "#{tabs}MY,#{start_time},#{end_time},#{start_y}"
+      command += ",#{end_y}" if end_y != start_y
+      @commands << command
+    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
+    def scale(
+      start_time:,
+      end_time: start_time,
+      easing: Easing::Linear,
+      start_scale:,
+      end_scale: start_scale
+    )
+      self.raise_if_trigger_called!
+      Internal.raise_if_invalid_start_time!(start_time)
+      Internal.raise_if_invalid_end_time!(end_time) if end_time
+      Internal.raise_if_invalid_easing!(easing)
+      Internal.assert_type!(
+        start_scale,
+        [Numeric, T[Array][Numeric], Osb::Vector2],
+        "start_scale"
+      )
+      Internal.assert_type!(
+        end_scale,
+        [Numeric, T[Array][Numeric], Osb::Vector2],
+        "end_scale"
+      )
+
+      end_time = "" if start_time == end_time
+      tabs = " " * self.tab_level
+
+      if start_scale.is_a?(Numeric)
+        unless end_scale.is_a?(Numeric)
+          raise InvalidValueError,
+                "start_scale and end_scale must be either both Numeric values or Vector2-like values."
+        end
+        command = "#{tabs}S,#{start_time},#{end_time},#{start_scale}"
+        command += ",#{end_scale}" if end_scale != start_scale
+        @commands << command
+      else
+        if end_scale.is_a?(Numeric)
+          raise InvalidValueError,
+                "start_scale and end_scale must be either both Numeric values or Vector2-like values."
+        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 =
+          "#{tabs}V,#{start_time},#{end_time},#{start_scale.x},#{start_scale.y}"
+        command += ",#{end_scale.x},#{end_scale.y}" if end_scale
+        @commands << command
+      end
+    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.
+    def rotate(
+      start_time:,
+      end_time: start_time,
+      easing: Easing::Linear,
+      start_angle:,
+      end_angle: start_angle
+    )
+      self.raise_if_trigger_called!
+      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_angle, Numeric, "start_angle")
+      Internal.assert_type!(end_angle, Numeric, "end_angle")
+
+      end_time = "" if start_time == end_time
+      tabs = " " * self.tab_level
+      command = "#{tabs}R,#{start_time},#{end_time},#{start_angle}"
+      command += ",#{end_angle}" if end_angle != start_angle
+      @commands << command
+    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] start_color
+    # @param [Osb::Color] end_color
+    def color(
+      start_time:,
+      end_time: start_time,
+      easing: Easing::Linear,
+      start_color:,
+      end_color: start_color
+    )
+      self.raise_if_trigger_called!
+      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")
+
+      end_time = "" if start_time == end_time
+      tabs = " " * self.tab_level
+      command =
+        "#{tabs}C,#{start_time},#{end_time},#{start_color.r},#{start_color.g},#{start_color.b}"
+      if end_color != start_color
+        command += ",#{end_color.r},#{end_color.g},#{end_color.b}"
+      end
+      @commands << command
+    end
+
+    # Flip the object horizontally or vertically.
+    # @param [Integer] start_time
+    # @param [Integer] end_time
+    # @param [Boolean] horizontally
+    # @param [Boolean] vertically
+    def flip(start_time:, end_time:, horizontally: true, vertically: false)
+      self.raise_if_trigger_called!
+      Internal.raise_if_invalid_start_time!(start_time)
+      Internal.raise_if_invalid_end_time!(end_time)
+      Internal.assert_type!(horizontally, Internal::Boolean, "horizontally")
+      Internal.assert_type!(vertically, Internal::Boolean, "vertically")
+
+      if horizontally && vertically
+        raise InvalidValueError,
+              "Cannot flip an object both horizontally and vertically."
+      end
+      if !horizontally && !vertically
+        raise InvalidValueError, "Specify a direction to flip."
+      end
+
+      direction = horizontally ? "H" : "V"
+      end_time = "" if start_time == end_time
+      tabs = " " * self.tab_level
+      command = "#{tabs}P,#{start_time},#{end_time},#{direction}"
+      @commands << command
+    end
+
+    # Use additive-color blending instead of alpha-blending.
+    # @param [Integer] start_time
+    # @param [Integer] end_time
+    def additive_color_blending(start_time:, end_time:)
+      self.raise_if_trigger_called!
+      Internal.raise_if_invalid_start_time!(start_time)
+      Internal.raise_if_invalid_end_time!(end_time)
+
+      tabs = " " * self.tab_level
+      command = "#{tabs}P,#{start_time},#{end_time},A"
+      @commands << command
+    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.
+    def trigger(on:, start_time:, end_time:)
+      self.raise_if_trigger_called!
+      Internal.raise_if_invalid_start_time!(start_time)
+      Internal.raise_if_invalid_end_time!(end_time)
+      Internal.assert_type!(on, String, "on")
+      Internal.assert_value!(on, %w[Passing Failing], "on")
+
+      unless block_given?
+        raise InvalidValueError, "Do not use an empty trigger."
+      end
+
+      if @commands.size > 1
+        raise RuntimeError, "Do not call #trigger after any other commands."
+      end
+
+      if @is_in_trigger
+        raise RuntimeError,
+              "Do not call #trigger inside another #trigger block."
+      end
+
+      command = " T,#{on},#{start_time},#{end_time}"
+      @commands << command
+
+      @is_in_trigger = true
+      yield self
+      unless @commands.size > 1
+        raise InvalidValueError, "Do not use an empty trigger."
+      end
+      @is_in_trigger = false
+      @trigger_called = true
+    end
+  end
+end

data/lib/osb/enums/easing.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Osb
+  module Easing
+    Linear = 0
+    Out = 1
+    In = 2
+    InQuad = 3
+    OutQuad = 4
+    InOutQuad = 5
+    InCubic = 6
+    OutCubic = 7
+    InOutCubic = 8
+    InQuart = 9
+    OutQuart = 10
+    InOutQuart = 11
+    InQuint = 12
+    OutQuint = 13
+    InOutQuint = 14
+    InSine = 15
+    OutSine = 16
+    InOutSine = 17
+    InExpo = 18
+    OutExpo = 19
+    InOutExpo = 20
+    InCirc = 21
+    OutCirc = 22
+    InOutCirc = 23
+    InElastic = 24
+    OutElastic = 25
+    OutElasticHalf = 26
+    OutElasticQuarter = 27
+    InOutElastic = 28
+    InBack = 29
+    OutBack = 30
+    InOutBack = 31
+    InBounce = 32
+    OutBounce = 33
+    InOutBounce = 34
+    ALL = 0..34
+  end
+end

data/lib/osb/enums/layer.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Osb
+  module Layer
+    Background = "Background"
+    Fail = "Fail"
+    Pass = "Pass"
+    Foreground = "Foreground"
+    Overlay = "Overlay"
+    ALL = %w[Background Fail Pass Foreground Overlay]
+  end
+end

data/lib/osb/enums/origin.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Osb
+  module Origin
+    TopLeft = "TopLeft"
+    TopCentre = "TopCentre"
+    TopCenter = "TopCentre"
+    TopRight = "TopRight"
+    CentreLeft = "CentreLeft"
+    CenterLeft = "CentreLeft"
+    Centre = "Centre"
+    Center = "Centre"
+    CentreRight = "CentreRight"
+    CenterRight = "CentreRight"
+    BottomLeft = "BottomLeft"
+    BottomCentre = "BottomCentre"
+    BottomCenter = "BottomCentre"
+    BottomRight = "BottomRight"
+    ALL = %w[
+      TopLeft
+      TopCentre
+      TopRight
+      CentreLeft
+      Centre
+      CentreRight
+      BottomLeft
+      BottomCentre
+      BottomRight
+    ]
+  end
+end

data/lib/osb/integer.rb

@@ -0,0 +1,19 @@
+class Integer
+  # Does nothing. Just a way to tell people it's represented in milliseconds.
+  # @return [Integer]
+  def ms
+    self
+  end
+
+  # Convert from seconds to milliseconds.
+  # @return [Integer]
+  def second
+    self * 1000
+  end
+
+  # Convert from percentage to float.
+  # @return [Float]
+  def percent
+    self / 100.0
+  end
+end

data/lib/osb/math.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Math
+  # Returns whether 2 real numbers are equal within tolerance.
+  # @param [Numeric] x
+  # @param [Numeric] y
+  # @param [Numeric] tolerance
+  # @return [Boolean]
+  def self.fuzzy_equal(x, y, tolerance = 1e-8)
+    (x - y).abs < tolerance
+  end
+end

data/lib/osb/numeric.rb

@@ -0,0 +1,7 @@
+class Numeric
+  # The degrees method is used to convert from degrees to radians.
+  # @return [Float]
+  def degrees
+    self * Math::PI / 180
+  end
+end

data/lib/osb/sample.rb

@@ -0,0 +1,34 @@
+module Osb
+  class Sample
+    # @api private
+    attr_reader :command
+
+    # @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 initialize(time:, layer:, file_path:, volume: 100)
+      Internal.assert_type!(layer, String, "layer")
+      Internal.assert_value!(layer, Layer::ALL, "layer")
+      Internal.assert_type!(file_path, String, "file_path")
+
+      layer_ =
+        case layer
+        when Osb::Layer::Background
+          0
+        when Osb::Layer::Foreground
+          1
+        when Osb::Layer::Fail
+          2
+        when Osb::Layer::Pass
+          3
+        else
+          raise InvalidValueError,
+                "An audio sample can only exists in one of these layers: " +
+                  "Background, Foreground, Fail or Pass."
+        end
+
+      @command = "Sample,#{time},#{layer_},\"#{file_path}}\",#{volume}"
+    end
+  end
+end

data/lib/osb/sprite.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Osb
+  # A still image.
+  class Sprite
+    # @api private
+    attr_reader :commands, :layer
+    include Commandable
+
+    # @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.
+    def initialize(
+      layer: Layer::Background,
+      origin: Origin::Center,
+      file_path:,
+      initial_position: nil
+    )
+      Internal.assert_type!(layer, String, "layer")
+      Internal.assert_value!(layer, Layer::ALL, "layer")
+      Internal.assert_type!(origin, String, "origin")
+      Internal.assert_value!(origin, Origin::ALL, "origin")
+      Internal.assert_type!(file_path, String, "file_path")
+      Internal.assert_file_name_ext!(file_path, %w[png jpg jpeg])
+      if initial_position
+        Internal.assert_type!(
+          initial_position,
+          Osb::Vector2,
+          "initial_position"
+        )
+      end
+
+      @layer = layer
+
+      first_command = "Sprite,#{layer},#{origin},\"#{file_path}\""
+      if initial_position
+        first_command += ",#{initial_position.x},#{initial_position.y}"
+      end
+      # @type [Array<String>]
+      @commands = [first_command]
+    end
+  end
+end

data/lib/osb/storyboard.rb

@@ -0,0 +1,232 @@
+# frozen_string_literal: true
+
+module Osb
+  # @api private
+  module Internal
+    # @api private
+    class LayerManager
+      attr_reader :background,
+                  :foreground,
+                  :fail,
+                  :pass,
+                  :overlay,
+                  :samples,
+                  :bg_and_video
+
+      def initialize
+        # @type [Array<Osb::Sprite, Osb::Animation>]
+        @background = []
+        # @type [Array<Osb::Sprite, Osb::Animation>]
+        @foreground = []
+        # @type [Array<Osb::Sprite, Osb::Animation>]
+        @fail = []
+        # @type [Array<Osb::Sprite, Osb::Animation>]
+        @pass = []
+        # @type [Array<Osb::Sprite, Osb::Animation>]
+        @overlay = []
+        # @type [Array<Osb::Background, Osb::Video>]
+        @bg_and_video = []
+        # @type [Array<Osb::Sample>]
+        @samples = []
+      end
+
+      # @param [Osb::Sprite, Osb::Animation, Osb::Sample, Osb::Background, Osb::Video] object
+      def add(object)
+        case object
+        when Osb::Sprite, Osb::Animation
+          case object.layer
+          when Layer::Background
+            @background << object
+          when Layer::Foreground
+            @foreground << object
+          when Layer::Fail
+            @fail << object
+          when Layer::Pass
+            @pass << object
+          when Layer::Overlay
+            @overlay << object
+          end
+        when Osb::Sample
+          @samples << object
+        when Osb::Background, Osb::Video
+          @bg_and_video << object
+        end
+      end
+
+      # @param [Osb::Group] group
+      def concat(group)
+        @background.concat(group.layers.background)
+        @foreground.concat(group.layers.foreground)
+        @fail.concat(group.layers.fail)
+        @pass.concat(group.layers.pass)
+        @overlay.concat(group.layers.overlay)
+        @samples.concat(group.layers.samples)
+      end
+    end
+  end
+
+  # When designing storyboard, we often want to group storyboard elements
+  # that are used in a similar context (eg. a scene), so this class' purpose
+  # is only to act as a container. You can add the elements directly to the
+  # +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
+    attr_reader :layers
+
+    def initialize
+      @layers = Internal::LayerManager.new
+    end
+
+    # Add an +Osb::Sprite+, +Osb::Animation+, +Osb::Sample+ or +Osb::Group+ to
+    # this group.
+    # @param [Osb::Group, Osb::Sprite, Osb::Animation, Osb::Sample] object
+    # @return [self]
+    def add(object)
+      Internal.assert_type!(
+        object,
+        [
+          Osb::Group,
+          Osb::Sprite,
+          Osb::Animation,
+          Osb::Sample,
+          Osb::Video,
+          Osb::Background
+        ],
+        "object"
+      )
+
+      case object
+      when Osb::Sprite, Osb::Animation, Osb::Sample
+        @layers.add(object)
+      when Osb::Group
+        @layers.concat(object)
+      end
+
+      return self
+    end
+
+    # Add an +Osb::Sprite+, +Osb::Animation+, +Osb::Sample+ or +Osb::Group+ to
+    # this group. Alias for +#add+.
+    # @param [Osb::Group, Osb::Sprite, Osb::Animation, Osb::Sample] object
+    # @return [self]
+    def <<(object)
+      self.add(object)
+    end
+  end
+
+  # Represent a 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
+    attr_reader :layers
+
+    def initialize
+      @layers = Internal::LayerManager.new
+    end
+
+    # Add an +Osb::Sprite+, +Osb::Animation+, +Osb::Sample+, +Osb::Video+,
+    # +Osb::Background+ or +Osb::Group+ to this storyboard.
+    # @param [Osb::Group, Osb::Sprite, Osb::Animation, Osb::Sample, Osb::Video,
+    #         Osb::Background] object
+    # @return [self]
+    def add(object)
+      Internal.assert_type!(
+        object,
+        [
+          Osb::Group,
+          Osb::Sprite,
+          Osb::Animation,
+          Osb::Video,
+          Osb::Background,
+          Osb::Sample
+        ],
+        "object"
+      )
+
+      case object
+      when Osb::Sprite, Osb::Animation, Osb::Sample, Osb::Video, Osb::Background
+        @layers.add(object)
+      when Osb::Group
+        @layers.concat(object)
+      end
+
+      return self
+    end
+
+    # Add an +Osb::Sprite+, +Osb::Animation+, +Osb::Sample+, +Osb::Video+,
+    # +Osb::Background+ or +Osb::Group+ to this storyboard. Alias for +#add+.
+    # @param [Osb::Group, Osb::Sprite, Osb::Animation, Osb::Sample, Osb::Video,
+    #         Osb::Background] object
+    # @return [self]
+    def <<(object)
+      self.add(object)
+    end
+
+    # Returns the storyboard string.
+    # @return [String]
+    def to_s
+      bg_and_video_layer =
+        @layers.bg_and_video.map { |object| object.command }.join("\n")
+      background_layer =
+        @layers
+          .background
+          .map { |object| object.commands.join("\n") }
+          .join("\n")
+      fail_layer =
+        @layers.fail.map { |object| object.commands.join("\n") }.join("\n")
+      pass_layer =
+        @layers.pass.map { |object| object.commands.join("\n") }.join("\n")
+      foreground_layer =
+        @layers
+          .foreground
+          .map { |object| object.commands.join("\n") }
+          .join("\n")
+      overlay_layer =
+        @layers.overlay.map { |object| object.commands.join("\n") }.join("\n")
+      samples_layer = @layers.samples.map { |object| object.command }.join("\n")
+
+      osb_string = "[Events]\n"
+      osb_string +=
+        "//Background and Video events\n" + bg_and_video_layer + "\n" +
+          "//Storyboard Layer 0 (Background)\n" + background_layer + "\n" +
+          "//Storyboard Layer 1 (Fail)\n" + fail_layer + "\n" +
+          "//Storyboard Layer 2 (Pass)\n" + pass_layer + "\n" +
+          "//Storyboard Layer 3 (Foreground)\n" + foreground_layer + "\n" +
+          "//Storyboard Layer 4 (Overlay)\n" + overlay_layer + "\n" +
+          "//Storyboard Sound Samples\n" + samples_layer + "\n"
+    end
+
+    # Generate an osb or osu file for this storyboard.
+    # @param [String] out_path path to .osb or .osu file
+    # @return [void]
+    def generate(out_path)
+      Internal.assert_file_name_ext!(out_path, %w[osb osu])
+
+      case File.extname(out_path)
+      when ".osu"
+        unless File.exist?(out_path)
+          raise InvalidValueError, "Cannot find osu file."
+        end
+
+        out_osu_file = ""
+        File
+          .readlines(out_path)
+          .each do |line|
+            if line.match(/[Events]/)
+              out_osu_file += self.to_s
+            else
+              out_osu_file += line
+            end
+          end
+
+        File.new(out_path, "w").write(out_osu_file)
+      when ".osb"
+        File.new(out_path, "w").write(self.to_s)
+      else
+        raise InvalidValueError, "Not osu or osb file." # should not be here
+      end
+    end
+  end
+end

data/lib/osb/vector2.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Osb
+  # Represents a 2d point or vector.
+  class Vector2
+    attr_accessor :x, :y
+    # @!attribute [rw] x
+    #   @return x coordinate of this vector
+    # @!attribute [rw] y
+    #   @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+
+    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
+        @x = x[0]
+        @y = x[1]
+      else
+        @x = x
+        @y = y
+      end
+    end
+
+    # Add another +Vector2+ to this one.
+    # @param [Vector2] vector
+    # @return [Vector2]
+    def +(vector)
+      Internal.assert_type!(vector, Vector2, "vector")
+      Vector2.new(self.x + vector.x, self.y + vector.y)
+    end
+
+    # Subtract another +Vector2+ from this one.
+    # @param [Vector2] vector
+    # @return [Vector2]
+    def -(vector)
+      Internal.assert_type!(vector, Vector2, "vector")
+      Vector2.new(self.x - vector.x, self.y - vector.y)
+    end
+
+    # Returns whether two +Vector2+ are equal within tolerance
+    # @param [Vector2] vector
+    # @return [Boolean]
+    def ==(vector)
+      Internal.assert_type!(vector, Vector2, "vector")
+      Math.fuzzy_equal(self.x, vector.x) && Math.fuzzy_equal(self.y, vector.y)
+    end
+
+    # 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+.
+    # @return [Vector2]
+    def clone
+      Vector2.new(self.x, self.y)
+    end
+
+    # Retrieves the coordinates in an Array.
+    # @return [Array(Float, Float)]
+    def to_a
+      [self.x, self.y]
+    end
+
+    # Returns a string representation of this +Vector2+.
+    # @return [String]
+    def to_s
+      self.to_a.to_s
+    end
+
+    # Returns the length of this +Vector2+.
+    # @return [Float]
+    def length
+      Math.sqrt(self.x**2 + self.y**2)
+    end
+  end
+end

data/lib/osb/video.rb

@@ -0,0 +1,17 @@
+module Osb
+  # A video.
+  class Video
+    # @api private
+    attr_reader :commands, :layer
+
+    # @param [String] file_path location of the background image 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_type!(start_time, Integer, "start_time")
+
+      @command = "1,#{start_time},\"#{file_path}\""
+    end
+  end
+end

data/lib/osb.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative "osb/integer"
+require_relative "osb/numeric"
+require_relative "osb/assert"
+require_relative "osb/math"
+require_relative "osb/vector2"
+require_relative "osb/color"
+require_relative "osb/enums/layer"
+require_relative "osb/enums/easing"
+require_relative "osb/enums/origin"
+require_relative "osb/commandable"
+require_relative "osb/animation"
+require_relative "osb/sprite"
+require_relative "osb/sample"
+require_relative "osb/video"
+require_relative "osb/background"
+require_relative "osb/storyboard"
+
+module Osb
+  VERSION = "1.0.3"
+end

metadata

@@ -0,0 +1,59 @@
+--- !ruby/object:Gem::Specification
+name: osb
+version: !ruby/object:Gem::Version
+  version: 1.0.3
+platform: ruby
+authors:
+- Dinh Vu
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2023-08-19 00:00:00.000000000 Z
+dependencies: []
+description: A simple framework for building osu! storyboard.
+email: dinhvu2509@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- 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/enums/easing.rb
+- lib/osb/enums/layer.rb
+- lib/osb/enums/origin.rb
+- lib/osb/integer.rb
+- lib/osb/math.rb
+- lib/osb/numeric.rb
+- lib/osb/sample.rb
+- lib/osb/sprite.rb
+- lib/osb/storyboard.rb
+- lib/osb/vector2.rb
+- lib/osb/video.rb
+homepage: https://github.com/nanachi-code/osb-ruby
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.6
+signing_key:
+specification_version: 4
+summary: osu! storyboard framework
+test_files: []