Crafty Beyond the Basics: Mouse and Touch Events

Crafty Beyond the Basics: Mouse and Touch Events

In the last Crafty series, you learned about different ways of moving elements around using the keyboard. While a keyboard can help you create a variety of games, some situations require you to control different mouse events to make the game more enjoyable. For example, consider a game where balloons show up at random places on the screen. If the user needs to click on the balloons to score points, you will definitely need a Mouse component.

Similarly, the Keyboard component will not be of any use when you are developing games for mobile devices. In this case, you will have to rely on the Touch component to create your games. In this tutorial, you will learn about both the Mouse and Touch components in Crafty.

The Mouse Component

The Mouse component is used to add basic mouse events to entities. Here is a list of all events included in this component:

• MouseOver: This event is triggered when the mouse enters inside an entity.
• MouseOut: This event is triggered when the mouse leaves an entity.
  
• MouseDown: This event is triggered when the mouse button is pressed on an entity.
  
• MouseUp: This event is triggered when the mouse button is released inside an entity.
  
• Click: This event is triggered when the mouse button is clicked inside an entity.
  
• DoubleClick: This event is triggered when the mouse button is double-clicked on an entity.
  
• MouseMove: This event is triggered when the mouse is moving inside an entity.

Keep in mind that mouse events will be triggered on an entity only if you have added the Mouse component to them. Here is some code that binds the MouseMove event to the box in the demo below:

var Box = Crafty.e("2D, Canvas, Color, Mouse")
  .attr({
    x: 200,
    y: 100,
    w: 200,
    h: 200
  })
  .color("black")
  .origin("center")
  .bind('MouseMove', function() {
    this.rotation += 1;
  });

After the box has been bound to the MouseMove event, every movement of the mouse over the box will rotate it by 1 degree. The .origin() method has been used to set the rotation point of our box to center. It can also take other values like "top left", "bottom right", etc. 

Try to move the cursor in and out of the box in the demo. Holding a mouse button down inside the box will trigger the MouseDown event and change the color of the box to red.

A MouseEvent object is also passed as a parameter to the callback function of all these mouse events. It contains all the data related to that specific mouse event. 

You can also check which mouse button has been clicked by the user by using the mouseButton property. For example, a left click can be detected by using Crafty.mouseButtons.LEFT. Similarly, a middle button click can be detected by using Crafty.mouseButtons.MIDDLE.

MouseDrag Component

The MouseDrag component provides an entity with different drag-and-drop mouse events. However, adding these events won't make much sense if the entity itself can't be dragged and dropped. You can add drag-and-drop abilities to an entity by using the Draggable component. This component listens to events from the MouseDrag component and moves the given entity accordingly. The MouseDrag component is automatically added to any entity with the Draggable component. 

The Draggable component has three methods: .enableDrag(), .disableDrag(), and .dragDirection(). The first two methods enable and disable dragging on an entity respectively. The third method is used to set the drag direction. 

By default, the entity will move in whatever direction the cursor is moving. However, you can restrict the motion of the entity to a vertical direction by using this.dragDirection({x:0, y:1}). Similarly, you can force an entity to only move in a horizontal direction by using this.dragDirection({x:1, y:0}). 

You can also specify the direction directly in degrees. For example, to move an element 45 degrees, you can simply use this.dragDirection(45) instead of this.dragDirection({x:1, y:1}).

Besides dragging and dropping elements around, it is also necessary to know when the drag started and stopped. This can be accomplished by using StartDrag and StopDrag events. There is also a Dragging event which is triggered while an entity is being dragged.

Here is the code to drag the red box in the demo below:

var hBox = Crafty.e("2D, Canvas, Color, Draggable")
  .attr({
    x: 50,
    y: 50,
    w: 50,
    h: 50
  })
  .color("red")
  .dragDirection(0)
  .bind('Dragging', function(evt) {
    this.color("black");
  })
  .bind('StopDrag', function(evt) {
    this.color("red");
  });

After setting the width, height and position of the box, I have used .dragDirection(0) to restrict the movement of our box in the horizontal direction. I have also used the .bind() method to bind the entity to the Dragging and StopDrag method. 

Changing the color to black gives the user an indication that the entity is currently being dragged. You could also use the StartDrag event instead of Dragging because the color of the entity only needs to be changed once. The Dragging event is more appropriate when you have to continuously change or monitor a property of the entity being dragged. For example, you can use the following code to disable the dragging on the box once it has reached the desired location.

hBox.bind('Dragging', function(evt) {
    this.color("black");
    if(this.x > 300) {
      this.disableDrag();
    }
});

The Touch Component

If you need to access touch-related events for an entity, you can use the Touch component. This component gives you access to four different events:

• TouchStart: This event is triggered when an entity is touched.
• TouchMove: This event is triggered when a finger is moved over an entity.
• TouchCancel: This event is triggered when something disrupts the touch event.
• TouchEnd: This event is triggered when a finger is raised over an entity or it leaves that entity.

The first three events have access to the TouchEvent object, which contains all the information about the touch.

Some games or projects might require you to detect multiple touches. This can be achieved by enabling multi-touch using Crafty.multitouch(true). Passing this method true or false turns the multi-touch on and off.

Before using the Touch component in your projects, you should know that it is currently incompatible with the Draggable component.

Conclusion

After completing this tutorial, you should now be able to properly handle different mouse events or create drag-and-drop-based games easily. Keep in mind that I have used Crafty version 0.7.1 in this tutorial, and the demos might not work with other versions of the library. 

In the next tutorial, you will learn how to use sprite sheets to animate different game characters in Crafty.