Followup: TODO for gamepad support

[parasyte]

Follows #34

• Add a gamepad tester to examples; for validating mappings
• Remap axes[4] and axes[5] extension (L2 and R2 analog triggers) to buttons[me.GAMEPAD.L2].value and buttons[me.GAMEPAD.R2].value
• Add a new API for reading and writing action states
  • me.input.isActionSet(action) (was me.input.isKeyPressed)
  • me.input.getActionState(action) (was me.input.keyState)
  • me.input.getActionValue(action) (NEW; returns action analog value)
  • me.input.getAction(action) (NEW; returns action analog value, digital state, and digital edge)
  • me.input.setAction(action, state, value) (NEW; sets action analog value and digital state)
• Add a new method for custom gamepad mapping, with a normalization function
  • me.input.setGamepadMapping(id, mapping)
  • The function signature has been changed to better fit the needs of remapping axes to button values; see below.
  • mapping is a hash table containing the following keys:
    • {Number[]} mapping.axes Standard analog control stick axis locations
    • {Number[]} mapping.buttons Standard digital button locations
    • {Number[]} [mapping.analog] Analog axis locations for buttons. See: https://developer.mozilla.org/en-US/docs/Web/API/GamepadButton
    • {Function} [mapping.normalize_fn] will be called on an unmapped axis or button with the following parameters:
      • {Number} value The raw value read from the gamepad driver
      • {Number} axis The axis index from the standard mapping, or -1 if not an axis
      • {Number} button The button index from the standard mapping, or -1 if not a button
    • normalize_fn must return a normalized value in range [-1.0..1.0], or 0.0 if the axis is unknown.

mapping.analog is specially for mapping analog buttons or pressure-sensitive buttons from an axis location to a button location. This is for things like the L2 and R2 analog triggers, and pressure sensitive D-pad and face buttons on a PS3 controller. Here's how it might look for remapping L2 and R2 triggers on a wired XBox 360 controller:

{
    "axes" : [ 0, 1, 3, 4 ],
    "buttons" : [ 11, 12, 13, 14, 8, 9, -1, -1, 5, 4, 6, 7, 0, 1, 2, 3, 10 ],
    "analog" : [ -1, -1, -1, -1, -1, -1, 2, 5, -1, -1, -1, -1, -1, -1, -1, -1, -1 ]
}

This will fill in that gap in the buttons array during remapping. A little extra code is necessary to combine the axis and the button to produce a meaningful result.

---

Some mapping test reports:

Chrome (45+) :

• PS3 Gamepad
• PS4 Gamepad
• XBox One Gamepad
• XBox 360 USB Gamepad
• XBox 360 Wireless Gamepad
• Wii Remote (not recognised by the browser)
• Wii "Classic" Gamepad (not recognised by the browser)
• Wii U Gamepad
• Ouya Gamepad

Firefox (39+) :

• PS3 Gamepad
• PS4 Gamepad
• XBox One Gamepad
• XBox 360 USB Gamepad
• XBox 360 Wireless Gamepad
• Wii Remote (not recognised by the browser)
• Wii "Classic" Gamepad (not recognised by the browser)
• Wii U Gamepad
• Ouya Gamepad

---

Wiimote on Mac requires a driver: https://github.com/alxn1/wjoy

I haven't mapped it out, yet. But initial testing shows a huge caveat; this driver reports the gamepad id as a string containing a MAC address (which is unique for each device). For this reason, I want to defer Wiimote support to a melonJS plugin; which is better suited to doing things like RegExp over gamepad id.

---

Ouya gamepad on Mac requires a driver: http://ouyaforum.com/showthread.php?3185-Ouya-controller-input-on-computer-macosx&p=78432&viewfull=1#post78432 This driver is unsigned, so requires disabling KEXT signature checking on OSX 10.10+:

$ sudo nvram boot-args=kext-dev-mode=1

After restarting, load the driver:

$ sudo kextload /System/Library/Extensions/OUYAGameController.kext

