Handling Input

Introduction

Now that we’ve got a sprite drawn up on the screen, know the basics of using components and attaching scripts, let’s move on to handling keyboard and mouse input in our game.

Handling Input Events

The way that Cocos Creator handles events is pretty straight forward. There is a built-in event system in Cocos and we can use that to handle and respond to all kinds of events, including input events. There are two kinds of events, the built-in events that can be handled at the node level and system events, that are handled in a slightly different manner. System events completely ignore nodes and are globally broadcast, while other events are propagated from node to node until the event is handled. Let’s start first with system-level events, the only two support events are Keyboard and Device Motion events. We will talk about motion events at a later point, so let’s focus on handling keyboard events. Keyboard events are handled using the global object cc.systemEvent like so:

const {ccclass, property} = cc._decorator;

@ccclass
export default class KeyboardScript extends cc.Component {
    public keys : Map<number,boolean> = new Map();

    onKeyDown(e:cc.Event.EventCustom){
        this.keys.set(e.keyCode,true);
        switch(e.keyCode){
            case cc.KEY.right:
                if(this.keys.has(cc.KEY.shift))
                    console.log("Right and shift pressed");
                else                    
                    console.log("Right pressed");
                break;
        }
        console.log(this.keys.size);
    }
    onKeyUp(e:cc.Event.EventCustom){
        this.keys.delete(e.keyCode);
    }

    onLoad () {
        cc.systemEvent.on(cc.SystemEvent.EventType.KEY_DOWN,
            this.onKeyDown,this);
        cc.systemEvent.on(cc.SystemEvent.EventType.KEY_UP,
            this.onKeyUp,this);         
    }
}

Keyboard handling in Cocos Creator is actually quite simple, there are two events you can wire up, KEY_DOWN and KEY_UP. The event handler is registered using on() connected to systemEvent, and is therefor handled globally. In this case, we check specifically if the right arrow is pressed and print accordingly.

Since Cocos Creator keyboard functionality is quite limited, we roll our own solution to track if multiple keys are pressed. When a key is pressed, we add it to a map, with the identifying key as the um… key. When the key is released, we remove it from the map. This gives us the ability to poll the currently pressed keys, as we do when the Right arrow key is pressed. We also check to see if the SHIFT key is currently pressed as well, and if it is, we print the appropriate message.

So that’s the basics of dealing with Keyboards, now let’s take a look at dealing with the mouse. Unlike System Events, mouse events are fired at a more local level. Let’s jump right in with the code:

const {ccclass, property} = cc._decorator;

@ccclass
export default class MouseScript extends cc.Component {
    onLoad () {

        this.node.on(cc.Node.EventType.MOUSE_DOWN,(e:cc.Event.EventMouse)=>{
            console.log("Mouse down on top of selected node");
            e.bubbles = false; // Handled event don't let it propogate!
        });

        this.node.on(cc.Node.EventType.MOUSE_LEAVE,(e:cc.Event.EventMouse)=>{
            console.log("Mouse no longer over " + e.currentTarget.name);
        });

        this.node.parent.on(cc.Node.EventType.MOUSE_DOWN,(e:cc.Event.EventMouse)=>{
            console.log("Mouse button pressed on parent.  Button: " + e.getButton());
        });
    }
}

We connect the event to the node in this case instead of to SystemEvent. In this example, we implement MOUSE_DOWN, MOUSE_LEAVE, and MOUSE_DOWN on our parent, the overall canvas. MOUSE_DOWN is fired when the mouse is clicked. Notice the call to e.bubbles setting it to false? This is to prevent the event from bubbling past this event handling. By setting this to false, the MOUSE_DOWN event will never fire on the parent because we ate the event when we handled it in the child. Set to true and the event will fire again and again for each MOUSE_DOWN handler.

In addition to MOUSE_DOWN and MOUSE_LEAVE there are also events for MOUSE_UP, MOUSE_ENTER, MOUSE_MOVE, and MOUSE_WHEEL. As you can see from our example, you can get further information about the mouse event using the EventMouse that’s passed into the event handler.