Using Beebasm for BBC Basic games programming (Mac & Windows)

on
In August 2021, I released Androidz Redux, a remastered version of my 1994 game Androidz. This process started a year ago, with a couple of days spent playing around with the original code, far away from a real BBC computer.

The original game was published in a magazine called Acorn Computing, and has been available to play online for a number of years now.

Because I wrote the game on an actual BBC Micro, I used what tools I had at the time, namely some graph paper to create the graphics, and the computer itself to do the actual coding. This is a world away from the tools we now have at our disposal. Fully rounded IDE's such as Visual Studio Code (my current favourite) make it an awful lot easier to program games. Even editors such as Notepad++ offers some ability to edit BBC Basic code.

One of the difficulties with editing old games on modern systems is ensuring that you are able to ensure that the BASIC code is properly tokenised before running on an emulator/system, and indeed, being able to prepare the 'virtual' disc images in order to load them into such systems.

Enter the tool Beebasm. This repo not only helps to assemble 6502 code, but it can also be used to create disc images containing the code. It is run as a command line utility, and can therefore work on various platforms. Despite its name however, Beebasm can also be used with BBC Basic programs. A few more steps are required, but otherwise it works.

This posting will attempt to outline how you can use Beebasm as part of an overall toolkit for creating bootable discs for the BBC Micro, or equivalent emulators.

Notably, the Windows platform offers an easier learning curve for these tools. As my primary platform is Mac OS, Apple's recent move to 64-bit versions of its operating system has rendered some of the original Mac versions of these tools obsolete. So you have to jump through a few more hoops to not only get Beebasm to run, but some of the Mac based emulators need to be built on your system in order to run.

Whichever platform you use, I would highly recommend installing Microsoft's Visual Studio Code. It's a great editor, and allows you to create a workspace, with which you can customise your editing environment for your project folder. And with its integrated Terminal functionality, you can run command line tools with ease within the software's editing interface.

Mac OS Tooling environment

  1. Head over to the Beebasm Github repo at Github.
  2. If you are familiar with Git, you can clone the repo to your local computer. Otherwise, you can simply download the zipfile to your computer, and unpack it wherever you wish.
  3. Open VS Code, and open the BeebAsm folder.
  4. Download and install the Beeb VSC extension for VS Code. This will help us add syntax highlighting to our code.
  5. We now need to build BeebAsm itself. Using the VS Code terminal, navigate to the folder containing the file 'Makefile' and enter the command make code.
  6. If you get an error message, the most likely cause is that you don't have GCC installed. There are a variety of solutions to this. You can either obtain Apple's Command Line developer tools, or you can install Homebrew. Either way, you should be able to then build the executable with the previous command.
  7. Now you have the tooling, you now need a decent BBC Micro emulator. There are a few choices available. I am currently using Tom Seddon's b2 emulator, for which installers exist for Mac OS, or you can clone the repo and build yourself.

Windows Tooling environment

Much of the tooling for BBC Micro games development has been on the MS Windows platform for years, and is therefore pretty well established.

Much of the steps for the Mac OS tooling are the same for windows. The key differences occur from step 6, if step 5 fails. The Beebasm repo suggests that you will need the MinGW and most basic subset of Cygwin, which provides Windows versions of the common Unix commands.

Once this tooling is installed, then the make code command should build Beebasm in your current folder.

Tom Seddon's b2 emulator is also available on the Windows platform.