[obiot]

note that the device test example is maybe a right place where to add simple gamepad tester :P

[obiot]

@parasyte : I added some testing report, based on my test, and the one you described in the other ticket, have a look to see if I missed anything

[obiot]

other improvements I could see, by looking at the API and what you did today :

• leverage the connected/disconnected event to lower the operation in the update function (but i'm mainly thinking about the remapping stuff)
• use the timestamp provided in the gamepad object to exit the update function if nothing happen since the last frame (although this is not supported in FF, but only in Chrome)

[obiot]

also, just an idea, but for the mapping function, why not also use it to apply a mapping to keyboard event ?
as an Id we could use the keyboard keyword for the id, and then we can just pass a default array to map the gamepad array to the keyboard one ?

[parasyte]

Hmm, in regard to the stuff you added to the TODO list with 360 support... that isn't right. ;) melonJS only supports remapping USB 360 controllers on Firefox right now, because that's all I have. The Wireless 360 controller has a different id string at the very least. (So it won't automatically use the mapping for USB controllers.)

As for the device test, I'm kind of OK with that, but I would prefer making it prettier than just dumping a bunch of text to the screen. I imagine something like the virtual gamepad on the HTML5 gamepad tester. We can use the Kenney gamepad UI graphics for it.

The connect/disconnect events won't help us, because the UA already removes disconnected gamepads from the navigator.getGamepads() result. And it adds them automatically, too. I see these events as more of an application-level thing; that the game can automatically pause when the gamepad is disconnected, for example, and resume when reconnected. The engine doesn't need to do that kind of thing.

The timestamp isn't portable, so I didn't bother with it. It also won't really save a whole lot of CPU or time anyway. It's a very, very minor optimization.

I already explained my reason for not mapping to keyboard events in #34 (comment) (It's already mapping to keyboard events right now, and it doesn't work for the analog axes.)

[parasyte]

@obiot I corrected some of the test report stuff in the first post.

[obiot]

about the timestamp, well i'm not sure, this is still a fair amount of code :
https://github.com/melonjs/melonJS/blob/ticket-34/src/input/gamepad.js#L78-L104

[obiot]

For the Wiimote, interestingly enough, that's all I see under Chrome :

Firefox does not even recognize it !

[parasyte]

The code you highlighted is just the inner loop that checks the state of buttons that are actually mapped. In the platformer demo, only up, down, left, right, and face_1 are mapped. So it only iterates five items. Hardly a worry for performance.

[obiot]

@agmcleod if i'm not wrong you do have a xbox one ? don't you ?

[parasyte]

I have a WIP patch to support the mapping.analog and mapping.normalize_fn options to setGamepadMapping. In addition, this support allows full remapping of any axis to any button.

Before I commit, it needs some testing (I don't have my gamepads with me right now) and I still need to implement the normalize_fn for OUYA. I have a pretty good idea what needs to be done with that.

This will give us standard mapping behavior for GamepadButton.value. We'll still need to work out the details with binding analog values to actions.

[obiot]

Hi, feel free to commit it now, i still my PS4 controller here at the office for testing, and I can do first level debugging session :P

[obiot]

tagging this one for 3.1.0 first, let's see what we do with the old API once the new one is in place (if remove then it's for 4.0.0)

[obiot]

@parasyte @agmcleod

some advice/questions here on what to do to add "support" for the two axis (independently of the above TODO functions to add), as I wanted to finish this part to have a full support for gamepads :

• currently the bindGamePad only allows to specify a button id. How shall we do to specify an Axe one (as they share the same numeric value at the end) ?
• shall we automatically map the axes value to the directional pad (left, right, up, down) ?

Bonus questions :

• shall we add some functions that allows to return the connected devices id/profile/amount ? or do we let the end user plays with navigator.getGamepads ? (we could just return the last value we got during the last frame)

[parasyte]

The changes required for binding axes will break the API. Might be something like this:

me.input.bind("walk", {
  type : me.input.GAMEPAD,
  index : 0,
  axis : me.input.GAMEPAD.AXES.LX
});

me.input.bind("walkLeft", {
  type : me.input.GAMEPAD,
  index : 0,
  button : me.input.GAMEPAD.BUTTONS.LEFT
});

Auto mapping: might be nice, but it will make the bind API gross if you don't want binding auto-mapped. The example above binds an action to the entire horizontal movement of an axis LX; the value range is [-1, 1]. Which is an intersection of two buttons: LEFT and RIGHT.

Binding to a sub-range of an axis is doable, but weird. And probably less useful than binding over the full range.

For the last bonus question, there's no need to inspect the connected devices. Just bind them (by index) and it either works if a device is connected there, or it doesn't! Best practice would be to bind the same action to multiple input devices ... which indicates that the API should do this for free! Bind an array of inputs to a single action?

me.input.bind("walkLeft", [
  {
    type : me.input.GAMEPAD,
    index : 0,
    button : me.input.GAMEPAD.BUTTONS.LEFT
  },
  {
    type : me.input.KEY,
    key : me.input.KEY.A
  },
  {
    type : me.input.pointer,
    button : me.input.pointer.LEFT
  }
]);

Maybe there's a better way to do it. Just brainstorming...

How about macro style? With rest... arguments instead of an explicit array...

me.input.bind(
  "walkLeft",
  me.input.defineGamepad(0, me.input.GAMEPAD.BUTTONS.LEFT)
  me.input.defineKey(me.input.KEY.A),
  me.input.definePointer(me.input.pointer.LEFT)
);

Magic! That last incantation looks like it could even do event-driven bindings. Just use a function as the first arg instead of a string (or Symbol). It's getting into the realm of polymorphic code, though, which scares me greatly. Maybe we'll provide a different method for that. ;P

me.input.bindEvent(
  function (e) {
    console.log(e);
  },
  me.input.defineGamepad(0, me.input.GAMEPAD.BUTTONS.LEFT)
  me.input.defineKey(me.input.KEY.A),
  me.input.definePointer(me.input.pointer.LEFT)
);

[obiot]

good input on the bind function, I will look into that, thanks :p

for the bonus question, you do have to think it terms of multiple gamepad being connected to a device, and probably multiplayer, or do you then present to the player(s) the list of gamepad so that they can choose the one they want to use for their player ?

[parasyte]

Nah, I think if they want multiplayer, the developers offer it by creating the bindings for multiple controllers. And if a user accepts the offer by connecting multiple controllers, everyone's happy!

UAs currently require the user to press a button before they will advertise the existence of a controller to JavaScript. So the flow described above makes sense that way. FWIW, the UA attaches controllers in the order that they are advertised. So the first person to push a button is always player 1... etc. I don't see any reason to do any more than that, TBH.

[obiot]

hmm I guess that would work as well, but until someone does implement a multiplayer with melonJS I suppose we won't really know :)

[parasyte]

There's really nothing wrong with polling for controllers. It just seems like a waste of time when you could instead use the offer/accept principle and not worry about it.

[obiot]

I finally went to something more simple that limit the changes in the API (as I'm still targeting a 3.x release style), but I do like your suggestions and they definitely be added here above in the proposed new API to read and write action states.

[parasyte]

Err, this is a breaking change: 42cac07#diff-687d58823d4a97e37dbf32eefd9a612eL327

[obiot]

melonJS/src/input/gamepad.js

Lines 385 to 392 in 42cac07

	// for backward compatiblity with 3.0.x
	if (typeof (button) !== "object") {
	button = {
	type : "buttons",
	code : button
	};
	console.warn("Deprecated: me.input.bindGamepad parameteres have changed");
	}

[parasyte]

Please document it.

[parasyte]

We can add the new API without breaking compatibility; binding inputs to actions, and querying action values. I'd like to start moving toward that soon, too. I'm open to better function naming conventions, if you have ideas!

[adrianhartanto0]

Just wondering, what are action states? Include example if possible. Thanks