API Reference

Storyboard

The storyboard object contains all sprites of your storyboard in their distinct layer array, his main purpose is to to create an interface with your sprites. Here is how the scruture of a storyboard object looks like:

Storyboard {
  layers: Map(5) {
    'Background' => [ [Sprite], [Sprite], [Sprite] ],
    'Fail' => [],
    'Pass' => [],
    'Foreground' => [ [Sprite] ],
    'Overlay' => []
  }
}

createSprite

Create a sprite object and link it directly to the storyboard object

parameters:

• Path: Relative path to your sprite, use the path starting from your beatmap folder, e.g "sb/myImage.png"
• Options: Configuration object of the sprite

return: Sprite

example usage:

// Basic sprite creation, without options
const sprite = storyboard.createSprite('bg.jpg');

// Advanced sprite creation, with options
const sprite_advanced = storyboard.createSprite('bg.jpg', {
  layer: "Foreground",
  origin: "Centre",
  x: 320,
  y: 200
});

write

Output the storyboard content into a file

parameters

• file_path: The file path that should be written

return: void

example usage:

const storyboard = new Storyboard();
storyboard.write('out.osb');

/* OUTPUT FILE
[Events]
//Background and Video events
//Storyboard Layer 0 (Background)
//Storyboard Layer 1 (Fail)
//Storyboard Layer 2 (Pass)
//Storyboard Layer 3 (Foreground)
//Storyboard Layer 4 (Overlay)
*/

toString

Converts a storyboard object to a string output, this is the function used to write.

parameters: none

return: String

example usage:

const storyboard = new Storyboard();
const stringified_storyboard = storyboard.toString();
console.log(stringified_storyboard);

Sprite

Same as storyboard, sprite have it own object type, which is used to interact with its parameters. Each sprite have a parameter array which contains all the parameters that you can add with the next functions

Sprite {
  events: [
    {
      type: 'F',
      easing: 0,
      start: 0,
      end: 1000,
      start_values: [Array],
      end_values: [Array],
      stringified: ' F,0,0,1000,0,1'
    }
  ],
  path: 'sb/p.png',
  origin: 'Centre',
  layer: 'Background',
  x: 320,
  y: 240
}

add

This function add a new event to the sprite

parameters:

• type: The type of the event (F,M,MX,MY...)
• times: Times of the event
• values: Values of the event
• easing (optional): Easing ID

return: void

example usage:

const storyboard = new Storyboard();
const sprite = storyboard.createSprite('sb/p.png');

// F,0,0,1000,0,1
sprite.add('F', [0, 1000], [0, 1]);

// F,0,0,,1
sprite.add('F', 0, 1);

// F,18,0,1000,320,240,320,340
sprite.add('M', [0, 1000], [320, 240, 320, 340], 18);

param

Generate a new parameter event (such as additive)

parameters:

• start: beginning of the parameter
• end: end of the parameter
• type: type of the parameter ('A' = additive)

return: void

example usage:

const storyboard = new Storyboard();
const sprite = storyboard.createSprite('sb/p.png');

// P,0,0,1000,A
sprite.param(0, 1000, 'A');

createLoop

Setup an osb loop by giving it an array of events

params

• start: Start of the loop
• loop_count: Number of iterations
• events: Array of events to be generated

return: void

example usage:

const storyboard = new Storyboard();
const sprite = storyboard.createSprite('sb/p.png');

sprite.createLoop(12451, 4, [
  newEvent('F', [0, 300], [0, 1]),
  newEvent('F', [700, 1000], [1, 0]),
]);

/* OSB OUTPUT
Sprite,Background,Centre,"sb/p.png",320,240
 L,12451,4
  F,0,0,300,0,1
  F,0,700,1000,1,0
*/

toString

Convert a sprite object to a string

parameters: none

return: String

Other functions

dotosb have a bunch of functions that can be used for multiple purposes outside of being dependant on an object.

newEvent

Generate a new detached event

parameters: same as add() function

return: Event object

newParam

Generate a new detached parameter event

parameters: same as param() function

return: Param object

fromFile

Convert a storyboard from a .osb file to a Storyboard object

parameters:

• path: Path to the .osb file

return: Storyboard

Constant

There is also a bunch of Constants that are available

EVENT_TYPES

Hashmap of all the event types and their number of parameters required