Storyboard Scripting

The following is a specification of Storyboard Scripting (SBS). It is primarily based on the official specifications and experience in making large SBs. This is not a step-by-step guide, although simple examples are provided. It is meant to exhaustively detail how SBS translates into actions on-screen in osu!.

Follow the links in the Storyboard Scripting (SBS) block at the bottom of each page. It is recommended you read the pages in the order listed, starting with General Rules:

Other Languages

Русский

This page and the rest of the guide describes the lines of scripting code that are placed into the .osb or .osu file, under [Events]. Commands in the .osb file for the beatmap will appear in all difficulties; those that appear in the .osu file will only appear in that given difficulty.

Basic Rules

Objects

• An "object" in the following sections is an instance of a sprite or an animation in your storyboard. Storyboards can also have sound; see that section for more details.
• The accepted formats are PNG and JPEG.
  • JPEG is lossy, which means it's smaller in filesize, but isn't pixel-for-pixel exactly what was input. It also doesn't support transparency. Therefore, it's good for backgrounds and for square, photo-realistic images.
  • PNG is lossless, which means it retains pixel-for-pixel information, but is of a larger filesize than JPEG. It supports transparency, so it's usually the best for foreground objects / text.
• Animation is done in-engine; don't use PNG's layers or animation features. Instead, save each frame as a separate file and name the files with a decimal number before the extension (e.g., "sample0.png", "sample1.png" for a 2-frame animation "sample.png").

Screen size

• The screen is 640 pixels wide by 480 pixels tall
• Coordinates are specified with X going to the right, Y going down, and the origin (0,0) at the upper-left corner of the screen. This is different from traditional Euclidean coordinate systems, but is the same as most computer-graphics systems.
• You are allowed to specify coordinates outside of these boundaries (e.g., for a sprite to come in from off-screen).
• The coordinates of your cursor will be displayed in the Design tab in the Beatmap Editor.

Layers

• All storyboard images are placed below the playtime objects. E.g., even the "highest" layer in Storyboarding will always be behind the HP bar, the circles/sliders/spinners, the cursor, etc.
• There are four Storyboard layers, in increasing order of priority:
  • Background
  • Fail (only displayed if the player is in the "Fail state", see Game State below)
  • Pass (only displayed if the player is in the "Pass state", see Game State below)
  • Foreground
• The Fail and Pass layers are never on-screen simultaneously.
• Overlapping rules:
  • Objects that overlap in different layers will be drawn in the order described above (e.g., any object in the Foreground layer will always be visible in front of any object in the Background, Fail, or Pass layers).
  • Objects that overlap in the same layer will be drawn in the order in which they are specified (e.g., if Object 1 is specified first in the .osb or .osu file, and then Object 2 is as well, but they are both in the same layer, Object 2 will appear in front of Object 1).
  • Commands from the .osb file take precedence over those from the .osu file within the layers, as if the commands from the .osb were appended to the end of the .osu commands. This does not overrule the four layers mentioned above. Example.
• By default, the background specified for the map (e.g., in the Design tab) is placed below all other layers. However, if you reference that same file as an object in your storyboard, it will disappear immediately after the map loads; it is common, therefore, to have your map background be the first object (time-wise) specified, and for it to fade out more elegantly.
• By default, the combo fire appears in front of the storyboard. If you would like the fire to appear behind the SB, include this line in the [General] section of the .osu file(s):

StoryFireInFront: 0

Game State

• The idea behind a storyboard over a video file is to allow the storyboard to change dynamically to fit the circumstances of gameplay.
• The most fundamental way to do this is that osu! only displays one of the Fail/Pass layers at one time, depending on the player's performance. These states are referred to as "Fail State" and "Pass State".
• States before the first playtime (e.g., before the first circle/slider/spinner, not necessarily before the MP3/OGG starts):
  • Always Pass State. Fail layer will never be displayed. It's not recommended you use either Pass or Fail layers at this point in the map, as it's meaningless to say the player is "passing" at this point.
• States during playtime ("draining time", when the player is expected to click on objects to keep their HP bar from draining):
  • Pass State if this is the first color combo or if the previous color combo ended with a Geki/Elite Beat! (all 300s in the color combo).
  • Fail State otherwise. Note that there is no state for just Katu/Beat!, unlike in the DS games (which had three states).
  • In Catch the Beat, this is always the state that the previous break was. The first playable section will always be Pass State.
  • In Taiko, Fail State if the player missed the last note, Pass State otherwise.