Building our sample project

    We now have the means to build and run our project. But we need a project! Let's do something nice and simple, the standard 'Hello World!' program.

    In VS Code, create a new file, called Hello.bas. The .bas extension can also be .txt, but if you ever intend to push your work to Github, for example, they recognise the .bas extension as Basic code.

    Enter the following code (normally, BASIC code on the BBC Micro requires line numbers. However, beebasm adds them automatically, so we don't need them):

    REM Hello World program
    MODE 2: REM 16 colour low resolution screen
    VDU 23;8202;0;0;0;: REM turn off flashing cursor
    PRINTTAB(4,15)"Hello World!"
    REPEAT
    VDU 19,0,RND(6),0,0,0: REM change background colour to a value between 0 and 6
    TIME=0:REPEAT UNTIL TIME=150: REM wait 150 centiseconds
    UNTIL FALSE
    END

    For the uninitiated, this program prints the text in the middle of a low resolution screen (the VDU 23 command turns off the flashing cursor), and changes the background colour (the VDU 19 command) at random every 150 centiseconds.

    Hello World - our sample project.

    Amazing stuff.

    Save the file into your project folder.

    Now, create a new file, called Boot.txt. Enter the following code:

    *BASIC
    PAGE=&1900
    *FX21
    CLOSE#0:CHAIN "HELLO"

    This 'boot' file allows us to auto run the disc image in our emulator, opening the Hello World program.

    Save the boot file.

    We currently have two files in our project, Hello.bas and Boot.txt.

    Beebasm requires a build file, with an .asm file extension in order to build your disc image. Create another new file, Hello.asm, and enter the following:

    PUTBASIC "Hello.bas","HELLO"
    PUTTEXT "Boot.txt", "!BOOT",&FFFF

    Beebasm needs to know what files to input, what to save them as, and in the case of the boot file, the start memory location. We also need to use the correct PUT* command for each file. BASIC files need PUTBASIC, while boot files are treated as text, which require the use of PUTTEXT.

    With this file saved, we now have 3 files in our project - Hello.bas, Boot.txt and now Hello.asm

    We can now create the disc image using Beebasm. Opening your terminal, enter the following command:

    beebasm -i Hello.asm -do Hello.ssd -opt 3 -title HelloW

    This command needs breaking down:
    • -i Hello.asm - this is the input argument, in this case, Hello.asm being the file.
    • -do Hello.ssd - this argument outputs the disc image we need for our emulator, in this case, Hello.ssd (ssd stands for single sided disc, you can replace this with dsd for double sided disc, but I've never had the need to create one)
    • -opt 3 - this argument ensures that the disc image is auto bootable.
    • -title HelloW - this last argument gives a name to the disc. This usually only appears if you type *CAT (or the shorthand - *.) in your emulator, which lists the disc contents - the disc title is one of the first items to be output.
    Press Enter, and some output will appear. You should now see a newly created disc image, called Hello.ssd. This is effectively our BBC floppy disc to load into our emulator.

    Open b2, and from the menu, select File > Run > Disc image... Locate your Hello.ssd image, and click Open. The emulator will then autoboot the disc, and within moments, you will see the Hello World program displayed.

    Using VS Code's Tasks feature to build and test your image

    The Tasks feature was something I was unaware of. It was thanks to Stardot user 'VectorEyes' that I became aware of it, and it is very useful.

    Check out VectorEyes' posting on the Stardot forum for more detail. The tasks.json file referenced there can be used in this project.

    Before going further, the Beebasm command from earlier needs putting in it's own file. Create a new file called build.sh, and paste in the Beebasm command from earlier:

    beebasm -i Hello.asm -do Hello.ssd -opt 3 -title HelloW

    We can now refer to this command via a keyboard shortcut, which is much more streamlined.

    In addition to the build task, we can create a task for testing a build. For this, we can set this task to open our emulator, and boot the disc file.

    Create a new file, called testinb2.sh, and enter the following:

    /Applications/b2.app/Contents/MacOS/b2 -b -0 /<<PATH>>Hello.ssd

    Change <<PATH>> for the path to your disc image. For the Windows platform, you would need to create a batch file (.bat), with similar commands.

    With everything set up, you can use the keyboard shortcuts within VS Code to run these two tasks, making it much easier to build and test disc images.

    Acknowledgements

    I hope that this article will prove useful to others who may be keen on pursuing retro coding on the BBC Micro, but didn't know where to start in programming and building distributable discs.

    I'd like to give thanks to the following individuals for their indirect help in preparing this article:
    • VectorEyes
    • tom_seddon
    • julie_m
    • tricky
    • SteveF
    For added context, the following threads on Stardot give added insight into the origination of this article:
    I suspect I may have skipped over some important details, or have misunderstood one or two key concepts. Do feel free to comment below, and I'll correct where required.

    Thanks for reading!

    Comments

    Post a Comment