Add ZEsarUX, ZX Spectrum emulator with game controller support

[dudleydes]

Would it be possible to add ZEsarUX by Cesar Hernandez to Retropie? Cesar is an active developer having released three versions in 2015. He also responds enthusiastically to feedback as he added SDL support at my request so that it would be possible to launch Speccy games from EmulationStation.

ZEsarUX has out-of-the-box game controller support for most games with further configuration possible with command line parameters. With the difficulties with installing lr-fuse, ZEsarUX would be a great addition to Retropie. Also, there is support for audio over HDMI.

This is how I installed and configured ZEsarUX on my RPi 1 Model B using the RetroPie V3.0 Beta 2 image.

Dependencies

From the INSTALL file from the source code, the dependencies are

• libssl
• libpthreads
• alsa
• sdllib (I think this should be libsdl)

I didn't need to install any of these.

Get Sources

Run the following:

wget http://downloads.sourceforge.net/project/zesarux/ZEsarUX-3.0/ZEsarUX_src-3.0.tar.gz
tar -xvf ZEsarUX_src-3.0.tar.gz
rm ZEsarUX_src-3.0.tar.gz

Build Binary

The best joystick to emulate is the Kempston. This can be coded into the binary with the following commands:

pushd ZEsarUX-3.0
sed -i 's/JOYSTICK_CURSOR_WITH_SHIFT/JOYSTICK_KEMPSTON/g' joystick.c

Now we can build the binary, then install it and the necessary files to the /opt/retropie/emulators/zesarux folder with the following commands:

export CFLAGS=-O3
export LDFLAGS=-O3
./configure --enable-raspberry --prefix /opt/retropie/emulators/zesarux
make clean
make
sudo make install
popd

Configure ZEsarUX

ZEsarUX reads a config file, ~/.zesaruxrc located in the home directory, upon loading. The config file allows for the same options to be passed in the command line. The file's contents should be as below:

;ZEsarUX sample configuration file
;
;Lines beginning with ; or # are ignored

;Run zesarux with --help or --experthelp to see all the options
--disableborder
--vo sdl
--ao alsa
--hidemousepointer
--disablefooter

;Remap Fire Event. Uncomment and amend if you wish to change the default button 3.
;--joystickevent 3 Fire

I have added the last line because it allows for the user to remap the fire event. On the PS3 controller, button 3 is Start so, with the --joystickevent flag, it is possible to remap to button 14 (X) for every game.

Configure RetroPie

It is possible to configure game controllers by adding command line parameters outlining the mappings. The best way to launch these games is by using bash scripts. I have used a configuration similar to that for DOSBox.

In /etc/emulationstation/es_systems.cfg, the extensions .sh and .SH need to be added to the tag for the zxspectrum entry.

In /opt/retropie/configs/zxspectrum/emulators.cfg, add the following:

zesarux="/home/pi/RetroPie/roms/zxspectrum/+Start\ ZEsarUX.sh %ROM%"
default="zesarux"

Launch ZEsarUX from EmulationStation

A rom +Start ZEsarUX.sh needs to be created in the zxspectrum rom folder. Its contents should be as follows:

#!/bin/bash
params="$1"
if [[ "$params" =~ \.sh$ ]]; then
    bash "$params"
else
    /opt/retropie/supplementary/runcommand/runcommand.sh 0 "/opt/retropie/emulators/zesarux/bin/zesarux $params" "zesarux"
fi

This script will make sure that both tapes and scripts can be launched from Emulationstation. By launching +Start ZEsarUX itself, the emulator will start and it is possible to load tapes using the in-game UI.

I'll write up some tutorials on how to use ZEsarUX and how to configure it for game controllers.

[joolswills]

I don't believe there is a general problem with installing lr-fuse - the user on that link disabled swap, so they likely just ran out of memory. lr-fuse will move out of "experimental" shortly, as it works well, and makes it easy to load/play spectrum games on joypad etc - i may make it the default.

