Commander X16 emulator Install Script

fadingrose

Install script for the Commander X16 emulator works on both Raspberry Pi & PC.

To get the emulator installed copy the script below into a new document and name it x16.sh and then drop it under the file location /RetroPie-Setup/scriptmodules/emulators under your Retropie setup. Then navigate to your RetroPie setup in the Retropie menu or you can do it via shell. Once in the setup, navigate to manage packages and you will find it under experimental packages ready to install.

X86/64 PC - This emulator works best on a PC

Raspberry Pi - Model 4 tested, It's a little slow and sluggish depending on the game run but many are choppy with sound, sluggish gameplay unless you go with text based adventures but possible work around's can be used to improve performance (needs further testing)

A Pi 5 could very well improve performance significantly if someone has one to test on.

#!/usr/bin/env bash
 
rp_module_id="x16"
rp_module_desc="Commander X16 Emulator"
rp_module_help="ROM Extensions: .prg .bin .x16\n\nCopy your Commander X16 programs to \$romdir/x16"
rp_module_licence="https://github.com/X16Community/x16-emulator/blob/master/LICENSE"
rp_module_repo="git https://github.com/X16Community/x16-emulator.git"
rp_module_section="exp"
rp_module_flags="dispmanx"
 
function depends_x16() {
    local depends=(build-essential libsdl2-dev libreadline-dev libpng-dev zlib1g-dev)
    getDepends "${depends[@]}"
}
 
function sources_x16() {
    gitPullOrClone
}
 
function build_x16() {
    make clean
    make -j$(nproc) || error "Build failed"
 
    if [[ ! -f "$md_build/x16emu" ]]; then
        error "x16emu binary not found, build might have failed"
    fi
 
    md_ret_require="$md_build/x16emu"
}
 
function install_x16() {
    md_ret_files=(
        'x16emu'
        'LICENSE'
        'README.md'
    )
 
    cat > "$md_inst/x16-launch.sh" << '_EOF_'
#!/bin/bash
 
# Get PRG file (first argument passed to the script)
PRG_FILE="$1"
 
DIRNAME=$(dirname "$PRG_FILE")
SUFFIX=$(basename "$PRG_FILE" | rev | tr '.' ' ' | awk '{print $1}' | rev)
 
# BIOS path resolved using the current user's home
BIOS_PATH="$HOME/RetroPie/BIOS/x16/rom.bin"
 
# Check for PRG and ROM existence
if [[ -z "$PRG_FILE" ]]; then
    echo "Usage: $0 path_to_game.prg" >&2
    exit 1
fi
 
if [[ ! -f "$BIOS_PATH" ]]; then
    echo "Missing rom.bin at $BIOS_PATH" >&2
    exit 1
fi
 
# Find x16emu binary relative to this script
SCRIPT_DIR="$(dirname "$0")"
 
# Launch emulator with ROM and game
if [ "$SUFFIX" = "img" ]; then
 exec "$SCRIPT_DIR/x16emu" -joy1 -joy2 -fullscreen -rom "$BIOS_PATH" -sdcard "$PRG_FILE" -bas "$SCRIPT_DIR/sdlaunch.txt"
else
 exec "$SCRIPT_DIR/x16emu" -joy1 -joy2 -fullscreen -rom "$BIOS_PATH" -fsroot "$DIRNAME" -prg "$PRG_FILE" -run
fi
_EOF_
 
    cat > "$md_inst/sdlaunch.txt" << '_EOF_'
LOAD"*",8
RUN
_EOF_
 
    chmod +x "$md_inst/x16-launch.sh"
}
 
function configure_x16() {
    mkRomDir "x16"
 
    local launch_prefix
    isPlatform "kms" && launch_prefix=""
 
    # Create BIOS path if needed
    if [[ ! -d "$biosdir/x16" ]]; then
        mkdir -p "$biosdir/x16"
    fi
    chown -R $user:$user "$biosdir/x16"
 
    if [[ "$md_mode" == "install" ]]; then
        mkUserDir "$md_conf_root/x16"
        mkUserDir "$md_conf_root/x16/$md_id"
        moveConfigFile "$home/.$md_id" "$md_conf_root/x16/$md_id"
    fi
 
    addEmulator 1 "$md_id" "x16" "$launch_prefix$md_inst/x16-launch.sh %ROM%"
    addSystem "x16" "Commander X16" ".prg .bas .basl .img"
}

