Storyboard Objects

For Objects in osu! and Beatmapping, see Hit Objects.

In Storyboarding, Objects are sprites or animations that appear on the screen and make up the storyboard. Instances of SB-specific audio can also be considered to be objects; however, for clarity, they have their own section of this guide.

Object Definition

You define an instance of a sprite on a single line in the [Events] section of an .osb or .osu file like so:

Sprite,<layer>,<origin>,"<filepath>",<x>,<y>

And an animation is defined:

Animation,<layer>,<origin>,"<filepath>",<x>,<y>,<frameCount>,<frameDelay>,<looptype>

Where:

• <layer> is the layer the object appears on. Valid values are:
  • Background
  • Fail
  • Pass
  • Foreground
• <origin> is where on the image should osu! consider that image's origin (coordinate) to be. This affects the <x> and <y> values, as well as several other command-specific behaviors. Valid values are (note the spelling "Centre" not "Center"):
  • TopLeft
  • TopCentre
  • TopRight
  • CentreLeft
  • Centre
  • CentreRight
  • BottomLeft
  • BottomCentre
  • BottomRight
• <filepath> is, in laymans terms, the filename of the image you want. But it's not always quite that simple:
  • If you have a subfolder inside your Song Folder, you need to include that, as well. E.g., "backgrounds/sky.jpg" if you have a subfolder called "backgrounds" with an image called "sky.jpg" in it. Start listing directories only from the Song Folder, where the .osu or .osb file is (i.e., a relative filepath). It should not have something like "C:" anywhere in it.
  • Animations are referred to without their number. So if you have "sample0.png" and "sample1.png" as two frames to make a single animation, you want to refer to it as "sample.png".
  • The ""s are technically optional, but they're required if your filename or subfolder name has spaces.
• <x> and <y> are the x- and y-coordinates of where the object should be, by default. The interpretation of this depends on the value of <origin>; for instance, to place a 640x480 image as your background, the values could be:
  • origin = TopLeft, x = 0, y = 0
  • origin = Centre, x = 320, y = 240
  • origin = BottomRight, x = 640, y = 480
  • etc.
• <frameCount> indicates how many frames the animation has. If we have "sample0.png" and "sample1.png", for instance, our frameCount = 2.
• <frameDelay> indicates how many milliseconds should be in between each frame. For instance, if we wanted our animation to advance at 2 frames per second, frameDelay = 500.
• <looptype> indicates if the animation should loop. Valid values are:
  • LoopForever (default if you leave this value off; the animation will return to the first frame after finishing the last frame)
  • LoopOnce (the animation will stop on the last frame and continue to display that last frame; useful for, e.g., an animation of someone turning around)

Notice that there is no indication of when the object should appear. That is entirely up to the commands themselves. The order of the object declarations in the .osu or .osb file only affects what overlaps what; it has no bearing on when the object appears (although it's conventional to keep the declarations ordered based on when they appear anyway).

Examples

Some examples of object declarations:

Sprite,Pass,Centre,"Text\Play2-HaveFunH.png",320,240

This declares a still image (sprite) based on the "Play2-HaveFunH.png" file located in the "Text" folder. The image appears on the Pass layer, and the center (centre) of the image will be located at (320,240) on the game screen (the exact center of the screen).

Animation,Fail,BottomCentre,"Other\Play3\explosion.png",418,108,12,31,LoopForever

This declares an animation, whose frames can be found as "explosion0.png", "explosion1.png" ... "explosion11.png" in the "Play3" folder in the "Other" folder. The image appears on the Failing layer, and the bottom center (centre) of the image will be located at (418,108) on the game screen. There are 12 frames in the animation (hence why the last frame is named "explosion11.png"), and there is a 31 millisecond delay between each frame (thus the animation takes 31 * 12 = 372 milliseconds to loop once). After the game has displayed the last frame for 31 milliseconds, it moves back to the first frame, continuing until the object is no longer appearing on the screen).