Options
All
  • Public
  • Public/Protected
  • All
Menu

Provides keyboard support for Excalibur.

Working with the keyboard is easy in Excalibur. You can inspect whether a button was just pressed or released this frame, or if the key is currently being held down. Common keys are held in the Keys enumeration but you can pass any character code to the methods.

Excalibur subscribes to the browser events and keeps track of what keys are currently held, released, or pressed. A key can be held for multiple frames, but a key cannot be pressed or released for more than one subsequent update frame.

Inspecting the keyboard

You can inspect Engine.input to see what the state of the keyboard is during an update.

It is recommended that keyboard actions that directly effect actors be handled like so to improve code quality:

class Player extends ex.Actor {
  public update(engine, delta) {
    if (engine.input.keyboard.isHeld(ex.Input.Keys.W) || engine.input.keyboard.isHeld(ex.Input.Keys.Up)) {
      player._moveForward();
    }

    if (engine.input.keyboard.wasPressed(ex.Input.Keys.Right)) {
      player._fire();
    }
  }
}

Events

You can subscribe to keyboard events through engine.input.keyboard.on. A KeyEvent object is passed to your handler which offers information about the key that was part of the event.

  • press - When a key was just pressed this frame
  • release - When a key was just released this frame
  • hold - Whenever a key is in the down position
engine.input.keyboard.on("press", (evt: KeyEvent) => {...});
engine.input.keyboard.on("release", (evt: KeyEvent) => {...});
engine.input.keyboard.on("hold", (evt: KeyEvent) => {...});

Hierarchy

Implements

Index

Constructors

constructor

Properties

eventDispatcher

eventDispatcher: EventDispatcher

Direct access to the game object event dispatcher.

Methods

emit

  • emit(eventName: string, eventObject?: GameEvent<any>): void
  • Emits a new event

    Parameters

    • eventName: string

      Name of the event to emit

    • Optional eventObject: GameEvent<any>

      Data associated with this event

    Returns void

getKeys

init

  • init(global?: GlobalEventHandlers): void
  • Initialize Keyboard event listeners

    Parameters

    • Optional global: GlobalEventHandlers

    Returns void

isHeld

  • isHeld(key: Keys): boolean
  • Tests if a certain key is held down. This is persisted between frames.

    Parameters

    • key: Keys

      Test whether a key is held down

    Returns boolean

off

  • off(eventName: string, handler?: function): void
  • Alias for removeEventListener. If only the eventName is specified it will remove all handlers registered for that specific event. If the eventName and the handler instance are specified only that handler will be removed.

    Parameters

    • eventName: string

      Name of the event to listen for

    • Optional handler: function

      Event handler for the thrown event

    Returns void

on

  • on(eventName: Events.press, handler: function): void
  • on(eventName: Events.release, handler: function): void
  • on(eventName: Events.hold, handler: function): void
  • on(eventName: string, handler: function): void

once

  • once(eventName: string, handler: function): void
  • Once listens to an event one time, then unsubscribes from that event

    Parameters

    • eventName: string

      The name of the event to subscribe to once

    • handler: function

      The handler of the event that will be auto unsubscribed

    Returns void

update

  • update(): void

wasPressed

  • wasPressed(key: Keys): boolean
  • Tests if a certain key was just pressed this frame. This is cleared at the end of the update frame.

    Parameters

    • key: Keys

      Test whether a key was just pressed

    Returns boolean

wasReleased

  • wasReleased(key: Keys): boolean
  • Tests if a certain key was just released this frame. This is cleared at the end of the update frame.

    Parameters

    • key: Keys

      Test whether a key was just released

    Returns boolean

Static extend

  • extend(methods: any): any
  • You may wish to extend native Excalibur functionality in vanilla Javascript. Any method on a class inheriting Class may be extended to support additional functionality. In the example below we create a new type called MyActor.

    var MyActor = Actor.extend({
    
       constructor: function() {
          this.newprop = 'something';
          Actor.apply(this, arguments);
       },
    
       update: function(engine, delta) {
          // Implement custom update
          // Call super constructor update
          Actor.prototype.update.call(this, engine, delta);
    
          console.log("Something cool!");
       }
    });
    
    var myActor = new MyActor(100, 100, 100, 100, Color.Azure);
    

    In TypeScript, you only need to use the extends syntax, you do not need to use this method of extension.

    Parameters

    • methods: any

      A JSON object contain any methods/properties you want to extend

    Returns any