osu! Storyboard

https://osu.ppy.sh/wiki/en/Storyboard
Admin
Documentation for storyboarding in osu!, covering the creation and scripting of custom animated...
Tokens:7,649
Snippets:114
Trust Score:9.5
Update:4 months ago
Show doc for...
Tokens:
Raw
### Loop Command Example

Source: https://osu.ppy.sh/wiki/en/Storyboard/Scripting/Compound_Commands

Demonstrates a loop that fades an object in and out repeatedly. The loop starts at 60000ms, runs for 30 iterations, with each iteration taking 1000ms. The fade-in occurs during the first 500ms of each iteration, and fade-out during the next 500ms.

```osu!Storyboard
Sprite,Pass,Centre,"Sample.png",320,240
_L,60000,30
__F,0,0,500,0,1
__F,0,500,1000,1,0
```

--------------------------------

### Example .osb Scripting

Source: https://osu.ppy.sh/wiki/en/Storyboard/Scripting/General_Rules

This is an example of storyboard scripting code that can be placed into the .osb or .osu file under the [Events] section.

```osu!sb
[Events]
// Background and Video events
// Background colour and image events
// Sprite and animation events
// Sample and audio channel events
```

--------------------------------

### Example: White Screen Transition in Storyboard

Source: https://osu.ppy.sh/wiki/en/Storyboard/Scripting/Compound_Commands

Demonstrates how to use Passing and Failing triggers to create a temporary white screen effect during state transitions. The example uses a large white image sprite to cover the screen for a specified duration.

```osu!Storyboard
Sprite,Foreground,Centre,"LargeWhiteImage.png",320,240
_T,Passing,20000,40000
__F,0,0,500,1
__F,0,500,501,0
_T,Failing,20000,40000
__F,0,0,500,1
__F,0,500,501,0
```

--------------------------------

### Play Audio Samples in Storyboard

Source: https://osu.ppy.sh/wiki/en/Storyboard/Scripting/Audio

Examples demonstrating how to play audio files at specific timestamps and layers. The first example plays a music track at 80% volume on the Pass layer, and the second plays a sound effect at 100% volume on the same layer.

```scripting
Sample,163520,2,"Audio\Best End.mp3",80
Sample,167201,2,"Audio\sfx\EndG-SmallExplosion.wav",100
```

--------------------------------

### Variable Substitution Example

Source: https://osu.ppy.sh/wiki/en/Storyboard/Scripting/Variables

This example demonstrates how the engine replaces variables with their defined values. Be cautious with short or general variable names as they can be substituted into unintended places.

```osu!sb
Sprite,Pass,Centre,"Sample.png",320,240
_C,0,58810,59810,0,255,0

```

--------------------------------

### Instantaneous State Changes

Source: https://osu.ppy.sh/wiki/en/Storyboard/Scripting/Shorthand

Multiple commands with the same start time but different end times can create instantaneous changes. This example shows an image jumping to full opacity halfway through a move command.

```storyboard
Sprite,Pass,Centre,"Sample.png",320,240
_F,0,1000,,0.5
_F,0,1500,,1
_M,0,1000,2000,0,0,320,240

```

--------------------------------

### Single-line Comment Example

Source: https://osu.ppy.sh/wiki/en/Storyboard/Scripting/General_Rules

Demonstrates the syntax for a single-line comment in storyboards. Note that these comments may be removed by the in-game editor.

```General
// This is a comment.
```

--------------------------------

### Move X Event Parameters

Source: https://osu.ppy.sh/wiki/en/Storyboard/Scripting/Cheat_Sheet

Define start and end X positions for a move event.

```osu!Storyboard Script
_MX,[...],startx,endx
```

--------------------------------

### Shorthand2 Event Notation (Same Start/End Time)

Source: https://osu.ppy.sh/wiki/en/Storyboard/Scripting/Cheat_Sheet

Use shorthand2 when the start and end time of an event are the same, simplifying the notation.

```osu!Storyboard Script
_M,0,1000,1000,320,240,320,240
becomes
```