Additional emulators are welcome of course - you could take a look at some existing RetroPie scriptmodules and perhaps try and build one based on the above information ?

[dudleydes]

I have installed lr-fuse but I've had problems getting Jetpac working with my PS3 controller. Also, a lot of games need controls to be remapped in-game each time I play them which is bit of a pain.

I shall build a scriptmodule for ZEsarUX. It'll be a good learning experience as well as a way of contributing to an excellent project. I've looked through existing scripts and I should be okay with converting the above to a scriptmodule except for editing es_systems.cfg. I will need guidance on this.

[HerbFargus]

in case you're interested there is also a zxspectrum emulator called unreal speccy portable that I tried (and failed) building a script at, you can see this post to at least get some ideas: http://blog.petrockblock.com/forums/topic/how-to-add-new-emulator-and-make-it-default/

[dudleydes]

I have started to write the scriptmodule for ZEsarUX. I have created a script called zesarux.sh, the contents of which are below.

#!/usr/bin/env bash

# This file is part of RetroPie.
# 
# (c) Copyright 2012-2015  Florian Müller (contact@petrockblock.com)
# 
# See the LICENSE.md file at the top-level directory of this distribution and 
# at https://raw.githubusercontent.com/RetroPie/RetroPie-Setup/master/LICENSE.md
#

rp_module_id="zesaurux"
rp_module_desc="ZX Spectrum emulator ZEsarUX"
rp_module_menus="4+"
rp_module_flags="dispmanx"

function sources_zesarux() {
    wget http://downloads.sourceforge.net/project/zesarux/ZEsarUX-3.0/ZEsarUX_src-3.0.tar.gz
    tar -xvf ZEsarUX_src-3.0.tar.gz
    rm ZEsarUX_src-3.0.tar.gz
}

I have placed it in ~/RetroPie-Setup/scriptmodules/emulators. When I run the Retropie setup script, the option to install ZEsarUX appears in the experimental menu. When I try to run it, nothing happens. I'm not getting any error messages. The script just stops after 1 or 2 seconds and nothing has downloaded. What am I missing?

[joolswills]

you have different spellings -

module id = zesaurux sources_moduleid - zesarux

[dudleydes]

Thanks. Always good to have a fresh pair of eyes look over code. Compiling at the moment...

[dudleydes]

I have developed a scriptmodule, below, for ZEsarUX. I have tested it on a RPi1 using a fresh v3.0 Beta 2 image using a TZX tape and a shell script to launch games. Both worked as expected.

Here is the script:

#!/usr/bin/env bash

# This file is part of RetroPie.
# 
# (c) Copyright 2012-2015  Florian Müller (contact@petrockblock.com)
# 
# See the LICENSE.md file at the top-level directory of this distribution and 
# at https://raw.githubusercontent.com/petrockblog/RetroPie-Setup/master/LICENSE.md.
#

rp_module_id="zesarux"
rp_module_desc="ZX Spectrum emulator ZEsarUX"
rp_module_menus="4+"

function depends_dosbox() {
    getDepends libssl-dev libpthread-stubs0-dev  libsdl1.2-dev
}

function sources_zesarux() {
    wget -q http://downloads.sourceforge.net/project/zesarux/ZEsarUX-3.0/ZEsarUX_src-3.0.tar.gz
    tar -xvf ZEsarUX_src-3.0.tar.gz
    rm ZEsarUX_src-3.0.tar.gz
}

function build_zesarux() {
    pushd ZEsarUX-3.0
    export CFLAGS=-O3
    export LDFLAGS=-O3
    ./configure --enable-raspberry --prefix "$md_inst"
    make clean
    make
    md_ret_require="$md_build/ZEsarUX-3.0"
}

function install_zesarux() {
    pushd ZEsarUX-3.0
    sudo make install
}

