Skip to content

Joystick implementation #163

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
craigthomas merged 2 commits into from
Dec 18, 2025
Merged

Joystick implementation #163

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b96e717
Add new routines to query game devices and poll from them.
craigthomas Sep 27, 2025
75274af
Clarify README for joystick usage and JDK and JRE selection.
craigthomas Dec 18, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
168 changes: 142 additions & 26 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,21 +9,25 @@

1. [What Is It?](#what-is-it)
2. [License](#license)
3. [Compiling](#compiling)
4. [Running](#running)
3. [Requirements](#requirements)
1. [Linux](#linux)
2. [Windows](#windows)
4. [Compiling From Source](#compiling-from-source)
5. [Running](#running)
1. [Specifying a System ROM](#specifying-a-system-rom)
2. [Trace Mode](#trace-mode)
5. [Cassette Tapes](#cassette-tapes)
6. [Cassette Tapes](#cassette-tapes)
1. [Reading](#reading)
2. [Writing](#writing)
6. [Disk Drives](#disk-drives)
7. [Disk Drives](#disk-drives)
1. [Loading a Disk Image](#loading-a-disk-image)
2. [Saving a Disk Image](#saving-a-disk-image)
7. [Configuration File](#configuration-file)
8. [Keyboard](#keyboard)
8. [Joysticks](#joysticks)
9. [Configuration File](#configuration-file)
10. [Keyboard](#keyboard)
1. [Emulated Keyboard](#emulated-keyboard)
2. [Pass-through Keyboard](#pass-through-keyboard)
9. [Current Status](#current-status)
11. [Current Status](#current-status)

## What Is It?

Expand Down Expand Up @@ -53,36 +57,129 @@ Third Party Licenses and Attributions below for more information on those
software components.


## Compiling
## Requirements

You will need a copy of the Java Development Kit (JDK) version 8 or greater
installed in to compile the JAR file. I strongly recommend using an open-source
licensed JDK build (GPL v2 with Classpath Exception), available at
[https://adoptopenjdk.net](https://adoptopenjdk.net) and install OpenJDK 8 or
OpenJDK 11.
The project needs several different packages installed in order to run the
emulator properly. Please see the platform specific steps below for
more information.

To build the project, switch to the root of the source directory, and type:
### Linux

At a minimum, you will need to install the Java Runtime Environment (JRE) 17 or
higher. Additionally, if you wish to use joysticks, you will need to install the
`libjinput` API bindings, add your username to the `group` file, as well as fix a
potential API binding bug.

1. *Required* - a Java Runtime Environment (JRE) version 17 or higher. The simplest way to
do this is to install OpenJDK 17 or higher. On Ubuntu or Debian systems, this can
be done with :

```bash
sudo apt update
sudo apt install openjdk-17-jre
```

2. *Optional* - for proper joystick support you will need to install the `jinput` joystick
library API on the system with:

```bash
sudo apt install libjinput-java libjinput-jni
```

Once installed, you may need to correct a missing file problem with the `libjinput-jni`
installation. The emulator dependencies require a shared object file called
`libjinput-linux64.so` to be present in the `/usr/lib/jni` directory. However, the
`libjinput-jni` package may only install a file called `libjinput.so`. The
solution is to create a symbolic link from `libjinput.so` to `linjinput-linux64.so`.
First, check to see if the `libjinput-linux64.so` file already exists with:

```bash
ls -l /usr/lib/jni
```

If the `libjinput-linux64.so` file is *NOT* listed, you will need to create a symbolic
link with the following command:

```bash
sudo ln -s /usr/lib/jni/libjinput.so /usr/lib/jni/libjinput-linux64.so
```

Finally, you will need to add yourself to the `input` group so that the emulator can read
joystick information:

```bash
sudo usermod -a -G input <your username>
```

You will need to end your current session and restart in order for the group information
to be updated. In some cases, you may need to reboot for the group change to take effect.

To run the emulator, see the section called [Running](#running) below.

### Windows

At a minimum, you will need to install the Java Runtime Environment (JRE) 17 or
higher.

1. *Required* - a Java Runtime Environment (JRE) version 17 or higher. I recommend using
Eclipse Temurin JRE (formerly AdoptJDK) as the software
is licensed under the GNU license version 2 with classpath exception. The latest
JRE builds are available at [https://adoptium.net/en-GB/temurin/releases](https://adoptium.net/en-GB/temurin/releases)
(make sure you select _JRE_ as the type you wish to download). Run the installer
and follow the directions as required to install the runtime.

To run the emulator, see the section called [Running](#running) below.

## Compiling From Source

_Note this section is optional - this is only if you want to compile the project
yourself from source code._ If you want to build the emulator from source code,
you will need a copy of the Java Development Kit (JDK) version 17 or greater
installed in to compile the JAR file.

### Linux

For most Linux distributions there is likely an `openjdk-17-jdk` package that will do
this for you automatically. On Ubuntu and Debian based systems, this is typically:

```bash
sudo apt update
sudo apt install openjdk-17-jdk
```

Next, to build the project, switch to the root of the source directory, and type:

```bash
./gradlew build
```

On Windows, switch to the root of the source directory, and type:
The compiled Jar file will be placed in the `build/libs` directory. Note that
for some components such as joystick detection and control to work correctly,
operating-specific steps may be required. See the _Requirements_ section above
to install necessary sub-systems.


### Windows

For Windows, I recommend using Eclipse Temurin JDK (formerly AdoptJDK) as the software
is licensed under the GNU license version 2 with classpath exception. The latest
JDK builds are available at [https://adoptium.net/en-GB/temurin/releases](https://adoptium.net/en-GB/temurin/releases)
(make sure you select _JDK_ as the type you wish to download).

Next, switch to the root of the source directory, and type:

```bash
gradlew.bat build
```

The compiled Jar file will be placed in the `build/libs` directory.
The compiled Jar file will be placed in the `build/libs` directory. Note that
for some components such as joystick detection and control to work correctly,
operating-specific steps may be required. See the _Requirements_ section above
to install necessary sub-systems.


## Running

For the emulator to run, you will need to have the Java 8 Runtime Environment (JRE)
installed on your computer. See [Oracle's Java SE Runtime Environment Download](https://www.oracle.com/technetwork/java/javase/downloads/jre8-downloads-2133155.html)
page for more information on installing the JRE. Alternatively, you can
use [OpenJDK](https://openjdk.java.net/install/).

Simply double-clicking the jar file will start the emulator running. By
default, the emulator will be in paused mode until you attach a system
ROM to it. You can do so by clicking *ROM*, *Load System ROM*. You can
Expand Down Expand Up @@ -192,6 +289,22 @@ select a location on your computer where the disk file will be saved to.
Once entered, the contents of the drive will be saved to the virtual disk
file, and can be loaded from the host computer in a future session.

## Joysticks

Joystick control is still experimental and only currently available under
Linux. When running the emulator, to set the joystick to be used,
click on *Joystick* and then *Left Joystick* or *Right Joystick* to select
which device should be used as the left or right joystick. If no USB
joystick devices are found, then *No joystick* will be the only option
available.

To troubleshoot joystick configuration, when the emulator starts, a
list of detected joysticks will be printed to the console. The
`Joystick #0` device will always be `No Joystick`. Other enumerated
joysticks will be printed after this one. The name of the detected joystick
can be used in the configuration file below to automatically associate
the left or right joystick device during emulator startup.


## Configuration File

Expand All @@ -205,19 +318,22 @@ Super Extended Color Basic ROM file).
Megabug).
* `cassetteROM` - the full path to the ROM file used in the cassette recorder.
* `drive0Image` - the `DSK` image to be used in drive 0.
* `drive1Image` - the `DSK` image to be used in drive 0.
* `drive2Image` - the `DSK` image to be used in drive 0.
* `drive3Image` - the `DSK` image to be used in drive 0.
* `drive1Image` - the `DSK` image to be used in drive 1.
* `drive2Image` - the `DSK` image to be used in drive 2.
* `drive3Image` - the `DSK` image to be used in drive 3.
* `leftJoystick` - the name of the detected joystick to use as the left joystick.
* `rightJoystick` - the name of the detected joystick to use as the right joystick.

Leaving any one of the keys out will result in the emulator ignoring that particular
ROM image. An example YAML configuration file that specifies ROMs to use for the
system, cartridge slot, cassette, and drive 0 is as follows:
configuration option. An example YAML configuration file that specifies ROMs to use for the
system, cartridge slot, cassette, joystick, and drive 0 is as follows:

```
systemROM: "C:\Users\basic3.rom"
cartridgeROM: "C:\disk11.rom"
cassetteROM: "C:\Users\zaxxon.cas"
drive0Image: "C:\megabug.dsk"
leftJoystick: "usb gamepad"
```

If you start the emulator without command-line arguments, it will look for a configuration file named
Expand Down
3 changes: 3 additions & 0 deletions build.gradle
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,9 @@ dependencies {
implementation 'org.apache.commons:commons-lang3:3.20.0'
implementation 'com.beust:jcommander:1.82'
implementation 'org.yaml:snakeyaml:2.5'
implementation 'net.java.jinput:jinput:2.0.10'
runtimeOnly 'net.java.jinput:jinput-platform:2.0.7:natives-linux'
implementation 'net.java.jutils:jutils:1.0.0'
testImplementation 'junit:junit:4.13.2'
testImplementation 'org.mockito:mockito-core:5.21.0'
}
Expand Down
Loading