--------------------------------

### Same Start and End Values

Source: https://osu.ppy.sh/wiki/en/Storyboard/Scripting/Shorthand

Abbreviate commands where the start and end values for an event are identical. This is useful for maintaining a specific value over a timespan. The shorthand omits the second instance of the value.

```storyboard
Sprite,Pass,Centre,"Sample.png",320,240
_V,0,1000,2000,0.5,2
_F,0,1000,2000,0.75

```

--------------------------------

### Move Y Event Parameters

Source: https://osu.ppy.sh/wiki/en/Storyboard/Scripting/Cheat_Sheet

Define start and end Y positions for a move event.

```osu!Storyboard Script
_MY,[...],starty,endy
```

--------------------------------

### Shorthand for Same Start and End Times

Source: https://osu.ppy.sh/wiki/en/Storyboard/Scripting/Shorthand

When a command's start and end times are the same, the end time can be omitted. This shorthand is useful for applying a constant state throughout a command's duration.

```storyboard
Sprite,Pass,Centre,"Sample.png",320,240
_F,0,1000,,0.5
_M,0,1000,2000,0,0,320,240
// ... more M commands

```

--------------------------------

### Vector Scale Event Parameters

Source: https://osu.ppy.sh/wiki/en/Storyboard/Scripting/Cheat_Sheet

Define start and end scale factors for width and height separately using vector scaling.

```osu!Storyboard Script
_V,[...],startx,starty,endx,endy
```

--------------------------------

### Move Event Parameters

Source: https://osu.ppy.sh/wiki/en/Storyboard/Scripting/Cheat_Sheet

Define start and end positions (x, y) for a move event within the playfield dimensions (640x480).

```osu!Storyboard Script
_M,[...],startx,starty,endx,endy
```

--------------------------------

### Fade Event Parameters

Source: https://osu.ppy.sh/wiki/en/Storyboard/Scripting/Cheat_Sheet

Specify start and end opacity for a fade event. Opacity ranges from 0 (invisible) to 1 (fully visible).

```osu!Storyboard Script
_F,[...],startopacity,endopacity
```

--------------------------------

### Scale Event Parameters

Source: https://osu.ppy.sh/wiki/en/Storyboard/Scripting/Cheat_Sheet

Specify start and end scale factors for a scale event. 1 equals 100% scale.

```osu!Storyboard Script
_S,[...],startscale,endscale
```

--------------------------------

### Color Event Parameters

Source: https://osu.ppy.sh/wiki/en/Storyboard/Scripting/Cheat_Sheet

Define start and end RGB color values for a color event. (255,255,255) is the original color, (0,0,0) is black.

```osu!Storyboard Script
_C,[...],r1,g1,b1,r2,g2,b2
```

--------------------------------

### Rotate Event Parameters

Source: https://osu.ppy.sh/wiki/en/Storyboard/Scripting/Cheat_Sheet

Specify start and end angles in radians for a rotate event. Positive angles indicate clockwise rotation.

```osu!Storyboard Script
_R,[...],startangle,endangle
```

--------------------------------

### Sprite and Animation Shorthand

Source: https://osu.ppy.sh/wiki/en/Storyboard/Scripting/Cheat_Sheet

Use shorthand notation when the start and end values for a sprite or animation event are identical. The blank space in the endtime field is required for standard notation.

```osu! Storyboard Script
_M,0,1000,,320,240,320,240
```

```osu! Storyboard Script
_M,0,1000,,320,240
```

--------------------------------

### Sequential Events with Same Duration

Source: https://osu.ppy.sh/wiki/en/Storyboard/Scripting/Shorthand

Use this shorthand when multiple values for the same event occur sequentially with a consistent duration between each change. The duration is calculated from the start and end times of the first event.

```storyboard
Sprite,Pass,Centre,"Sample.png",320,240
_F,0,51000,52000,0,1,0.5,1,0

```

--------------------------------

### Storyboard Trigger Syntax

Source: https://osu.ppy.sh/wiki/en/Storyboard/Scripting/Compound_Commands

