Module: Osb

Defined in:
lib/osb.rb,
lib/osb/color.rb,
lib/osb/video.rb,
lib/osb/assert.rb,
lib/osb/sample.rb,
lib/osb/sprite.rb,
lib/osb/vector2.rb,
lib/osb/animation.rb,
lib/osb/background.rb,
lib/osb/dsl/object.rb,
lib/osb/storyboard.rb,
lib/osb/commandable.rb,
lib/osb/enums/layer.rb,
lib/osb/dsl/commands.rb,
lib/osb/enums/easing.rb,
lib/osb/enums/origin.rb

Defined Under Namespace

Modules: Commandable, Easing, Layer, Origin Classes: Animation, Background, Color, Group, Sample, Sprite, Storyboard, Vector2, Video

Constant Summary collapse

VERSION = 
"1.1.3"

Instance Method Summary collapse

Instance Method Details

#additive_color_blending(start_time:, end_time:) ⇒ void

This method returns an undefined value.

Use additive-color blending instead of alpha-blending.

Parameters:



210
211
212
213
214
215
216
 
# File 'lib/osb/dsl/commands.rb', line 210

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

#animation(layer: Osb::Layer::Background, origin: Osb::Origin::Center, file_path:, initial_position: nil, frame_count:, frame_delay:, repeat: false) ⇒ void

This method returns an undefined value.

Create a moving image.

Parameters:

  • layer (String) (defaults to: Osb::Layer::Background) —

    the layer the object appears on.

  • origin (String) (defaults to: Osb::Origin::Center) —

    where on the image should osu! consider that image's origin (coordinate) to be.

  • file_path (String) —

    filename of the image.

  • initial_position (Vector2, nil) (defaults to: nil) —

    where the object should be by default.

  • frame_count (Integer) —

    how many frames the animation has.

  • frame_delay (Integer) —

    how many milliseconds should be in between each frame.

  • repeat (Boolean) (defaults to: false) —

    if the animation should loop or not.



77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
 
# File 'lib/osb/dsl/object.rb', line 77

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

#background(file_path:) ⇒ void

This method returns an undefined value.

Set the background image for the beatmap.

Parameters:

  • file_path (String) —

    location of the background image relative to the beatmap directory.



110
111
112
113
114
 
# File 'lib/osb/dsl/object.rb', line 110

def background(file_path:)
  self.raise_unless_inside_storyboard!

  @storyboard << Background.new(file_path: file_path)
end

#color(start_time:, end_time: start_time, easing: Easing::Linear, start_color:, end_color: start_color) ⇒ void

This method returns an undefined value.

The virtual light source colour on the object. The colours of the pixels on the object are determined subtractively.

Parameters:



173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
 
# File 'lib/osb/dsl/commands.rb', line 173

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

#fade(start_time:, end_time: start_time, easing: Easing::Linear, start_opacity:, end_opacity: start_opacity) ⇒ void

This method returns an undefined value.

Change the opacity of the object (how transparent it is).

Parameters:

  • start_time (Integer)
  • end_time (Integer) (defaults to: start_time)
  • easing (Integer) (defaults to: Easing::Linear)
  • start_opacity (Numeric)
  • end_opacity (Numeric) (defaults to: start_opacity) 


27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
 
# File 'lib/osb/dsl/commands.rb', line 27

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

#flip(start_time:, end_time:, horizontally: true, vertically: false) ⇒ void

This method returns an undefined value.

Flip the object horizontally or vertically.

Parameters:

  • start_time (Integer)
  • end_time (Integer)
  • horizontally (Boolean) (defaults to: true)
  • vertically (Boolean) (defaults to: false) 


196
197
198
199
200
201
202
203
204
 
# File 'lib/osb/dsl/commands.rb', line 196

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

#group(name: nil) ⇒ void

This method returns an undefined value.

Group multiple objects for clarity.



65
66
 
# File 'lib/osb/dsl/object.rb', line 65

def group(name: nil)
end

#hsl(h, s, l) ⇒ Color

Create a new hsl Color.

Parameters:

Returns:



132
133
134
 
# File 'lib/osb/color.rb', line 132

def hsl(h, s, l)
  Color.from_hsl(h, s, l)
end

#move(start_time:, end_time: start_time, easing: Easing::Linear, start_position:, end_position: start_position) ⇒ void

This method returns an undefined value.

Move the object to a new position in the play area.

Parameters:



51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
 
# File 'lib/osb/dsl/commands.rb', line 51

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_x(start_time:, end_time: start_time, easing: Easing::Linear, start_x:, end_x: start_x) ⇒ void

This method returns an undefined value.

Move the object along the x axis.

Parameters:



75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
 
# File 'lib/osb/dsl/commands.rb', line 75

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_y(start_time:, end_time: start_time, easing: Easing::Linear, start_y:, end_y: start_y) ⇒ void

This method returns an undefined value.

