Custom GameShell image (v0.3) with standalone emulators

Hi everyone,

as discussed in other threads, I was thinking about taking the base OS image and add the standalone emulators so that newcomers can get most systems running with improved perfomance by just adding games (and the odd bios file).

This is purely aimed at people that just want to emulate games without tinkering with the system too much. It is still advised to get acquainted with the system itself if something goes wrong some time in the future.

I’ve tried to keep changes to the image file to a minimum, I only cleaned up the file structure a little and added the standalone emulators in a way that they are usable from the start (e.g. the correct path to the roms is already configured).

Included are: PocketSNES, fceux (NES), gPSP (GBA), ohboy (GB), PCSX (PSX) and PicoDrive (Mega Drive / Genesis).

Here’s the link to the image file: Download

To install the image, do the following (this is written for Windows users):

  1. Install Win32DiskImager
    Download Win32DiskImager or another program that can write images to SD cards
  2. Flash the image
    Run the program, connect the SD card you want to install the image on (at least 8GB) and in Win32DiskImager choose the image file and the correct drive letter for the SD card and hit “Write”.
    (Make extra sure this is the correct drive, as everything on it will get deleted to write the image on it!)
  3. Boot the system up
    After the process is finished, put the SD card into your GameShell and boot it. If everything worked out, you should see the normal launcher menu (with some fancy icons thanks to this thread)
  4. (Optional) Expand the file system
    Use PuTTY or a similar program to ssh into your GameShell and after logging in (username: cpi, password: cpi), type in the following: “bash <(curl -s”
    Let it do its thing until it asks if you want to expand the file system to match the size of your SD card. Type “Y” and hit enter and after that, all the space of your SD card should be available.
  5. Access your GameShell
    Use FileZilla or a similar program to ssh into your GameShell (for tutorials on how to do that, please search on the forums)
  6. Put games on it
    The only two things you have to do now are:
    a) put games on the device: for that go to “home/cpi/games/” and in the respective folder (GB for Game Boy, GBA for Game Boy Advance, MD for Mega Drive / Genesis, NES for … NES, PSX for PlayStation and SNES for the Super NES) and just upload the roms to that folder
    b) the GBA and PSX emulator need a bios file to run. For the GBA emulator, put the bios file named “gba_bios.bin” in “home/cpi/apps/emulators/GBA/”. For the PSX emulator, put the file named “scph1001.bin” in “home/cpi/apps/emulators/PSX/bios/”. Make sure the files are spelt exactly like that!
  7. Have fun!
    Voila, you should be able to play all your favorite retro games now!

If you find mistakes or have problems with the image, please let me know. I tested all the emulators, but cannot guarantee that they work flawlessly (I just installed them for you :wink: ).
If there’s enough interest for a v0.4 image with the same setup, let me know. I chose v0.3 mainly because that’s what I’m using and I heard that 0.4 introduced some new compatibility issues.

Now have fun with your GameShell! :smiley:


You’re a legend, cheers !

Only mentioning it, due to the last statement re: interest on 0.4.

Previously, 0.3 was considered to be an unstable version, and users were advised to go to 0.2 for a stable experience.

Relatively, 0.4 was considered to be a stable release, with the biggest fault being the screen tearing.

The question is, is there any reason for choosing 0.3 over 0.2? I love your work and your initiative to do this! Just a little quizzical on the initial OS choice.

Also, on that note, the HP code craft script re: filesystem expansion - watch out re: using it to automatically configure retroarch. With the current version being newer, and some settings applied in the configuration being deprecated, it can lead to more issues than desired. For filesystem expansion, I am a huge fan of @guu’s work on a custom 0.4 image that automatically expands.

1 Like

Thanks for the feedback. I’ve used v0.3 since I got my GameShell and had the feeling that it’s pretty stable. The only problems I have are that Lima doesn’t seem to do anything different than fbturbo and that there’s screen tearing.
I’ll try doing a v0.4 version when I get the time, as I’m curious about the update myself.

Thanks a lot for the warning concerning the script, is there a way to just use the file system expansion script without using all the rest?

every os every one ,yeah~

Re: the filesystem expansion script, unless you tell it to do anything besides the expansion (which initially had a small bug re: answering yes = no; which has hopefully been addressed now??), it should only do what you tell it to. If you’ve changed settings in the retro arch config, they could get overwritten. That said, seeing as this is focussed around stand-alones, I’m guessing you haven’t.

I’m trying to include the auto-expansion script that @guu wrote, but I have to install Ubuntu on a VM first. ^^

1 Like

I’m super loving this idea btw!! It will make life for beginners so much easier! Just got a few more ideas that could be implemented. :slight_smile:
I’ve just reread how much I wrote. I am so sorry for the wall of text!! But yeah, I am super excited for this initiate you’ve taken! Here we go!

Even though it’s targeted mainly at stand-alone emulators, one thing that comes up a lot is getting mame to work, ie where to put bios files, and which ones to use. Unfortunately most of them are for retroarch. Having steps in your original post would make this an all in one tutorial to be reckoned with.

Some people also have trouble setting up the mupen64 plus emulator, so having that all loaded up would make life easy.

Likewise, with the chocolate doom/hexen wrapper. That requires some manual tinkering with making action files, custom icons, and messing with the config file. The problem with that is you can’t exactly include *.wad files, and say you just made aliases; if someone didn’t want a game, it would just be sitting there.

