//------------------------------------------------------------------------------
// CONSTRUCTOR SCOPE
//------------------------------------------------------------------------------
/**
* Creates a collection of named input actions and analog axes.
*
* @constructor
* @param {rune.input.Keyboard} [keyboard] Keyboard to read.
* @param {rune.input.Gamepad} [gamepad] One player's gamepad to read.
*
* @class
* @classdesc
* Use Inputs.createActions() for automatic updates before scene logic. A directly
* constructed collection must be updated once before its owner's game logic.
* Devices are borrowed and are never disposed by this collection.
*/
rune.input.Actions = function(keyboard, gamepad) {
//--------------------------------------------------------------------------
// PUBLIC PROPERTIES
//--------------------------------------------------------------------------
/**
* Keyboard used by all actions. May be replaced or set to null.
*
* @type {rune.input.Keyboard}
*/
this.keyboard = keyboard || null;
/**
* Player's gamepad. May be replaced or set to null.
*
* @type {rune.input.Gamepad}
*/
this.gamepad = gamepad || null;
//--------------------------------------------------------------------------
// PRIVATE PROPERTIES
//--------------------------------------------------------------------------
/**
* Registered actions.
*
* @type {Array.<rune.input.Action>}
* @private
*/
this.m_actions = [];
/**
* Registered analog axes, sampled after digital actions.
*
* @type {Array.<rune.input.Axis>}
* @private
*/
this.m_axes = [];
/**
* Whether action states should be sampled.
*
* @type {boolean}
* @private
*/
this.m_enabled = true;
};
//------------------------------------------------------------------------------
// PUBLIC PROTOTYPE GETTER AND SETTER METHODS
//------------------------------------------------------------------------------
/**
* Whether actions and axes are sampled. Disabling resets both and retains bindings.
*
* @member {boolean} enabled
* @memberof rune.input.Actions
* @instance
* @default true
*/
Object.defineProperty(rune.input.Actions.prototype, "enabled", {
/**
* @this rune.input.Actions
* @ignore
*/
get : function() {
return this.m_enabled;
},
/**
* @this rune.input.Actions
* @ignore
*/
set : function(value) {
this.m_enabled = Boolean(value);
if (!this.m_enabled) {
this.reset();
}
}
});
/**
* Whether this collection has been disposed.
*
* @member {boolean} disposed
* @memberof rune.input.Actions
* @instance
* @readonly
*/
Object.defineProperty(rune.input.Actions.prototype, "disposed", {
/**
* @this rune.input.Actions
* @ignore
*/
get : function() {
return this.m_actions == null;
}
});
//------------------------------------------------------------------------------
// PUBLIC PROTOTYPE METHODS
//------------------------------------------------------------------------------
/**
* Creates an action, or returns the existing action with the same name.
*
* @param {string} name Non-empty action name.
* @returns {rune.input.Action} The registered action.
* @throws {TypeError} If the name is invalid.
* @throws {Error} If the collection is disposed.
*/
rune.input.Actions.prototype.create = function(name) {
if (this['disposed']) {
throw new Error("Actions: Cannot create an action after disposal.");
}
var action = this.get(name);
if (action == null) {
action = new rune.input.Action(name);
this.m_actions.push(action);
}
return action;
};
/**
* Finds an action without creating it. Names are matched without regard to case.
*
* @param {string} name Action name.
* @returns {?rune.input.Action} The action, or null if missing or disposed.
*/
rune.input.Actions.prototype.get = function(name) {
if (this['disposed'] || typeof name !== "string") {
return null;
}
name = name.toUpperCase();
for (var i = 0; i < this.m_actions.length; i++) {
if (this.m_actions[i]['name'] === name) {
return this.m_actions[i];
}
}
return null;
};
/**
* Creates an analog axis, or returns the existing axis with the same name.
* Axis names and action names occupy separate namespaces.
*
* @example
* controls.bindKey("LEFT", "A");
* controls.bindKey("RIGHT", "D");
* controls.createAxis("MOVE_X")
* .bindActions("LEFT", "RIGHT")
* .bindStick("left", "x");
* var movement = controls.getAxis("MOVE_X").value;
*
* @param {string} name Non-empty axis name.
* @returns {rune.input.Axis} The registered axis.
* @throws {Error} If the name is invalid or the collection is disposed.
*/
rune.input.Actions.prototype.createAxis = function(name) {
if (this['disposed']) {
throw new Error("Actions: Cannot create an axis after disposal.");
}
var axis = this.getAxis(name);
if (axis == null) {
axis = new rune.input.Axis(name);
this.m_axes.push(axis);
}
return axis;
};
/**
* Finds an axis without creating it. Names are matched without regard to case.
*
* @param {string} name Axis name.
* @returns {?rune.input.Axis} The axis, or null if missing or disposed.
*/
rune.input.Actions.prototype.getAxis = function(name) {
if (this['disposed'] || typeof name !== "string") {
return null;
}
name = name.toUpperCase();
for (var i = 0; i < this.m_axes.length; i++) {
if (this.m_axes[i]['name'] === name) {
return this.m_axes[i];
}
}
return null;
};
/**
* Removes and disposes a named axis, leaving actions and devices unchanged.
*
* @param {string} name Axis name.
* @returns {boolean} Whether an axis was removed.
*/
rune.input.Actions.prototype.removeAxis = function(name) {
var axis = this.getAxis(name);
if (axis == null) {
return false;
}
this.m_axes.splice(this.m_axes.indexOf(axis), 1);
axis.dispose();
return true;
};
/**
* Adds a key binding, creating the action if needed.
*
* @param {string} name Action name.
* @param {string} key Keyboard key name.
* @returns {rune.input.Action} The action, for additional bindings.
* @throws {Error} If the name, key or collection state is invalid.
*/
rune.input.Actions.prototype.bindKey = function(name, key) {
return this.create(name).bindKey(key);
};
/**
* Adds a gamepad button binding, creating the action if needed.
*
* @param {string} name Action name.
* @param {number} button Non-negative integer button ID.
* @returns {rune.input.Action} The action, for additional bindings.
* @throws {Error} If the name, button or collection state is invalid.
*/
rune.input.Actions.prototype.bindButton = function(name, button) {
return this.create(name).bindButton(button);
};
/**
* Reads the combined held state of an action.
*
* @param {string} name Action name.
* @returns {boolean} Whether held. Missing actions return false.
*/
rune.input.Actions.prototype.pressed = function(name) {
var action = this.get(name);
return action != null && action['pressed'];
};
/**
* Reads whether an action became held in the current update.
*
* @param {string} name Action name.
* @returns {boolean} Whether just pressed. Missing actions return false.
*/
rune.input.Actions.prototype.justPressed = function(name) {
var action = this.get(name);
return action != null && action['justPressed'];
};
/**
* Reads whether the last held binding was released in the current update.
*
* @param {string} name Action name.
* @returns {boolean} Whether just released. Missing actions return false.
*/
rune.input.Actions.prototype.justReleased = function(name) {
var action = this.get(name);
return action != null && action['justReleased'];
};
/**
* Combines two actions into an axis. Both or neither held returns zero.
*
* @param {string} negativeName Action for -1.
* @param {string} positiveName Action for 1.
* @returns {number} -1, 0 or 1.
*/
rune.input.Actions.prototype.axis = function(negativeName, positiveName) {
var negative = this.pressed(negativeName) ? 1 : 0;
var positive = this.pressed(positiveName) ? 1 : 0;
return positive - negative;
};
/**
* Removes and disposes a named action without affecting input devices.
*
* @param {string} name Action name.
* @returns {boolean} Whether an action was removed.
*/
rune.input.Actions.prototype.remove = function(name) {
var action = this.get(name);
if (action == null) {
return false;
}
this.m_actions.splice(this.m_actions.indexOf(action), 1);
action.dispose();
return true;
};
/**
* Removes all actions, axes and their bindings.
*
* @returns {undefined}
*/
rune.input.Actions.prototype.clear = function() {
if (!this['disposed']) {
while (this.m_axes.length > 0) {
this.m_axes.pop().dispose();
}
while (this.m_actions.length > 0) {
this.m_actions.pop().dispose();
}
}
};
/**
* Clears sampled states, retaining bindings and leaving devices unchanged.
*
* @returns {undefined}
*/
rune.input.Actions.prototype.reset = function() {
if (!this['disposed']) {
for (var i = 0; i < this.m_actions.length; i++) {
this.m_actions[i].reset();
}
for (var j = 0; j < this.m_axes.length; j++) {
this.m_axes[j].reset();
}
}
};
//------------------------------------------------------------------------------
// INTERNAL PROTOTYPE METHODS
//------------------------------------------------------------------------------
/**
* Samples actions and then axes once per update, after device updates.
*
* @returns {undefined}
* @package
* @ignore
*/
rune.input.Actions.prototype.update = function() {
if (!this.m_enabled || this['disposed']) {
return;
}
for (var i = 0; i < this.m_actions.length; i++) {
this.m_actions[i].update(this.keyboard, this.gamepad);
}
for (var j = 0; j < this.m_axes.length; j++) {
this.m_axes[j].update(this);
}
};
/**
* Releases actions, axes and device references. Safe to call repeatedly.
*
* @returns {undefined}
* @package
* @ignore
*/
rune.input.Actions.prototype.dispose = function() {
this.clear();
this.m_actions = null;
this.m_axes = null;
this.m_enabled = false;
this.keyboard = null;
this.gamepad = null;
};