Skip to main content

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

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!
    Labels:

    Comments

    Post a Comment

    Popular posts from this blog

    Polymer Picker, and why 8-bit programming matters to me

    Late last year, I released a BBC Micro game, Polymer Picker . Realising that 2022 marked the centenary of the BBC, as well as the 40th anniversary of the release of the BBC computer (which was designated as one of the BBC's 100 Objects ), I wanted to work on something that related to the BBC's mission of being able to 'educate, inform and entertain' . So what better way than to release a game for the BBC computer, that in a sense, fulfils those values? But, with video games being so widely available, and playable on all kinds of devices, why did I decide to create my own game for such a niche platform?  Video games are big business. They have been for a number of years. In May 2023, it was reported that Nintendo's latest edition of The Legend of Zelda sold in excess of 10 million copies in three days .  However, there remains sustained interest in video games from yesteryear. Children who grew up in the 8-bit computer revolution are now into their 40s and 50s, and
    Post a Comment
    Read more

    Rough guide to building UK election maps for D3.js

    During my time at CITY A.M. I helped to build an interactive British General Election Map . This blog outlines how I created it. Let's see the map then Here's a simplified version of the map, hosted at Codepen. See the Pen D3 Election Map by Stephen Scott ( @sassquad ) on CodePen . Here, the map looks rather small, as it has been resized to fit the page. You can use your mouse wheel (or double-click/double-tap) to zoom in or out of the map, and click constituencies to view more detailed results on the left hand side. Each constituency is coloured according to party livery. This blog post gives a very general guide as to how that map was created. I'll be adding further detail about the creation of the map in subsequent posts. Acknowledgements This project was the work of several people, in addition to myself. Here are the other former colleagues who collectively made the election map possible: Michael King (back end programming of data capture system) Bill
    Post a Comment
    Read more