1 - You will need to source the rom.bin file from the following location

https://github.com/commanderx16/x16-rom

This can't be included in the script so you will have to manually source it yourself and drop it into the folder x16 under BIOS

2 - Games & applications - Takes .prg, .bin, .x16 and even .sdcard images. All games come with multiple files IE .PRG, BIN etc so each game will need it's own folder for storing the necessary files to run each game unless your using .sdcard images of each game which should contain all the files needed to run a game inside the .sdcard image. Visit the following link to download games, applications and so on, many are open source.

https://cx16forum.com/forum/viewforum.php?f=29

3 - Controllers - They are bound to -joy1 -joy2 of the emulator so the emulator should just pick up your controllers straight away with no configuration needed. You will need a keyboard attached as many games and application require one plus it's required to exit the emulator.

4 - Exiting the emulator - ALT + F4 on your keyboard

5 - documentation you will find in the link below on how to use the emulator, write code, build games and so fourth.

https://github.com/X16Community/x16-docs

Screenshots included below

Screenshot from 2025-04-18 17-48-30.png

Screenshot from 2025-04-18 17-48-43.png

Screenshot from 2025-04-18 17-49-06.png

Screenshot from 2025-04-18 17-49-22.png

Screenshot from 2025-04-18 18-50-43.png

Screenshot from 2025-04-18 18-51-02.png

fadingrose

@fadingrose Few updates

1 - I removed the simlink and passed through an argument for it to find the rom.bin folder (bios) under BIOS/x16
2 - Games will need to make sure they have all the correct files so ideally you want a folder for each game with all their respective .PRG, .Bin and so fourth inside.

Now i just need to work out controllers and how to exit cleanly back to Retropie

JimmyDansbo

@fadingrose
Hi, I have been playing around with RetroPie and your script to install the Commander X16 emulator on the system.
I got it working, but unfortunately it runs much to slow to be usable.

I had to modify your script a little to get things working. Here is the modified script:

#!/usr/bin/env bash

rp_module_id="x16"
rp_module_desc="Commander X16 Emulator"
rp_module_help="ROM Extensions: .prg .bin .x16\n\nCopy your Commander X16 programs to \$romdir/x16"
rp_module_licence="https://github.com/X16Community/x16-emulator/blob/master/LICENSE"
rp_module_repo="git https://github.com/X16Community/x16-emulator.git"
rp_module_section="exp"
rp_module_flags="dispmanx"

function depends_x16() {
    local depends=(build-essential libsdl2-dev libreadline-dev libpng-dev zlib1g-dev)
    getDepends "${depends[@]}"
}

function sources_x16() {
    gitPullOrClone
}

function build_x16() {
    make clean
    make -j$(nproc) || error "Build failed"

    if [[ ! -f "$md_build/x16emu" ]]; then
        error "x16emu binary not found, build might have failed"
    fi

    md_ret_require="$md_build/x16emu"
}

function install_x16() {
    md_ret_files=(
        'x16emu'
        'LICENSE'
        'README.md'
    )

    cat > "$md_inst/x16-launch.sh" << '_EOF_'
#!/bin/bash

# Get PRG file (first argument passed to the script)
PRG_FILE="$1"

DIRNAME=$(dirname "$PRG_FILE")
SUFFIX=$(basename "$PRG_FILE" | rev | tr '.' ' ' | awk '{print $1}' | rev)

# BIOS path resolved using the current user's home
BIOS_PATH="$HOME/RetroPie/BIOS/x16/rom.bin"

# Check for PRG and ROM existence
if [[ -z "$PRG_FILE" ]]; then
    echo "Usage: $0 path_to_game.prg" >&2
    exit 1
fi

if [[ ! -f "$BIOS_PATH" ]]; then
    echo "Missing rom.bin at $BIOS_PATH" >&2
    exit 1
fi

# Find x16emu binary relative to this script
SCRIPT_DIR="$(dirname "$0")"

# Launch emulator with ROM and game
if [ "$SUFFIX" = "img" ]; then
 exec "$SCRIPT_DIR/x16emu" -joy1 -joy2 -fullscreen -rom "$BIOS_PATH" -sdcard "$PRG_FILE" -bas "$SCRIPT_DIR/sdlaunch.txt"
else
 exec "$SCRIPT_DIR/x16emu" -joy1 -joy2 -fullscreen -rom "$BIOS_PATH" -fsroot "$DIRNAME" -prg "$PRG_FILE" -run
fi
_EOF_

    cat > "$md_inst/sdlaunch.txt" << '_EOF_'
LOAD"*",8
RUN
_EOF_

    chmod +x "$md_inst/x16-launch.sh"
}

