Joystick Library

XC=Basic3 Joystick Library Documentation

Overview

The XC=Basic3 Joystick Library simplifies the integration and management of joystick inputs for Commodore 64 applications, especially games. Joystick reading is not a difficult task with XC=Basic3 standard keywords, but lib_joy.bas provides convenience functions that I have found usable in many projects.

Installation

To incorporate the library into your XC=Basic3 program, include it at the beginning with the following line:

INCLUDE "lib_joy.bas"

Make sure that the path to lib_joy.bas accurately reflects your project's directory structure.

Constants

The library defines two constants for joystick identification:

• JOY1: Represents the joystick in port 1
• JOY2: Represents the joystick in port 2

These constants are used in all functions to define the joystick you want to read. The only exception is JoyUpdate subroutine that automatically updates the state of both joysticks.

Subroutines

JoyUpdate()

This function updates both joysticks' states and should be called at the start of each game loop iteration to ensure the program is working with the most current input data.

Directional and Button Press Checks

• JoyUp(JoyNr): Returns TRUE if the UP direction is active.
• JoyDown(JoyNr): Returns TRUE if the DOWN direction is active.
• JoyLeft(JoyNr): Returns TRUE if the LEFT direction is active.
• JoyRight(JoyNr): Returns TRUE if the RIGHT direction is active.
• JoyFire(JoyNr): Returns TRUE if the FIRE button is active.
• JoyIdle(JoyNr): Returns TRUE if joystick is in the center position and fire button is not active.
• JoyCenter(JoyNr): Returns TRUE if joystick is in the center position.

JoyNr is the joystick identifier (JOY1 or JOY2).

State Change Detection

• JoySame(JoyNr): Checks if the joystick's state has remained unchanged since the last update.
• JoyFirePressed(JoyNr): Detects if the fire button was pressed since the last update.
• JoyFireReleased(JoyNr): Detects if the fire button was released since the last update.

Axis Movement Functions

Convenience functions typically used to modify coordinates of moving game object.

• JoyXAxis(JoyNr): Returns -1, 0, or 1 for left, no movement, or right movement.
• JoyYAxis(JoyNr): Returns -1, 0, or 1 for up, no movement, or down movement.

Wait Functions

• JoyWaitIdle(JoyNr): Halts execution until the joystick is in a neutral position and fire is not pressed.
• JoyWaitClick(JoyNr): Waits for a complete click (press and release) of the fire button.

Example Program

This example demonstrates how to use the XC=Basic3 Joystick Library to move sprites based on joystick inputs.

INCLUDE "../libs/lib_joy.bas"

MEMSET 16320, 64, 255

DIM X(2) AS WORD
DIM Y(2) AS BYTE

X(0) = 100
Y(0) = 100
X(1) = 200
Y(1) = 100

PRINT "Press joy2 fire to start"
CALL JoyWaitClick(JOY2)

DO
    SPRITE 0 AT X(0),Y(0) SHAPE 255 ON
    SPRITE 1 AT X(1),Y(1) SHAPE 255 ON

    CALL JoyUpdate()

    IF JoyUp(JOY1) THEN Y(0) = Y(0) - 1
    IF JoyDown(JOY1) THEN Y(0) = Y(0) + 1
    IF JoyLeft(JOY1) THEN X(0) = X(0) - 1
    IF JoyRight(JOY1) THEN X(0) = X(0) + 1

    X(1) = X(1) + JoyXAxis(JOY2)
    Y(1) = Y(1) + JoyYAxis(JOY2)

    IF JoyFirePressed(JOY1) OR JoyFirePressed(JOY2) THEN
        EXIT DO
    END IF

    DO LOOP WHILE SCAN() < 256
    DO LOOP WHILE SCAN() > 255
LOOP

In this example, joystick inputs are used to control the movement of two sprites on the screen. It showcases initial setup, continuous input reading, directional movement, axis-based movement, and exit conditions based on button presses.