Commodore‎ > ‎BASIC‎ > ‎Keywords‎ > ‎

JOY

Keyword Abbreviation Token (hex) Version(s) Classification
JOY J{Shift+O} CF 3.5,7.0 Function
RECORD RE{Shift+C} CF 4.x Command and Statement

  Syntax  
JOY gamePort )
 
Parameters Type Legal Value(s) Note(s)
gamePort Numeric
1 or 2
 
Returns Type Value(s) Note(s)
joyFlags Integer
0 ~ 8 (direction)
+128 (fire button)
 
  Purpose  
Return a value indicating the state of a joystick.
 
  Remarks  
The JOY function is used for "commuicating" with a joystick.  Similar to the screen and keyboard in that the direction is one-way and you don't need to OPEN a "file" to communicate.  Unlike the screen and keyboard, you can't open a file to a joystick.  By the way, the JOY function is for reading a digital joystick, which are almost always used with Commodore computers.  For example the Commodore 1311 Joystick.  I hear these are terrible.  Fortunately many other joysticks were made.  Those for Atari 2600 also work on Commodores.  Well except for the TED series; for them, look at the Commodore 1341 Joystick.
 
The parameter gamePort selects which of two possible physical connectors on the computer should be read for a joystick value.  On the TED series and the C128 (the only released machines supporting JOY), most of the lines used by the gamePort are also used by the keyboard.  So pressing keys on the keyboard may generate false JOY values and, likewise, moving the joystick or pressing some of its buttons may interfere with reading the keyboard (GET/INPUT).  The computer has no way to know if a joystick is actually connected.  Some devices that can plug into the game port, like a mouse, paddles, and light pen may trigger some values which can be "detected" by JOY, but the meaning of these other devices has nothing to do with real joystick values described below.
 
The value returned, joyFlags consists of a low-order 4 bits which holds a direction (described below), and bit 7 (value 128) is set when the "fire" button is pressed.  Some joysticks (or other "game controllers") may have multiple buttons.  They may all trigger the "fire" button read by JOY, or only some of them.  It wouldn't be very useful joystick if none of them worked.
 
The direction is zero if the joystick is cenetered.  Otherwise, the direction is similar to the polar coordinates used in bitmap graphics and MOVSPR: the angle is measured clockwise starting from the "12 o'clock" (north) position.  While the polar coordinates use degrees, a relatively common unit of angular measurement that ranges from 0 to 359, the JOY direction ranges from 1 to 8.  So you'll need to do a little math if you want to convert back and forth.  To spare you the math, here is a simple table.
 
joyFlags direction BASIC angle Description
0 0 n/a Centered
1 1 Up
2 2 45° Up + Right
3 3 90° Right
4 4 135° Down + Right
5 5 180° Down
6 6 225° Down + Left
7 7 270° Left
8 8 315° Up + Left
128 0 n/a Button + Centered
129 1 Button + Up
130 2 45° Button + Up + Right
131 3 90° Button + Right
132 4 135° Button + Down + Right
133 5 180° Button + Down
134 6 225° Button + Down + Left
135 7 270° Button + Left
136 8 315° Button + Up + Left
 
You can extract the direction from the joyFlags with the BASIC expression JOY(gamePort) AND 15.  You can extract the state of the "fire" button with JOY(gamePort) AND 128.  Once you have the direction you can convert it to a BASIC graphic angle with the expression A = ( direction - 1 ) * 45.  If the result (A) is less than zero then no direction was pressed at all.
 
If gamePort is omitted or is not a valid expression, SYNTAX ERROR occurs.  If gamePort is a string, TYPE MISMATCH ERROR occurs; you can use VAL to make a string numeric.  Otherwise the gamePort is converted with INT.  If the result is neither 1 or 2 then ILLEGAL QUANTITY ERROR occurs.
 
Examples:
PRINT JOY(1)
 128                  button is pressed, but stick is centered

READY.
PRINT JOY("1")
 
?TYPE MISMATCH ERROR 
READY.
 
  Compare With  
 
  Contrast With  
 
  See Also  

© H2Obsession, 2014
Comments