=====================
"JOY" by Einar Saukas
=====================

JOY is a generic library for reading joystick (and keyboard) controls.

It recognizes multiple directions (or fire) pressed simultaneously, supports 
Kempston and Sinclair joysticks, and also keyboard keys Q-A-O-P-M/Space. It can 
be used in Boriel's ZX Basic or directly in Assembly.


========================
USAGE: Boriel's ZX Basic
========================

Using JOY from Boriel's ZX Basic is very easy. At the beginning of your program,
you must include the library, as follows:

    #include "joy.bas"

Inside your program, declare a variable to store joystick controls currently
pressed:

    DIM k AS UBYTE

Whenever you want to read current input from Kempston joystick for instance, use
this function:

    LET k = joyKempston()

Afterwards, whenever you want to verify if a certain direction (or fire) was
pressed, you just need to check corresponding bits in this variable, like this:

    LET k = joyKempston()
    IF (k & JOY_FIRE) THEN
       ...
    END IF
    IF (k & JOY_UP) THEN
       ...
    END IF

That's all!!!

Now if you want to read current input from a Sinclair joystick instead, you only
need to modify the line above as follows:

    LET k = joySinclair()

Or to read current input from a Cursor joystick:

    LET k = joyCursor()

Or to read current input from the keyboard:

    LET k = joyKeyboard()

Alternatively you can use a more generic function so you assign the chosen
control to a variable somewhere else, then use this variable as parameter later:

    DIM joystick AS UBYTE
    ...
    LET joystick = JOY_KEMPSTON
    ...
    LET k = joyControl(joystick)


===============
USAGE: Assembly
===============

Using JOY directly from Assembly is very easy. Somewhere in your program, you 
must include the library, as follows:

    include "joy.asm"

Whenever you want to read current input from Kempston joystick for instance, use
this routine:

    call joyKempston

Afterwards, each bit of register A will be set if the corresponding direction
(or fire) was pressed. You can use it like this:

    call joyKempston
    ld b,a
    and JOY_FIRE
    call c, ...
    ld a,b
    and JOY_UP
    call c, ...

Or, even better:

    call joyKempston
    rrca
    call c,... ; JOY_FIRE
    rrca
    call c,... ; JOY_UP

That's all!!!

Now if you want to read current input from a Sinclair joystick instead, you only
need to modify the line above as follows:

    call joySinclair

Or to read current input from a Cursor joystick:

    call joyCursor

Or to read current input from the keyboard:

    call joyKeyboard

Alternatively you can use a more generic routine so you assign the chosen 
control to register A prior to calling it:

    ld a,JOY_KEMPSTON
    call joyControl


=======
LICENSE
=======

You can freely use JOY in your own programs, or implement new routines based on
it. The only condition is that, in either case, you must credit JOY in your
documentation!


=======
CREDITS
=======

Created by Einar Saukas.