Defines the general structure for storyboard triggers, including trigger type, start and end times, and event parameters. This format is used to control when specific storyboard events occur.

```plaintext
_T,(triggerType),(starttime),(endtime)
__(event),(easing),(relative_starttime),(relative_endtime),(params...)
// More events allowed
```

--------------------------------

### Apply Yellow Color to Sprite

Source: https://osu.ppy.sh/wiki/en/Storyboard/Scripting/Commands

Applies a yellow color to a sprite over a specified duration. This example demonstrates setting specific RGB values for yellow.

```osu!Storyboard
Sprite,Pass,Centre,"Sample.png",320,240
_C,0,58810,59810,255,255,0

```

--------------------------------

### Declare Audio Sample

Source: https://osu.ppy.sh/wiki/en/Storyboard/Scripting/Audio

Use this format to declare an audio sample that will play at a specific time and layer. The volume can be adjusted, with 100 being the default.

```scripting
Sample,<time>,<layer_num>,"<filepath>",<volume>
```

--------------------------------

### Parameter Event (Flip/Blend)

Source: https://osu.ppy.sh/wiki/en/Storyboard/Scripting/Cheat_Sheet

Apply parameters like horizontal flip (H), vertical flip (V), or additive blend mode (A) to an event.

```osu!Storyboard Script
_P,[...],p
```

--------------------------------

### General Command Structure

Source: https://osu.ppy.sh/wiki/en/Storyboard/Scripting/Commands

The basic structure for all storyboard commands. It defines the event type, easing, timing, and parameters.

```plaintext
_ (event),(easing),(starttime),(endtime),(params...)
```

--------------------------------

### Define an Animation

Source: https://osu.ppy.sh/wiki/en/Storyboard/Scripting/Cheat_Sheet

Use this format to define an animation. Include frame count, frame delay, and loop type in addition to sprite parameters.

```osu!Storyboard Script
Animation,"layer","origin","filepath",x,y,frameCount,frameDelay,looptype
_event,easing,starttime,endtime,[params]
_event, [...]
```

--------------------------------

### Shorthand Event Notation

Source: https://osu.ppy.sh/wiki/en/Storyboard/Scripting/Cheat_Sheet

Use shorthand to script multiple similar events over the same time span by specifying a duration.

```osu!Storyboard Script
_event,easing,starttime,endtime,val1,val2,val3,...,valN
would create events:
_event,easing,starttime,endtime,val1,val2
_event,easing,starttime + duration,endtime + duration,val2,val3
_event,easing,starttime + 2duration,endtime + 2duration,val3,val4

etc.
```

--------------------------------

### Move object from top-left to bottom-right

Source: https://osu.ppy.sh/wiki/en/Storyboard/Scripting/Commands

Moves an object across the screen from the top-left corner to the bottom-right corner over 4.5 seconds.

```osu!storyboard
Sprite,Pass,Centre,"Sample.png",320,240
_M,0,1500,6000,-110,-100,740,580
```

--------------------------------

### Basic Sprite Declaration

Source: https://osu.ppy.sh/wiki/en/Storyboard/Scripting/Objects

Declares a static image (sprite) in the storyboard. Specify the layer, origin, file path, and default coordinates.

```osu! storyboard
Sprite,Pass,Centre,"Text\Play2-HaveFunH.png",320,240
```

--------------------------------

### Define a Static Sprite

Source: https://osu.ppy.sh/wiki/en/Storyboard/Scripting/Cheat_Sheet

Use this format to define a static sprite in the storyboard. Specify the layer, origin, file path, and position.

```osu!Storyboard Script
Sprite,"layer","origin","filepath",x,y
_event, easing, starttime, endtime, [params]
_event, [...]
```

--------------------------------

### Define Standard Loop

Source: https://osu.ppy.sh/wiki/en/Storyboard/Scripting/Cheat_Sheet

Defines a loop to repeat a set of events a specified number of times. Events within the loop should be timed with a zero-base.