function configure_zesarux() {
    mkRomDir "zxspectrum"

    rm -f "$romdir/zxspectrum/Start ZEsarUX.sh"
    cat > "$romdir/zxspectrum/+Start ZEsarUX.sh" << _EOF_
#!/bin/bash
params="\$1"
if [[ "\$params" =~ \.sh$ ]]; then
    bash "\$params"
else
    $rootdir/supplementary/runcommand/runcommand.sh 0 "$md_inst/bin/zesarux \$params" "$md_id"
fi
_EOF_
    chmod +x "$romdir/zxspectrum/+Start ZEsarUX.sh"
    chown $user:$user "$romdir/zxspectrum/+Start ZEsarUX.sh"

    # move any old configs to the new location
    if [[ -d "$home/.zesaruxrc" && ! -h "$home/.zesaruxrc" ]]; then
        mv "$home/.zesaruxrc/"* "$configdir/zxspectrum/"
        rmdir "$home/.zesaruxrc"
    fi
    ln -snf "$configdir/zxspectrum/.zesaruxrc" "$home/.zesaruxrc"

    cat > "$configdir/zxspectrum/.zesaruxrc" << _EOF_
;ZEsarUX sample configuration file
;
;Lines beginning with ; or # are ignored

;Run zesarux with --help or --experthelp to see all the options
--disableborder
--disablefooter
--vo sdl
--ao alsa
--hidemousepointer

--joystickemulated Kempston

;Remap Fire Event. Uncomment and amend if you wish to change the default button 3.
;--joystickevent 3 Fire
_EOF_

    chown -R $user:$user "$configdir/zxspectrum"

    chown $user:$user "$configdir/all/emulators.cfg"

    addSystem 1 "$md_id" "zxspectrum" "$romdir/zxspectrum/+Start\ ZEsarUX.sh %ROM%" "" ".sh"
}

Curiously, es_systems.cfg already had shell scripts (.sh, .SH) included in permitted ROMs for zxspectrum.

Please let me know if there is any further testing or info you would like.

[joolswills]

you don't need these lines:

    export CFLAGS=-O3 
    export LDFLAGS=-O3
...
    rm -f "$romdir/zxspectrum/Start ZEsarUX.sh"
...
    # move any old configs to the new location
    if [[ -d "$home/.zesaruxrc" && ! -h "$home/.zesaruxrc" ]]; then
        mv "$home/.zesaruxrc/"* "$configdir/zxspectrum/"
        rmdir "$home/.zesaruxrc"
    fi
...
    chown $user:$user "$configdir/all/emulators.cfg"

there may be other changes needed - I can put together something based on this when I next get a free moment - but well done with the module :)

[joolswills]

no need for "sudo" in the make install also as script is already run as root.

[dudleydes]

Thanks for the feedback. I've run the scriptmodule with the changes you mentioned and ZEsarUX installed fine. In fact, the time to run the script was almost halved.

[joolswills]

probably due to the lower optimisation level - it may be slightly faster with -O3 (or not), but we default our optimisations flags to -O2 they can be overridden though as needed. I'm sure the emulator runs at full speed anyway though. if O3 was definitely needed it can be added by appending it to the existing CFLAGS via make (without doing the export which would overwrite our retropie-setup flags)

[chernandezba]

Hi.

I'm Cesar Hernandez, the author of ZEsarUX emulator. Well, about O3 optimizations, the best way to compile ZEsarUX on Raspberry Pi is using export CFLAGS=-O3 export LDFLAGS=-O3

before configure. Why? Because it tells the gcc compiler to optimize the code, so it will run faster. For example, on my RPI1, the emulator becomes almost unplayable without those optimizations.

You said " probably due to the lower optimisation level - it may be slightly faster with -O3 (or not), but we default our optimisations flags to -O2 they can be overridden though as needed. I'm sure the emulator runs at full speed anyway though. "

Well, O3 is better than O2. As the gcc manual says:

" -O3

Optimize yet more. -O3 turns on all optimizations specified by -O2 and also turns on the -finline-functions, -funswitch-loops, -fpredictive-commoning, -fgcse-after-reload, -ftree-vectorize and -fipa-cp-clone options. "

