Skip to main content

Installing the tools

WORK IN PROGRESS!

This page is not quite ready for visitors yet. Please check again another time.

In this chapter we get you started with the tools you'll need to build a basic platform game. These tools include the necessary programs to build your code into a working program, the tools to write your code in the first place as well as tools you might need to test your code on your computer (i.e. an emulator), as well as create images and other assets for your game.

About the Docker toolchain​

Installing loads of development tools is really tedious, time consuming and can be an unreliable experience, complicated by different users' computers having different software already installed.

To make things easier to manage, we've created something called a "Docker image" which bundles lots of the tools needed to do SMS development together and allows them to be run in a clean and controlled environment called a "container".

In order to run Docker images you will need a piece of software, called Docker Desktop, which is freely available to download and which, if you're familiar with Docker already, you may already have.

Since the tools we've selected for this SMS toolchain run natively under the Linux operating system, you will need to be running your version of Docker Desktop either on a Linux computer, or on a recent MacOS computer (since MacOS is sufficiently related to Linux to allow this to work) or, if you're using a Windows computer, through Microsoft's compatibility layer, known as Windows Subsystem for Linux, or WSL.

Setting up Docker and getting the toolchain image working might seem like a bit of a hassle, but it should still be less work overall than building or installing all the tools from scratch, and the goal is to get you running development tools smoothly and reliably as quickly as possible.

Note that the Docker toolchain only really supplies command-line utilities. GUI applications like IDE (code editor), retro console emulator, image editing tool and sound creation tool all need to be downloaded manually for your operating system – see below.

Installing Docker​

  1. Download and install Docker for desktop: https://www.docker.com/products/docker-desktop/
  2. Run the Docker application, accept the terms, skip registration / login and wait for Docker to finish starting up (the whale icon in the notification bar will stop animating)
  3. Open a Terminal on your computer and type docker pull retcon85/toolchain-sms. Wait for this to finish.
  4. Use the cd (and if necessary mkdir) command(s) to change to a folder you want to be the root of your Retcon projects. e.g. you could make a retcon folder inside your projects folder. Make sure you are in that folder before running the next instruction.
  5. Run the following command to register the special sms function on your shell:
echo "export RETCON_HOME=$(pwd)" >> ~/.zshrc && \
docker run --rm retcon85/toolchain-sms -c 'cat zsh-function' >> ~/.zshrc

  1. Close your Terminal and open a new one.

  2. Test your new sms tool works, by running sms sdcc -v in the new Terminal. You should see something similar to this if successful:

    SDCC : mcs51/z80/z180/r2k/r2ka/r3ka/sm83/tlcs90/ez80_z80/z80n/ds390/TININative/ds400/hc08/s08/stm8/pdk13/pdk14/pdk15/mos6502 4.2.0 #13081 (Linux)
    published under GNU General Public License (GPL)

    If not, ask for help.

Installing Visual Studio Code​

You may have wondered how software code gets written – does it need some special magic software, or is it as easy as writing a document in a notepad application?

The answer is, surprisingly: both.

In most cases you can write software using a plain text editor, since most software source files are simply plain text.

However, writing code is a sufficiently technical task that it becomes much easier when you have more advanced tools at your disposal than just the free note taking apps that come with your operating system.

There are some "advanced" text editors out there, like Sublime, or Notepad++, which software developers something use but (in our humble opinion) the ultimate development experience is to be found in the so-called Integrated Development Environments (or IDEs). Examples of popular IDEs include Microsoft's premium Visual Studio, IntelliJ IDEA and family, the open source Eclipse Project and the open source Visual Studio Code project.

It's the last of these which we recommend getting started with, as it's the IDE of choice for a huge number of developers and software companies, it has a huge marketplace of add-on functionality, it is under continuous development and supported by a big company (Microsoft) with updates coming thick and fast, and best of all it's totally FREE!

Installing Visual Studio Code is super easy: just go to https://code.visualstudio.com and follow the instructions specific to your operating system.

