movy.js is an easy-to-use animation engine based on three.js and gsap.

Getting Started

Make sure you have node.js (version >= 12) installed on your computer.

You can install movy.js simply by:

npm i -g movy

To run movy.js, enter the following command in your terminal:

movy

It will show a list of example animations in the examples folder.

To create your own animation, you can start a new javascript file. Following is a simple hello-world example:

import * as mo from "movy";

const t = mo
  .addText("movy.js is simple!", {
    scale: 1,
    color: "yellow",
  })
  .reveal();

mo.run(); // Should call this method at the end!!!

Save the file as hello.js. To open the animation in the browser, you can

movy hello.js

Note that changing the source code will automatically refresh the browser content.

Add objects into the scene

To add new objects into the scene, you can use mo.add___() methods. For example:

Method	Comment	Preview
mo.addCircle()	Add a circle
mo.addRect()	Add a rect
mo.addTriangle()	Add a triangle
...	...	...

Customize objects

All methods above can take extra named arguments for object customization. For example, to set the object color, you can use

mo.addTriangle({ color: "yellow", scale: 0.5 });

This will create a half-size yellow triangle.

Furthermore, you can pass

Methods	Comment	Preview
mo.addCircle({ x: 0.5, y: 0.2 })	Set X and Y coordinates to be (0.5, 0.2). Note that movy.js uses Cartesian coordinates for 2D objects (y-axis pointing upwards).
mo.addCircle({ position: [0.1, 0.2, 0] })	position specifies the circle coordinates similar to x, y, z parameters. However it takes an array of numbers.
mo.addRect({ rz: 0.25 * Math.PI, });	Rotate the rect along the Z axis by π/4.
mo.addRect({ rx: 0.5, ry: 1 })	Note that movy.js internally uses 3D coordinates. You can also rotate any 2D object along X and Y axis by rx and ry parameters.
mo.addCircle({ scale: 0.5, })	Scale the circle by 0.5 (half size).
mo.addCircle({ sx: 1.5, sy: 0.5 })	Create an ellipse by scaling along X and Y axis differently.
mo.addCircle({ color: "#3498db" })	You can pass hex code, e.g. "#3498db" to specify object color. Alternatively, you can use X11 color name, e.g. "blue".

More shapes

Besides, you can use mo.add___Outline() methods to create outlined shapes. For example:

Method	Comment	Preview
mo.addCircleOutline()	Add circle outline.
mo.addRectOutline()	Add rect outline.
mo.addTriangleOutline()	Add triangle outline.
...	...	...

All named arguments mentioned in the previous section still works for these outlined shapes. Moreover, you can pass

Methods	Comment	Preview
mo.addCircleOutline({ lineWidth: 0.3, })	Set the line width of the circle outline to 0.3.
mo.addRectOutline({ width: 1.5, height: 1, })	Instead of sx and sy to scale a shape, you can alternatively use width and height to specify the size of a shape. This method will not scale the line strokes unevenly.

Add animations

For each added scene object, you can call, e.g. obj.fadeIn(), obj.reveal(), obj.grow(), etc. to add different animations.

const rect = mo.addRect();

rect.grow();  // This will add grow animation to the circle object.

The following table lists the common animations supported by movy.js.

rect.fadeIn()		rect.wipeIn()
rect.grow()		rect.rotateIn()
rect.reveal()		rect.shake2D()

Customize animations

All animations can take following parameters for customization.

rect.fadeIn({t: 1})	t parameter specifies when the animation should be started. For example, t: 1 specifies that the animation should start at 1 second. t: '<' specifies that the animation should begin at the same time of the previous animation. t: '+=1' specifies that the animation should starts 1 second after all previous animations finish. movy.js internally uses gsap. For more information, please refer to Understanding the Position Parameter.
rect.fadeIn({duration: 2})	Set the animation duration to 2 seconds.
rect.fadeIn({ease: 'linear'})	ease parameter specifies the easing curve used for the animation. Different animations are pre-configured with different default easing functions. However, you can overwrite this to completely change the nature of your animation. For more information, please refer to gsap / Eases

Note that some animation can take extra parameters. For example, you can pass { direction: 'down' } in obj.reveal() to specify the direction from which the object reveals.

Combining animations

By combining existing animations with some parameter tweaking, we can derive more complicated and beautiful animations.

mo.addRectOutline()
  .reveal()
  .moveTo({ rz: Math.PI * 4, duration: 2 })
  .fadeOut();