• States during break time (between playtime segments):
  • Pass State if the HP bar ended above half in the last playtime section (i.e., the "O" symbol appears).
  • Fail State otherwise (i.e., the "X" symbol appears).
  • In Taiko, if it reaches certain quota at certain time. Let's give 2 example in here,
    • Example A: Get an 96.5% accuracy while HP bar still 40% it still gives Pass instead Fail.
    • Example B: Get too much 100s about 30 notes and gives you D while your HP bar still around 30% gives Fail instead Pass. (In this case referred to this map)
• States after last playtime, if the map had at least one break:
  • Pass State if at least half of the breaks occurred in the Pass State.
  • Fail State otherwise.
• States after last playtime, if the map had no breaks:
  • Same as during break time.

Time

• Time is measured in milliseconds (1000 ms = 1 second) from the start of the beatmap's main MP3/OGG, including negative values to indicate an intro.
• Time in SB is not dependent upon timing of the beatmap itself (e.g., how many measures there are or beats per minute). Therefore, it is recommended that the beatmap be reasonably well-timed before storyboarding, as it will be harder to adjust these times later.
• Time is not constrained to the length of the song; it is possible to have negative values for events before the song starts (an intro), and for values that extend beyond the last playable section or even the end of the MP3/OGG (an outro).
• When loaded, the map will start from the earliest event specified or from time 0, whichever is earlier.
  • In the former case, the Skip button will be displayed to the user. Clicking it or pressing the Spacebar will skip to time 0. The game reverts to normal pre-map skip behavior (e.g., press skip again to go straight to the countdown - unlike EBA, restarting the map takes you all the way back to the start, not to time 0).
• The game will transition to the score results screen as soon as the last event occurs, or the user clicks the Skip button or presses the spacebar.
  • This includes events that are on BOTH the Pass/Fail layers, even though only one will be displayed. E.g., if your Fail storyboard ends at time 20000 and your Pass storyboard ends at time 25000, the game will wait until time 25000 even if the player is in the Fail State (all objects will disappear). Therefore, it's best to ensure that both Pass and Fail ending variants take the same amount of time to complete.
  • Events will continue even if the user skips to the results screen early, and the audio produced by the storyboard can still be heard.
• When in the Beatmap Editor's Design tab, the current time in milliseconds is displayed. Press Ctrl+C to copy the current time to your clipboard.

Comments

You can do single-line C-style comments, but be advised they may be removed if you save in the in-game editor. By default there are some to suggest the separation of commands into the four layers.

// This is a comment.

Unlike in C/C++/C#/Java, you can't put a comment on a line after a valid command. You also can't do block comments.

	Beatmap Editor	[+]
META Beatmap Editor Sections Compose • Design • Timing • Song Setup Components Beat Snap Divisor • Custom Sample Overrides • Distance Snap • Kiai Time Difficulties Easy • Normal • Hard • Insane Mapping Beatmapping • Mapping Techniques • Timing (How to time songs) • Modding • Storyboarding (Scripting) • Skinning (Skin.ini)

List of guides in osu!
Official FAQ and Ranking Guidelines	Game FAQ • Ranking Criteria • Standard Ranking Criteria • Taiko Ranking Criteria • Catch the Beat Ranking Criteria • osu!mania Ranking Criteria
General Mapping/Modding Info	How to mod? • List of Mapping Techniques • Taiko Map Guidelines • Filling The Song Set-up fields • Making Good Sliders • Fitting the Size-limit
Modding Aides	AIBat
Skinning/Hitsound Info	Skinning in General • Making Properly Centered Spinners • Custom Hitsound Library • Adding Custom Hitsounds • Making the Background of Things Transparent
Storyboarding Info	Storyboard Scripting • Reducing SB Load
Video Editing	How to Compress Videos Without Destroying Their Quality • How to Add Videos taken from Youtube
Common Mistakes	How To Correctly Change Map's Artist/Title • Basic MP3 Modifications
Miscellaneous	Changing Title Text • Music Theory • Setting the Offset on the Correct Beat • Collab Information • Starting a Beatmap Project • Live Streaming osu! • Getting songs from Videogames