cthulhu2 / jspeccy

A multiplatform ZX Spectrum emulator written in Java

JSpeccy: A multiplatform ZX Spectrum emulator written in Java

• Emulates ZX Spectrum models 16k, 48k, 128k, +2 and +2a.

• Uses the same Z80 core as the Z80Core project.

• Contended memory emulation.

• Border effects (Aquaplane, The Sentinel).

• Selectable border size (no border, standard, complete and huge).

• High resolution color effects (Uridium, Black Lamp).

• Emulation of screen scanlines, PAL effect or RGB monitor.

• Floating bus emulation (Arkanoid, Sidewize, Cobra).

• Beeper & MIC emulation (Cobra’s Arc).

• Read/Write SNA/Z80/SP/SZX snapshot formats.

• LOAD/SAVE Tape files in TAP/TZX/CSW formats.

• Emulates Kempston, Sinclair 1/2, Cursor AGF and Fuller joysticks using keyboard cursor keys.

• AY-3-8910 PSG emulation, including Fuller Audio Box, with Mono & Stereo ABC/ACB/BAC modes.

• Interface I with up to 8 Microdrives, using real emulation when using MDV files.

• Interface II ROM emulation.

• Multiface One/128/Plus 3 emulation.

• ULA+ mode support (up to 64 colors on screen).

• LEC Memory expansion, up to 528 KB, to use LEC CP/M v2.2, using Microdrives as storage.

• Window can be maximized up to x4.

• Selectable emulation speed up to x10 (35 Mhz CPU).

• Translations to English, Spanish and Italian.

• Complete command line support, to integrate JSpeccy with front-ends.

• Support for the Recreated ZX Spectrum Bluetooth keyboard.

Building the emulator

To build JSpeccy you need to have Apache Maven installed, Java 17 or newer and run the following command from the console to generate an executable jar file called jspeccy.jar under the target directory:

mvn clean package

The compiled artefact generated by the build process is an executable wrapped Java jar file that includes all the required dependencies for JSpeccy to run.

% file ./target/jspeccy.jar
./target/jspeccy.jar: Bourne-Again shell script executable (binary data)

Note	The file path to the project must not contain any spaces for the build to succeed.

To scan the source code for potential programming issues run the following commands from the console:

mvn spotbugs:check
mvn spotbugs:gui

Please note, that for convenience, this project also includes a Maven wrapper script, mvnw, which can be used to install and run a sandboxed version of Maven thus eliminating the requirement to have a shared version of Maven installed on your system. The wrapper script can be invoked with the same parameters as Maven itself. e.g. ./mvnw clean package.

Running the emulator

To run JSpeccy, you need to have Java 17, or a later version, installed. Run with:

./target/jspeccy.jar

A configuration file named JSpeccy.xml will be created on the user directory.

On Unix/Linux platforms using X11, Java 8 have a bug redrawing the screen. Java 8 uses the XRender extension by default and this causes some problems. To resolve it, you can test two possible solutions:

First, you can add the option that uses the OpenGL backend:

java -Dsun.java2d.opengl=True -jar ./target/jspeccy.jar

The OpenGL backend solution can be problematic when a good OpenGL driver is not available or X11 is using Mesa. In these cases you can use:

java -Dsun.java2d.xrender=false -jar ./target/jspeccy.jar

Please note that the XRender redraw bug is still present in Java 19, so you need still need to the solution described above.

Web: JSpeccy (only in Spanish, I’m sorry)

Project documentation summary

The build process includes support for generating a detailed product documentation summary which includes SpotBugs reports and OWASP dependency vulnerability reports amongst other useful pieces of information.

To generate the reports run the following command:

mvn clean install site

And then open the resulting target/site/index.html file in a web browser.

Native code compilation

JSpeccy currently supports experimental compilation to native code using Spring Boot and GraalVM. Whilst the instructions below are aimed at macOS, the process can be adapted work on other operating systems.

Install GraalVM using brew:

echo
echo "Installing GraalVM (https://github.com/graalvm/homebrew-tap)"
brew install --cask graalvm/tap/graalvm-ce-java17
brew upgrade --cask graalvm/tap/graalvm-ce-java17

# On macOS Catalina, you may get a warning that "the developer cannot be
# verified". This check can be disabled in the "Security & Privacy"
# preferences pane or by running the following command:
xattr -r -d com.apple.quarantine "/Library/Java/JavaVirtualMachines/graalvm-ce-java17-22.3.1"
export PATH="/Library/Java/JavaVirtualMachines/graalvm-ce-java17-22.3.1/Contents/Home/bin:$PATH"
export GRAALVM_HOME=/Library/Java/JavaVirtualMachines/graalvm-ce-java17-22.3.1/Contents/Home/

If you are managing your Java environments using JEnv, you’ll simply need to let JEnv know how to find GraalVM. i.e.

jenv add /Library/Java/JavaVirtualMachines/graalvm-ce-java17-22.3.1/Contents/Home/
jenv shell graalvm64-17.0.6

Verify you are using GraalVM:

% java --version
openjdk 17.0.6 2023-01-17
OpenJDK Runtime Environment GraalVM CE 22.3.1 (build 17.0.6+10-jvmci-22.3-b13)
OpenJDK 64-Bit Server VM GraalVM CE 22.3.1 (build 17.0.6+10-jvmci-22.3-b13, mixed mode, sharing)

And finally compile JSpeccy with Maven:

mvn clean install -P native

This will generate an executable artefact in the target directory, which unlike the non-native build artefact, does not include the .jar file name extension.

% file ./target/jspeccy
./target/jspeccy: Mach-O 64-bit executable x86_64

The target file can be invoked using the following command:

./target/jspeccy