JSIDPlay2

JSIDPlay2 is a highly compatible and cycle-exact Commodore 64 (C64) emulator. It is written in Java and features:

• Emulation library of core functions for the C64 and supportive devices
• A console player
• A JavaFX user interface
• High-performance WebAssembly/JavaScript version (using TeaVM) with additional worker thread support
• Server-side streaming capability of C64 content with audio and video
• WhatsSID? Music recognition system (what is currently playing?)
• Included demo pages (e.g., c64jukebox.vue and various example pages)

Prerequisites

Java Requirements

• Building: Java 17 or newer.
• Runtime: Java 17 or newer (Oracle Java8 64-bit is also supported for bytecode compatibility).

Recommended IDE

• IntelliJ IDEA (Community or Ultimate Edition) is recommended.
• Eclipse is also supported.

Build and Launch

Building the Project

Use the following command to build the project. Replace javafx.platform with your platform (linux, linux-aarch64,
win, mac, or mac-aarch64).

mvn -Djavafx.platform=linux clean install

• PC Version: target/standalone
• Website Version: target/deploy

Launching JSIDPlay2

User Interface (JavaFX on PC)

mvn exec:java -Dexec.mainClass=ui.JSidPlay2Main

Server (Web Interface)

mvn exec:java -Dexec.mainClass=server.restful.JSIDPlay2Server

Then open http://127.0.0.1:8080 in your browser.

For detailed server setup (NGINX, MySQL, WhatsSID), see docs/SERVER_SETUP.md.
For the developer release process, see docs/RELEASE_HOWTO.md.
For the JCommander usage, see docs/JCOMMANDER_USAGE.md.
For the latest changes, see CHANGELOG.md.
For plans, see TODO.md.

Running UI Tests

mvn -Djavafx.platform=linux clean install -P release

Note: Disable screensaver to avoid interference with tests.

Docker/Jenkins Pipeline Support

Prerequisites (Linux)

Allow the Docker container to open a window (once):

xhost +local:docker

Jenkins Pipeline Setup

On Jenkins host install Docker and Docker Compose:

sudo apt-get install docker.io
sudo curl -L "https://github.com/docker/compose/releases/download/v2.23.1/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose
sudo usermod -aG docker jenkins   # Who is allowed to call docker
sudo usermod -aG docker ken       # Who is allowed to call docker
sudo systemctl restart jenkins

In Jenkins, click New Item → give it a name → choose Pipeline → OK.
Under Pipeline → Definition, select a pipeline script from SCM (Jenkinsfile).
Choose your SCM (e.g., Git) and set the repository URL and branch.

Management

• Start: docker compose -f src/main/docker/docker-compose.XXX.linux.yml up
• Stop: docker compose -f src/main/docker/docker-compose.XXX.linux.yml down

Advanced Configuration

Optional Deployment Properties

Set these properties via -D at the command line or via IntelliJ IDEA path variables or Eclipse IDE string
substitution:

• -Dcgsc.7z=<path> : Path to CGSC.7z
• -Dgb64.mdbfile=<path> : Path to GameBase64.mdb
• -Dhvmec.zip=<path> : Path to HVMEC.zip
• -Dhvsc.7z=<path> : Path to HVSC.7z
• -DserverUrl=<url> : Upload URL scp://<username>>:<password>>@<serverip>/home/ken</serverip></password></username>
• -Dupx.exe=<path> : Path to UPX executable

Deployment to Web Server

mvn -Djavafx.platform=linux clean deploy

Builds and uploads target/deploy to the configured web server.

Hardware and System Setup

Joystick Support (Linux)

Grant access to input devices:

sudo usermod -a -G input $(whoami)
# Reboot after running this command

HardSID Setup

For HardSID4U, HardSID Uno, and HardSID UPlay USB devices in VirtualBox:

1. Connect the HardSID device.
2. VirtualBox: Allow Windows to use USB hardware via the toolbar.
3. Linux Host: Add your user to the vboxusers group.
4. JSIDPlay2: Switch from Emulation to HardSID4U in settings. Check the console for errors.

Audio Routing (Ubuntu/Pulseaudio):
Connect mixed/out to Microphone/in. In a terminal:

parec --latency-msec=1 | pacat --latency-msec=1
# OR
pactl load-module module-loopback latency_msec=1
# Unload with: pactl unload-module module-loopback

• Ensure volume control is visible: gsettings set com.canonical.indicator.sound visible true
• If microphone is greyed out: kmix -> "Output device" -> "Analog Stereo Duplex".

Development and Troubleshooting

Working with Eclipse

1. mvn -Djavafx.platform=linux clean install
2. mvn eclipse:eclipse
3. In Eclipse: Right-click Project → Maven → "Update Project"

Internal Build Testing

cd target/standalone
cp ../deploy/*.sh .
chmod +x *.sh
./jsidplay2.sh ~/path/to/sidfile.sid
# Also available: ./jsidplay2-console.sh, ./sidblastertool.sh, ./recordingtool.sh

Monitoring and Debugging

• Remote Debugging: -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=9999
• JVisualVM (JMX):
  • -Dcom.sun.management.jmxremote.port=9999
  • -Dcom.sun.management.jmxremote.ssl=false
  • -Dcom.sun.management.jmxremote.authenticate=false
  • -Dcom.sun.management.jmxremote.local.only=false
  • -Djava.rmi.server.hostname=<server-ip>
• Memory Analysis (MAT):
  • jmap -dump:format=b,file=heap.bin <JavaProcessId>
  • Load heap.bin in Eclipse MAT.
  • Tip: Increase MAT memory in MemoryAnalyzer.ini (e.g., -Xmx=5g).

Debugging JavaFX Nodes

Snippet to dump the scene graph:

private void dump(Node<?> n, int depth) {
    for (int i = 0; i < depth; i++) System.out.print("  ");
    System.out.println(n);
    if (n instanceof Parent)
        for (Node<?> c : ((Parent) n).getChildrenUnmodifiable())
            dump(c, depth + 1);
}

General Tips

• HTTPS (Certbot): sudo certbot certonly --standalone -d haendel.ddns.net
• JAR Association: Right-click JAR → Open with... → Choose /path/to/java -jar -> Remember file type assignment.