[Tutorial] How to load Vic-20 Cartridges straight from EmulationStation

Nicxiv

Introduction
At no point do I endorse or support piracy or theft of intellectual property in any form.

The Commodore Vic-20, released in 1980, is a historic piece of computing history not only was it the first computer to sell over one million units, but its legacy is apparent in the Commodore 64, the best selling computer model of all time. The Vic delivers capable hardware (for the time) and a shockingly low (for the time) price. This system encapsulates Jack Tramiel's vision for what computing in the 1980s could be (low-cost, powerful enough, and charmingly hamstrung in curious ways).

If you are anything like me, you probably have fond memories of the Commodore Vic-20, and you probably want to play some classic Vic-20 games on your RetroPie installation.

Thankfully, RetroPie allows you to install Vice-Emu, the C64, C128, C16, Plus4, PET, CBM, and Vic-20 Emulator. This can, of course, be found in the setup utility under (as of RetroPie 4.6):

setup>manage packages>optional packages>vice

I leave the actual installation up to you.

This installation of Vice is great, in that it allows you to select whether you want to emulate a Vic20 with or without a cartridge inserted. This is great if you want to play a Disk or a Tape. Unfortunately, cartridges on the Vic20 are not quite that simple.

The Vic20's Cartridge Problem
Cartridges on the Vic20 fall into 2 categories:

Cartridges that are exactly 4kb and load in at $A000 (the autoload address)
Everything else.

The first type of cartridge has 1 physical ROM chip (4kb) where the program is stored. The second type of cartridge has 2 ROM chips so that the programs can be split around the kernel.

Vice is very good at loading the first type (use the xvic-cart setting). Unfortunately, Vice is not so nice about loading the second type.
This isn't entirely Vice's fault as there is no standard singular ROM file for "big" VIC20 games. Instead, most games come in multiple files.

They can still be loaded by Vice but it takes some finagling (in a graphical environment, this is done by using the menu to load the two parts, but that isn't terribly friendly). We can use command-line arguments to load all the parts in one step from emulation, but setting this up might take some 1337-Haxor knowhow.

A note on ROMs
When you "dump your multi-ROM carts yourself", to run them they will need to be addressed to where in memory they are supposed to live.
These locations and their associated extensions are:

A000 - .a0
B000 - .b0
2000 - .20
4000 - .40
6000 - .60

Most ROMs that are found online (just for the sake of argument mind you) typically either specify in their filename which addresses they want or already have the correct extension applied. Either way, ensure that any of your own personal ROMs that you want to run have the appropriate extensions. Then Zip all the Roms together. (My script takes a .zip file to keep things neat)

Step 1 - find the emulator binaries
The first thing we need to know is where the vice emulator is installed. We can find this, in our config files. Just check your configs/c64/emulators.cfg file. In my case, I discover that the binaries are located at:

/opt/retropie/emulators/vice/bin/

We can double-check this with:

ls /opt/retropie/emulators/vice/bin/

we get:
c1541  cartconv  petcat  vice.sh  vsid  x128  x64  x64dtv  x64sc  xcbm2  xcbm5x0  xpet  xplus4  xscpu64  xvic

Everything seems to be in order; our vic20 emulator is /opt/retropie/emulators/vice/bin/xvic

So now we know where were are going to be targetting.

Step 2 - create our new launch script
You may place your custom script wherever you would like, but for this tutorial, I chose to keep them in a custom subdirectory of vice/bin/

We can make this file with:

sudo mkdir -p /opt/retropie/emulators/vice/bin/customlaunchers/vic20
sudo nano /opt/retropie/emulators/vice/bin/customlaunchers/vic20/advcart.sh

Once in nano just copy in my program

#!/bin/bash

BIN="/opt/retropie/emulators/vice/bin/xvic"
ROM="$1"
PARAMS=("${@:2}")

source "/opt/retropie/lib/archivefuncs.sh"

#unpack the zip file to find our rom images
archiveExtract "$ROM" ".a0 .b0 .20 .40 .60"

function makeargs {
        # check successful extraction and if we have at least one file.
        if [[ $? == 0 ]]; then
                #build the cart image
                for f in "$arch_dir"/*; do
                        #assign ROM to correct memory locations
                        case "$f" in
                                *.a0 )
                                        cartA[0]="-cartA"
                                        cartA[1]="$f"
                                ;;
                                *.b0 )
                                        cartB[0]="-cartB"
                                        cartB[1]="$f"
                                ;;
                                *.20 )
                                        cart2[0]="-cart2"
                                        cart2[1]="$f"
                                ;;
                                *.40 )
                                        cart4[0]="-cart4"
                                        cart4[1]="$f"
                                ;;
                                *.60 )
                                        cart6[0]="-cart6"
                                        cart6[1]="$f"
                                ;;
                        esac
                done
        fi
}

makeargs
"$BIN" -chdir "$arch_dir" "${PARAMS[@]}" "${cartA[@]}" "${cartB[@]}" "${cart2[@]}" "${cart4[@]}" "${cart6[@]}"
archiveCleanup

Just be sure to change the BIN variable to the binary location of xvic (found in step 1).
Exit and save, and now we move on to adding our script to emulationstation.

Step 3 - adding our script to emulation station
Remember all the way back in step 1, where we used our config file to find the binaries?
Reopen configs/c64/emulators.cfg and add the following line:

vice-xvic-advcar = "/opt/retropie/emulators/vice/bin/customlaunchers/vic20/advcart.sh %ROM%"

Save and restart emulation station.

Step 4 - select our new emulator
Launch one of our zipped ROM file through the menu, then select our new emulator option for the current program. With any luck, you should now be able to play all the classic!

Play wonderful multirom games like Ms. Pacman or Donkey Kong! (really a standout on the system)

Screen Shot 2020-05-17 at 2.57.00 PM.png

Nicxiv

Oh, one last thing that I completely forgot to mention in the original post,
Depending on where you create your shell script. You might need to use

sudo chmod 777 /opt/retropie/emulators/vice/bin/customlaunchers/vic20/advcart.sh

Otherwise, you might run into problems with execution.

CCFox

@Nicxiv

Can this script be used for lr-vice script module that @valerino has created for splitting the lr vi-vice cores into the independent emulators?

https://retropie.org.uk/forum/topic/25576/new-scriptmodules-lr-vice-xvic-gsplus-proper-lr-mess-integration/162?_=1589761552827

Kind Regards

CCF

Nicxiv

@CCFox Unfortunately no, I haven't looked into Libretro's backend enough quite yet. Thus I'm not sure how the core differs from the standalone in terms of interfacing.

Edit: I will see what I can do and post the results.

Edit2: It seems doable, I will have a crack at it, and see about making this work, but there really isn't much documentation on the github page, so it might take a moment to figure out how these advanced options are applied. Hopefully, I can make a script to do this without much hassle.

CCFox

@Nicxiv

Thank you for your reply and your efforts.

Kind Regards

CCFox

UDb23

Great guide, thanks a lot !
Nice to see some love for the Vic.

saccublenda

@Nicxiv Now I can play Buck Rogers Planet Of Zoom. Thanks!