Why MBTweener?

Like most of the tools I create I made MBTweener because I had a problem. I was looking for a light tweening engine that could tween some css properties (i.e. use suffixes like px and %) as well as some normal numbers. I only needed it for one page of the website and only for one or two things on that page, so I was looking for the lightest tween engine I could find for the task.

Problem: there weren’t any. I found some really good and capable Tweening engines...that were approaching 100kb minimized with their CSS capable portions imported as well. I also found some really light engines that were nice, but they had no ability to CSS properties with suffixes (except for one that allowed you to handle the tween tick by tick in your own custom function...which seemed to me like it wasn’t even a tweening engine at that point any more).

So, like so many other projects I’ve made, I settled on “screw it, I’ll make my own.” The goal being a super light-weight tweening engine that’s easy to use and suffixed CSS property capable. This is not intended to outdo the feature lists of many of the well established tweening engines out there. Its intention is to provide a decent amount of features while still being extremely lightweight. And the end result is a decently capable engine that’s just a touch over 7kb minified (as of v 1.0.0). Download MBTweener here.

Simple Tweening

MBTweener is simple to use. You can either use the static MBTweener.to method, or you can use new MBTween, with both options taking the exact same list of possible arguments. The main differences between the two is the MBTweener is self managed and will remove any previous tweens on the same object before running itself, while instantiating an MBTween is completely “you"-managed, opening the door to you doing whatever you like. That, and with instantiating an MBTween you have to call a instance.start() method to actually start the tween.

Here’s an example of both tweening an object’s x property to 50 and y property to 100 with a 1000 millisecond duration:

MBTweener.to(obj, 1000, {x:50, y:100});

// or

var tween = new MBTween(obj, 1000, {x:50, y:100});

With MBTweener keep in mind that it is managed and only allows one set of tweens per object. So calling it twice in a row for 2 different properties, the 2nd will override the first and the first just won’t happen. This is nice because it makes tweening super easy: if you use that method exlusively then it’s a simple matter of “call it and that’s what’ll happen", overriding anything else that may interfere. But it is a limitation to keep in mind with that method too, meaning each of the properties has to tween with the same duration and other tween settings as each other.

Tween Start and End Point

The above examples just tween those properties from their current values to those new ones. To set both the start and ending values you’d do this:

MBTweener.to(obj, 1000, [{x:0, y:0}, {x:50, y:100}]);

Note: the paremeter usage is identical with the arguments for new MBTween, I’ll just show 1 from now on for brevity.

Basically instead of just passing an object with the end properties, you pass a 2 valued array with the start properties then the end properties.

Using Settings

After the object, duration, and properties parameters there is also an optional settings parameter. There you can set things like a suffix to use (such as px or % for CSS properties), the easing function to use, whether or not to round end results to whole numbers (useful for tweening a number you’ll display visually, like an increasing score text), onComplete and onCancel functions, and a data property where you can store anything you may want on that tween which will be passed to any onComplete or onCancel event.