function configure_x16() {
    mkRomDir "x16"

    local launch_prefix
    isPlatform "kms" && launch_prefix=""

    # Create BIOS path if needed
    if [[ ! -d "$biosdir/x16" ]]; then
        mkdir -p "$biosdir/x16"
    fi
    chown -R $user:$user "$biosdir/x16"

    if [[ "$md_mode" == "install" ]]; then
        mkUserDir "$md_conf_root/x16"
        mkUserDir "$md_conf_root/x16/$md_id"
        moveConfigFile "$home/.$md_id" "$md_conf_root/x16/$md_id"
    fi

    addEmulator 1 "$md_id" "x16" "$launch_prefix$md_inst/x16-launch.sh %ROM%"
    addSystem "x16" "Commander X16" ".prg .bas .basl .img"
}

After the Commander X16 emulator had been downloaded, compiled, configured etc. I needed to enter:
RetroPie-Setup -> Configuration/Tools -> backends -> x16
and change it to
using SDL1 on desktop
Some packages related to the x11 window manager were installed and afterwards it seems I can use any of the backend options to launch the emulator.

Oh and I have a single gamepad attached to my Pi400 and it works fine with -joy1 and -joy2 added to the commands.

I hope this helps you along your way and maybe you will be able to squeeze out a bit of extra performance of the raspberry pi so the Commander X16 emulator can run at full speed.

fadingrose

@JimmyDansbo Fantastic and thank you for the updated script, it installed fine on my test virtual machine under Retropie and my 8bitdo controller just worked without issues and zero configuration. The Raspberry Pi 4 though it installs fine and i dropped in the bios and some games in the relevant location to test but currently battling with my 8bitdo controller as it refuses to connect to the Raspberry Pi. Besides my controller woes though the emulator booted fine and a game ran ok, it was a little sluggish for that specific game but it runs.

I'll give the controller and a few games a full test once i fix that unrelated controller woe

I was looking at countless different solutions for the exit game and now i know that -joy1, -joy2 etc works maybe i can get Retropie to send a signal, command or something to -joy1, -joy2 for someone to press a button combination that will kill the emulator process.

Been side tracked with other projects so i'll figure out my controller issues and get back to testing.

Once the script is fully complete i may get a proper write up guide done for the emulator in PI IE where to put the bios, the games and how they need to be named, stored, controllers and any configurations needed and so on and then hopefully i'll figure out how to get all this info to the Retropie team and see if they eventually get it added properly.

Never sent a request or anything before so don't know the process as of yet

Still this is great progress and it works perfect if i could only exit haha.

JimmyDansbo

@fadingrose What would be the "normal" way of exiting from emulating C64 (vice) ?
I have just installed it on my Retro Pi setup and the only way I can figure to exit Vice is to press F12 and then choose quit from the menu.

fadingrose

@JimmyDansbo I believe with Vice it's the way you described but i ain't played that emulator in a long time due to owning a C64C & TheC64 so no need to use it. I did briefly look at the documentation for the x16 and unless i missed it couldn't figure out how to exit the emulator with the keyboard or find a menu to exit if there even is one.

If it's the case with the x16 not having a menu so they can exit then it will have to be some kind of a key/button mapping to kill it if that would be the case.

JimmyDansbo

@fadingrose
I could do a pull request on the emulator to add a key combination to do a clean exit. I am thinking something along the lines of CTRL+X
Would that be helpful in this context?

fadingrose

@JimmyDansbo That would be super useful and helpful as at the moment i was playing with idea to get Retropie to just kill the emulator and boot a user back to the pie menu. Not elegant and people would need to take into consideration to save their progress or what ever first but it would work if it didn't break anything.

If there was even just a keyboard solution of CTRL+X to shut it down safely that would be much better and maybe someone with more knowledge than me may bind that key combination to a controller combination so the emulator thinks when they press say start & hotkey it simulates a CTRL+X keyboard press.

