An overview of enchant.js

Enchant.js is made up of a core library and plugin libraries. The main plugins are included on game dev and sharing site 9leap.net, so you can try out these plugins easily.
For those learning enchant.js, code.9leap.net provides an easy way to do so.

The basics of enchant.js

Enchant.js is a library which runs in HTML5 compatible browsers. It can be used to develop games easily, but can of course be used to create programs other than games.
An example of a simple program which uses enchant.js is shown below.

 enchant(); // declares the use of enchant.js
window.onload = function(){ // run this function after the window has been loaded
   game = new Core(320,320); // create a new game with resolution of 320x320
   game.preload('fig1.png','fig2.png'); // specifies which image files should be loaded when the game starts
   game.onload = function(){ // describes what should be executed when the game starts
      var bear = new Sprite(32,32); // create a sprite
      bear.image = game.assets['fig1.png']; // specifies the image file *this must have been preloaded
      bear.x = 50; // specifies position on the x-axis
      bear.y = 50; // specifies position on the y-axis
      game.rootScene.addChild(bear); // display the image on the screen
   }
   game.start(); // begin the game
} 

After creating an instance of the Core class, from within window.onload, and after preloading the images for use by the game, the contents of game.onload are executed.

A majority of the game processing is actually defined by the contents of game.onload.

Entities

Scenes, sprites, labels, and groups are images which are displayed, and are abstracted by enchant.js into entities, which make up games. All entities inherit the Entity class, and are displayed by being given a specific position on the x and y axes, and then by being added to a specific scene. The steps which create an instance of the Game class are as follows. Since the default scene is by default set to game.rootScene, it is commonplace to use addChild to this to display something on the screen.

Scenes can contain groups. Since groups can also be added to other entities (like scenes) with addChild, when displaying something on the screen, you need to keep track of which scene the group is being added to.

If you need to remove an entity from a scene, use removeChild.

The actual screen is displayed depending on sprites and labels. The word “sprite” originally has the meaning of a “fairy-like creature,” and means the image is expected to fly around the screen.

Labels, like their name suggests, display characters on the screen.

Events

Events take place when something touches something else on the screen, when a specific amount of time has passed, or some other type of change occurs.
When events take place, functions called “event listeners” can be created.

By adding event listeners to entities, the entities can be controlled.
When the event listeners are triggered, they issue commands to their parent entity.

 var bear = new Sprite(32,32); // create a sprite
bear.image = game.assets['fig1.png']; // set the image to be displayed
bear.x = 50; // set the position on the x-axis
bear.y = 50; // set the position on the y-axis

bear.addEventListener('enterframe',function(){ // add an event listener
   // the event listener for the enterframe event
   this.x+=2; // move two pixels to the right
});
game.rootScene.addChild(bear); // show the image on the screen 

By doing this, animation of the bear moving to right can be displayed on the screen. The enterframe event calls all entities displayed on the screen one-by-one and in a fixed interval.

Another example

 bear.addEventListener('touchend',function(){ //add an event listener
   //event listener for the touchend event
   this.x+=2; //move two dots to the right
}); 

By changing the event name to touchend, this time the character will only move 2 pixels to the right when clicked by the user, and makes the sprite interactive.

To create an event listener for the entire screen, add an event listener to the scene itself.

 game.rootScene.addEventListener('touchend',function(param){ // scene event listener
   bear.x = param.x; // move the bear to the clicked location
   bear.y = param.y;
}); 

Event listeners can accept parameters. Here, by using param, the event listener passes the coordinate which was clicked.

Here, by substituting the coordinates of the bear with the position clicked on the screen, the character is moved. Events can also be added to an entity multiple times.

Classes

When you get accustomed to developing, making more complicated games will become easier by creating your own custom classes. Classes in enchant.js can be created with the Class.create function.

 Bear = Class.create(Sprite, { // declare a custom class called Bear
   initialize:function(){ // initialize the class (constructor)
      Sprite.call(this,32,32); // initialize the sprite
      this.image = game.assets['fig1.png']; // set the image
      game.rootScene.addChild(this);
   }
}); 

By defining this class, it is easier to create this character going forward.

 bear = new Bear(); 

That’s it. Just by doing this, we create an instance of the custom Bear class, which inherits the Sprite class. By inheriting the class, we easily create the Bear class which contains all of the functions of the Sprite class.
To not use inheritance, the following is used.

 hoge = Class.create({
   initialize:function(){
      this.x=10;
   }); 

Also, defining an event listener here makes it easier going forward.

 Bear = Class.create(Sprite, { // define the custom class
   initialize:function(){ // initialize the class (constructor)
      Sprite.call(this,32,32); // initialize the sprite
      this.image = game.assets['fig1.png']; // designate the sprite image
      game.rootScene.addChild(this);
   },
   onenterframe:function(){ // enterframe event listener
      this.x+=2;
   },
   ontouchend:function(){ // the event listener for the touchend event
      this.y+=10;
   }
}); 

It will help you immensely to be able to write classes like this. A class you’ve created once can be copied over and over.

 bear1 = new Bear();
bear1.x=100;

bear2 = new Bear();
bear2.x=150; 

Being able to effectively apply these classes will increase the efficiency with which you develop games.

Collision detection

To find out if an entity has intersected, or made contact with, another entity, use within or intersect.

 if(bear1.intersect(bear2)){ // if bear1 hits bear2
   bear1.x -= 10;
   bear2.x += 10;
} 

Lastly

This concludes our introductory explanation of enchant.js. The reference manual contains more detailed information about the library. By being able to use even more techniques, we believe you’ll be able to enjoy the library even more.

Enjoy!

This post is also available in: Japanese, Portuguese (Brazil)