Foundation.TouchController

Event-driven reaction to mouse and touch events is not always the most convenient way of working when all other game logic is wrapped in a linear loop. If you're happy using event-driven reactions for these events, you can use standard event listeners. However, if you prefer to deal with mouse and touch events in loop updates, the TouchController type provides a convenient way of doing so.

Internally, mouse and touch events are buffered per update. When you check for a current touch event, you are in fact checking if such an event happened at any time in the current update.

This type abstracts mouse and touch events into one interface. On systems with both mouse and touch interfaces, both event types will be tracked, but mouse events will be given higher priority than touch events. For touch interfaces, the number of touch points tracked can be customized.

Note that move events are only tracked as children of down events. When a down event occurs, the instance will start listening for move events. When an up event occurs, the instance will stop listening for move events.

In addition to tracking events per update, this touch controller also abstracts hit detection. The following touch types are tracked:

  • down (mouse down or touch start)
  • move (note: only generated as a child of a down event)
  • up (mouse up, cancel, out, touch end, cancel, etc.)
  • firstHold (start of long press)
  • hold (long press in progress)

Example

// In some sprite or tile's update method, using the touch controller 
// instance from the default game prefab (stored as 'game')
if (game['touch'].downOn(this)){
  console.log("Mouse or touch directly down on the current sprite");
}


Implementation Details

Reference paths

  • '/foundation/_digest.ts'
  • '/foundation/core/actors/_digest.ts'
  • '/foundation/core/actors/TouchController.ts'

Extends

This type extends:

equals() calls will always be false. clone() calls return null. free() releases all internal event listeners

Implements

This type does not implement any interfaces (except those in the base).


Constructors

(container: HTMLElement, camera: Camera, time: GameTimeTracker, maxTouchID: number = 0, historyPoints: number = 10)

  • References to the game instance's HTML container, camera, and time tracker must be passed. These are needed to translate touch points into world space, and track updates.
  • By default, only 1 touch point (id: 0) is tracked. Increasing the maximum touch id will result in additional points being tracked.
  • By default, a maximum of 10 touch events are held in the buffer. In most circumstances this will be sufficient for tracking events from the mouse and 1 touch point. If increasing the number of tracked touch points, you will need to increase this value too.

Instance Methods

anyTouchEvent(type?: number, out?: Vector2): boolean

  • Returns true if any mouse / touch event (down, up, move, firstHold, hold) has been detected in the current update.
  • For versions 0.8+, the type of event to check for can be passed as an optional first argument. When using this argument, the world coordinates of the event can also be retrieved by use of an optional out vector.

downOver(obj: Tile|Sprite, checkCollider: boolean = false, outVector?: Vector2): boolean

  • Returns true if any down event has been detected in the current update, which is over the specified tile or sprite's bounds. Otherwise false.
  • Optionally, outvector may be passed to retrieve the x and y world coordinate of the event.
  • To check, instead, if the event is over a sprite's collider, pass true for checkCollider.

downOn(obj: Tile|Sprite, checkCollider: boolean = false, outVector?: Vector2): boolean

  • Like downOver(), but only returns true if the object is the highest (most toward the end of the list) object which the event is over on its layer.

moveOver(obj: Tile|Sprite, checkCollider: boolean = false, outVector?: Vector2): boolean

  • Returns true if any move event has been detected in the current update, which is over the specified tile or sprite's bounds. Otherwise false.
  • Optionally, outvector may be passed to retrieve the x and y world coordinate of the event.
  • To check, instead, if the event is over a sprite's collider, pass true for checkCollider.
  • Note: Move events are only tracked as children of down events.

moveOn(obj: Tile|Sprite, checkCollider: boolean = false, outVector?: Vector2): boolean

  • Like moveOver(), but only returns true if the object is the highest (most toward the end of the list) object which the event is over on its layer.

upOver(obj: Tile|Sprite, checkCollider: boolean = false, outVector?: Vector2): boolean

  • Returns true if any up event has been detected in the current update, which is over the specified tile or sprite's bounds. Otherwise false.
  • Optionally, outvector may be passed to retrieve the x and y world coordinate of the event.
  • To check, instead, if the event is over a sprite's collider, pass true for checkCollider.

upOn(obj: Tile|Sprite, checkCollider: boolean = false, outVector?: Vector2): boolean

  • Like upOver(), but only returns true if the object is the highest (most toward the end of the list) object which the event is over on its layer.

firstHoldOver(obj: Tile|Sprite, checkCollider: boolean = false, outVector?: Vector2): boolean

  • Returns true if any firstHold event has been detected in the current update, which is over the specified tile or sprite's bounds. Otherwise false.
  • Optionally, outvector may be passed to retrieve the x and y world coordinate of the event.
  • To check, instead, if the event is over a sprite's collider, pass true for checkCollider.

firstHoldOn(obj: Tile|Sprite, checkCollider: boolean = false, outVector?: Vector2): boolean

  • Like firstHoldOver(), but only returns true if the object is the highest (most toward the end of the list) object which the event is over on its layer.

holdOver(obj: Tile|Sprite, checkCollider: boolean = false, outVector?: Vector2): boolean

  • Returns true if any hold event has been detected in the current update, which is over the specified tile or sprite's bounds. Otherwise false.
  • Optionally, outvector may be passed to retrieve the x and y world coordinate of the event.
  • To check, instead, if the event is over a sprite's collider, pass true for checkCollider.

holdOn(obj: Tile|Sprite, checkCollider: boolean = false, outVector?: Vector2): boolean

  • Like holdOver(), but only returns true if the object is the highest (most toward the end of the list) object which the event is over on its layer.