spite / storyline.js

Storyline - generic sequencer for JavaScript projects

Storyline.js - Multi-purpose sequencer

Storyline.js is a library to help define a storyboard using natural language.

This is the refined and polished version of the sytem created for BEYOND and cru·ci·form.

Check out the example to see it in action: Storyline.js with CSS 2D transforms.

Using Storyline.js

There's two parts: Storyline.js is the parser and player, and then a storyboard source object that defines the story. A storyline source has this format:

{
    "value1": [
        "0 cut to 10",
        "2 linear to 3"
    ],
    
    "value2": [
        "0 cut to 0",
        "4 ease to 1",
        "6 ease to 0"
    ]
}

This source object is a map of keys (each key is a value that you will be using in your code x, angle, power, etc.), and each key contains an array of entries. Each entry defines a point in time, and a storyline action, and has the following syntax:

{time in seconds} {action to perform} {value of action}

The actions are:

• cut to instanteously changes to {value}
• linear to will linearly interpolate from the last defined value to {value}
• ease to will ease in-out from the last defined value to {value}

Minimal example

Include Storyline.js

<script src="Storyline.js"></script>

Create a storyline from a structured storyboard source. By calling storyline.get you can get the updated value:

var storyline = STORYLINE.parseStoryline( {

    "value1": [
        "0 cut to 0",
        "5 ease to 1",
        "10 ease to 0"
    ]
    
} );

function update() {
    
    requestAnimationFrame( update );
    console.log( storyline.get( 'value1', ( Date.now() / 1000 ) % 10 ) );
    
}

update();

External storyboard example

Simply export the storyline into its own file, and include it like a normal script.

var storyline = STORYLINE.parseStoryline( {

    "value1": [
        "0 cut to 0",
        "5 ease to 1",
        "10 ease to 0"
    ]
    
} );

Or load the content with AJAX and parse it when it's loaded:

var oReq = new XMLHttpRequest();
oReq.onload = function() {
	storyline = STORYLINE.parseStoryline( this.responseText );
	/* ready to use */
};
oReq.open( 'get', 'storyboard.json', true);
oReq.send();

Status

This is the first release. Next steps are to add syntax to control the easing functions, probably something like:

{time} ease to {value} { [ set of easing control points] }

Also, support specific functions to simplify animations:

{time} {wiggle|shake} {extent}

As always: forks, pull requests and code critiques are welcome!

License

MIT licensed

Copyright (C) 2015 Jaume Sanchez Elias, http://www.clicktorelease.com

storyline.js's Issues

.get() returns null in between points

Consider the following example:

"x": [
   "0 cut to 0",
   "2 ease to 10",
   "4 cut to -5"
]

At t = 0, x is 0.
At t = 1, x is some value between 0 and 10.
At t = 2, x is 10.
At t = 3, x is null.
At t = 4, x is -5.

I would expect x to hold its value until the next point. In this example, to stay at 10 for 2 seconds and then cut to -5.