I'll continue to fiddle about with this kill the the emulator solution though as a temp measure till something more better has been added.

cheers

JimmyDansbo

@fadingrose I have created code to let the emulator exit on CTRL+x and if SELECT+START is pressed on a joypad.
You can find my repo here: https://github.com/JimmyDansbo/x16-emulator/tree/key_button_exit

I have not yet added it as a PR to the official emu as I am not sure if other people actually want this...

If you install from my repository, linked above, you can exit the emulator simply by pressing SELECT+START on a joypad or by pressing CTRL+x on the keyboard.

fadingrose

@JimmyDansbo That's brilliant thank you

I did add to the script for the emulator process to be killed with a key combination and chose ctrl and x as a test at first so i could kill it whilst the emulator is running but my Proxmox vm decided using ctrl is a no no so i switched the keys to a and delete but still no change and no killing of emulator and just not got round to testing it on a pi though.

Just for clarification here was my change

#!/usr/bin/env bash

rp_module_id="x16"
rp_module_desc="Commander X16 Emulator"
rp_module_help="ROM Extensions: .prg .bin .x16\n\nCopy your Commander X16 programs to \$romdir/x16"
rp_module_licence="https://github.com/X16Community/x16-emulator/blob/master/LICENSE"
rp_module_repo="git https://github.com/X16Community/x16-emulator.git"
rp_module_section="exp"
rp_module_flags="dispmanx"

function depends_x16() {
    local depends=(build-essential libsdl2-dev libreadline-dev libpng-dev zlib1g-dev)
    getDepends "${depends[@]}"
}

function sources_x16() {
    gitPullOrClone
}

function build_x16() {
    make clean
    make -j$(nproc) || error "Build failed"

    if [[ ! -f "$md_build/x16emu" ]]; then
        error "x16emu binary not found, build might have failed"
    fi

    md_ret_require="$md_build/x16emu"
}

function install_x16() {
    md_ret_files=(
        'x16emu'
        'LICENSE'
        'README.md'
    )

    cat > "$md_inst/x16-launch.sh" << '_EOF_'
#!/bin/bash

# Get PRG file (first argument passed to the script)
PRG_FILE="$1"

DIRNAME=$(dirname "$PRG_FILE")
SUFFIX=$(basename "$PRG_FILE" | rev | tr '.' ' ' | awk '{print $1}' | rev)

# BIOS path resolved using the current user's home
BIOS_PATH="$HOME/RetroPie/BIOS/x16/rom.bin"

# Check for PRG and ROM existence
if [[ -z "$PRG_FILE" ]]; then
    echo "Usage: $0 path_to_game.prg" >&2
    exit 1
fi

if [[ ! -f "$BIOS_PATH" ]]; then
    echo "Missing rom.bin at $BIOS_PATH" >&2
    exit 1
fi

# Find x16emu binary relative to this script
SCRIPT_DIR="$(dirname "$0")"

# Launch emulator in background
if [ "$SUFFIX" = "img" ]; then
    "$SCRIPT_DIR/x16emu" -joy1 -joy2 -fullscreen -rom "$BIOS_PATH" -sdcard "$PRG_FILE" -bas "$SCRIPT_DIR/sdlaunch.txt" &
else
    "$SCRIPT_DIR/x16emu" -joy1 -joy2 -fullscreen -rom "$BIOS_PATH" -fsroot "$DIRNAME" -prg "$PRG_FILE" -run &
fi

EMU_PID=$!

(
    stty -echo -icanon time 0 min 0
    trap "kill $EMU_PID; reset; exit" INT TERM

    a_pressed=false

    while true; do
        read -rsn1 key1
        if [[ "$key1" == 'a' ]]; then
            a_pressed=true
        elif [[ "$key1" == $'\x7F' && "$a_pressed" == true ]]; then
            kill "$EMU_PID"
            break
        fi
        sleep 0.1
    done
    reset
) &

wait $EMU_PID
reset
exit 0
_EOF_

    cat > "$md_inst/sdlaunch.txt" << '_EOF_'
LOAD"*",8
RUN
_EOF_

    chmod +x "$md_inst/x16-launch.sh"
}

