add joy(1): joystick script for all emulators, and docs

remove old /sys/src/games/nes/joynes in favor of joy(1).
joy(1) has more buttons for the other emulators;  there is
no longer a significance in the order of the keys.
document nusb/joy, add information in each emulator manpage.

6 files changed, 87 insertions, 33 deletions

diff --git a/sys/man/1/atari b/sys/man/1/atari
index 934794a04..d47927953 100644
--- a/sys/man/1/atari
+++ b/sys/man/1/atari
@@ -46,6 +46,9 @@ Enable audio output.
 .TP
 .B -x
 Scale the screen to a given factor regardless of the window's size.
+.PP
+A joystick may be used to play the emulator via
+.IR joy (1).
 .SH SOURCE
 .B /sys/src/games/2600
 .SH BUGS
diff --git a/sys/man/1/joy b/sys/man/1/joy
new file mode 100644
index 000000000..30325ddd1
--- /dev/null
+++ b/sys/man/1/joy
@@ -0,0 +1,45 @@
+.TH MUS 1
+.SH NAME
+joy \- joystick input for games
+.SH SYNOPSIS
+.B joy
+[
+.I player
+]
+.SH DESCRIPTION
+.I Joy
+interprets input from a USB joystick device
+(see
+.IR nusb (4))
+to pass it on to a console emulator
+as a string of controller keys
+which are pressed down.
+.PP
+The optional
+.B player
+argument specifies a player number
+for those emulators that support it.
+It should be an integer equal to 1 or greater.
+Currently only players 1 and 2 are supported.
+.PP
+Note that each USB controller has its own mappings
+and the program may have to be modified
+to use its own key ids.
+.SH EXAMPLES
+Use USB device 10 as a joystick
+for the player number 1's controller
+with the Nintendo Entertainment System (NES) emulator:
+.IP
+.EX
+% nusb/joy /dev/usb/ep10.0 | joy 1 | games/nes -a rom.nes
+.EE
+.SH "SEE ALSO"
+.IR atari (1),
+.IR nintendo (1),
+.IR sega (1),
+.IR nusb (4)
+.SH SOURCE
+.B /rc/bin/joy
+.SH HISTORY
+.I Joy
+first appeared in 9front (June, 2014).
diff --git a/sys/man/1/nintendo b/sys/man/1/nintendo
index c1b6b29f5..e0b64d67e 100644
--- a/sys/man/1/nintendo
+++ b/sys/man/1/nintendo
@@ -134,6 +134,11 @@ sets HiROM.
 .TP
 .B -m
 Enable mouse emulation using system mouse. Mouse button 1 (left button) engages the SNES left mouse button. Mouse button 3 (right button) engages the SNES right mouse button. Holding down mouse button 2 (middle button) disengages the SNES mouse entirely so that the Plan 9 cursor offset can be adjusted to align with the SNES cursor.
+.PP
+Each of these emulators support the use of joysticks via
+.IR joy (1).
+.I Nes
+also supports selecting the joystick for either player 1 or 2.
 .SH SOURCE
 .B /sys/src/games/gb
 .br
diff --git a/sys/man/1/sega b/sys/man/1/sega
index b23437baf..6660b0d0b 100644
--- a/sys/man/1/sega
+++ b/sys/man/1/sega
@@ -44,6 +44,9 @@ Enable audio output.
 .TP
 .B -x
 Scale the screen to a given factor regardless of the window's size.
+.PP
+Each of these emulators support the use of joysticks via
+.IR joy (1).
 .SH SOURCE
 .B /sys/src/games/md
 .SH BUGS
diff --git a/sys/man/4/nusb b/sys/man/4/nusb
index cfad251bc..86cb3fdc0 100644
--- a/sys/man/4/nusb
+++ b/sys/man/4/nusb
@@ -35,6 +35,12 @@ usbd - Universal Serial Bus drivers
 ]
 .I devid
 .PP
+.B nusb/joy
+[
+.B -d
+]
+.I devid
+.PP
 .B nusb/serial
 [
 .B -d
@@ -135,6 +141,27 @@ process them.
 Mouse events are sent to
 .BR /dev/mousein
 in the same way.
+.SS Joysticks
+.I Joy
+parses data packets from a given endpoint and prints back
+any changes in the device's axes or buttons.
+Buttons are identified via an integer id.
+.PP
+Directional buttons are reported as axes
+with 3 positions:
+.IR 0 ,
+.IR 128 ,
+and
+.I 255
+for left (or up), center and right (or down) respectively.
+Messages are in the form \fIaxis id position\fR.
+.PP
+On/off buttons are reported as either
+.I down
+or
+.I up
+respectively.
+Messages are in the form \fIdown\fB|\fIup id\fR.
 .SS Disks
 .I Disk
 configures and manages USB mass storage devices. It
@@ -239,6 +266,7 @@ compatible with
 .SH SOURCE
 .B /sys/src/cmd/nusb
 .SH "SEE ALSO"
+.IR joy (1),
 .IR audio (3),
 .IR ether (3),
 .IR mouse (3),
@@ -248,6 +276,9 @@ compatible with
 .IR shr (3),
 .IR nusbrc (8),
 .IR kbdfs (8)
+.SH HISTORY
+.I Joy
+first appeared in 9front (March, 2014).
 .SH BUGS
 The various device drivers are generic USB drivers and
 may work only for certain devices of each class.
diff --git a/sys/src/games/nes/joynes b/sys/src/games/nes/joynes
deleted file mode 100755
index 2240b88e9..000000000
--- a/sys/src/games/nes/joynes
+++ /dev/null
@@ -1,33 +0,0 @@
-#!/bin/rc
-# run as "nusb/joy epX.Y | joynes N", where N=[1,2]
-
-awk -safe -v 'joy='$1 '
-	BEGIN { k[0] = "" }
-
-	/^axis 0 0/   { k[0] = "left " }
-	/^axis 0 255/ { k[0] = "right " }
-	/^axis 0 128/ { k[0] = "" }
-
-	/^axis 1 0/   { k[1] = "up " }
-	/^axis 1 255/ { k[1] = "down " }
-	/^axis 1 128/ { k[1] = "" }
-
-	/^down 7$/ { k[3] = "b " }
-	/^down 8$/ { k[2] = "a " }
-	/^down 1$/ { k[4] = "control " }
-	/^down 2$/ { k[5] = "start " }
-
-	/^up 7$/ { k[3] = "" }
-	/^up 8$/ { k[2] = "" }
-	/^up 1$/ { k[4] = "" }
-	/^up 2$/ { k[5] = "" }
-
-	{
-		if(joy != "")
-			printf "joy%s ", joy
-		for(i = 0; i <= 5; i++)
-			printf k[i]
-		printf "\n"
-		fflush
-	}
-'