Enchant.js Guide

by Patrick Casao, Cal Poly


13 Plugin: Timeline - tl.enchant.js

You can reach the timeline plugin example here.

Subsections
01 A Word on tl.enchant.js
02 Timeline Methods
03 Timeline Example


13.01 - A Word on tl.enchant.js

tl.enchant.js is a plugin that lets us control entities using time-based animation as opposed to the default frame-based animation. Using the methods provided by this plugin, we can create simple animations and cutscenes that depend on time instead of frames.


13.02 - Timeline Methods

Let’s discuss some of the methods that tl.enchant.js provides.

To start, we have the methods setFrameBased and setTimeBased. Calling this method from an entity sets its behavior to use frames or time, respectively.

The moveBy method takes in the parameters x, y, and time. It moves the entity in the x and y direction defined by the parameter x and y in the amount of time defined by the parameter time. There are also methods moveX and moveY which only take in a single parameter x or y and move the entity in that direction.

The moveTo method is similar to the moveBy method in that it takes in the same parameters and moves the entity based on this information. The difference is that the x and y parameters define a location on the scene which the entity is going to be moved to. For example:


SOME_SPRITE.tl.moveBy(10, 10, 1000) 
	
moves SOME_SPRITE 10 units in the positive x-direction and 10 units in the positive y-direction. And:

SOME_SPRITE.tl.moveTo(10, 10, 1000) 
	
moves SOME_SPRITE to the position 10, 10 on the scene.

The delay method takes in the parameter time and waits until that amount of time has passed before executing the next function. It’s often used in conjunction with the then function, which takes in a parameter as a function to be executed.

SOME_SPRITE.tl.delay(1000).then(function(){
	console.log(“Ready!”);
})
	
This waits 1000ms then executes the call to console.log.

If you want to execute a chain of delays, you might want to use the cue method. The cue method takes in a series of time values and methods and executes the methods when the specified time is reached.

SOME_SPRITE.tl.cue({
	0:function(){this.doSomething;},
	500:function(){this.scene.removeChild(this);}
});
	
This calls SOME_SPRITE’s doSomething() method at 0ms, and then removes SOME_SPRITE from the scene at 500ms.

The loop method takes no parameters and continuously runs a method.

SOME_SPRITE.tl.delay(1200).then(function(){
	console.log(“Log call);
}).loop();
	
This call waits 1200ms and then calls console.log continuously.

The rotateBy method takes in the parameters degree and time, and then rotates the entity by the value of degree by the value of the parameter time.

The rotateTo method takes in the parameters degree and time as well, but instead rotates the entity to the value of degree by the value of the parameter time.

SOME_SPRITE.tl.rotateBy(45, 1000)
	
This rotates SOME_SPRITE by 45 degrees in the span of 1000ms.

SOME_SPRITE.tl.rotateTo(45, 1000)
	
This rotates SOME_SPRITE to a 45 degree rotation relative to its initial orientation in the span of 1000ms.

The methods fadeOut and fadeIn lower and raise the entity’s opacity to 0.0 or 1.0 in the amount of time defined by the parameter time. The method fadeTo is similar to these methods except it also takes in the final opacity as a parameter.


13.03 Timeline Example

In my example, I created a short cutscene in which a player character delivers flowers to a female character. As the player character reaches the female character, she turns around and fireworks go off in the background.


p = new Player();
p.tl.setTimeBased();
p.tl.cue({
	0:function(){this.setStanding;},
	2:function(){this.moveAcross();}
});
	
The player sprite is controlled using the cue method which, at specific times, sets the current frames for the player to cycle through.

g = new Girl();
g.tl.setTimeBased();
g.tl.cue({
	1000:function(){
		console.log("Turn girl.");
		this.scaleX *= -1.0;
	}
});
		
	
The female character sprite is controlled using the cue method. At 1000ms, the female character is scaled in the x-direction by -1.0, giving it the appearance that she’s turned around.

bg.tl.setTimeBased();
bg.tl.cue({
	1000:function(){
		this.tl.delay(1200).then(function(){
			addParticles(Math.random() * stgWidth, Math.random() * stgHeight/4, 2, Math.floor(Math.random() * 3.0));
		}).loop();
	}
});
	
The fireworks are controlled using the cue method. At 1000ms, the fireworks being to spawn every 1200ms using a delay method with an attached loop method.

So that's a demonstration of the timeline methods in order to create a time-based cutscene. The final product is visible below in Figure 13.01.



Figure 13.01: Completed Timeline Scene

In the next section we will discuss the Mixing Plugin.