I have tested the emulator on my rpi1 (not on a rpi2 or higher), and using O3 works well, but without using any O*, it becomes almost unplayable. I haven't tested it with O2, but it will be probably slower than O3.

So please include those optimization sentences export CFLAGS=-O3 export LDFLAGS=-O3

before the configure

Thanks Cesar

[dudleydes]

I have built ZEsarUX with the -O3 and the default RetroPie setting, -O2, flags and have not noticed any discernible difference in performance.

[chernandezba]

With RPI1 or RPI2?

[joolswills]

I doubt you will. We chose O2 for reason as our default. There may be no noticeable difference at all, and in fact in some cases O2 may be quicker. In some cases the additional levels can increase cache misses etc. It depends on the code though of course. There are cases of course where O3 does help (with code that does well with vectorisation for example)

https://wiki.gentoo.org/wiki/GCC_optimization (not specific to arm but one reference)

-O3: the highest level of optimization possible. It enables optimizations that are expensive in terms of compile time and memory usage. Compiling with -O3 is not a guaranteed way to improve performance, and in fact, in many cases, can slow down a system due to larger binaries and increased memory usage. -O3 is also known to break several packages. Using -O3 is not recommended.

Once we have the script incorporated I may add O3 as you have requested, but not as above - that would override our global flags. I don't think you need to add O3 to the linker flags.

[chernandezba]

Well I haven't tested with O2 so I can not tell you if it will work well at least with a RPI1. Maybe you can wait for me to test it on my RPI1. About this: "-O3 is also known to break several packages. Using -O3 is not recommended." The emulator has been compiled with O3 a lot of times so I'm sure that it doesn't break anything.

By the way, you have the last word about it. If you want to compile only with O2 it's ok ;)

Cheers Cesar

[joolswills]

I would be interested in your test results. Our default compile flags btw are

rpi1

-O2 -mfpu=vfp -march=armv6j -mfloat-abi=hard

and for rpi2

-O2 -mcpu=cortex-a7 -mfpu=neon-vfpv4 -mfloat-abi=hard

[joolswills]

I have added the module based on your above code with a few changes (some I already mentioned). Please let me know if it works ok for you.

[dudleydes]

I've noticed that line 15 says

function depends_dosbox()

when it should say

function depends_zesarux()

Apologies, the perils of copy and paste, I suppose.

I'll test the scriptmodule in the next day or two.

[joolswills]

should be sorted now thanks.

[dudleydes]

I have tested the scriptmodule on the RPi 1 and 2 and everything is working as expected. While testing, I found that, on the RPi 1 with overclocking set to medium, the game Rainbow Islands ran better in terms of speed and music when compiled with the -O2 flag rather than the -O3 flag. I have let Cesar know and unless I hear from him, I shall close this issue in a few days.

[joolswills]

also, if just doing -O3 as above you will lose the -mfpu=vfp -march=armv6j -mfloat-abi=hard - you could test with that too, but O2 should be fine for this.

[joolswills]

(The compiler might create code to use hardfloats by default, but from earlier testing, this was the best overall performance vs compile time)

[chernandezba]

Hi I haven't got much time to test it on RPI1, maybe I can test O2 vs O3 on Monday or Tuesday. But if you tested it and consider that it's even better to compile with O2 it's ok for me :)

Thanks Cesar

[chernandezba]

Hi

Tested O2 and O3 with Rainbow Islands on Spectrum 128k. http://www.worldofspectrum.org/pub/sinclair/games/r/RainbowIslands.tap.zip

No difference between O2 or O3. In both cases, rpi cpu usage is 80%, 13 FPS on emulator and frameskip autoset to 3 (game enables real video). My rpi1 is set to 800 MHz.

So, I think O2 is correct for compiling the emulator

Cheers Cesar

[dudleydes]

It has come to my attention that version 3.0 of ZEsarUX supports custom config files for every game. Launching games by script is no longer necessary so I have decided to simplify the +Start ZEsarUX script. Also, I noticed that games with spaces in their names were not loading with the current script.

I have written a new version of the configure section of the existing scriptmodule to resolve these issues.

