An example of scripting in .osb.
This 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, while those that appear in the .osu file will only appear in that given difficulty.
For objects in osu! and Beatmapping, see: Hit Objects
A Storyboard object is an instance of a sprite or an animation in a storyboard. Storyboards can also have sound, see the Audio guide for more details.
The accepted formats for objects are PNG and JPEG. JPEG is lossy, which means it is smaller in file size, but does not precisely save each pixel. It also does not support transparency. Therefore, it is good for backgrounds and for square or photo-realistic images. PNG is lossless, which means it retains pixel-by-pixel information, but is of a larger file size than JPEG. It supports transparency, so it is usually the best for foreground objects / text.
Animations are done in-engine, so the PNG layer system or animation features should not be used. 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").
Editor screen size. Green is screen size and Red is play area
The editor screen is 640 x 480 pixels and the general play area is 510 x 385 pixels.
Coordinates are specified with positive values for X
going to the right, positive values for Y
going down, and the origin (0,0) being placed at the upper-left corner of the screen. It is possible to specify coordinates to be outside of these boundaries (e.g., for a sprite to come in from off-screen).
Editor coordinates:
Screen | x | y |
---|---|---|
Editor | 0–640 | 0–480 |
Play area | 60–570 | 55–440 |
All storyboard sprites are placed below the skin and hit objects. So, even the "highest" (Foreground) layer in the storyboard will always be behind the HP bar, the circles/sliders/spinners, the cursor, etc.
These are the four storyboard layers, in increasing order of priority:
Note that the "Fail" and "Pass" layers are never on-screen simultaneously, unlike in the design tab.
By default, the preview background (the background visible in song select) specified for the beatmap is placed below all other layers. However, if that same file is referenced as an object in the storyboard, it will disappear immediately after the beatmap loads. It is common to have the beatmap's preview background to be the first object (time-wise and sprite-wise) specified, and to use the "fade out" (brighten) command to "introduce" the background to the audience.
The idea behind using a storyboard rather than a video file is the ability to change elements dynamically to fit them to the gameplay's circumstances. osu! only displays one of the Fail/Pass layers at once, 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):
States during playtime ("draining time", when the player is expected to click on objects to keep their HP bar from draining):
States during break time (between playtime segments):
States after the last playtime, if the beatmap had at least one break:
States after last playtime, if the beatmap had no breaks:
Use CTRL+C to copy the timestamp.
.mp3
/.ogg
), including negative values to indicate an intro.Skip
button will be displayed to the user. Clicking it or pressing Space
will skip to time 0. The game reverts to normal pre-map skip behaviour (e.g., press Skip
again to go straight to the countdown — unlike in Elite Beat Agents, where restarting the beatmap takes the player all the way back to the start, not to time 0).Skip
button or presses Space
.
Ctrl
+ C
to copy the current time to the clipboard.Single-line C-style comments can be added, but be advised they may be removed if the beatmap is saved 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, comments can not be put on a line after a valid command. Block comments are unavailable as well.