MBTweener.to(obj.style, 1000, {top:20, height:100}, {
        data:'whatever you want'

function myTweenCompleted(tween, data) {
    alert('tween on '+tween.target+' finished!');

function myTweenCanceled(tween, data) {
    alert('tween on '+tween.target+' cancelled!');

suffix - Can be any string you want added to the end of the number value when it’s applied to the object. Notice that here I’m tweening the obj.style object and the properties top and height with a suffix of “px". They will be tweened to 20px and 100px respectively. This is how you easily tween CSS values. Other suffixes like “%” will work just fine as well. In fact, it’ll take anything. You could even tween an innerHTML property of an element that holds “1000 health” and set a suffix of “ health” to tween that visual text. Note: The suffix property affects all properties in a given tweening instance. To just put a suffix on certain ones simply write them as a string with that suffix, such as MBTweener.to(obj.style, 1000, {left:'50px', top:'100%'});

easing - A string indicating to use any of the easing functions included. By default uses ’easeInOutSine’, but can take from any of the following: ’linear’ ’easeInSine’ ’easeOutSine’ ’easeInOutSine’/’swing’ (same thing) ’easeInExpo’ ’easeOutExpo’ ’easeInOutExpo’ ’easeInElastic’ ’easeOutElastic’ ’easeInOutElastic’ ’easeInCircular’ ’easeOutCircular’ ’easeInOutCircular’ ’easeInBack’ ’easeOutBack’ ’easeInOutBack’ ’easeInBounce’ ’easeOutBounce’ ’easeInOutBounce’ ’easeInCubic’ ’easeOutCubic’ ’easeInOutCubic’

round - A true or false to round all values during the duration of the tween. For example if tweening some text, (such as by tweening an innerHTML property) you could set this to true so that it doesn’t show decimals for the tween. Likewise in some situations it’s useful to be able to keep an object’s x and y coordinates on whole numbers only. False by default, but there if you need it.

onComplete - Set this to a function that will call when the tween completes naturally. Will call with two parameters sent: the tween object itself (which has a target property so that you can easily access the target of the tween) and the data property you set when you made the tween (or undefined if there isn’t one).

onCancel - Set this to a function that will call when the tween is cancelled before completion (such as if instance.stop() is called on a tween instance or a new MBTweener.to call to the object being tweened overrides the current one). Will call with two parameters sent: the tween object itself (which has a target property so that you can easily access the target of the tween) and the data property you set when you made the tween (or undefined if there isn’t one).

onStop - Set this to a function that will call when the tween ends for any reason (cancelled or completed). Will call with two parameters sent: the tween object itself (which has a target property so that you can easily access the target of the tween) and the data property you set when you made the tween (or undefined if there isn’t one).

react - Set this to reference a React.js class and it will automatically update states of the same name as the properties being tweened when the tween is completed or cancelled.

states - When using the react property if a states object is used then you can define state names to update and which tweened property they should match, for example states:{tweenedProp:'stateName'}, as opposed to having to use states of the same name as the properties being tweened.

data - Just any old data you want attached to the tween. String, object, whatever.

More on MBTween

Remember than when using new MBTween you are responsible for managing it. You can do that by utilizing the following MBTween methods and properties.

tween.start() - The tween does not actually start until this is called. It is meant to be called only once.

tween.stop() - Cancel an in-progress tween by calling this. This will only do anything if the tween was actually running, and will return true or false based on whether it did actually stop an active tween or not. For example: the onCancel function will NOT be called if you call stop on a tween that was already complete anyway.

tween.running - A read-only property that tells you whether or not the tween is going at this moment.

tween.target - The target object of the tweeen.

tween.duration - The duration of the tween in milliseconds.

MBTween.defaultEase - [static] A string that will be the default easing used for all tweens when none is explicitly given. Default is 'easeInOutSine'.

MBTween.FPS - [static] A number representing the frames per second rate at which tweens will update. Default is 30. Needs to be changed before any tweens are created only.

Chaining and Delaying Tweens

Another neat ability of MBTweener stuff is the ability to easily make a chain of tweens and/or delays that call one after another. This is done by a series of MBTween objects and an MBTween.chain static method.

    new MBTween(obj, 1000, {x:50}),
    new MBTween(obj, 1000, {x:80}),
    new MBTween(obj, 1000, {x:120}, {onComplete:function(){alert('done!');}})

You can also throw delays in there like so:

    new MBTweenDelay(500),
    new MBTween(obj, 1000, {x:50}),
    new MBTween(obj, 1000, {x:80}),
    new MBTweenDelay(800),
    new MBTween(obj, 1000, {x:120}, {onComplete:function(){alert('done!');}})

Licensing & Download

There you go, that pretty much explains it all. Now you just need to get it and know how you’re allowed to use it. Basically: it’s just totally free. I actually use a couple functions in it that were BSD license, so I decided to make the whole thing BSD licensed (as opposed to my normal MIT license). But the end result is basically the same: use it however you want (commercial, non-commercial, whatever) just leave the code comment in place in the JS that tells the copyright info. Basically the same deal as jQuery, or any of the other free tools people use. It’s just...free. I have used this tweening engine in some pretty complex stuff, including tieing it in with jQuery like APIs, doing animations in 3D with it, and building both top-down and platform style HTML5/JS games utilizing it. I consider it quite stable at this point, but if you find a bug please do let me know.

Current version is 1.1.0 as of 3/26/2016.


Download MBTweener