After you've installed it, you might want to familiarise yourself with its features, but essentially it's a glorified text editor which is highly configurable. You might want to install the following plugins straight away, by searching on the "Marketplace" section (click the button on the left hand toolbar which looks like four squares with the top right square slightly offset):

  • Hex Editor with Tags – useful for looking at ROMs you are building or want to hack
  • C/C++ – useful when it comes to writing and editing the source files in this tutorial
  • C/C++ Extension Pack – ditto
  • C/C++ Themes – ditto
  • WLA-DX for VSCode – not so useful for this tutorial, but a must-have if you want to write assembler in WLA-DX
  • Z80 Assembly – probably not necessary if you're using WLA-DX and have the above plugin, but can't hurt to have
  • Emulicious Debugger – not explained in this tutorial, but might be useful one day for you
  • Quit Control for VSCode – invaluable if, like me, you find yourself accidentally closing VSCode more than you'd like :)

It's really easy to change settings in VSCode but there are so many of them it will make your head spin. If you open the Settings screen you'll find you can search for whatever settings you can think of and chances are someone will have thought of it and built it. You can change settings globally, on a per workspace basis (i.e. according to what project folder you have open) and, with a little more effort, you can also change settings based on what type of file you have open.

One setting that is part of my DNA now is the "auto-save" feature and I have it set to save my files whenever I change focus away from VS Code which has saved my bacon more times than I care to relate. It's not for everyone, but I swear by it.

Installing Emulicious​

Writing a program for a retro console, building a ROM, flashing it to a real hardware device and sticking it into your console only to find that you've made a silly mistake and it doesn't work is no kind of sensible workflow. What's more if you're not sure exactly what's wrong with your program, tracking down the bug can be a painstaking process to say the least.

Much more economical in terms of your time is to use a console emulator, which runs on the same computer as you're writing code with, to rapidly test and debug your program.

Of the many emulators out there for the Master System, Emulicious is hands down and without a doubt the best, in terms of accuracy and developer tools. It also emulates the Game Gear (which, after all, is almost the same as the Master System), MSX (which is a close cousin), and the Nintendo Game Boy and Game Boy Color (which are distant relatives).

If you're using a different emulator for Master System, our candid advice: stop.

Install instructions (should work for any OS)​

  1. Download and install Emulicious. This will allow you to play the games you write:
  • Go to https://emulicious.net/downloads/ and download Emulicious with 64 bit for Java to somewhere temporary (e.g. your Desktop folder)
  • Unzip the Emulicious-with-Java64.zip file
  • Create a new folder called Emulicious inside your Applications folder
  • Copy all of the files from inside the unzipped folder into the Emulicious folder you just created
  • Double-click the Emulicious.jar file to run it. It will probably say that you can't because it's not trusted...
  • ... so open System Preferences and select Security & Privacy, and select the "Open Anyway" button. This will trust the file in future.
  1. Emulicious should now be open. Change some basic settings:
  • File > Reload ROM On Change – turn ON
  • Options > Graphics > 4X Size – turn ON
  • Options > Emulation > Master System > Hide Borders – turn OFF

🎉🎉🎉 YOU HAVE NOW INSTALLED ALL THE TOOLS YOU NEED TO BUILD AND RUN GAMES 🎉🎉🎉

You might also want to install the tools below, or their alternatives, so you can design your own game assets.

Installing Aseprite / Libresprite​

We just love Aseprite for retro art design. It's designed specifically for pixel art and has some really neat features for both still images and animation that make it a joy to work with.

The downside: it's not open source software and it costs $20 to download an official installer. Personally we think it's $20 well worth paying and it goes directly to the developer who almost certainly deserves your support!

On the other hand, if you don't feel like stumping up, there are three other options:

  1. You can build Aseprite from source. If it's for personal use, this is permitted by the end user license agreement, although it's a bit of a hassle.
  2. You can download the free and open source Libresprite which was forked from Asesprite while it was still open source.
  3. You could use some other free software, like GIMP which is free and very capable, if not really designed for retro game art.

Installing the Furnace tracker​

If you want to create some sound effects or music for your game, one of the most popular ways to do so is using a piece of software called a tracker and the tracker "du jour" at the time of writing is Furnace.

You should be able to download the latest version of Furnace for your operating system from the link above.