Move the object along the y axis.

Parameters:



99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
 
# File 'lib/osb/dsl/commands.rb', line 99

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

#out_path(path) ⇒ Object

Set the output directory of this storyboard.

Parameters:

  • path (String) —

    path to .osb or .osu file



14
15
16
17
 
# File 'lib/osb/dsl/object.rb', line 14

def out_path(path)
  self.raise_unless_inside_storyboard!
  @out_path = path
end

#rgb(r, g = nil, b = nil) ⇒ Color

Create a new rgb Color.

Parameters:

  • r (Integer, String, Array<Integer>) —

    red value, a hex String, or an Array of 3 Integers.

  • g (Integer) (defaults to: nil) —

    green value

  • b (Integer) (defaults to: nil) —

    blue value

Returns:



123
124
125
 
# File 'lib/osb/color.rb', line 123

def rgb(r, g = nil, b = nil)
  Color.new(r, g, b)
end

#rotate(start_time:, end_time: start_time, easing: Easing::Linear, start_angle:, end_angle: start_angle) ⇒ void

This method returns an undefined value.

Rotate the object around its origin.

Parameters:

  • start_time (Integer)
  • end_time (Integer) (defaults to: start_time)
  • easing (Integer) (defaults to: Easing::Linear)
  • start_angle (Float) —

    start angle in radians.

  • end_angle (Float) (defaults to: start_angle) —

    end angle in radians.



149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
 
# File 'lib/osb/dsl/commands.rb', line 149

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

#sample(time:, layer:, file_path:, volume: 100) ⇒ Object

Add an audio sample to the storyboard.

Parameters:

  • time (Integer) —

    the timestamp that the sound should start playing.

  • layer (String) —

    the layer you want the sound to be on.

  • file_path (String) —

    filename of the audio.

  • volume (Integer) (defaults to: 100) —

    indicate the relative loudness of the sound.



131
132
133
134
135
136
137
138
139
140
 
# File 'lib/osb/dsl/object.rb', line 131

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

#scale(start_time:, end_time: start_time, easing: Easing::Linear, start_scale:, end_scale: start_scale) ⇒ void

This method returns an undefined value.

Change the size of the object relative to its original size. Will scale seperatedly if given +Osb::Vector2+s or +Array+s. The scaling is affected by the object's origin

Parameters:



125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
 
# File 'lib/osb/dsl/commands.rb', line 125

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

#sprite(layer: Layer::Background, origin: Origin::Center, file_path:, initial_position: nil) ⇒ void

This method returns an undefined value.

Create a still image.

Parameters:

  • layer (String) (defaults to: Layer::Background) —

    the layer the object appears on.

  • origin (String) (defaults to: Origin::Center) —

    where on the image should osu! consider that image's origin (coordinate) to be.

  • file_path (String) —

    filename of the image.

  • initial_position (Osb::Vector2, nil) (defaults to: nil) —

    where the object should be by default.



39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
 
# File 'lib/osb/dsl/object.rb', line 39

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

#storyboard ⇒ void

This method returns an undefined value.

Create an osu! storyboard.

Raises:

  • (RuntimeError) 


21
22
23
24
25
26
27
28
29
30
31
 
# File 'lib/osb/dsl/object.rb', line 21

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

#trigger(on:, start_time:, end_time:, &blk) ⇒ void

This method returns an undefined value.

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.

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.

Examples:

img.trigger(on: "Passing", start_time: 0, end_time: 1000) do
  img.fade(start_time: 0, start_opacity: 0.5)
end

Parameters:

  • on (String) —

    indicates the trigger condition. It can be "Failing" or "Passing".

  • start_time (Integer) —

    the timestamp at which the trigger becomes valid.

  • end_time (Integer) —

    the timestamp at which the trigger stops being valid.



243
244
245
246
247
248
249
250
251
 
# File 'lib/osb/dsl/commands.rb', line 243

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

#vec2(x = 0, y = 0) ⇒ Vector2

Create a 2d vector.

Parameters:

  • x (Numeric, Array<Numeric>) (defaults to: 0) —

    x coordinate of this 2d vector, or an +Array+ of 2 numbers.

  • y (Numeric) (defaults to: 0) —

    y coordinate of this 2d vector

Returns:



91
92
93
 
# File 'lib/osb/vector2.rb', line 91

def vec2(x = 0, y = 0)
  Vector2.new(x, y)
end

#video(file_path:, start_time:) ⇒ void

This method returns an undefined value.

Set the video for the beatmap.

Parameters:

  • file_path (String) —

    location of the video file relative to the beatmap directory.

  • start_time (Integer) —

    when the video starts.



120
121
122
123
124
 
# File 'lib/osb/dsl/object.rb', line 120

def video(file_path:, start_time:)
  self.raise_unless_inside_storyboard!

  @storyboard << Video.new(file_path: file_path, start_time: start_time)
end