function configure_zesarux() {
    mkRomDir "zxspectrum"

    cat > "$romdir/zxspectrum/+Start ZEsarUX.sh" << _EOF_
#!/bin/bash 
params="\$1" 
pushd "/opt/retropie/emulators/zesarux/bin" 
if [[ "\$params" =~ \.sh$ ]]; then 
    ./zesarux 
else 
    ./zesarux "\$params" 
fi
popd
_EOF_
    chmod +x "$romdir/zxspectrum/+Start ZEsarUX.sh"
    chown $user:$user "$romdir/zxspectrum/+Start ZEsarUX.sh"

    ln -sf "$configdir/zxspectrum/.zesaruxrc" "$home/.zesaruxrc"

    cat > "$configdir/zxspectrum/.zesaruxrc" << _EOF_
;ZEsarUX sample configuration file
;
;Lines beginning with ; or # are ignored

;Run zesarux with --help or --experthelp to see all the options
--disableborder
--disablefooter
--vo sdl
--ao alsa
--hidemousepointer

--smartloadpath /home/pi/RetroPie/roms/zxspectrum

--joystickemulated Kempston

;Remap Fire Event. Uncomment and amend if you wish to change the default button 3.
;--joystickevent 3 Fire
_EOF_

    chown $user:$user "$configdir/zxspectrum/.zesaruxrc"

    addSystem 1 "$md_id" "zxspectrum" "$romdir/zxspectrum/+Start\ ZEsarUX.sh %ROM%" "" ".sh"
}

Selecting the +Start ZEsarUX script in ES will allow the launch of ZEsarUX which will be useful to users who wish to load tapes or snapshots from the emulator itself as well as experimenting with various settings. To facilitate this, I have included a --smartloadpath parameter in the config file, .zesarux, to set the default path for loading tapes to the zxspectrum rom folder.

I have tested the script and everything is working as it should. Could the scriptmodule be updated? Thanks.

[joolswills]

It would be handy if you could check out how to do git pull requests etc - makes it simpler to merge in updates. The above code looks good, except the hardcoded path - "$md_inst/bin" should be used not ""/opt/retropie/emulators/zesarux/bin"

[joolswills]

and also /home/pi/RetroPie/roms/zxspectrum is another hardcoded path - it should be $romdir/zxspectrum - ill make the changes and commit - just a heads up for next time.

[chernandezba]

As I said before, I haven't still tested retropie. I have to test it soon... But I have noticed one thing.. Why you run ZEsarUX with --vo sdl --ao alsa? ZEsarUX supports also sdl audio, so, why don't you run with: --vo sdl --ao sdl Maybe the sound will improve.... Cheers

[joolswills]

I have enabled the dispmanx SDL backend by default for this emulator now - which fills the screen better - can be adjusted from the dispmanx config in retropie-setup. It's possible it could cause slowdown - not noticeable on my pi2 though, but it reduces tearing (forced double buffering)

[dudleydes]

@chernandezba

I've tried setting the audio driver to sdl and I'm not noticing any improvement on RPi 1 or RPi 2.

[dudleydes]

I tried to update the RetroPie script but I get an update failed error message. This is the message on the RPi 2.

If I delete the scriptmodule zesarux.sh, then the update works.

The new script works fine with the updated version.

[dudleydes]

I tried ZEsarUX with dispmanx enabled on the RPi 1 model B with overclocking set to medium. I found that the audio was better with dispmanx disabled. I used the intro music to Chuckie Egg to test.

Audio on the RPi 2 is fine with dispmanx enabled. Maybe we can leave dispmanx disabled on RPi 1?

[joolswills]

you get the error because you have locally edited the file. You can do "git reset --hard" or so.

I think enough has been done to the script for now. I would like to close this ticket.

[joolswills]

or do as it says and stash your changes if you want to keep them. There are plenty of git tutorials on the net :)

[dudleydes]

Thanks for clearing up the failed update. Yep, I'll close this ticket. Any further changes I'll use a pull request.