There were quite a few other ones too, in the “let’s play insert game series of tutorials in the forum. That might end up having to be multiple versions of the image, since some people might just want to emulate.

Editing the action files to allow emulators to read more file types would be useful for quick and easy dragging and dropping of roms. Eg, for snes, include “zip, 7z, smc, fig” etc (sorry this is off the top of my head) in particular, allowing the emulator to load up compressed archive. Just include a note to say that some super rom sets include multiple version of a rom in a single compressed archive, and will just use the first one in the list. Ie it will work, just it might end up in Spanish.

Since bilinear filtering is a big slowdown that some people have managed, and this tutorial is aimed at faster standalone emulators, possibly either having it preconfigured as such in all the emulators and retroarch, or including instructions to do so would be beneficial.

Speaking of settings, a small thing, but make sure that you’ve cleared all of your wifi settings. Just for personal security, in case someone can use information re your SSID/password combination to do something malicious. Likewise with your retroarch config file, in case you’ve left your username and password for retro achievements sitting around. Game history in retro arch clearing could be useful. Remember the days when we could see the last games the devs played? Ah classic. Possibly to just avoid any complications in case you are asked to produce original games you have allegedly run. (WORST case scenario lol, but gotta protect your own hide!)

Pico-8 is another thing I’ve seen people struggle with re: installation, mainly re: the latest version not matching up with the expected file version. Also, having something explaining to ignore the md5 file check would be good to know.

Other useful scripts could also be implemented. Like the one to allow you to take a screen shot. And the one with the hooks to allow a hot key to adjust the volume and brightness from anywhere; Especially useful since this image is using standalone emulators, and won’t have retroarch to adjust the volume.

All of these are scattered all over the forum, so if you want a hand finding links to how to do them for reference, I am happy to help out.

On another note, possibly also put a reference to the date this thread was last edited, in case anyone accesses this half a year from now or more, and want to know how current it all is. Also links, crediting other peoples work whenever possible!


Wow that’s a lot of suggestions (and I just woke up, lol), thanks so much!

I will definitely try to add stuff like the volume and brightness hotkey.
As for Mame, Mupen 64 and the other included games: sadly I haven"t touched those myself (I’m not an arcade gamer and N64 emulation doesn’t seem to work that well) so I’d have to go through tutorials myself.
Also, I want to keep the instructions to set this image up as short as possible, so if I can’t pre-configure something to work “out of the box” then it might already be too much. But I will go through your suggestions again when I find the time and see what I can implement. :slight_smile:

1 Like

In this custom image, did you add the standalone ohboy! emulator?

This is awesome! I’ve been waiting for something like this. Thank you so much!

Yes, sorry, I should have mentioned somewhere which emulators are included.

1 Like

I remember a while back in another post, you mentioned you had access to a standalone NES emulator. Was this omitted from the list for any reason? (I’m still craving the Japanese Castlevania 3 extra music haha)

Speaking of the list, perhaps also including a version number and changelog would be a good idea, so people know when updates happen.

Did you manage to implement guu’s auto expanding script?

Alternatively, using github for community driven push/pull requests would streamline the process as you make changes.

On a random note, the standalone emulators you’ve chosen are the same ones included with the stock clockwork OS 0.4 image; besides ohboy which is unique to your version. This makes your image a great option for those wanting to have all the benefits of both 0.3 and 0.4. Best of both worlds.

1 Like

Ah, I didn’t know they already did that on v0.4.
If I had known, maybe I wouldn’t have done this whole project. :smiley:

The NES emulator is called fceux and it’s also on the image, I just forgot to mention it. ^^

Sadly I have no experience with git (except for downloading stuff) and I have very little time at the moment. Also, I probably won’t do regular updates, I just want to make it auto-expandable and add the volume hotkey.

1 Like

No, it’s a really good project, given the issues people have reported on 0.4. Admittedly I haven’t experienced them, but that doesn’t mean they don’t exist.
Think of it as the same thing as people still preferring windows 7 over windows 10.

0.4 came with a lot of extra indi games. If like you, someone only wants to emulate, your image is perfect!

Just confirming something. Re: gpSP, and the bios location, was gpSP installed in the path:


This was the path you mentioned to install the gba bios. The bios file should be installed in the same directory as gpSP. By default I have my gpSP installed in the path:


This is where all of my emulators, and my gba bios for gpSP are stored. There is a separate directory where other bios are stored, including another gba bios for mgba:


This post has a screenshot of the pre-requisite directories.

I haven’t had a chance to try your image, so chances are you’ve got it all working perfectly with the correct directories. But I just wanted to run it by you. :slight_smile:

I have every emulator in its own directory, so it should work with the bios in the mentioned directory. I did it that way because some emulators save stuff in their directory (I think gPSP also does that) and I wanted to keep everything clearly separated.

1 Like

Gotcha!! I figured you would have gotten it right, since it’s what you’re running. Was just doing an audit/cleanup of my own emulator directory, and you’re definitely right! It’s a real mess of files, having everything just dumped in the emulators directory! :slight_smile:

hi man, I put all you say (bash etc) and nothing happened any ideas ? and another favor can you help me with the 0.4 I want run games at it. please

Can you specify where you are stuck? Does the image not load?
Concerning v0.4, I heard it already has the emulators installed, but I don’t have much experience with that version, for now my custom image is only available for v0.3.