```osu! Storyboard Script
_L,starttime,loopcount
__event, [...]
__event, [...]
```

--------------------------------

### Enable Skin Sprites in Storyboards

Source: https://osu.ppy.sh/wiki/en/Storyboard/Scripting/osu%21_File_Toggles

Allows storyboards to reference sprites from the player's current skin by their filenames. This is useful when not forcing a specific skin or when using a map-specific skin.

```ini
[General]
UseSkinSprites: 1
```

--------------------------------

### Declare Variables

Source: https://osu.ppy.sh/wiki/en/Storyboard/Scripting/Variables

Declare custom variables in the [Variables] section of your .osb file. These variables can represent strings, paths, or color values.

```osu!sb
[Variables]
$colour_green=0,255,0
$sample_path="Sample.png"

```

--------------------------------

### Fade object in and out

Source: https://osu.ppy.sh/wiki/en/Storyboard/Scripting/Commands

Fades an object from invisible to half-transparent over 1 second, stays at half-transparent for 2 seconds, then fades out completely over 1 second.

```osu!storyboard
Sprite,Pass,Centre,"Sample.png",320,240
_F,0,1000,2000,0,0.5
_F,0,4000,5000,0.5,0
```

--------------------------------

### Play Sound Effect

Source: https://osu.ppy.sh/wiki/en/Storyboard/Scripting/Cheat_Sheet

Plays a sound effect at a specified time and layer with a given volume. The file path must be enclosed in double quotes.

```osu! Storyboard Script
Sample,time,layer,"filepath",volume
```

--------------------------------

### Define Trigger Loop

Source: https://osu.ppy.sh/wiki/en/Storyboard/Scripting/Cheat_Sheet

Defines a loop that triggers animations based on play-time events. Trigger loops execute once when triggered and are zero-based.

```osu! Storyboard Script
_T,triggerName,start,end
__event, [...]
__event, [...]
```

--------------------------------

### Animation Declaration

Source: https://osu.ppy.sh/wiki/en/Storyboard/Scripting/Objects

Declares an animated sequence of images. Specify layer, origin, file path, default coordinates, frame count, frame delay, and loop type.

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

--------------------------------

### Scale object to larger size

Source: https://osu.ppy.sh/wiki/en/Storyboard/Scripting/Commands

Zooms an object in from invisible to five times its original size over 500 milliseconds.

```osu!storyboard
Sprite,Pass,Centre,"Sample.png",320,240
_S,0,36500,37000,0,5
```

--------------------------------

### Keep object visible for a duration

Source: https://osu.ppy.sh/wiki/en/Storyboard/Scripting/Commands

Makes an object appear on screen and remain fully visible for 2 seconds without any fading.

```osu!storyboard
Sprite,Pass,Centre,"Sample.png",320,240
_F,0,1000,3000,1,1
```

--------------------------------

### Warning: Variable Name Collisions

Source: https://osu.ppy.sh/wiki/en/Storyboard/Scripting/Variables

Illustrates a potential issue where a variable name like '$number_of_loops' could be mistakenly replaced in other parts of the script, such as color values, if not carefully managed. This highlights the importance of using descriptive variable names.

```osu!sb
[Variables]
$number_of_loops=12

[Events]
// ...

Sprite,Pass,Centre,"Sample.png",320,240
_C,0,6000,7000,12,12,12

```

--------------------------------

### Easing Function Values

Source: https://osu.ppy.sh/wiki/en/Storyboard/Scripting/Commands

A table listing the numerical values for different easing functions used in storyboard commands. These control the acceleration and deceleration of events.