function configure_x16() {
    mkRomDir "x16"

    local launch_prefix
    isPlatform "kms" && launch_prefix=""

    # Create BIOS path if needed
    if [[ ! -d "$biosdir/x16" ]]; then
        mkdir -p "$biosdir/x16"
    fi
    chown -R $user:$user "$biosdir/x16"

    if [[ "$md_mode" == "install" ]]; then
        mkUserDir "$md_conf_root/x16"
        mkUserDir "$md_conf_root/x16/$md_id"
        moveConfigFile "$home/.$md_id" "$md_conf_root/x16/$md_id"
    fi

    addEmulator 1 "$md_id" "x16" "$launch_prefix$md_inst/x16-launch.sh %ROM%"
    addSystem "x16" "Commander X16" ".prg .bas .basl .img"
}

I will give your repo a test though when i get the chance and if people actually want it that would be great, if not i am sure i will eventually work out the solution for killing it.

Much appreciated

JimmyDansbo

@fadingrose We were talking on the Commander X16 discord and it seems that there is consensus to let the emulator handle ALT+F4.
On normal use, that key combination will never reach the emulator, but when running under emulation station, that combination will reach the emulator and I have created a new branch that handles that.

I am not sure how familiar you are with git, but you just do

git clone https://github.com/JimmyDansbo/x16-emulator.git
git checkout alt_f4

fadingrose

@JimmyDansbo I have used git briefly for adding minetest maps i created but need to familiarize myself properly with it. Been a bit busy and hectic here so on the weekend i will get back to this and can focus and test.

That's good though and hopefully if ALT+ F4 are using that will be great for Retropie as users can just exit the emulator with that unless i map the keys to pad buttons and get Retropie to use this.

ExarKunIv

@fadingrose

if memory serves me right all you need to do is change the repo line to this

rp_module_repo="git https://github.com/X16Community/x16-emulator.git alt_f4"

i will have to double check that im still half asleep

JimmyDansbo

@ExarKunIv
I just tried it on the command line and I think that just clones the repository into a different directory name.
The command line is: git clone -b alt_f4 https://github.com/jimmydansbo/x16-emulator.git

I am not sure how to add that -b option to the repo line.

@fadingrose do let me know how you get along during the weekend. If it works with ALT+F4, I will do the pull request against the official emulator and hopefully the rest of the gang will accept it.

mitu

@JimmyDansbo said in Commander X16 emulator Install Script:

I just tried it on the command line and I think that just clones the repository into a different directory name.

That's ok, but if you put it in the rp_module_repo variable in the scriptmodule, RetroPie will do the right thing (and not literally execute the contents as a command) and clone from the repo then switch to the branch provided in the last parameter. You can even add a 4th parameter to indicate the commit from which the source is built.

fadingrose

@JimmyDansbo Been rather busy but i had chance to test it. I gave it a test on my Raspberry Pi model 4 and sadly it doesn't do anything under Retropie. I am in the process of re installing and will test again. I did go to test under my proxmox VM but i couldn't figure out how to get Proxmox to let me use alt & f4 to test so i just switched straight to my Pi.

Once it finishes i'll re install and do another test

fadingrose

@JimmyDansbo A re install and tested and ALT + F4 takes me straight back to the Retropie menu so that works like a charm cheers. Hopefully it will make it into the emulator permanent if the X16 team agree but we can at least know it worked.

I'll get working on some documentation soon so anyone using the script will know how to install, run and even use the emulator.

fadingrose

I have updated the description and the script after some testing, it will need further testing by other people and hopefully someone with a Pi5 can give it a test and report back on performance. I will do some further testing on the PI4 using the official Retropie image instead of Retropie through the Debian OS desktop which i'm sure the desktop will take some performance away and see if there is any tricks or anything to squeeze some extra performance.

So far though it seems to run ok even if a little sluggish but it's perfectly usable and there isn't any show stopping issues that would consider it broken or anything.

JimmyDansbo

@fadingrose In my point of view, Commander X16 on Raspberry Pi 4 and 400 is more or less unusable.
A lot of games a depending on the exact speed of the Commander X16 and when it is only running at something lik 60-70% of correct speed, things just don't work as expected, even sound will likely be weird :(
Hopefully some performance can be found so we can get closer to 95-100% even on pi4/400.

JimmyDansbo

I am happy to report that my PR to add handling ALT+F4 to the emulator has just been merged into the official repository.