```plaintext
Value | Description  
---|---
0 | Linear: no easing  
1 | Easing Out: the changes happen fast at first, but then slow down toward the end  
2 | Easing In: the changes happen slowly at first, but then speed up toward the end  
3 | Quad In  
4 | Quad Out  
5 | Quad In/Out  
6 | Cubic In  
7 | Cubic Out  
8 | Cubic In/Out  
9 | Quart In  
10 | Quart Out  
11 | Quart In/Out  
12 | Quint In  
13 | Quint Out  
14 | Quint In/Out  
15 | Sine In  
16 | Sine Out  
17 | Sine In/Out  
18 | Expo In  
19 | Expo Out  
20 | Expo In/Out  
21 | Circ In  
22 | Circ Out  
23 | Circ In/Out  
24 | Elastic In  
25 | Elastic Out  
26 | ElasticHalf Out  
27 | ElasticQuarter Out  
28 | Elastic In/Out  
29 | Back In  
30 | Back Out  
31 | Back In/Out  
32 | Bounce In  
33 | Bounce Out  
34 | Bounce In/Out  
```

--------------------------------

### Move object vertically

Source: https://osu.ppy.sh/wiki/en/Storyboard/Scripting/Commands

Moves an object from the bottom of the screen to the top over 4.5 seconds, keeping its horizontal position unchanged.

```osu!storyboard
Sprite,Pass,Centre,"Sample.png",320,240
_MY,0,1500,6000,-100,580
```

--------------------------------

### Define Variable

Source: https://osu.ppy.sh/wiki/en/Storyboard/Scripting/Cheat_Sheet

Defines a variable within the [Variables] section of an .osb file. Variables are replaced at save time.

```osu! Storyboard Script
[Variables]
$white=255,255,255
```

--------------------------------

### Move object horizontally

Source: https://osu.ppy.sh/wiki/en/Storyboard/Scripting/Commands

Moves an object from the left side of the screen to the right side over 4.5 seconds, keeping its vertical position unchanged.

```osu!storyboard
Sprite,Pass,Centre,"Sample.png",320,240
_MX,0,1500,6000,-110,740
```

--------------------------------

### Use Variables in Storyboard Events

Source: https://osu.ppy.sh/wiki/en/Storyboard/Scripting/Variables

Reference declared variables by their name (including the '$') within storyboard event parameters. The engine will substitute the variable's value during processing.

```osu!sb
Sprite,Pass,Centre,$sample_path,320,240
_C,0,58810,59810,$colour_green

```

--------------------------------

### Apply Horizontal and Vertical Flip to Sprite

Source: https://osu.ppy.sh/wiki/en/Storyboard/Scripting/Commands

Applies temporary horizontal and vertical flips to a sprite for a specified duration. These parameters only apply during the active time range.

```osu!Storyboard
Sprite,Pass,Centre,"Sample.png",320,240
_P,0,60000,62000,H
_P,0,60000,62000,V

```

--------------------------------

### Rotate object multiple times counterclockwise

Source: https://osu.ppy.sh/wiki/en/Storyboard/Scripting/Commands

Spins an object counterclockwise four full rotations (8*pi radians) over 600 milliseconds.

```osu!storyboard
Sprite,Pass,Centre,"Sample.png",320,240
_R,0,47210,47810,0,-25.133
```

--------------------------------

### Rotate object between angles

Source: https://osu.ppy.sh/wiki/en/Storyboard/Scripting/Commands

Rotates an object from -45 degrees to +45 degrees (clockwise) over 600 milliseconds.

```osu!storyboard
Sprite,Pass,Centre,"Sample.png",320,240
_R,0,47210,47810,-0.785,0.785
```

--------------------------------

### Scale object non-uniformly

Source: https://osu.ppy.sh/wiki/en/Storyboard/Scripting/Commands

Widens an object to twice its original size while reducing its vertical size by half, over 500 milliseconds. Initial scale is 1x for both axes.

```osu!storyboard
Sprite,Pass,Centre,"Sample.png",320,240
_V,0,36500,37000,1,1,2,0.5
```

--------------------------------

### Apply Color Change to Sprite

Source: https://osu.ppy.sh/wiki/en/Storyboard/Scripting/Commands

Applies a color change to a sprite over a specified duration. The color is defined by RGB byte values (0-255).

```osu!Storyboard
Sprite,Pass,Centre,"Sample.png",320,240
_C,0,58810,59810,0,0,0,255,255,255

```
Tokens:
Raw