In last November’s Digest, we started a project to dissect the classic C64 title Crossroads, published by Compute!’s Gazette magazine in December 1987. We got a handle on how the game works by playing it, and by inspecting the running game state in Retro Debugger, a C64 emulator with memory visualization features. In this issue, we’ll get up close and personal with the Crossroads machine code, using a tool called a disassembler. Combined with what we’ve learned, and some world knowledge of Commodore programs, we can begin to produce human-readable assembly language source code for the game.

Crossroads was so popular that Compute! commissioned a sequel, Crossroads II: Pandemonium, which was published in December 1988. I did some searching to see if anyone has disassembled the Crossroads games already, and discovered an excellent disassembly of Crossroads II by Github user hyphz. For the sake of the exercise, I did not look closely at this disassembly at first, but I do expect the original Crossroads to be similar in many ways.

We won’t do a full disassembly of Crossroads in a single newsletter, but we’ll answer some of the most important questions. Before we do that, let’s see what everyone else is up to!

PET core pre-release

Olaf “Rhialto” Seibert is working on a Commodore PET core for the MEGA65, and has invited everyone to help test a pre-release version. The Filehost download includes core builds for R3 and R6 boards, and a copy of the necessary ROM files that you install on the SD card in a folder named pet/.

Do keep in mind that this is a pre-release and may be missing features. Check out the Commodore PET core on Github to see source files and file bugs. Many thanks to Rhialto for this exciting project!

Gaplus arcade core

muse continues to deliver arcade core goodness! This month, it’s Gaplus, the third game in the Galaga series from Namco. As usual, you will need to download the Gaplus core, locate MAME ROMs on the Internet, then follow the set-up instructions to produce the files for the SD card. The Gaplus core is available for both R3 and R6 mainboards.

I encountered an issue with the R6 version when using HDMI video where after a few seconds the game video becomes a static screen of vertical bars. This does not occur over VGA, or with the version for the R3 mainboard. A fix is in progress.

Goodwell’s QR code generator

Goodwell, aka The 8 Bit Theory on YouTube, recently attempted an experiment to write a QR code generator for multiple vintage Commodore computers in multiple languages, including BASIC 2, BASIC 7, C, 6502 assembly language—and BASIC 65 for the MEGA65. The video about the experience discusses implementation techniques and performance characteristics of these implementations. Definitely check it out, it’s worth watching the whole thing.

Goodwell uploaded the MEGA65 version to Filehost, and is continuing to refine it. It might even get added to the MEGA65 Intro Disk menu system, to make it easier to share URLs in the menu text. The Github repo for the QR code generator has all of the versions of the experiment, as source code.

Don’t miss Goodwell’s follow-up video about the MEGA65’s technical design, based on his early experiences developing for the computer.

MegaMage by SirGeldi

Hot off the presses! SirGeldi on Forum64.de has posted MEGAMage, a Roguelike adventure game written entirely in BASIC. Adorable character graphics and fast map scrolling enhance the gameplay. Even better, SirGeldi built the tools used to develop the graphics, map, and object and monster metadata for the game on the MEGA65 in BASIC, and has included these tools on the disk!

Download the .zip file from SirGeldi’s message post, unpack it, and transfer the D81 disk image to your MEGA65. To start the game, mount the disk image, then:

RUN "MEGAMAGE"

Even more Featured Files!

Soccer, by SirLazarus, is a new soccer-themed paddle game. It is written in BASIC, and requires the latest ROM beta version 920409 because it uses recently added features. (This ROM update will be included in the next stable release package.) Grab your paddle controllers and check it out!

Jotto 2020, by ToneDeF, is a word puzzle game similar to Mastermind. It plays something like Wordle, though its invention pre-dates Wordle by a year. ToneDeF originally wrote this for other micros, and made this new version for the MEGA65 in BASIC.

Pac-man in BASIC demo, by xlar54. This playable demo sports many features of the arcade classic, including music, sound, and polished graphics. xlar insists this is just a demo, but only a few features are missing (most notably power pellets). And yes, this too is implemented entirely in BASIC 65.

Opal Dance, by lochmana, is a colorful puzzle and maze game. Match colored pieces by walking into them, but think before you move! Each match of two pieces replaces the first piece with a wall, and removes the second piece. Clear as much of the level as you can.

Mega65 Perpetual Calendar, by gcastel (MiddleAgedCoder on Discord). Generate calendars for any month of any year. Developed for BASIC 65 with Eleven, you can get the source code from Github.

Xemu keyboard layout reference for Windows, by Discord user Digger. Windows users, keep this handy app open alongside the Xemu emulator to remember how to replicate MEGA65 keystrokes on the PC keyboard. See also the project homepage (in German), and the README file (in English) included with the download.

mouSTer back in stock

mouSTer, the USB-to-Commodore DB9 adapter for modern USB mice and game controllers, is back in stock after a long hiatus. This is one of the best ways to use a modern USB mouse with the MEGA65. It even works with wireless mice that use USB dongles. Get one while you can!

See RetroHax’s update from December 30, 2024 for details.

Digest administrative note

I am considering migrating the Digest to a new email newsletter service. As Substack evolves their business model and practices, I want to make sure the Digest is hosted on services that remain open and compatible with the values of the MEGA65 project. I’ll let everyone know in advance before I make changes.

The change should be fully automatic, including migrating donations made through the Substack interface as paid subscriptions. Hopefully I can migrate the read-aloud podcast feed URL automatically as well, but this will depend on how your podcast app is subscribed. I’ll try to figure it out and let you know. If anyone has any feedback on this change, please let me know. I know a couple of you are using the Substack app to read it, which should be the only case affected by a migration.

You can always find all issues of the Digest on my website and subscribe to it using an RSS feed reader. You can also become a patron of the Digest at ko-fi.com/dddaaannn.

The art of disassembly

A quick recap: A computer’s CPU performs instructions encoded as bytes in the computer’s memory. This machine code is difficult to work with as a list of numbers, so when we humans want to write a program, we use a programming language, and a tool that converts that language to machine code for the computer to execute. Assembly language is a human language that most closely resembles the machine code, with human-readable names for each machine code instruction. The corresponding conversion tool is called an assembler.

There’s a simple assembler built into the MEGA65’s machine language monitor. You can start the monitor by entering the MONITOR command at the READY prompt. Try doing this now, and use the A command to assemble this short program:

MONITOR
A1600 LDA #$01
STA $D020
LDA #$00
STA $D021
RTS

After the last line, press Return on a line by itself to stop the assembler.

As you type each line, the monitor converts the instruction to the corresponding machine code. It stores the machine code at the requested address in memory, and also prints the address and machine code bytes to the screen, as hexadecimal values.

A 1600  A9 01     LDA  #$01
A 1602  8D 20 D0  STA  $D020
A 1605  A9 00     LDA  #$00
A 1607  8D 21 D0  STA  $D021
A 160A  60        RTS

The monitor can also reverse this process, to show you which instructions are represented by bytes in memory. This process is known as disassembly. Use the D command followed by the address:

D1600

Sure enough, the program you just entered is right where you put it, at address $1600. There’s also a bunch of other stuff after the last instruction you typed starting at address $160B, maybe garbage data or something left behind by another program. These bytes may or may not represent machine code instructions, but the disassembler diligently tries to interpret them as instructions either way. These instructions are what the CPU would perform if you told it to treat that memory as code.

The number of bytes used to encode an instruction differs depending on the instruction. Some instructions, like RTS, are encoded as a single byte. Others, like LDA #$01, use two bytes. Still others such as STA $D020 require three bytes. Anything trying to interpret bytes as machine code—whether that’s a disassembler or the CPU itself—needs to know the address of the first byte of the first instruction, or it could get very confused.

Try using the disassemble (D) command again, this time with a starting address of $1601:

D1601

The monitor tries to disassemble some of the memory of the program you entered, but the result looks nothing like the program. $1601 is the address of the second byte of the LDA instruction, $01, which to the disassembler (and the CPU) looks like a version of the ORA instruction that uses two bytes. At address $1603, the next byte $20 looks like a three-byte JSR instruction. Coincidentally, the next incorrect instruction gets the disassembler back on track, aligned with the correct first instruction byte at address $1607. But by now, a CPU trying to execute this code will get very lost, and probably crash.

Disassemblers are not magic, and they need help from the operator—that’s you—to convert machine code back into human-readable assembly language. The disassembly process requires research, maybe some guessing and checking, taking notes, and labeling addresses and values once you’ve figured out what they mean. A modern disassembly tool can make this process surprisingly easy.

Introducing Ghidra

Ghidra is a powerful disassembler and reverse engineering multi-tool. It supports many types of CPU machine code, including the 6502, and supports extensions to add more. Ghidra was originally developed by the United States National Security Agency (NSA), and has been released as open source and free of cost.

I want to credit two YouTube videos on the topic of using Ghidra for reverse engineering Commodore 64 programs: Introduction to Ghidra by David Youd, and How to start a new C64 project in Ghidra by Jarkko Lehti. These are worth watching when you get a chance, and we’ll be using Lehti’s configuration files in a moment.

Setting up Ghidra

As of this writing, the latest version of Ghidra is v11.2.1. It’s a Java-based application, and it requires a recent version of the Java runtime (21 or later), which you may need to install or upgrade. Ghidra will tell you if your Java is too old. Properly installed, Windows users can double-click on ghidraRun.bat to start the program, and macOS and Linux users invoke the ghidraRun shell script.

As usual, macOS will refuse to run the scripts and tools until you have blessed them in the Privacy & Security panel. You probably know the drill by now. Attempt to start ghidraRun, dismiss the complaint, open macOS Settings: Privacy & Security, scroll down, click Open Anyway. If you use Ghidra for other stuff later, you’ll need to similarly bless some internal components, which you can do in the Terminal app on the command line:

xattr -cr ./Ghidra/Features/FileFormats/os/mac_arm_64/lzfse
xattr -cr ./Ghidra/Features/Decompiler/os/mac_arm_64/decompile
xattr -cr ./Ghidra/Features/Decompiler/os/mac_arm_64/sleigh
xattr -cr ./GPL/DemanglerGnu/os/mac_arm_64/demangler_gnu_v2_*

When you run Ghidra for the first time, it will ask for the path to the Java home directory. This will depend on your operating system. On macOS using Java 23 from Oracle, the path is:

/Library/Java/JavaVirtualMachines/jdk-23.jdk/Contents/Home

Ghidra opens its main window, from which you create or select a project, and open tools.

Creating the project

Let’s start a new project using the crossroads.prg file that we extracted from the disk image in last month’s Digest.

Create a new project:

1. Open the File menu, select New Project.

2. Select “Non-Shared Project,” click Next.

3. Create a new folder for the project, and select it. Enter a project name, such as “Crossroads.” Click Finish. The dialog window closes, and the project is created.

Next, import the crossroads.prg file:

1. Open the File menu, select Import File.

2. Navigate to the file crossroads.prg, then Select File To Import.

3. Leave the Format set to “Raw Binary.”

4. Click the ... button next to Language. Select “6502,” which is at the top of the list for this version of Ghidra. Click OK.

5. Leave everything else at default settings, then click OK. Another window opens with some information about the file. Dismiss this with OK.

Finally, double-click on the crossroads.prg file in the project to open it in the CodeBrowser tool. The first time you do this, Ghidra will offer to analyze the file. Say Yes. Leave the default set of analyzers selected, then click Analyze. The analysis doesn’t produce spectacular results just yet, but it’s usually worth doing.

Here is crossroads.prg in all its glory, in the CodeBrowser window. These are the same bytes we saw in the hex dump, but now they’re listed one per line. We will use this interface to massage the data as we learn what each part of it means.

Commenting the code

Let’s start by telling Ghidra the C64 memory address where this data gets loaded. Because this is a PRG file, it begins with two bytes that are not loaded into memory. We could have gone through an extra step to remove these bytes before importing the data, but for our purposes, it’s enough to just take these into account when telling Ghidra where everything lives.

This data gets loaded into a single block of memory that starts at address $0801. Minus the two PRG header bytes, we can tell Ghidra to start counting addresses at $07FF:

1. In the Window menu of the CodeBrowser window, select Memory Map. The Memory Map window opens, showing one “RAM” segment that starts at address 0000.

2. Select the “RAM” line, then locate the button whose tooltip reads “Move a block to another address,” a blue arrow-cross icon.

3. For the New Start Address, type 07ff. Click OK.

4. Close the Memory Map window.

Notice that the data is now lined up with the memory addresses. The first byte of the BASIC bootstrap is at $0801, and the two-byte end-of-BASIC terminator is at $080B. (We peeked at this in the previous Digest.)

Let’s add a comment describing this data. Right-click on the line for $0801 to open the context menu. Select Comments > Set EOL Comment… In the window that opens, type a useful description, such as: “Start of BASIC bootstrap.” You may wish to add a similar comment on $080C, for “End of BASIC bootstrap.”

Initiating disassembly

The BASIC bootstrap uses the SYS command to invoke machine code starting at decimal address 2300. Ghidra even shows the “2300” characters next to the byte listing, guessing that we might be interested in what these look like as ASCII characters. In hexadecimal, this address is $08FC.

Navigate to this address in the byte listing. Here’s a quick way: press “G” (for “go”), then enter the address in hexadecimal (08fc).

Start the disassembly at this address: press “D” (for “disassemble”).

Ghidra has just done a bunch of work for us! It took our word for it that the bytes starting at $08fc are machine code: $a9 $ff represent the LDA #$ff instruction, which Ghidra spells LDA #0xff, and updated the code listing accordingly. It proceeded to the next instruction, and kept going as long as it was reasonably certain that the CPU would treat those bytes as instructions as it executed.

Scroll down, and notice that Ghidra stopped disassembly at address $0cab, where it found an RTS instruction. The bytes starting at $0cac may be more CPU instructions, but Ghidra doesn’t know this for sure. In fact, we can see evidence that it may be data and not instructions: the bytes from $0cb1 to $0cba spell out “CROSSROADS” in ASCII. Ghidra doesn’t know this is more likely to be PETSCII and not ASCII, but it displays the ASCII letters for our benefit, just in case.

Keep scrolling, down to $0dc5. Ghidra found more code! Starting with the first address we gave it, Ghidra decoded each instruction, and when it found a branching instruction or subroutine call, it continued disassembly at that location, filling everything in. It assigned some temporary labels for things that look like functions, such as FUN_0dc5. As we try to understand what the program does, we can replace these labels with more intuitive names. In the end, we’ll have a fully human-readable assembly language program. (Or as human readable as assembly language gets, anyway.)

Ghidra made similar attempts to highlight data locations referenced in the code, assigning labels such as DAT_08b0. Everything referenced by something else is annotated with the cross references. For example, the byte at address $08b0 is read by an instruction at address $0a7a, so it lists 0a7a(R) (“R” for “read”) next to $08b0.

We can add our own labels. Let’s do this for our entry point, $08fc:

1. Press “G” for go. Enter 08fc.

2. Press “L” for label. Enter a label name of start. Because this is the entry point of the program, select the “Entry Point” property. Click OK.

Importing C64 symbols

Ghidra has invented labels for all of the data and code referenced by the disassembled code. The addresses within the imported data range have blue labels and cross references.

Where the code references an address not in the imported range, Ghidra also generated a label, and colored it red. Consider the first few instructions of the program, starting at $08fc:

LDA #0xff
STA DAT_d40e
STA DAT_d40f

This loads $ff into the accumulator, and stores that value to addresses $d40e and $d40f. If these were just memory locations, we would assume that these are variables used by the game for storing game state, like the player’s position. In this case, we can apply some knowledge of how the Commodore 64 works: addresses in the range $d000-$dfff are input-output registers that control, or are controlled by, the computer’s hardware. We can look up what these registers do in a Commodore 64 technical reference.

In this case, these registers belong to the SID sound chip, specifically the frequency of the oscillator on voice #3. We don’t yet know why the program does this, but we do know that’s what it does. The next two instructions and a bit more knowledge of C64 programming gives us a hint:

LDA #0x80
STA DAT_d412

The technical reference says $d412 is the SID voice #3 control register. Setting bit 7 like this tells it to use the “noise” waveform. Crossroads is certainly a noisy game, but it’s probably setting this up to use as a random number generator, or at least a seed for one. We’ll have to keep our eye out for something that samples a value from voice #3.

Now that we’ve identified DAT_d40e et al., we could update the labels to something that describes their functions. To do this, you would right-click on the label and select Edit Label… (or move the cursor onto the label and press “L”).

Considering that the C64 I/O registers always do the same thing in every program, it would be nice if Ghidra could automatically recognize all of them and give them useful names. The following is one way to do this, based on the files supplied by Jarkko Lehti to accompany his YouTube video on the subject.

Download these C64 symbol files:

• IO.txt: the I/O registers

• KERNAL.txt: the KERNAL jump table subroutines

• RAM.txt: commonly used C64 internal KERNAL variables

• IO_d000.bin: a binary snapshot of the initial values of C64 I/O registers

• kernal_e000.bin: a binary snapshot of the C64 KERNAL

The .txt files tell Ghidra to apply certain labels to certain addresses when they appear in the code. The .bin files fill in the memory ranges themselves in the Ghidra project, so you can get some idea of what’s actually there in the C64’s memory.

In your project, the IO and KERNAL data will exist as overlays. An overlay is a portion of memory that may contain different things at different times, based on system state. With the Commodore 64, I/O registers and KERNAL ROM occupy addresses that can also refer to RAM, based on the memory banking register. Ghidra can only see that an instruction accesses an address, not the memory map of the computer at the time the instruction is called. Telling Ghidra that these memory regions are overlays accounts for the possibility that a given reference to an address may refer either to I/O and ROM, or the underlying RAM.

To create the IO overlay:

1. From the CodeBrowser window, open the File menu, Add To Program…

2. Select IO_d000.bin, click Add To Program.

3. In the Add To Program dialog, click Options… Select Overlay, use a Block Name of IO, and set the Base Address to d000. Click OK in the Options dialog, then click OK in the Add To Program dialog. Dismiss the Import Results window.

To create the KERNAL overlay, repeat these steps with the kernal_e000.bin file, using a Block Name of KERNAL and a Base Address of e000.

Now we can import the symbols that describe addresses in these regions. Ghidra is a highly scriptable application environment, and we can use a script that comes with Ghidra to import the .txt symbols files.

To import the symbols:

1. From the Window menu, select Script Manager.

2. Scroll down to find ImportSymbolsScript.py. Double-click it to run it.

3. When prompted, select the IO.txt file. Click “Go baby go!”

4. Repeat these steps for the KERNAL.txt file, and again for the RAM.txt file.

Ghidra now knows about the I/O registers via an overlay with sensibly named symbols. Ghidra still doesn’t know which references refer to RAM and which refer to I/O. We have to tell it.

Go (“G”) back to the STA instruction at $08fe. Its destination is still the red symbol DAT_d40e. Click on it, then press “R” to edit the reference. In the pop-up window, double-click the reference, then change the dropdown menu that says “RAM:” to “IO:”. Click Update, and close the reference editor. The symbol has changed to D40E_FRQ_3_LO. That’s… better.

It’s unusual for a C64 game to un-bank the I/O registers, so it’s a little inconvenient that each label needs to be applied like this. I haven’t found a good way to automatically declare all references to be for the IO overlay. One possibility might be to add IO_d000.bin as a non-overlay region, then edit the IO.txt symbols file to remove the IO:: part of each address. For now, I like keeping IO as an overlay, because it accurately describes how the C64 works.

I did find a reasonably fast way to update all of the labels manually using Ghidra’s search feature. In the Search menu, select Program Text… Prepare a search for DAT_d in All Fields of the Listing Display, and click Search All. A window opens with the search results, and clicking on a result causes the Listing display to jump to that location. I got 38 results, and it only took me a few minutes to update all of the references to use the IO labels. It’s not the most fun I’ve ever had with a computer, but it didn’t take so long that I regretted not automating it.

Getting some answers

Now that we have at least some idea of what we’re looking at, let’s try to answer a few questions that will help us understand how Crossroads works. These are just questions that occurred to me, in the order I thought to ask them. They may not be the best questions, or in the best order. But let’s see what happens.

Does the program call the KERNAL jump table?

This is an easy one. A call to the KERNAL jump table would look like a JSR to a hexadecimal address beginning with an f. Ghidra will have generated a label like FUN_ffd2 prior to me updating it to use the KERNAL overlay’s symbols, so just like we used a search of DAT_d to find I/O register references, we can search for FUN_f to find calls to KERNAL routines. I get no results from this search, so I’m fairly confident that Crossroads does not call KERNAL routines. Alas, we don’t get to use our KERNAL overlay. Maybe next time.

Does the program use KERNAL vectors?

As we’ve discussed in previous issues of the Digest, most games drive their game loop using CPU interrupts. There are two ways to set up an interrupt handler: replace the KERNAL’s interrupt handlers in $fffa-$ffff, or use a KERNAL vector to add a custom subroutine to the KERNAL’s interrupt handler. Let’s check the latter option first, because it’s more common for simple C64 games.

The designers of the Commodore ROM wanted people to use the VECTOR KERNAL call to read and update the KERNAL vector table, and that’s still a best practice for MEGA65 programs. Even early on, C64 programmers skipped over that part of the manual, and just wrote to the C64 vector table at $0314-$0333. We can search for the string 0314 to find any direct references to the IRQ vector.

Yup, there it is. The instructions at $0ba8-$0bb1 are writing address $11c4 to the KERNAL IRQ vector $0314-$0315.

LDA #0xc4
STA 0314_IRQ_VECTOR_LO
LDA #0x11
STA 0315_IRQ_VECTOR_HI

This appears to be the only vector touched, and it is only set in this one location in the code that Ghidra has disassembled. Let’s go to the address being written to the vector and check it out: “G”, then 11c4.

Hoo boy, Ghidra hasn’t disassembled this yet! This is because the main routine, which sets up the game and installs the IRQ vector, doesn’t actually call the IRQ handler directly. We have a bit more work to do. Press “D” to start disassembly from this address. Also, press “L” to add an entry point label, with a name such as irq.

We’ll have to re-do our searches for I/O register labels and KERNAL calls now that we have more disassembled code. That’s just how it goes. I found 8 more I/O registers, but still no KERNAL calls.

Does the program do any C64 CPU bank switching?

I mentioned that most games leave I/O registers banked to $d000-$dfff, the initial state of the C64. We can double-check that by looking for references to the C64 bank switching register, address $0001.

A search for DAT_0001 does produce two results in the start-up routine, so it’s worth taking a closer look. Starting at address $09f9, the routine sets this to $73, or binary %01110011. According to C64 technical documentation, this setting makes sure the C64 character ROM—the graphics data for the PETSCII font—is visible at $d000-$dfff instead of the I/O registers. It’s not that way for long, though. Just below, at address $0a10, the banking register gets set to $77, or binary %01110111, which switches the I/O registers back in.

While the character ROM is visible, a short loop copies the first 472 bytes of PETSCII graphics data to address $2000.

	LDX #0x0
LAB_09ff:
	LDA DAT_d000,X
	STA 0x2000,X
	LDA DAT_d0ec,X
	STA 0x20ec,X
	INX
	CPX #0xec
	BNE LAB_09ff

Now that we know what this does, we can rename the LAB_09ff label to something like copy_char_loop, and add explanatory comments to the bank switching instructions. We can also relabel DAT_0001 while we’re at it.

Does the program use any self-modifying code?

From our perspective as reverse engineers, one of the scariest things a program can do is modify its own code. The program is entirely within its right to do this—code is just data in memory—but it means that the disassembler may not be seeing the code in the form it is executed.

To find places where the program might be modifying itself, we have to look for attempts to store values in locations that Ghidra believes are inside subroutine code. I bet there’s a way to get Ghidra to make a list of such places, but I haven’t found one yet. I did notice, however, that Ghidra refers to such addresses by the name of the function, plus an offset, like this example near the entry point:

LDA #0x0
STA FUN_0b4a+1
LDA #0x28
STA FUN_0b4a+2

These address expressions appear in a grey color. From visual inspection, I found only a few examples of this. Thankfully, they were all short subroutines that were easy to understand, and all of the self-modifications were to addresses for LDA and STA instructions.

Several of these appear to be simple utility functions for using addresses from variables together with indirect addressing. For example, FUN_0b4a is simply the STA instruction in absolute Y-indexed addressing mode, followed by an RTS. To use this routine, the program writes an address into the STA instruction, sets the A and Y CPU registers, then calls the subroutine:

FUN_0b4a
  STA 0x0000,Y
  RTS

This probably saved the developer some headache, using a single self-modifying mechanism instead of having every subroutine modify its own instructions. The initialization routine near the entry point uses this mechanism as part of a loop to fill some memory with zeroes.

Is there any more code?

We found the entry point and the IRQ vector routine, and we identified self-modifying code and confirmed that it’s not doing something crazy like dynamically writing JMP instructions to memory at run time. It looks like Ghidra has found most of the code in the program. Are we safe to conclude that the remaining unidentified regions are static data, or perhaps initialized variable space?

This requires a bit of judgement, a bit of guesswork, and a willingness to change our minds later, but we can start to form some conclusions from a visual inspection of Ghidra’s analysis. Here’s what I see so far:

• $080d-$08fb: I see some repeating numeric patterns that are unlikely to be instructions. Ghidra found cross-references into this memory starting at $08b0, and they’re all read-only references from the initialization routine. The program must refer to some of this data with dynamically calculated addresses that Ghidra can’t see. It’s not conclusive, but with no obvious writes to this memory, this is probably static data, such as graphics patterns.

• $0cac-$0dc4: Ghidra is displaying obvious patterns in the ASCII decoding that match text displayed on the game’s screen, with strings such as “CROSSROADS” and “1PLAYER,” and many space characters ($20). There are only a few explicit read-only references. This is probably character data for the static parts of the display.

• $0f65-$11c3 and $15fe-$1693: These are less obvious to me just from staring at them. Some of it is clearly data, but I don’t yet know how to interpret patches of it. Once again, there are no explicit instructions writing to these areas.

For now at least, I feel confident that these regions are static data and not code, and that Ghidra has found all of the code in the program.

What’s in the data?

We can learn more about the suspected data regions by double-clicking on the cross-references and digging around the code that refers to them. We can also make some guesses about how the data is encoded, and try to decode it to see if we recognize any patterns, similar to how we identified text strings with Ghidra’s built-in ASCII decoding.

I’m especially interested to find the character graphics data that gives Crossroads its special flair. This is likely to take the form of monochrome character pixel data, where each byte represents a row of 8 pixels, and consecutive bytes are stacked, usually in a square of 8 rows. If we visualized the bytes in suspicious data regions this way, would the Crossroads cast of characters jump out at us?

Ghidra has extensive features for visualizing data structures. Once we have a guess as to how data should be interpreted, we can paint data types onto the bytes and see if they make sense. For example, to visualize a byte as a binary number:

1. Locate address $080f. The byte value is $44. Ghidra doesn’t know how to interpret this, so it displays a type of ??, its hex value, and its ASCII value.

2. Right-click on it to open the context menu, navigate to Data, and select the byte type. Ghidra updates ?? to db.

3. Right-click again, navigate to Data, and now select the Settings… option that has appeared now that the value has a type. Change Format to “binary” and Padding to “padded.” Click OK. Ghidra updates the visualization to a padded binary value: 01000100b.

Let’s try this for a chunk of the data region $080d-$08f9. (We can always undo it later.) Click-drag with the mouse, or move the cursor to the first line and hold Shift while cursoring down, to select lines. Use the Data context menu to make them all bytes displayed as padded binary.

083d ff    db    11111111b    ; ########
083e 8f    db    10001111b    ; #   ####
083f ff    db    11111111b    ; ########
0840 3c    db    00111100b    ;   ####
0841 7e    db    01111110b    ;  ######
0842 7e    db    01111110b    ;  ######
0843 ee    db    11101110b    ; ### ###
0844 87    db    10000111b    ; #    ###

It’s a little difficult to make out when displayed as 0’s and 1’s, but I see some familiar faces. Going eight bytes at a time, I see two frames of animation for each of an enemy missile ($080d), a bullet ($081d), the Human/player ($082d), the Purple Rubberhead ($083d), and more. I have to squint to see the rest, but if each of the nine enemies gets 16 bytes starting at $083d, it feels safe to say these are graphics tiles up to at least $08cd.

How does the program set up character graphics data?

We have a rough idea that the game keeps its graphics assets starting at $080d, and establishes its custom character font at $2000 with some combination of this data and PETSCII characters from character ROM. We’ve already found where the set-up routine ($08fc) copies the character ROM to $2000. What else does it do?

It’s relatively easy to see that a big chunk of the set-up routine is messing around in the $2000 memory region. Starting from the beginning, it sets a few registers, then immediately dives into the work of rendering the character data, with various loops and STA instructions indexing into this memory.

The characters of Crossroads walk in four directions, with two frames of animation. We only found two frames of animation in the graphics data, with the characters facing to the right. Can you guess where it gets the graphics for the other three directions?

To achieve the full effect, the set-up loop takes the 8x8 right-facing creature graphics and writes it into character graphics memory. Then it flips each byte horizontally and writes the left-facing copy. Then it rotates it 90 degrees one way for up-facing, and 90 degrees the other way for down-facing.

Moreover, the second step of each character’s animation is drawn across two character tiles, for that slick grid-breaking animation. The creature takes up two characters on the 40x25 screen for this half step, and no other creature or item is allowed in either tile at this moment. The set-up routine renders these half-steps dynamically from the 8x8 pixel data, using bit shifting instructions to produce half-tile images. I see groups of four bit shifting instructions at $0a5d and $0a6d that might be involved in this process.

Just after setting up the character data at $2000, the program sets VIC register $d018 to $18. This establishes how the VIC uses memory, and indeed, it sets the character memory pointer to $2000. It also sets the screen memory location to $0400. The VIC-II can only see 16 KB of the address space at a time, and which 16 KB is selected by a register at $dd00. Crossroads does not appear to change this register from its default setting.

Future possibilities with Ghidra

That’s a good start, and plenty for a single newsletter. Ghidra is a very powerful tool and I’m still learning about all it can do.

Ghidra is highly extensible, and there is substantial potential for extensions and scripts to support C64 and MEGA65 development and reverse engineering. In his video, Jarkko Lehti is using his own Ghidra fork with a few nice features such as PETSCII string visualization.

When I was squinting at the character set data, I was wishing for a bit of tool support for visualizing bitfields as graphics, much like how Retro Debugger lets you view memory contents in different ways. I wonder if Ghidra can do custom inline data visualizers like this, or if a feature like this is already available.

The annotated disassembly can be exported in multiple formats, but none of them resemble something that could be re-assembled by a tool such as Acme assembler. A custom export tool or post-processing script would be handy for that, and would be easy to write.

Of course, the thought naturally occurs to someday use Ghidra to disassemble MEGA65 machine code programs. It’d take some effort, but it is possible to write an extension to provide 45GS02 CPU support to the disassembler. Ghidra has an entire language for specifying new processors called SLEIGH.

It’d also be good to generate symbols files and overlays for all of the MEGA65’s I/O register personalities. I already have symbol generator scripts that could be tweaked to produce something that Ghidra can import.

In practice, most MEGA65 machine code programs that exist today have friendly authors that have open sourced their code. It’s still fun to think about.

I chose Crossroads for this demonstration for a few reasons. For one, it really was one of my favorite games, so I was excited to play with it. But also, I had a suspicion that its internals were straightforward enough to understand through disassembly. As fast and seamless as Crossroads is to play, you only need to know a few things about C64 programming to start to make guesses about how it works just from looking at it.

Many C64 games and demos use data compression techniques to limit disk space and loading times. This can make disassembly more difficult, because you can’t just load the PRG into Ghidra directly. One possible technique is to run the program in Retro Debugger, let it decompress everything into memory, then take a snapshot of the memory of the running program. You can then apply disassembly techniques to the snapshot. I suspected that Crossroads did not use compression for code, and felt comfortable just loading the PRG file directly into Ghidra.

If you’re interested in writing programs for the MEGA65, it’s worth studying C64 programs. The Commodore 65 was designed as a true technological successor to the C64, and many C64 programming techniques apply to C65 and MEGA65 programs. The original source code for many C64 programs have been lost to time, but we can use tools like Retro Debugger and Ghidra to pull them apart and reconstruct their secrets.

There’s one more tool that we can use to reverse engineer C64 programs—and it’s sitting right beside you. The MEGA65 can run many C64 programs in its GO64 mode, and you can use the MEGA65 core’s serial debugger, along with a powerful frontend like m65dbg, to analyze a running program. We’ll have to revisit this in a future Digest.

Onward into the new year!

— Dan

Hey everyone! I hope you’re all ready for some end-of-the-year relaxation, maybe some time off work, spent with family, in whatever temperature extreme you’re experiencing in your hemisphere. I also hope you’ll get some time to play with your MEGA65, because you’re gonna need it!

There are so many project announcements this month that I’ve decided to dedicate this entire issue to new downloads, to celebrate everyone’s talent and enthusiasm, and to give thanks for our wonderful community. We will finish our Crossroads disassembly project in January.

SidPlay65

There’s a new way to make music with your MEGA65, thanks to MEGA65 developer LightTangent! SidPlay65 is a MEGA65 program that re-implements the SIDPlayer music system from Compute! Publishing. It plays single-SID and dual-SID songs, and supports some advanced SIDPlayer format features like colorful PETSCII banner displays and karaoke lyrics.

SIDPlayer was one of several major tentpole products for the Commodore 64 from Compute!, along with Crossroads and the hit word processing package SpeedScript. The initial version of SIDPlayer appeared as a type-in in the book All About the Commodore 64, Volume Two by Craig Chamberlain. It included rudimentary music editing software, and a player routine that could be embedded in your BASIC or machine language programs. Chamberlain revised the system and published the Enhanced SIDPlayer in the book COMPUTE!’s Music System for the Commodore 128 & 64, this time with a companion floppy disk instead of type-in code.

The SIDPlayer system was a huge hit in the United States, and C64 owners produced thousands of songs and shared them on online services like Delphi and Quantum Link. Some SIDPlayer songs were written to be played on two SID chips simultaneously for a total of six simultaneous voices, made possible by either having two C64s, hacking a C64 to add a second SID chip, or using the SID Symphony Stereo Cartridge from Dr. Evil Laboratories. Today, this legacy lives on in the Compute!’s Gazette SID Collection (CGSC). You can download the whole set to play on your C64 or MEGA65, or browse and play the collection in a web browser with the website DeepSID.

LightTangent disassembled the original SIDPlayer program, and used the findings to write SidPlay65. Many thanks to LightTangent for this ambitious project!

Full-color full-motion video demos by MirageBD

MirageBD has been researching methods for streaming full-color full-motion video from the SD card. So far, Mirage has produced two brilliant demos: HyperBallad, the Björk music video masterpiece (1995), and Duel, a scene from the movie Electric Dreams (1984). Both demos launch from a D81 disk image, and stream data directly from a large file on the SD card.

Important note: Running these demos requires a fast SD card, very likely an SD card faster than the one that was included with your MEGA65. As lydon explained on Discord, the bundled cards are optimized for a longer lifespan, at the expense of some speed. If these demos glitch out after the first couple of seconds, consider getting a SanDisk Ultra brand microSD card.

COPA65 by Bananzi

Ever wanted to copy and paste text in the MEGA65 screen editor? Now you can, with this clever extension by Bananzi! COPA65 adds a text clipboard to the built-in editor experience, as well as both keyboard and mouse methods for selecting text.

With COPA65 installed, simply press Ctrl + C to wake it up, then press one of the command keys. For example, use the C command (press Ctrl + C, then press C) to set the start of a selection, move the cursor to the end of the selection, then use the C command again to copy the text. Finally, move the cursor to where you wish to paste, then use the V command.

Other commands can quickly select characters, words, and lines, and can insert pasted text instead of overwriting. See the detailed manual included with the download for instructions on installation and use.

COPA65 requires ROM beta version 920398 or later, which is when we formalized the extension mechanism being used. This is newer than the ROM included in release package v0.96. You can update to the latest ROM beta version, or wait for the v0.97 release package, which hopefully will be out soon.

Really amazing work, Bananzi!

Midnight Mega by nobruinfo

Bruno (nobruinfo on Discord) has been working on a powerful file browser, which he calls Midnight Mega. You can use Midnight Mega to browse your SD card, mount disk images, and view and copy files.

Midnight Mega is still in a beta testing release, and it is recommended to back up your data regularly. Please report any issues you find, and join the discussion on the #midnight-mega channel of the MEGA65 Discord. Also note that it only supports disk images and the internal floppy drive; it does not yet support external IEC drives.

Gurce disassembles Sea Wolf

My series on disassembling Crossroads is directly inspired by Gurce, who recently disassembled another classic C64 game, Sea Wolf. In this submarine battle game, you (and an optional second player) use paddle controls to maneuver submarines to fire missiles at battleships. The game’s lineage goes all the way back to the electro-mechanical arcade game Periscope by Sega (1966), followed by a similar electro-mechanical version by Midway called Sea Devil. Midway launched a video arcade version under the name Sea Wolf in 1976. Commodore International produced a home version for the VIC-20 and C64 in 1982.

Gurce made two videos about his disassembly project. Part 1 introduces the game and the project, and presents a few findings. The extended part 2 presents the entire project, with live demos and slides. You can read Gurce’s complete notes and the final disassembly on Github. With disassembly in hand, Gurce was able to modify the game to support four players, with two paddles on each of the two joystick ports.

Disassembling classic games is a great way to learn about programming for the C64 and the MEGA65. What game would you disassemble?

Featured Files Cornucopia!

muse has given us another arcade core! Stargate is the 1981 sequel to the arcade classic Defender, a fast-paced horizontal shooter. As with other arcade cores, you will need to search for ROM data files and follow the installation instructions. The core is available for both R3 and R6 mainboards.

Fireplace is a short BASIC demo by Urban Lindeskog, featuring PETSCII flames and crackling sound effects. Drag your MEGA65 out to the living room and run this for the holidays to keep your family warm.

RobH developed an example of sprite to character collision detection in BASIC, then followed up with a Lode Runner-like ladder climbing demo. These demos show off how to implement several game mechanics with this technique, including a player sprite, walls, collectibles, ladders, and doors. Both include well-commented BASIC source code.

Alpha Burst is a brief graphics-only demo by Drex, with brilliant colors and a borderless display. Run this on real hardware for full effect.

Disk Doctor Mega by tundra/C is a low-level disk viewer and editor for both physical floppy disks and virtual D81 disk images. Inspect your disk tracks and sectors, and potentially recover data from damaged disks.

Unelite Part 1 by mk9 is a text adventure game with PETSCII graphics. Use the joystick to select options in this branching sci-fi narrative.

45GS02 Quick Reference, and other media

I brought a few gifts to the party as well. You can still buy the 45GS02 quick reference as a mousepad or a poster. If you’d prefer a digital copy, you can now download the 45GS02 Quick Reference PDF for free. I also uploaded the BASIC65 Quick Reference PDF from the User’s Guide for similar convenience.

When I took my MEGA65s to computer shows earlier this year, I made some paper items to keep at the table to help show it off. I have uploaded these designs to Filehost, in case anyone else wants to use them. The MEGA65 Conference Table standee design is designed to be printed professionally on a 11" x 17" sign, and has facts and figures about the computer. The MEGA65 Demo Booklet prints in landscape orientation on 8-1/2" x 11" paper, suitable for spiral binding on the top long edge, and features diagrams, screenshots, and very brief instructions intended for someone unfamiliar with the computer to try it out in just a few minutes. Accompany this with an SD card pre-loaded with the mentioned disk images for full effect.

Here we are wrapping up another calendar year! I am grateful for everyone who has supported this newsletter over the previous two years, both with recurring donations and with kind words. If you haven’t already, please consider setting up a recurring donation to keep this resource sustainable. Visit: https://ko-fi.com/dddaaannn/

Have a great holiday! See you next year.

— Dan

Santa called his elves together
To soup up his old sleigh
So Rudolph and the other reindeer
Could rest on Christmas day

He’s got a million miles to travel
And to do it in one day
And that’s why Santa Claus
Has a souped-up Santa sleigh

Got a rocket burnin’ mighty quick
Turnin’ Santa’s souped-up sleigh
Comes in like a streak of light
And it goes out the same way

When you hear that rocket roar
You know Santa’s on his way
But he’ll be back again next year
In his souped-up Santa sleigh

— “Santa’s Souped-up Sleigh,” from the film Melvin & Howard, dir. Jonathan Demme

One of my all-time favorite games for the Commodore 64—and I know I’m not alone in this—is Crossroads, the single-screen maze shoot’em’up by Steve Harter, published in Compute!’s Gazette magazine as a type-in program in December 1987. The game features dozens of enemies of a variety of types and colors, all fighting each other in a cacophony of attacks and explosions. You’re dropped into the fray to collect items called “spars,” which provide you some protection against attacks, and which the enemies also consume. The game supports one or two players on joysticks, and both players battle for survival simultaneously.

Some people like to say that typing in programs from magazines and books helped them learn how to write programs of their own. I can see how that might be true for BASIC programs, though I can’t honestly say I learned anything from type-ins when I was in grade school. For programs written in languages other than BASIC, Compute! offered no way to learn. In this interview with Steve Harter by Kirk Israel, Steve says he wrote Crossroads in assembly language, but Compute! never published assembly language listings for full programs in magazines. Instead, Compute! published such programs as columns of numbers, along with a helper program that assisted with keying these values directly into memory. The most you could learn from these type-ins was data entry, and perseverance.

(As an aside: I’m aware of only two cases where Compute! published full assembly language program listings for the C64, both as books: the LADS assembler and the SpeedScript word processor. Steve wrote Crossroads using LADS.)

Over the next two issues of this Digest, we’ll crack open the original Crossroads program and see what we can learn, using two modern reverse engineering tools for your PC. This month, we’ll take a look at Retro Debugger, a C64 emulator with real-time memory visualization features. To keep this newsletter to a reasonable length (😬) we’ll discuss just enough to get started, and ask a few specific questions of interest about the game.

As always, let us begin with some MEGA65 news!

New Filehost feature: high score tables

Filehost has a fun new feature for competitive MEGA65 gaming: high score tables! When you upload your game to Filehost, you can choose to enable “Highscore submission.” This allows players to submit their high scores by clicking the plus ("+") button on your game’s Filehost detail page, uploading a screenshot as evidence. All score submissions must be approved by you before appearing on the page. You will receive a message when a player submits a score for your game.

Check out the high score table on Classy as an example.

Thanks as always to Tayger for the Filehost innovations! Everyone go out and rack up those high scores!

Galaga, Ghosts’n’Goblins, and Xevious now available for R6 boards; TI-99/4A now available for R3 boards

Over the last year or so, muse has given us alternate cores for the arcade games Galaga, Ghosts’n’Goblins, and Xevious, originally released for the R3 mainboard. Now, thanks to Robert Jaremczak (rjaremczak), there are R6 versions for these cores: Galaga R6, Ghosts’n’Goblins R6, and Xevious R6. See the original installation instructions for the R3 cores, which also apply to the R6 versions.

zeldin has updated the TI-99/4A core several times since its initial release, and as of version 1.3, the core is available for the R3 mainboard as well as R6. Go grab the latest, and be sure to file any bugs you find.

I had a few people respond to last’s month’s Digest to point out that core availability is currently a sticking point with regards to mainboard revisions, with some cores only available for R3 and others only for R6. Core developers must put in additional effort to support both mainboards, and not everybody owns both boards for testing. If you’re working on a core and need assistance building it for a board revision that you do not own, please reach out to the MEGA65 community on Discord or by email. We will eagerly connect you with resources for building and testing your core on both revisions.

Thank you Robert and zeldin for working on cores!

Last call for R3 Real-Time Clock replacements (Grove RTC)

Back in 2022, we noticed that a small but significant percentage of R3 mainboards had faulty Real-Time Clock (RTC) chips. Paul quickly put together a workaround involving a core update and an inexpensive RTC breakout board and Grove connector. This requires a soldering iron to put together, but no expertise: it’s just four wires. Nevertheless, I wanted to make sure that everyone who needed one could get one easily, so I built a bunch of them and made them available for the cost of shipping. The MEGA65 team also supported this effort financially out of their own pockets.

I will be ending my distribution offer at the end of 2024. I have about a dozen units remaining, and am willing to send them out to anyone who needs them. If you have an R3 mainboard and believe your Real-Time Clock is faulty, please follow these instructions for testing your RTC and requesting a unit. I will email you with instructions to send me the shipping cost by PayPal, then get one out to you, while supplies last.

Please do not request one if you don’t need one. Only a fraction of the MEGA65s delivered in 2022 have this issue. Follow the instructions to test your MEGA65 before requesting a replacement. If you discover you need one later than the end of this year, consider ordering the parts and cooking one up yourself. These are easy to build!

The sega-adapter is great actually

This isn’t news so much as just boasting, but last month I mentioned the sega-adapter project as a fun way to connect Sega Genesis-style game controllers to Commodore computers. Since I sent newsletter, I had some boards printed, got the parts together, and assembled a few. Chat, I can heartily recommend it, especially when used with the 8bitDo Retro Receiver for Sega Genesis ($16 on Amazon). The 8bitDo Retro Receiver pairs with almost any modern Bluetooth game controller, including Nintendo, Playstation, and older Xbox controllers (but not newer Bluetooth LE Xbox controllers). 8bitDo also makes a Bluetooth Sega Genesis gamepad; be sure to get the M30 Bluetooth model, not the “M30 2.4G wireless” model. I got my Nintendo Switch Pro controller to be a 3-button game controller for my MEGA65!

The sega-adapter is a pretty simple project, with the following parts:

• A 9-pin male connector, for the incoming Sega Genesis controller signal (such as the 8bitDo Retro Receiver)

• A PIC microcontroller

• A capacitor

• Header pins, and a “pigtail” cable for the 9-pin female connector that goes to the MEGA65 (or what have you)

• Optional header pins and jumper to switch between C64 and Amiga modes—or you can just use solder to set it to C64 mode permanently

That’s it. If you buy the exact parts recommended by the project, everything goes together using a soldering iron, and something to apply crimping force to the pigtail’s ribbon cable. You also need an inexpensive PIC microcontroller programmer such as a generic “PICKit3” device; I bought one for $33 on Amazon. I got the boards from OSHPark and parts from Digikey, for a total unit cost of about $16 each for a batch of ten adapters. The recommended 9-pin connectors were the most expensive parts, and you might be able to find cheaper ones in different form factors.

I’d never worked with PIC microcontrollers before! For software, I only needed the free version of Microchip MPLAB X IDE and the pre-built release of the sega-adapter .hex file.

To program the PIC, put it on a breadboard, then connect five of the wires of the PICKit3 to pins of the PIC, as described in the pinout diagrams (which I’m including below). Leave the sixth wire disconnected. You also need to apply about 5 volts of DC power across the PIC power pins. The PICKit3 does not supply power the microcontroller, and it needs to be powered to accept programming. You can use a little battery box, a wall wart of appropriate voltage, or a bench power supply.

I’m not selling these, I’m just showing off. It was a fun afternoon project, with a satisfying result, and because I made ten I have my holiday gifts all sorted.

Playing Crossroads

The first step to reverse engineering anything is to understand what the thing does. We can learn a lot about Crossroads just from playing it.

Archive.org has complete scans of Compute!’s Gazette magazine, and Crossroads is in issue 54, December 1987. An amusingly nostalgic way to acquire the Crossroads program would be to enter the “MLX” data entry program listed in the magazine, then use MLX to enter the 6,676 hexadecimal numbers for the game. (That’s 5,935 program bytes, plus error checking digits.) I recommend simply downloading the Compute!’s Gazette cover disk image archive. The disk image for the December 1987 issue is named 1987-12.d64. This disk image works great with the C64 core for the MEGA65. (Alas, I could not get it to run in GO64 mode. Maybe later we can figure out why.)

We can learn some useful things about Crossroads even before we run it. If we browse the disk directory, we can see that there are many files from this issue of the magazine, but the game likely consists of a single PRG file named CROSSROADS.

LOAD "$",8
LIST

We can load this file from disk into memory, using the ,8,1 arguments to LOAD to tell it to use whatever memory start address that CROSSROADS prefers:

LOAD "CROSSROADS",8,1

The program loads, and we’re back at the READY. prompt. Because the game didn’t do anything fancy to start automatically, we can guess that the program has loaded to the start of BASIC memory, and probably begins with a BASIC bootstrap program that invokes the machine code, like we’ve done for our own programs. Let’s confirm this:

LIST

Sure enough, there is a one-line BASIC program in memory:

10 SYS2300

Connect a joystick to port 2 (first player), then start the program with the RUN command. The game starts without any further disk activity, which confirms our hypothesis that this is a single-file game.

If you’ve never played Crossroads before, take some time to enjoy it! Shoot bullets at monsters by pressing the fire button, and collect the white spinning “spars” to gain shields and progress to the end of the level. Connect a second joystick and invite a friend!

Observing the game

As you play, try to make some guesses about how the game works, and come up with some questions you would like answered. Your own questions and hypotheses will guide your reverse engineering process.

Here are just a few things I noticed that might be worth exploring:

Program states. The game starts with an “attract mode” where a bunch of enemies duke it out on a maze without a player present, and with a scrolling message across the top of the screen. Like many vintage arcade games, attract mode appears very similar to gameplay, and likely reuses the game’s logic with minor changes. The game starts the first level when the player presses the fire button. Each level starts with an introductory animation where creatures appear with special graphical and sound effects. The players are the last to arrive. Then play begins. A level ends when a player collects a number of spars, at which point the game pauses until a key is pressed, and the game restarts at the next level. The game ends when both players are out of lives.

Creature properties. Creatures and players have a number of shields that protect them from attacks. Each attack deducts a shield, and the creature is destroyed when attacked without shields. A creature or a player gains a shield by picking up a spar. The player’s shield count appears at the top of the screen, under the “S.” Other creatures also have shield counts, but these are not visible. Player actions are controlled by joystick inputs; creature actions are controlled by algorithms. Each creature is of one of nine types, and the type describes their action patterns, reactions to collisions with bullets and other creatures, and the initial number of shields.

Character graphics. The maze and the creatures appear to occupy a grid in the same shape as the C64’s 40 x 25 character mode, and every element appears to be the size of a single character. It’s likely that at least some of these graphical elements are using VIC-II character graphics, where the glyphs of some letters, numbers, and symbols in the PETSCII typeface have been replaced with these designs. Each element is of a single color and high resolution, 8 x 8 pixels per character.

Creature half-steps. Even though creatures are the size of a single grid tile, they appear to traverse the screen in half-tile steps! If creatures are implemented with character graphics, the game must be doing something interesting to allow a creature to appear this way.

Sprites. There appear to be too many creatures and bullets on the screen at one time for the game to be using the eight VIC sprites to draw them. While advanced techniques like sprite multiplexing (which we discussed previously) could use sprites to draw more than eight objects at a time, there’s nothing in the design of this game that prevents more than eight objects from appearing on the same scan line, so this seems unlikely. However, there is an explosion effect that occurs when a creature takes damage, and this appears to overlay the character graphics. This suggests that this effect might be done with sprites.

Sound. The soundscape of Crossroads consists entirely of sound effects that represent activity on the screen: creatures appearing at the start of the level, player bullets firing, enemy bullets firing, shields absorbing damage, creatures and bullets being destroyed, and spars getting collected. There’s so much going on early in the level that each sound may be difficult to pick out, and it’s a bit easier after the screen is mostly clear. I’ll be interested to see how sounds are allocated to the three SID channels, especially when there are more than three events causing sound at a time.

In that interview with the developer that I mentioned earlier, Steve confirms that the creatures use character graphics, and the explosions use sprites. Steve also mentions that the sprite images for the explosion animations are generated randomly.

Examining the PRG

We want to use modern PC tools to examine the program, so we need to extract the PRG file from the disk image. Graphical tools like DirMaster (Windows only) or DroiD64 (Java, multi-platform) work nicely, or you can use the c1541 command included with the VICE emulator:

c1541 1987-12.d64 -read crossroads crossroads.prg

You can use a tool called a hex viewer to examine the bytes of the PRG file. I like a terminal-based hex viewer called hexyl, and there are many others to choose from. We won’t spend more than a minute staring at raw bytes, but we can use this to get our bearings. Here are the first few dozen bytes of the PRG file:

00000000  01 08 0b 08 0a 00 9e 32  33 30 30 00 00 00 00 00  |.......2300.....|
00000010  44 aa aa 11 00 00 00 00  11 aa aa 44 00 00 00 00  |D..........D....|
00000020  00 3c 3c 00 00 00 00 00  00 3c 3c 00 00 00 38 38  |.<<......<<...88|
00000030  30 7f be 68 ce ec 38 38  30 7f 76 30 30 38 ff 8f  |0..h..880.v008..|
...

As we’ve seen before, a PRG file starts with two bytes that specify the load address for the program. In this case, the first two bytes are $01 and $08, specifying the Commodore 64 BASIC start address of $0801 hexadecimal, or 2049 decimal. The PRG address bytes are not written to memory, they only tell the BASIC command LOAD "CROSSROADS",8,1 where to put the rest of the data.

The subsequent bytes describe the one-line BASIC program we saw earlier:

• $0b $08: The address of the next line. In this case, it’s the end-of-program marker: $080b.

• $0a $00: The line number. $000a = 10 decimal.

• $9e: The C64 BASIC token for SYS.

• $32 $33 $30 $30: PETSCII for 2300.

• $00: End of line.

• $00 $00: End of program. If you count from $0801, you’ll see this is at address $080b, from the first bytes of the first line.

These 12 bytes start at address 2049, which means the rest of the program data starts at address 2061 ($080d). Interestingly, the SYS command uses address 2300 ($08fc). The data starting at address 2061 might be code, or it might be something else. We don’t know yet. We only know that the byte at address 2300 is the beginning of a machine code instruction, and that it’s the first instruction executed by the program.

It’s amusing to compare this hex dump to the listing in the magazine. (Well I think it’s amusing.) Note that Compute!’s Gazette program listings have nine bytes on a line, but only the first eight bytes are part of the program. The ninth byte is a checksum, which the MLX program uses to verify that you entered the line correctly. If it didn’t do this, entering these programs would be a nightmare, as opposed to merely a nuisance.

Introducing Retro Debugger

If programming is the art of telling a computer what to do, debugging is the art of figuring out why it’s not doing what you meant. One of the best ways to do that is to peek inside the computer’s memory as it steps through your instructions, and try to line up the evolving state of the computer with your own mental model. This process is often so opaque and frustrating that I sometimes wish I could just rip the top off the chips and look inside as the program is running. Thanks to high fidelity emulators running on modern computers, this fantasy is now a reality.

Retro Debugger by Marcin Skoczylas is an emulator for the C64, Atari XL/XE, and Nintendo Entertainment System, with some powerful real-time debugging tools. As the emulator runs, you see the C64 screen in one window, and use other windows to render the memory in different useful ways: as hex values, as machine code instructions, as graphics in common VIC-supported formats, and as a color-coded memory map. All of this is updated as the emulation runs at full speed, and you can pause execution and manipulate system state as a program runs.

Let’s use Retro Debugger to inspect Crossroads, and follow up on a few of our assumptions about how the game does graphics.

Setting up Retro Debugger

Download the latest Retro Debugger release for your platform (Windows, macOS, or Linux). You also need the original C64 ROM and 1541 DOS code. Retro Debugger opted not to include these in the distribution, but you can get them directly by installing the VICE emulator. You’ll have to dig around the VICE folder for the appropriate .bin files. On my Mac, I found them here:

./VICE.app/Contents/Resources/share/vice/C64/
./VICE.app/Contents/Resources/share/vice/DRIVES/

Retro Debugger needs the ROM files to be in a single folder, with specific filenames. Create a new folder for these (such as inside the Retro Debugger folder), make duplicates of the files from VICE, and rename them as shown:

• .../C64/basic-901226-01.bin -> basic

• .../C64/chargen-901225-01.bin -> chargen

• .../C64/kernal-901227-03.bin -> kernal

• .../DRIVES/dos1541-325302-01+901229-05.bin -> dos1541

• .../DRIVES/dos1541ii-251968-03.bin -> dos1541II

When you start Retro Debugger for the first time, you need to tell it where to find the ROM files. Open the Settings menu, select C64, then Select C64 ROMs folder. Navigate to the folder you created with the ROM files in it. Retro Debugger loads the ROMs and starts the emulation. If it complains, make sure the ROM files are in the right place and have been renamed as expected.

Behold, the insides of the C64! You can see the CPU bouncing around the instructions for blinking the cursor at the READY prompt, and all of the memory and register updates that go with it. With the “C64 Screen” window active, you can interact with the C64 as you would with VICE, typing BASIC commands and whatnot.

Retro Debugger starts with some of its tools visible, but there are many more. With the cursor still at the READY prompt, open the VIC Editor menu, and select C64 Charset. The C64 Charset window opens. At this point, you should see what the VIC is currently using for its character set, which at the moment is standard C64 PETSCII. Resize the window to make the characters easier to see.

On my computer, I need to make the text bigger to be useful. Some windows, like the C64 Screen and Charset windows, have fixed-sized content, and you can drag the window corners to resize. In other windows, to increase the text size, right-click on the window, then adjust the Font Size slider. These windows can also be resized to display more information. The app will remember your window layout between sessions.

Retro Debugger is based on VICE, and has all of its debugging features. To pause the emulator, press F10 (or open the Code menu, then select Pause). While paused, press F10 repeatedly to advance by one instruction at a time. Press F11 to resume full speed. You can also set breakpoints on instructions, set watchpoints on memory locations, and can navigate to instructions that access specific memory addresses. You can even rewind the emulation to the instruction that last accessed a memory address.

For more information on features and keyboard shortcuts, see docs/README-C64-65XE-NES_Debugger.txt, included with the program.

Playing Crossroads in the emulator

There are two ways to get Crossroads running in the emulator. One method is to open the D64 disk image, then type the BASIC commands to load and run the game, as you would on a C64. Because Crossroads is a single PRG file, you can also just open the PRG file that we extracted earlier. Opening the PRG is often faster, especially if you need to reset the program.

Open the File menu, then select Open. Select the crossroads.prg file. This will load and run the game immediately, so prepare your speaker or headphones volume for the game’s violent introduction.

Next, open the Settings menu, then Joystick #2, and select a configuration for the joystick. With the joystick set to “Keyboard,” the cursor keys move the stick, and the right Alt key is the fire button. Or you can connect any PC-compatible game controller. If a controller is connected, its device name will appear in the menu.

Select the C64 Screen window, then press fire to start a game. Good luck!

Investigating character graphics

We have a hypothesis about how Crossroads uses character graphics. Let’s see if we can confirm this hypothesis in Retro Debugger.

When you started the game, it installed a new character set and told the VIC to use it. The Charset window now shows new graphics tiles: a limited set of PETSCII letters and numbers, and nearly all of the graphics for the game. You can see four types of maze wall, the “spar,” and various images for each of the creature types and bullets facing all four directions. Each of these are unique tiles of 8-by-8 pixels, and the tiles can be placed anywhere on the 40-by-25 tile grid.

We’ve made a discovery! The spar appears to be animating directly inside the Charset window! While Crossroads animates creatures using multiple static tile definitions, it animates the spar simply by continuously updating its single tile definition. This conserves charset tiles, at the expense of some CPU time.

If we squint, we can start to see how the game achieves its “half step” effect for creatures. When a creature is standing fully on a tile position, it is drawn as a single tile based on which direction it is facing. When a creature is walking between two tile grid spaces, it occupies both space, with a tile for each half of the image. There is a tile pair for each of the four directions. Each creature has two animation frames, and it appears that Crossroads stores both frames as single tiles, and uses only the second frame for the half-step tiles, for a total of 16 tile definitions per creature.

How the VIC finds character sets

The Charset window determines the memory location of the character set data that the VIC is using based on hardware registers, then draws the data it finds as characters. We can use some Commodore 64 knowledge to figure out where in memory this character set is stored.

The way the VIC-II accesses memory is a little bit complicated. The VIC can only access one of the four 16 KB banks at a time. Additionally, the C64 architecture makes a special accommodation so the VIC can access the PETSCII character set from an upper bank of ROM even when a lower bank is selected. This configuration for how the VIC sees memory is managed by the second of the C64’s two CIA chips. This is controlled by the lowest two bits of the CIA data register at $DD00.

In Retro Debugger, select the C64 Memory window. With this window selected, you can use either the Page Up/Page Down keys or your mouse’s scroll wheel to browse memory. You can also jump directly to an address by pressing Ctrl+G (or on macOS, Command+G), then typing the address in hexadecimal. Use this to jump to the register address $DD00.

Tip: Be careful what you type when the Memory window is active. If the cursor is on a memory value, typing hexadecimal digits will modify memory. When you type Ctrl+G (or Command+G) to go to an address, double-check that the cursor has moved into the address column before typing the address.

With Crossroads running, the register at $DD00 is set to $C7, so the lowest two bits are %11. According to C64 technical documentation, this points the VIC at bank 0, addresses $0000-$3FFF. It also tells the VIC to see the PETSCII character set at addresses $1000-$1FFF, hiding the RAM at these addresses from the VIC. This only hides the RAM from the VIC, not the CPU.

Still in the C64 Memory window, jump to register $D018 (53272 decimal). This register tells the VIC where to find screen memory within the selected bank, and where to find the character set. With the game running, this appears to be set to $19. This value is interpreted as follows:

• $19 = %0001 1001

• The upper four bits specify the location of screen memory, as a multiple of 1024 ($0400) bytes. %0001 = 1, so screen memory starts at address $0400. This is an offset from the beginning of the selected bank, and in this case the bank is 0, so the final address is $0400.

• The next three bits specify the location of character memory, as a multiple of 2048 ($0800) bytes. %100 = 4, so character memory starts at address $2000.

• The last (least significant) bit is ignored.

Be aware that the character memory offset gets described in manuals and online resources in different ways. I just described it the way the C64 wiki does: a three-bit number times 2048. Other books, including the MEGA65 manual, describe it as the upper three bits of a four-bit number whose last bit is 0, times 1024. The math works out the same either way.

With the selected CIA configuration, a program could tell the VIC to use the PETSCII character set from ROM by setting the three bits to %010 = 2 times 2048 = address $1000. Crossroads tells the VIC to look at $2000 instead, which is RAM where Crossroads can install its custom character set.

Let’s confirm our understanding. In the C64 Memory window, go to address $2000.

The C64 Memory window doesn’t know what the values in memory mean, but it tries to help us out by displaying them in four different ways: as hex bytes, as PETSCII characters, as character graphics data, and as sprite graphics data. In this case, we’re looking at character graphics data, so that view makes the most sense, and the other views are mostly nonsense. Scroll down to address $21F8 to see the spar glyph data being animated by the program.

Cheating at Crossroads

The C64 Memory window lets us peek into the computer’s memory as it is running, and also lets us change memory as we like. If we knew where to look, we could change properties of the game, such as the number of lives the player has. So how do we know where to look?

Locating variables is such a common task that the debugger has a tool just for this. Open the C64 menu, then select the C64 Memory Monitor. (This is a new tool, not the C64 Memory window that we’ve been using.) Resize this innocuous-looking little window to make it bigger.

Start a new single-player game by pressing the fire button on the joystick configured for port #2. The level clears, creatures spawn in, and finally the player arrives.

The player starts with 4 lives. We can know for sure that somewhere in the computer’s memory is a representation of this value, and this representation will change when the player loses a life. We don’t know where it is, or how the value is represented.

Let’s take a guess that the number of lives is stored as a byte, encoded as a non-negative integer. In other words, if we search the computer’s memory for a value of 4, there’s a chance that this might be how it stores the number of lives. This is just a guess! We can start with this, and refine our guess if it doesn’t work out.

With the emulation still running, in the C64 Memory Monitor, click the Capture button. Retro Debugger takes a snapshot of all of memory, and a giant list of memory addresses and values appears. Next, set the filter settings:

1. Check the box next to “Changed.” The list updates to show only the memory that differs from the captured snapshot in the current state of the emulation.

2. Check the box next to “Matches prev.” Click the value box, type 04, then press Enter. (It’s important to press Enter in this field, or the value won’t stick.) The Memory Monitor now lists all of the memory locations that were set to $04 when you clicked the Capture button, but currently contain something else.

3. Finally, check “Matches current,” and set its value to $03.

The list narrows to just the memory addresses that were 4, and are now 3. You may see more than one row, but likely only a few. Of all 65,536 memory addresses in the computer, these are the only ones that meet the criteria. This list updates in real-time as the emulation runs, and some rows will flicker in and out as memory changes.

Select the C64 Screen window again, and use your gamepad or the keyboard to move the player into harm’s way until they run out of shields and lose a life. The number of lives shown in the top display reduces to 3. Press F10 to pause the emulation.

One of the addresses that meet the filter criteria in the Memory Monitor is $0011. Let’s take another guess that this is player 1’s life count. This is a good guess for at least two reasons. It’s an address in the Zero Page (addresses $0000-$00FF), which is a common place to put variables. It’s also the only row that doesn’t flicker while the emulation is running.

On the row showing address $0011, click the “Memory” button. This updates the C64 Memory window to highlight that location. As expected, its value is currently $03. Now change this value: select the Memory window, then type 07. Press the F11 key to unpause the emulator.

Hmmm, the number of player lives on the screen still shows “3.” Was our guess incorrect? Try killing off the player one more time. Success! The life count now reads “6,” one less than the value we set. Double-check that the value at address $0011 is now $06.

When we dig deeper into the machine code next month, we should expect to find instructions that manipulate address $0011, and can probably assume that the code is related to the number of lives of player 1. We can use that information and some inductive reasoning to determine the purpose of the surrounding code, and figure out the rest of the program.

We got a bit lucky with our guesses in this example, though truthfully many games store the number of player lives this way. What if our guesses were wrong, and the number of lives wasn’t stored as a non-negative integer in a byte value? One possible strategy would be to locate the code that updated the “4” on the screen to a “3.” We could use the Memory Monitor against the screen codes for those characters, or we could locate the screen memory address and ask Retro Debugger to tell us which instruction last changed it. It might be possible to figure out from nearby code where it reads the value that it displays, and how the value is interpreted.

More things to try

Retro Debugger comes packed with plenty of toys for messing with the state of the emulator. Browse the menus and experiment! Most menu items open a new window with interesting features. Here are just a few ideas.

Locate that first instruction. Recall that the BASIC bootstrap invokes the machine code at address 2300, or $08FC in hexadecimal. Pause the emulator by pressing F10. Select the C64 Disassembly window, type Ctrl+G (or Command+G for macOS) to go to address $08FC. We can see that the first few instructions initialize some hardware registers: $D40E, $D40F, $D412. You can look up these addresses in C64 technical documentation to see what they do. Researching all of the code this way is a bit tedious, but it’s fun to see the code sitting right there in memory. We’ll use a more powerful tool for investigating this code in next month’s Digest.

Watch the SID chip make sound. Open the C64 menu, then the C64 SID sub-menu, then the C64 SID tool. The C64 SID window opens, showing information about the SID chip’s three sound voices. (Check out one of the earliest Digest issues for an introduction to the SID chip.) Keep this window open, play the game for a bit, and watch the SID waveforms as the enemies duke it out.

Draw on the screen. Open the VIC Editor menu, and select Show VIC Editor. This window resembles the screen, and by default shows the tile grid and the pixel grid. This is a powerful tool for updating the VIC data in real time, and there’s quite a bit of documentation of its features in the text file. For now, select the C64 VIC Editor window, then left-click on an empty space on the Crossroads maze. It fills in with a character. Try making a wall of characters in the maze. Another discovery! The characters block the path of creatures, and the player! It is likely that the game code reads screen memory directly to detect whether a creature is adjacent to a wall.

Watch for sprites. The VIC Editor highlights sprites with a red box. If you zoom out in this window with the mouse scroll wheel, you can see that Crossroads keeps the sprites off screen when not in use. Play the game to cause explosion effects as shields and creatures are destroyed. Notice that the red boxes appear around the explosions in progress, then retreat out of view when no longer needed.

We’ve only scratched the surface of what Retro Debugger can do, and we’ve already learned quite a bit about how Crossroads works. We’ll be able to apply this knowledge as we start investigating the code.

Next month, we’ll introduce Ghidra, a powerful tool for inspecting machine code. With some effort and ingenuity, we’ll be able to produce a complete human-readable assembly language source listing for the game—the listing that Compute!’s Gazette refused to print.

Before you ask: no, there is currently no real-time memory visualization tool like Retro Debugger for the MEGA65 or the Xemu emulator. Yes, it would be cool. LGB tells me more work is needed on Xemu before it can support real-time memory visualization. In the short term, we’re more likely to see investment in the serial debugging protocol and tools like m65dbg, which can be used with both the Xemu emulator and with real MEGA65 hardware over a JTAG connection.

This Digest is made possible by an amazing group of supporters. Only supporters are allowed to complain when the feature article isn’t specifically about the MEGA65. To become a supporter, visit: ko-fi.com/dddaaannn

More next month!

— Dan

Everyone who owned a Commodore 64 had at least one joystick, a game controller consisting of a lever that could be pushed in eight directions and a single action button. Games based on this controller typically involved the player using the stick to move an avatar—a spaceship, a person, a creature—as well as pushing the action button to activate a weapon against some enemies. The button on this kind of joystick was almost universally referred to as the “fire” button for how often it was used to launch missiles or shoot bullets.

Then came the Nintendo Entertainment System with its gamepad controller, a plastic rectangle with a directional thumb pad, two action buttons, and two more business-like buttons intended for pausing the game and accessing menus. NES games, especially Super Mario Bros. and The Legend of Zelda, popularized a new game design language based on the two action buttons. While Mario-like platform games were made for the C64 and its one-button joystick, expecting the player to shove the joystick forward (“up”) to jump, every generation of gamers that followed the NES expected to be able to jump in a platform game by pressing one of the two action buttons.

The vast majority of C64 games used the one-button joystick protocol. But there have been several attempts, both vintage and modern, to bring multi-button gaming to the C64, and to other computers with 9-pin joystick ports. This is of particular interest to modern retro game developers who want to use multi-button game design conventions while coding for the C64 and MEGA65.

In this Digest, we’ll explore a bit of the history of 9-pin game controllers, and investigate several methods used to implement multi-button schemes. We’ll look at the fundamentals of game controller electronics, and game controller programming. We’ll also take a closer look at several modern game controllers and controller adapters you can buy today for your MEGA65.

But first news!

More MEGA65 parts available separately

Last month, we noticed that Trenz Electronic is now making the MEGA65 mainboard available for preorder as a standalone part. Trenz has since added more MEGA65 parts to their store: the MEGA65 keyboard, the plastic case, the floppy drive, and the power supply. The keyboard is a sophisticated part, including the mechanical key switches, keycaps, cable, metal frame, and LEDs. The case includes other plastic bits such as the ALPS floppy drive eject button and reset button cap. You could, in theory, assemble a full MEGA65 from the spare parts available.

Math wizards may notice that the cost of the parts all together add up to more than the cost of a complete MEGA65. I can’t speak for Trenz, but this jibes with my limited understanding of the microeconomics of short-run niche electronics. Without economies of scale, Trenz has to account for labor, logistics, and potential lossage to support the individual items, even when pulling from the same stock they use to assemble full units. As deft puts it, “Imagine buying a car one piece at a time.”

I’m grateful that they’re making these available, so we have potential replacement parts, as well as options for other projects.

“Should I upgrade my mainboard?”

Did you receive your MEGA65 in 2022, or buy it second-hand from someone who did? Then your computer has the revision 3 (R3) mainboard. Starting in 2024, Trenz Electronic began shipping MEGA65s with the revision 6 (R6) mainboard, which has several changes from R3. If you’re unsure which MEGA65 mainboard you have, you can double-check which one you have in the MegaInfo panel: open the Freezer (hold Restore for one second, then release), then press Help. It’ll say which one you have next to “MEGA65 Model.”

Should owners of the R3 board upgrade to the R6? Probably not. It is unlikely that a difference between the R3 and R6 mainboards would be worth the cost of a new mainboard to most R3 owners. The differences may not even be noticeable.

There are a few notable categories of changes between the R3 and R6 boards: bidirectional cartridge and joystick I/O lines, an added SDRAM chip, and electrical fixes.

Bidirectional cartridge lines. The original R3 mainboard supports the vast majority of cartridges made for the Commodore 64, which provide program data as input to the computer. It will also support cartridges made for the MEGA65 in the future. The cartridge port changes in the R6 board apply to a few electronically fancy cartridges that communicate with the computer using both input and output. For example, the MSSIAH MIDI interface cartridge works with the C64 core, and requires the R6 mainboard. EasyFlash 3 is also known to require the R6. Notably, an EasyFlash 1 cartridge can be both read from and written to by an R3 MEGA65. That’s how we’ve been testing the MEGA65 cartridge protocol.

Bidirectional joystick port lines. The original R3 mainboard also supports the vast majority of game controller peripherals for the C64, which provide input to the computer about how the user is manipulating the controller. A few unusual peripheral designs use the data lines for both input and output, to implement more buttons or other features with proprietary protocols. The R6 mainboard adds support for such protocols. See this month’s feature article for more on game controller protocols.

SDRAM chip. The R6 adds an SDRAM chip that is intended to broaden the possibilities for alternate FPGA cores. It is possible that someday there could exist an alternate core that requires the R6 and doesn’t run on the R3. Personally, I think it’s worth tempering these expectations. I’ve discussed this with a bunch of people familiar with MiSTer-style core development, and they have all estimated that the most compelling alternate cores for the MEGA65—including an Amiga core—should fit the original R3 board. There may never be an alternate core that requires the SDRAM, even though it was added for this purpose. No core exists today that requires an R6, and I’m not aware of anyone working on one.

Most importantly, the MEGA65 core does not use the new SDRAM component. All software written for the MEGA65 will run on both R3 and R6 mainboards, now and in the foreseeable future. There are no plans to treat the SDRAM chip as a memory expansion for the MEGA65.

Minor fixes. Lastly, the R6 board implements some minor fixes for known issues. If you are noticing these issues on an R3 board, you may be able to use inexpensive workarounds, such as an HDMI repeater or a replacement Real-Time Clock. If you’re not noticing these issues, you won’t notice the fixes with an upgrade. This category also includes a few changes to accommodate the availability of components; these changes don’t affect the functionality of the computer.

I know I’ve spent a lot of money over the years indulging my FOMO by buying hobby computers “just in case” I want them later, and it’d be hypocritical of me to say an R6 is not a worthy upgrade to an R3 when I own one of each. But given that a new mainboard is more than half the cost of a new MEGA65, it’s worth resisting the temptation to think other people have all of those things and you have none of them. Really, R3 and R6 are mostly identical.

Portland Retro Gaming Expo 2024

I took the MEGA65 to the Portland Retro Gaming Expo in Portland, Oregon, mere weeks after getting back from Chicago. PRGE is another massive show, but with a different vibe from VCF Midwest. As the name implies, the show is dominated by vintage gaming, with free-to-play arcade and gaming console exhibits, gaming tournaments, several concurrent tracks of talks and panels, meet-and-greet booths with voice acting and YouTube celebrities, and a massive vendor floor with multiple eras of console games and related merchandise.

PRGE has always featured vintage home computing in its line-up, but representation of the home 8-bits on the vendor floor has waned as our vintage hardware has become more collectible. This year, PRGE established a “home computing” exhibit to keep some of our favorite computers in the show. My MEGA65 booth joined several large displays of Texas Instruments, Commodore, Atari, and Apple vintage equipment, as well as more obscure Z80-based computers. I sat closest to the tournament area, where competitors tore through Street Fighter and Rivals of Aether as commentators hyped up the crowd. I was also across from the big surprise of the show, a large display by The Last Blockbuster, with Blockbuster video iconography, merch, and racks of VHS tapes.

My MEGA65 table was much larger and more welcoming to visitors than it was at VCF Midwest. I’m grateful to Hans, the show runner, for gifting me two tables, and for lending me a big screen TV. And I got to hang up the banner! Even in this back corner of the show floor, the MEGA65 drew a lot of attention, and I spent nearly all of the first day on my feet, answering questions, shaking hands, and handing out cards and mousepads. Several people from press outlets wanted interviews. If the fire alarm hadn’t gone off in the middle of the day, I may never have had a break for lunch. The second day was quieter, but I still had quite a few kids stop by for a round of Unicone or First Shot.

It was especially gratifying to see young people take an interest in the MEGA65. Some of them already knew what it was and were excited to see it in person, some dragged their parents over to the table for a look, and several sat down at the computer for long stretches of time to peruse the demo disks and write short programs. I talked to MEGA65 owners and wannabe owners, and plenty of people simply intrigued by an 8-bit style computer that seemed familiar but unlike anything they’d seen before. I got to introduce many people to the stories of both the Commodore 65 and the MEGA65.

New TI-99/4A core

My very first computer was a Texas Instruments TI-99/4A, and now thanks to zeldin, I can recreate those childhood memories! Mega99 is a TI-99/4A core, written from scratch exclusively for the MEGA65. The core needs the ROM files from the MAME project (ti99_4a.zip, ti99_fdc.zip, and ti99_speech.zip) as well as the provided mega99sp.bin file in the root of the SD card. Flash the core to a spare slot in the core selection menu.

As of this writing, the core is only available for the R6 boards. This is not a matter of hardware capacity, and hopefully zeldin can produce a build for R3 owners in the future.

Be sure to read the README.md file for installation and usage instructions. The core matches the 99/4A CPU timing by default, and can also run in a turbo mode. And get yourself the TI-99/4A User’s Guide to remind yourself how this thing works! Hint: the Mega key is the FUNC key, and many text entry features use it.

Thank you zeldin for this excellent and nostalgic core!

Featured Files

Here are some recent demos uploaded to Filehost worth checking out:

• Shodan, by Drex.

• 3D functions and Patterns, by adorigatti.

• HyperBallad, by MirageBD.

Joytest65

This month’s Digest is all about joystick and paddle programming, so I made a joystick and paddle tester app to go with it. It includes documentation and assembly language source code.

• Download joytest65 from Filehost.

The 9-pin connector

The C64 was one of several early computers that adopted the Atari joystick port standard from the Atari 2600 (1977), and supported the use of Atari game controllers to play C64 games. I’m most familiar with the classic Atari CX40 joystick, but there were many others, and everyone has a favorite. Commodore used the Atari-style controller connector on everything from the VIC-20 to the Amiga, and they intended the C65 to have two 9-pin peripheral ports, just like the C64. The MEGA65 has two 9-pin peripheral ports on the left-hand side.

Nintendo released the NES in the USA with a proprietary controller connector and more buttons, and the game console arms race that followed produced more custom connectors, more buttons, and more evolutions in game design language. Commodore made two attempts to follow suit in their final years, both using new protocols over the original Atari-style connector: the C64GS and the Amiga CD32. These protocols were backwards compatible with older Commodore computers, and the new consoles also supported the one-button controllers and ran compatible games.

Commodore also made several types of computer mice that used the 9-pin connector, especially the 1351 mouse for the 8-bit computers, and the Amiga mouse. As you probably know by now, your MEGA65 supports both types of mice, using built-in adapter logic to make the Amiga mouse appear to software as a 1351. See the User’s Guide, 2nd edition, for information on how to configure the mouse emulation mode. We won’t cover the mice protocols in this issue of the Digest.

What follows is a description of how Atari and Commodore computers use the 9-pin connector for game controllers. Other 8-bit computers and early game consoles used the connector, but not necessarily the same wiring or protocols.

Joystick fundamentals

A standard 9-pin one-button joystick tells the computer that the action button is being pressed by connecting pin #6 to pin #8 (the ground pin, labeled “GND”). This doesn’t require any fancy electronics, it’s typically just a button connected to these two pins. When the player presses down on the button, two pieces of metal in the button make contact, completing an electronic circuit. When the player releases the button, a mechanical spring-like action separates the two pieces of metal, breaking the circuit and signaling to the computer that the button was released. This kind of button is also known as a momentary switch.

Pins #1, #2, #3, and #4 work similarly, representing the joystick directions up, down, left, and right, respectively, when connected to pin #8. The joystick indicates a diagonal direction by completing two circuits simultaneously, such as up and left. Typically, there are no fancy electronics involved here either. The joystick is built such that when the user pushes on the stick, it closes one or two momentary switches wired to those pins.

Within the MEGA65, these pins are connected to the Complex Interface Adapter (CIA) chip, which translates these electronic signals into register values that can be read by a program. Try this: connect a joystick to port 2, and run the following simple program:

10 PRINT PEEK($DC00)
20 GOTO 10

The program prints the number 127 repeatedly. Move the joystick and press the fire button. The number changes depending on which buttons are pressed.

This register value is a bit field, where each button is assigned to a bit. If the button is not pressed, the bit is 1 (“high”). If the button is pressed, the bit is 0 (“low”). This is why the register value is 127 when no buttons are pressed: all of the bits associated with the buttons are “held high” until they are “pulled low” by the button presses. (The register has additional bits not connected to the joystick pins.)

The one-button 8-direction joystick protocol can be summarized as follows:

• Buttons connect pin to GND; CIA bit = 0 when pressed

• Pin #1: Up, CIA bit 0

• Pin #2: Down, CIA bit 1

• Pin #3: Left, CIA bit 2

• Pin #4: Right, CIA bit 3

• Pin #6: Fire, CIA bit 4

• Pin #8: Ground (GND)

%01111111 = 127

%01111110 = 126: up
%01111010 = 122: up and left
%01101010 = 106: up, left, and fire

It is the program’s responsibility to read these register values, do the math, then change the game state appropriately, such as to move the player sprite around the screen.

Like the C64, the MEGA65 has two CIA chips. Only the first CIA is used to read the joystick ports. And yes, these are the same CIA chips that provide timers and other features.

The CIA and port 1

Register $DC00 represents joystick port 2. To read the status of joystick port 1, you read register $DC01.

C64 owners remember this one: with a joystick connected to port 1 and the cursor at the READY prompt, you can get junk to show up on the screen just by jiggling the stick around. This is no longer true with the MEGA65 in MEGA65 mode (as of release v0.96), but you can still reproduce this in GO64 mode or the C64 core. Try it!

The C64 uses the CIA chip connected to the joystick ports for multiple purposes. This includes reading the keyboard. When you type on the keyboard, it pulls down the CIA bits in certain patterns, just like a joystick on port 1 does. This is why, when the C64 is expecting keyboard input, a joystick in port 1 moving around can seem like typing. Even though you can prevent this effect in code for a game, many C64 games simply assumed that most people would keep their joystick connected to port 2.

The MEGA65 is better behaved because its keyboard handling uses a different mechanism that is not as reliant on the CIA chip. A couple of specific functions still test the CIA for specific key presses, but in general, port 1 joystick events are much less likely to interfere with the keyboard.

Reading the joystick from BASIC 65

BASIC 65 provides a handy function for reading the state of the joysticks. The JOY(port) function returns a value that represents joystick activity on the requested port (1 or 2). Instead of a bit field, the JOY() function returns a number from 0 to 8, where 0 means the joystick is in the center, and 1 through 8 are the eight directions counting clockwise from “up.” When the button is pressed, it adds 128 to this value. See the User’s Guide for a table and example program.

10 PRINT JOY(2)
20 GOTO 10

As of ROM beta version 920397, the JOY() function can also read both joystick ports simultaneously, and report a merged result. To request this, use a port number of “3”: JOY(3). This is intended solely to allow a game to work with a single joystick in either port, so the player doesn’t have to change their joystick connections to play. It does not return a useful result when two joysticks are connected and moved simultaneously. If your game uses two joysticks, use JOY(1) and JOY(2) separately. This feature will be in the next MEGA65 stable release.

A machine code program can read the state of the joystick by accessing the CIA registers and interpreting the bits directly. For best results, such a program must take interrupts into account if it leaves the KERNAL interrupt handler active.

The KERNAL interrupt handler messes with the CIA registers many times per second to process certain keyboard events. A program wanting a clean read of the CIA register must disable interrupts to prevent the handler from messing up the result.

The program has to tell the CIA chip to ignore the state of the keyboard when reading the joystick. I won’t cover how this works in detail, just know that the way to do this is to write the value $FF to the data register ($DC00 or $DC01) before reading it.

Here’s the complete sequence for a clean read of port 2 in assembly language:

sei        ; Disable interrupts
lda #$ff
sta $dc00  ; Lock out the keyboard lines on port 2
lda $dc00  ; A = port 2 pin state
cli        ; Re-enable interrupts

Paddle pairs and potentiometers

In addition to joysticks, the Atari controller standard also supports a paddle controller. A paddle uses a dial-like wheel instead of a joystick. A game can detect how far the wheel is turned by reading more registers. This controller is called a “paddle” after the seminal home computer game Pong, which used such a controller to manipulate a paddle in a virtual game of ping pong.

Each joystick port supports two paddles, each with its own dial and fire button. The MEGA65, Commodore 64, and Atari 2600 all have two joystick ports, for up to four paddle players. The two dial-like controls are also used together by peripherals such as light pens or mice, where the two inputs represent movement along X and Y axes.

The paddle protocol is different from the joystick protocol. Electronically, the fire buttons are wired to joystick port pins #2 for the first paddle and #3 for the second paddle, connecting them to pin #8 (GND) when pressed. A program can read these pins using the CIA data registers, just like reading the joystick. The register bits read 0 when the button is pressed.

The paddle dial itself is a potentiometer, also known as a variable resistor or “pot.” Instead of simply connecting or disconnecting the path between two pins like the fire button, the potentiometer forms an electrical connection between two pins through an amount of electrical resistance that the computer can measure. When the player turns the knob, the amount of resistance changes, indicating the position of the dial. The first paddle on a port connects signal pin #5 (“POTX”) to pin #7, where the computer provides a voltage of +5V. The second paddle on the port uses signal pin #9 (“POTY”) and pin #7.

The paddle protocol:

• Potentiometers connect pin to +5V

• Buttons connect pin to GND; CIA bit = 0 when pressed

• Pin #2: Paddle A button, CIA bit 1

• Pin #3: Paddle B button, CIA bit 2

• Pin #5: Paddle A analog (POTX)

• Pin #7: +5V

• Pin #8: Ground (GND)

• Pin #9: Paddle B analog (POTY)

Resistor values and register values

Strangely, Commodore used a different potentiometer in their own paddles compared to the ones by Atari, and the two paddle types produce different numbers when accessed from a Commodore program. It is generally understood, and some have measured, that Commodore paddles use a potentiometer rated at 470 kΩ (kilo-ohms), and Atari paddles are rated at 1 MΩ (mega-ohms), with the measured resistance range a bit less but on that order of magnitude. This means that when an Atari paddle is connected to a Commodore, turning the knob goes from the minimum value to the maximum value in half the rotational distance (half the “throw”) than an official Commodore paddle. In practice, this can be both good and bad: shorter throw can result in faster play, but with less accuracy and a large “dead zone” where the resistance is above the maximum recognized by the computer.

I wanted to know the actual resistance value range recognized by the MEGA65, so I started by measuring the resistance of my Commodore and Atari paddles with an ohmmeter. What I discovered was a bit of a surprise.

I took some ohmmeter measurements of my Commodore and Atari paddles, and also tested the values returned by the BASIC 65 POT() function, which returns a value from 0 to 255 based on the dial setting. Both paddles had a minimum resistance in the fully clockwise position, then increased counter-clockwise to their maximum. The Commodore paddles measured a minimum of 44 Ω to a maximum of 166 kΩ. The POT() function returned a value of 220 at the maximum, not the full 255. Atari paddles had a higher resistance of 124 Ω at minimum to 782 kΩ at maximum. Here, the POT() function returned the full 255 after only a third of a turn, with a whopping dead zone of two thirds of a rotation, returning 255 for that portion.

So I opened the cases of both sets of paddles, and discovered that my Commodore paddles have a potentiometer rated at 200 kΩ, far less than the 470 kΩ that others have reported. My Commodore paddles also have a capacitor in parallel with the signal lines, which smoothes out the signal and shouldn’t affect the DC resistance, but is notable because it is absent from other paddles. I asked some friends to open theirs and they all reported 470 kΩ pots, so I must have some weird ones.

While it’s reasonable in the abstract that a Commodore program should be able to detect the full range of motion of the Commodore paddle knob, it may have turned out to be unreasonable in practice. A game expecting the full value range to represent a full turn of the knob might be unplayable with Atari paddles, and vice versa. Perhaps Commodore decided to split the difference at some point and changed to a 470 kΩ potentiometer, and I just happen to have an earlier model of the paddles.

Of course, it's possible that a previous owner of my paddles replaced the pots with the unusual values and these didn't come from Commodore.

Reading paddles from BASIC 65

As with joysticks, BASIC 65 has a function for reading paddles: POT(paddle) returns a paddle position as a number between 0 and 255, and adds 256 if the paddle’s button is pressed. The paddles on joystick port 1 are #1 and #2, and the paddles on joystick port 2 are #3 and #4.

10 PRINT POT(1), POT(2), POT(3), POT(4)
20 GOTO 10

The MEGA65 paddle registers

The MEGA65 has dedicated circuitry and registers for reporting the four paddle values. A MEGA65 machine code program can read these values directly from registers.

• $D620: Port 1, paddle X

• $D621: Port 1, paddle Y

• $D622: Port 2, paddle X

• $D623: Port 2, paddle Y

The fire buttons on the two paddles work just like joystick buttons, and can be read directly from the CIA data register for the appropriate port.

That's all a MEGA65 programmer needs to know. On the C64, the process is a little more elaborate, and it's interesting to know why.

Reading paddles the old-fashioned way

The CIA chip only knows how to handle digital signals (1’s and 0’s), and can’t read a resistance value (an analog value in a range). Instead, it gets the help of another chip in the chipset more familiar with converting between analog and digital signals: the SID sound chip.

To read a paddle value, a program first tells the CIA to connect the SID to one of the joystick ports. The program must then wait briefly before reading the value from a SID register. The SID needs a small amount of time to read the resistance value and update the register. During this time, the SID charges an internal capacitor that is connected to the signal and voltage lines of the controller. Once it is charged, the SID flips to a different circuit that discharges it. The SID determines the resistance of the paddle controller from the amount of time it takes to perform this charge-discharge process. To convert this to a value between 0 and 255, the SID needs 512 CPU cycles. At the end of this time, the SID updates its register value.

512 machine cycles at a rate of 1 MHz takes about 1/1950th of a second. That doesn't sound like a lot, but it can be a long wait for an action game, over 10% of the time it takes to draw a frame of graphics. Of course, the program is welcome to do other things during this time. A game loop could set the CIA select bits at the beginning of the frame, then read the paddle values near the end of the game logic, adding a busy-wait at the end as needed.

The SID can only be connected to one joystick port at a time. To read paddles from both ports, a program must connect to the first port, wait the 512 cycles, read the SID registers, then connect to the second port, wait another 512 cycles, and read the SID registers again. A game that reads all four paddles may or may not need to be clever to use the waiting time wisely, depending on how much time the game needs per frame.

If the program leaves the SID connected to a single port and takes over the hardware interrupt vectors (such that the KERNAL interrupt handler isn’t messing with the CIA connections), it can skip the wait and just read the SID register at its convenience. The register will contain the last stable value.

The C64 Wiki page on paddles has a diagram of the resistor-capacitor circuit that the SID is using to measure the resistance value in the controller. I was confused at first because the diagram makes it look like the capacitor is provided by the paddle controller, outside of the joystick port. This is not the case: the SID provides the capacitor part of the RC circuit. The capacitor present in my Commodore paddles bridges the +5V and signal lines, and is there for smoothing purposes and is not part of the RC timing circuit. Other paddles don’t have the smoothing capacitor.

The C64 way to read paddles from machine code

A C64 machine code program must perform the full procedure to read an analog value from the SID chip: select the port to connect the SID chip, wait briefly, then read the result from a SID register.

To select the port, set bits 6 and 7 of register $DC00: for joystick port 1, set bit 6 = 1 and bit 7 = 0; for joystick port 2, set bit 6 = 0, bit 7 = 1. This is the same address as the CIA data register for reading joystick pins on port 2, but you use this address even when connecting the SID to joystick port 1. That's just how the CIA chip is wired.

The program then waits briefly for the SID to get the value. On a C64, this relatively easy: perform a busy-wait loop for some number of iterations. Based on a reference table of cycle counts per instruction, you probably only need 103 or so repetitions of a loop, but it doesn’t hurt to wait longer. The C64 CPU runs at 1 MHz, so 512 CPU cycles is sufficient.

(The MEGA65 normally runs its CPU at 40 MHz. To reproduce the SID reading procedure, you have two options: temporarily down-clock the CPU to 1 MHz for the busy-wait, or perform the busy-wait loop 40 times. Note that instruction cycle counts differ on the 45GS02 CPU than on the 6502.)

After the delay, the values of the two paddles can be read from SID registers $D419 and $D41A. The ROM code that implements the BASIC POT() function takes an additional step to debounce the register value, which just means to wait until two consecutive reads of the register return the same value.

Here is code for the complete procedure, reading the state of both paddles on port 2:

    ; Disable interrupts
    sei

    ; Down-clock MEGA65 CPU to 1 MHz
    ; FAST $D031.6 -> 0
    lda #$40
    trb $d031

    ; Connect SID to port 2 analog inputs
    lda #%10000000
    sta $dc00

    ; Wait for SID to read, ~512 1 MHz cycles
    ldx #$00
-   inx
    bne -

    ; Read port 2 paddles, with debounce
-   lda $d419
    cmp $d419
    bne -
    sta paddle2a

-   lda $d41a
    cmp $d41a
    bne -
    sta paddle2b

    ; Reset MEGA65 CPU to 40 MHz
    ; FAST $D031.6 -> 1
    lda #$40
    tsb $d031

    ; Re-enable interrupts
    cli

; ...

paddle2a:  !byte $00
paddle2b:  !byte $00

Two buttons—and why not a third

The Commodore 64 Games System (1990), aka the C64GS, repackaged the C64 into a keyboard-less console box. To enhance the console’s gaming potential, the Cheetah Annihilator joystick had two buttons: a trigger button in the joystick grip, and a second button that could be detected separately in the base. This two-button protocol worked over the 9-pin connector and could be supported by any C64 game that knew about it. Only a few games were written to support it.

Math wizards may notice that all nine of the joystick port pins have been assigned: up, down, left (or paddle A button), right (or paddle B button), paddle B (“POTY”), fire, +5V, GND, and paddle A (“POTX”). That’s nine. So how is the second button connected?

In the two-button protocol, the second button uses paddle A’s analog line (pin #9, “POTX”). Unlike the other joystick buttons that connect their respective pins to pin #8 (GND, “pulled low”), this button connects pin #9 to pin #7 (+5V, “pulled high”), with a current-limiting resistor to protect the sensitive CIA and SID chips. (One recommended resistance value I’ve seen is 270-330 ohms.) To a program, a button press looks like a paddle dial flipping between its minimum and maximum positions.

The Cheetah Annihilator only had two action buttons, but if someone were to add a third button to such a controller, it would have an easy way to connect: just use the other paddle line (pin #5, “POTY”). This three-button protocol was uncommon in vintage joysticks, but is generally accepted by controller modders and homebrew controller makers, because it’s a natural extension of the two-button protocol, and doesn’t require fancy electronics beyond the button and safety resistor.

The three-button protocol:

• Pin #1: Up, CIA bit 0

• Pin #2: Down, CIA bit 1

• Pin #3: Left, CIA bit 2

• Pin #4: Right, CIA bit 3

• Pin #5: Button C, via POTX

• Pin #6: Button A, CIA bit 4

• Pin #7: +5V

• Pin #8: Ground (GND)

• Pin #9: Button B, via POTY

To read the complete state of a three-button controller, simply combine the techniques for joysticks and paddles. Here’s an example of reading all buttons from port 2 in BASIC:

10 J = JOY(2)
20 D = J AND 128     : REM: THE DIRECTION
30 A = J > 127       : REM: BUTTON A
40 B = POT(3) < 128  : REM: BUTTON B
50 C = POT(4) < 128  : REM: BUTTON C

Reading the additional buttons from machine code is similar to reading the paddle values. A C64 program must still connect the SID to the port, wait for the SID to sense the button value, then read the value from the SID register. A MEGA65 program can just read the paddle registers.

Five buttons??

An 8-way joystick with two or three action buttons brings Commodore gaming one step forward in 1980’s game design language. Math wizards may notice that the NES gamepad has not three but four buttons: A, B, Start, and Select. Can we support all four with minimal changes to the protocol?

5plusbuttonsJoystick, by crystalct, specifies a five-button protocol using a neat trick: button #4 triggers “up” and “down” simultaneously, and button #5 is “left” and “right.” A normal joystick can’t activate these opposing directions at the same time, so they uniquely identify the buttons. This scheme has the disadvantage of not being able to use buttons #4 and #5 simultaneously with the joystick—pressing button #4 and “up” at the same time would only register the button—but they can still plausibly be used as Start and Select buttons, which aren’t typically combined with other buttons during play.

crystalct has published the schematic and board design for a joystick that supports this protocol, and you can order the board from PCBWay. It would be easy to hack a NES-style gamepad to support this with just a few wires. The two buttons are easy to detect with the CIA data registers, though they won’t work with the current version of BASIC 65’s JOY() function, which interprets the directional buttons to direction values only.

The project includes a C64 joystick test program also useful for trying out three-button controllers (PRG download). It works with the C64 core; I had difficulty running it with the MEGA65 core in GO64 mode. crystalct also personally modded dozens of games to add multi-button features—though none use the 4th and 5th buttons, as far as I can tell.

More buttons and bidirectional protocols

Game consoles that followed the NES had seven or eight buttons in addition to the directional pad. How far can we go, using the same 9-pin joystick port?

The protocols we’ve discussed so far could all be considered passive protocols: the controller can report the state of the joystick and buttons to the computer by mechanically completing circuits across the connector pins, and the computer does all the work to interpret these input signals. To be able to report more sophisticated inputs using the same pins, we need an active protocol, where the computer not only reads signals from the controller, but also sends signals to the controller. Perhaps it’d be more accurate to call these bidirectional protocols, because the output signals could be manipulating otherwise “passive” digital electronics in the controller, such as a key matrix. These days, microcontrollers are cheap, and modern game controllers contain tiny computers of their own, capable of an active dialog with the host computer.

The Amiga CD32 game controller provided seven buttons: red, blue, green, and yellow action buttons, left and right shoulder buttons, and one menu button. It used the same 9-pin connector, and did so in a way that allowed the CD32 to support all previous Commodore-compatible passive controllers and allowed the CD32 controller to be used as a passive two-button controller on other Commodores. This required the computer to treat pin #5 as an output pin to select either active or passive mode: the CD32 would hold this pin low relative to the +5V line to request the active protocol—something other Commodores wouldn’t do. When in active mode, the computer sends pulses to the controller on pin #6. With each pulse, the CD32 controller rotates through the seven buttons, reporting the status of each button on pin #9. This mechanism is called a shift register and is typically implemented with a common shift register chip in the controller.

While the backwards-and-forwards compatibility of this design is impressive, it rules out the ability for C64 programs to support a CD32 controller, because the C64 cannot treat pin #5 as an output. Perhaps someday we could add a CD32 controller mode to the MEGA65 core, but there just aren’t many CD32 controllers around. Would be a fun VHDL experiment, though.

Sega game consoles also used a 9-pin connector, though they did not use Commodore-compatible pin assignments. The Sega Master System started with a passive two-button controller protocol, and the Sega Genesis (aka Mega Drive) added more buttons (first 3+1 then 6+1) with an active protocol: one pin was a dedicated output from the console that marched through two, four, or eight cycles, alternating high and low, and the definition for each of six input pins changed for each cycle. The full state table is a bit complex, trying to be backwards compatible with previous standards. (This appears to be based on timing? I got a bit lost trying to read about it.)

I always feel obligated to mention: Do not connect a Sega Master System or Sega Genesis controller directly to a Commodore. The incompatible wiring protocol could damage the delicate CIA chip. The MEGA65 is a bit more robust in this regard, but the MEGA65 core won’t assign the pins in a way that matches the controller.

These newer controllers weren’t the first to take advantage of bidirectional communication to support more buttons. The ColecoVision Hand Controller sported the usual 8-way joystick, and also a number pad with twelve buttons. Surprisingly, this protocol only uses seven of the nine pins, and the computer selects between one-button joystick mode or number pad mode by connecting one of two pins to power. In number pad mode, each button is represented as a combination of the pin signals. For example, when the “5” button is pressed in this mode, pins #2 and #3 are pulled low. When the “4” button is pressed, pins #1, #2, and #3 are pulled low. This means that only one button can be recognized reliably at a time. If “4” and “5” are both pressed, only “4” is recognized.

None of these protocols work with the Commodore 64, and due to the lack of a prevalent commercial implementation, there is no real consensus on a common protocol for Commodore 8-bit computers that supports more than three buttons. One glimmer of hope is the in-progress Protovision Protopad, a project that intends to produce an eight-button controller (four action, two shoulder, two menu) with support for both the passive three-button protocol and a proprietary eight-button protocol, selectable by software. The active protocol uses an elegant and fast multiplexing technique compatible with the C64’s CIA bidirectional capabilities. It’s not clear if or when the hardware part of this project will come to fruition, but the Protopad Development Guide defines the protocol. It’s a fun read. (Well I think it’s fun.)

This brings us back to the topic of MEGA65 mainboard revisions. A Commodore-compatible active protocol game controller would use bidirectional communication over the joystick port data lines, and therefore would require an R6 mainboard. That is, if such a controller existed. I’m rooting for the Protopad, but in the meantime, I’m focusing on passive protocol controllers, which work with both R3 and R6 mainboards.

Modern game controllers and adapters

You can find plenty of vintage Commodore-compatible one-button 9-pin game controllers at flea markets, computer conventions, and online auction websites. Many are still in working order, and hobbyists refurbish and re-sell them. You can also get new 9-pin game controllers ranging from hand-assembled hobbyist projects to limited run Kickstarters to fully manufactured products.

There are also quite a few hobbyist electronics projects to make adapters for non-Commodore game controllers, both new and vintage, so that they work as Commodore 9-pin game controllers. A few of these implement the three-button protocol, or have a way to switch between multiple protocols. You can buy some of these pre-assembled; others are only available as schematics, and require ordering the parts separately and assembling them with a soldering iron.

The following are just a few examples of useful and interesting game controllers and adapters.

Game controllers

RetroGameBoyz gamepads. Mike of retrogameboyz.com has been making new game controllers for vintage computers since 2017. Mike offers a wide variety of styles, platforms, and configurations. My favorites are the NES-style game pads, which include 9-pin connectors, long cables, and attractive decorative faceplates. Mike even makes a MEGA65-themed game pad! This one supports the one-button protocol, and wires the second action button to “up,” which is used as “jump” in many C64 platform games. I’m working with Mike—well, I’ve asked Mike and he’s doing all the work—to produce a custom MEGA65-themed controller that supports the three-button protocol, for future MEGA65 multi-button games.

The Commotron wireless gamepad. The Commotron Gamepad Turbo 2000 Super is a fully assembled gamepad with two unique properties. For one, it’s wireless, with a dongle and a range of six meters. And for two, it supports six remappable button layouts including the an “up” button in addition to the three-button protocol. It’s currently sold out in the Commotron store, but they’re taking pre-orders for more, and third-party sellers still have some.

The Commotron powers on into a mode compatible with the three-button protocol described above, where button “1” is the primary fire button. I couldn’t find the instructions for the Commotron online, so for the benefit of future web searchers:

• Buttons: directional pad (up, down, left, right), Map, Auto; and four action buttons, starting right-most going counterclockwise: 1, 2, 3, and “up.”

• Button 1 is the primary fire button, for one-button games. In C64 mode, buttons 2 and 3 are POTX and POTY, respectively. The “up” button triggers the “up” direction signal, good for “jump” in one-button platform games.

• The controller takes two AAA batteries. The dongle connects to the joystick port and is powered by the computer.

• Both the controller and the dongle have a light on them:

  • Off: no power, or in standby mode.

  • Blinking: waiting to connect.

  • On: connected.

• To connect, press the Auto button.

• To select a preset, hold the Map button and press a direction:

  • Left: Commodore/ZX Spectrum mode (the default). POTX and POTY connect to +5V when active, per the three-button protocol.

  • Up: Amiga and Atari ST mode. These computers connect these pins to GND when active.

  • Right: Atari 7800 mode. Buttons 1 and 2 are “right” fire; button 3 is “left” fire.

• You can swap the functions of button 1 and the “up” button. To swap, hold Map and press Down.

• You can enable auto-fire to have the buttons trigger repeatedly while held down. To toggle auto-fire mode, press Auto. To change the fire rate, hold Map and press an action button:

  • Button 1: 3 clicks per second

  • Button 2: 5 clicks per second

  • Button 3: 8 clicks per second

  • Button “up”: 13 clicks per second

Neo-Atari controllers. The modern-day company that owns the Atari trademark has made a largely successful play for our nostalgia-filled hearts with recreations of vintage consoles with varying degrees of authenticity and modernity. This includes new versions of the classic 9-pin game controllers, including the CX40+ joystick, the CX30+ paddles, and the CX78+ two-button gamepad. (We didn’t get the Atari CX78 in the USA back in the day, so this is news to me!) Wireless models of the CX40+ and the CX78+ are available for pre-order, and will include both 9-pin and USB-A wireless dongles, so you can use them with emulators on a PC and with vintage and retro hardware. I haven’t tested this model of paddles yet and would expect them to support the Atari resistance range.

Hyperkin 9-pin controllers. Hyperkin makes a series of retro gaming consoles, as well as game controller peripherals for consoles old and new. Two of their controllers are compatible with Commodore and Atari computers. The Hyperkin Trooper most resembles the classic Atari CX40, with the fire button duplicated for left-handed and right-handed play. The Hyperkin Ranger is a gamepad-style controller with one fire button, and even includes a single paddle wheel in a unique design. The Ranger also supports left-handed and right-handed play with a switch. Both the Trooper and the Ranger are in stock at Amazon.com.

Note: The Ranger’s paddle wheel is useless on Commodores. The potentiometer covers the full Atari range, 0 Ω to 1 MΩ. Less than a fifth of the throw registers between 0 and 255 with the SID, worse than an Atari paddle. I can barely get a middle value to register in my joystick-paddle tester, and can’t imagine using this paddle knob for Commodore gaming.

Ultimate ArcadeR Classic. The ArcadeR is a one-button protocol 9-pin joystick built to last. It uses arcade-quality parts and is designed to be repairable and moddable, including auto-fire options. The joystick has quite a bit of travel, for better and for worse, and the switches make satisfying click sounds.

Controller adapters

Retro Rewind C64 Genesis adapter. This pre-assembled adapter converts a Sega Genesis controller to a C64/Amiga controller. It supports both the one-button + “up” button configuration and a C64GS-style two-button configuration, selectable by a jumper (a little metal piece you push onto some pins on the adapter). Another jumper changes which pin is used for the second action button: POTX for “C64” mode and POTY for “Amiga” mode. Use this with a vintage Sega Genesis controller, or combine it with the 8BitDo wireless Genesis-compatible controller for cable-free multi-button gaming.

sega-adapter. If you’re handy with a soldering iron, the sega-adapter project is a Sega Genesis controller adapter with some cool features. It supports both the one-button + “up” protocol and the three-button protocol, and you can switch between them by holding the Start button. This project was tested extensively with the 8BitDo wireless Genesis-compatible controller. The microcontroller code is open source, so you can customize it with your own features. Note the special instruction to invert the 2nd and 3rd button signals to comply with the C64 version of the three-button protocol.

mouSTer. I would put the mouSTer multi-function USB 9-pin adapter at the top of my list for lots of reasons, except they’re sold out everywhere, and not available as a DIY board either. This clever versatile device is the best way to connect a modern USB mouse to the MEGA65 or other Commodores, and it also adapts USB gamepads and joysticks with support for the three-button protocol, as well as crystalct’s 5plusbuttonsJoystick protocol. It’s highly configurable: to upload new configuration, put a configuration file on a USB stick and shove the stick into the adapter. I love it, but yeah, it’s currently unavailable.

Unijoysticle 2. This bare board project connects to both joystick ports simultaneously, and pairs with any modern Bluetooth game controller. The C64 model supports the three-button protocol and the 5plusbuttonsJoystick protocol. Normally for sale on Tindie, this one is also out of stock, though designs are available under an open hardware license so you can make your own.

SNES controller adapters. snes2c64 and PadSwitcher64 are two projects with interesting takes on multi-button support. snes2c64 adapts the six-button SNES controller to a three-button C64 controller, using a programmable Arduino Nano for custom button mapping and auto-fire options. PadSwitcher64 connects to both 9-pin joystick ports to support all six SNES buttons with a proprietary passive protocol.

I’m most excited about the possibility of the three-button protocol for MEGA65 games. It’s relatively easy to find pre-assembled controllers, easy to implement in software and modified hardware, compatible with both R3 and R6 mainboards, and is the closest thing we have to an implemented standard for multi-button Commodore-compatible game controllers. I’ll let you know what Mike and I come up with for controllers and software support. If you can get your hands on a Commotron, or are handy enough to build a sega-adapter, those are also good options.

Give joytest65 a try and let me know how it works for your game controllers.

Happy gaming!

— Dan

It’s a busy month! I just got back from the Vintage Computer Festival Midwest (VCFMW), the large-and-getting-larger-every-year vintage computer show. This was my first visit at this particular show, and it was great fun. I bring back a few photos, a few stories, and too much stuff from the free table.

But first, the news.

Catching up on pre-orders; mainboards now available separately

Trenz Electronic is making steady progress on shipping all of the pending MEGA65 preorders, on schedule to get everyone taken care of by the end of the calendar year. A new pre-order for a MEGA65 placed today should have a lead time of only a few months. If you placed a pre-order and have received an email with an invoice, be sure to submit payment promptly. Invoiced but unpaid orders expire within a few weeks, to allocate inventory to others waiting on a pre-order. (Thankfully, you can just re-make your expired order, and you’ll receive it fairly soon.)

With this milestone comes some exciting news! Trenz Electronic is now accepting preorders for MEGA65 mainboards without the enclosure, keyboard, or floppy drive. This is great for electronics projects, custom enclosures, or just keeping a spare. You can make your own keyboard with some effort, and the floppy drive is a standard IDE drive and cable. The standalone mainboards are expected to ship in mid-2025.

Many owners of the 2022 edition of the MEGA65 (mainboard revision R3A) asked for the ability to replace the mainboard with the latest hardware revision (R6), and it’s great that Trenz is providing this option. This is just my opinion, but if you simply want a MEGA65 with the revised hardware, you might get a better result buying a complete new computer, and selling your 2022 edition on the secondary market. The mainboard is more than half the cost of the computer, and unless you want to keep the spare R3 board, you’re unlikely to recoup that cost after an upgrade. Of course, there are no guarantees on the secondary market, but it’s worth giving it a thought. Personally, I own two MEGA65s and a spare board, a Nexys dev board—and dozens of other computers. But you might not want to follow my example.

Speaking of owning lots of computers, Trenz has lifted the one-per-person limitation on MEGA65 pre-orders. If you want to outfit a classroom, hand out MEGA65s at parties, or just make a cool fort out of the boxes, now is your chance!

Thanks as always to everyone at Trenz Electronic for their partnership on the MEGA65 project.

Filehost messaging feature

Filehost, our community file and information sharing board, has a new feature! You can now receive private notifications from the system, and send and receive private messages with other users. If you have a pending notification or incoming message, a red dot will appear on the user icon in the upper right corner.

To receive incoming notifications and messages, you must enable them: go to User menu > User Settings, check “Allow to receive messages from users” and “Inform me about comments on my entries,” then click Submit.

To access your messages: User menu > Messages.

To start a new private conversation with another user: click the plus sign next to Subjects, select the user, enter a subject, then enter the first message. Only users who have enabled incoming messages appear in the list of users.

To add to an existing conversation: select the subject from the list, then scroll to the bottom of the conversation and enter the next message.

Huge thanks to Tayger for this new feature, and all of his work on this essential community resource!

New C64 core documentation

Boris has been working on extended documentation for the C64 core. The docs are now “feature complete,” with coverage of every feature and common task, including how to install JiffyDOS or use the built-in RAM expansion unit (REU). Be sure to send Boris your feedback and thanks, via Discord or email. Thank you, Boris!

Recent Filehost uploads

A few recent Filehost uploads for you to try:

• Quadratic Equation Solver, by fredrikr, an equation root finder

• 3D 4-in-a-row, by fredrikr, a 4x4x4 two-player tile placement game

• Pelota, by SirLazarus, a single-player paddle game; requires a recent ROM beta

• Hang the DJ, by mk9, a Hangman-style word game

• romlister, by nobruinfo, a small utility to list which ROMs you have on your SD card

Greetings from Chicagoland!

I just flew back from Vintage Computer Festival Midwest and boy are my arms tired. Literally. I took my MEGA65, printed table displays, a bunch of backup equipment, and bundles of 45GS02 mousepads to give away. I use this weatherproof hard case when I travel with my MEGA65, and I always carry it onto the plane and put it in the overhead bin. For this trip, the less delicate stuff went into a large checked bag. Who knew 100 mousepads would be so heavy! Thankfully, everything made it there and back safely.

The event took place at the Renaissance Schaumburg Convention Center Hotel, in Schaumburg, Illinois, in the Chicagoland area. The show consumed an entire expo floor and a separate presentation space for talks. This venue is also a nice hotel, and many exhibitors and visitors stayed here or in a nearby Embassy Suites. I didn’t take enough photos to do justice to the scale of this show, but hopefully you can get a sense of it.

I prepared a bunch of table tchotchkes, more than I actually needed, including a colorful banner, an informational standee, a “demo” booklet that someone could use to launch and browse software on the SD card, and various boxed software and accessories. I didn’t have a good way to hang the banner, so it ended up being more of a tablecloth, but it still added some color. I also made business cards with a full-color photo on one side and links to resources on the other. And a custom t-shirt to wear, because why not.

Ladies and gentlemen: the Commodore 65

My table included my MEGA65, Jim Happel’s MEGA65, and two original Commodore 65 prototypes owned by Jim Brain. After having been on the MEGA65 project for two years, it was a real thrill to be able to see a C65 prototype and the MEGA65 side by side. It was also the best conversation starter: most passersby knew the C64 and never heard of the C65, so I could just point to the C65 first, then tell the rest of the story. Several people knew of the C65 and were excited to see it in person, taking selfies with the computer. I took a bunch of photos myself for future reference.

I tried to spend some time with Jim Brain’s copies of the demo disks, both on the C65 and on the MEGA65. It was a sobering reminder of how the C65 prototypes were not ready to be software platforms that the demo disks were hard-coded to specific versions of the ROM. Disks were generally not working on the C65. I could list directories but not load files. I got the IFF slideshow disk to work on the MEGA65—and of course I forgot about the topless woman until it showed up right as some young kids were walking up to the table.

One especially fun find was a message that Fred Bowen posted to the comp.sys.cbm Usenet group on September 17, 1993, subject line, “What’s a C-65???” Fred’s message puts the date of the liquidation sale around July 1993, and claims the prototypes numbered around 50. (According to Brian Bagnall’s Commodore: The Final Years, “By 1991, Commodore had at least 205 pilot production C65 machines. ‘We had a room full of them at one point,’ says [chip designer Bill] Gardei. ‘If you counted all the variants, 205 would not be an unreasonable guess.’”) In the message that follows, “Grapevine” refers to The Grapevine Group Inc. of Suffern, New York, one of two companies known to have acquired and re-sold the prototypes.

From: fred@cbmvax.cbm.commodore.com (Fred Bowen)
Newsgroups: comp.sys.cbm
Subject: Re: What’s a C-65???
Date: 17 Sep 93 14:56:25 GMT
…

Apparently Grapevine picked up some C65’s during Commodore’s liquidation of its warehouse/storage areas a couple of months ago.

What is a C65? A product that almost made it out the door. What you’re seeing are “alpha” pilot-production units. There were only something like 50 units made, and a dozen or more of these were distributed around engineering, system developers, etc. Obviously, they were never meant to be sold to the public, but…

CPU CSG65CE02, running at 3.54MHz
RAM 128K, expansion to ~8MB
ROM 128K, including C65 mode (v10.0), C64 (v2.2) mode, & DOS
Video CSG4567 “VIC-III”
I/O Built-in DMA/blitter
Built-in 6511-type UART, supports MIDI data rate.
All C64 ports: parallel, expansion, etc.
new RAM expansion port, accessible by DMA and video chips.

I guess that’s enough for now. But be warned- these boards are very out of date-the ROMs, PLA’s, etc. are pre-pre-preALPHA, there are absolutely NO spare parts (so if it breaks, that’s it!), all systems are PAL (but they display okay on regular 1084-type monitors in analog mode). Oh, and there aren’t any manuals. I’m surprised that Grapevine can sell them as “new” equipment. Buyer beware, and all that.

All things considered, not a bad machine, though. I still use mine :-)

At some point during the conference, some guy I’d never met showed up at the table and started opening the C65 case. I politely but firmly discouraged him from touching it without Jim Brain’s permission. The guy smiled and introduced himself as Jim Brain. 😅 We were having some difficulty with non-functioning keys on one of the C65s, and Jim noticed a small break in the keyboard ribbon cable that will need repair. Thankfully, and amazingly, Jim has two C65s, so we temporarily swapped the keyboards to form a fully functioning unit. Jim was careful to keep track of the fact that we swapped the keyboards, so they could be reunited with their original cases later.

The C65 prototype is held together with one screw in the front-right of the case near the floppy drive. The rest of the case is all plastic tabs, to make it easy to open and repair. I got to see and photograph the internals of both machines. Developer unit #23 contained the revision 2A mainboard, and a memory expansion module.

As impressive as the C65 is as a historical artifact, I’m relieved to realize that I don’t want to own one. Not that that was ever an option, with working units selling on eBay for $30,000. A recent auction for a broken one ended north of $12,000. The prototype plastic is weird, the keyboards are mushy compared to a good condition production C128, and the working ones barely work and are difficult to maintain. I’m grateful for collectors like Jim for keeping them alive as long as possible and sharing them with the world. And I’m grateful for the MEGA65 for not only letting me access a piece of this history in my own home, but for being a satisfying instrument of recreational computing in its own right.

Reactions

Quite a few people saw the READY. prompt and wanted to type their own GOTO 10 program. Several young kids took the time to write a longer program, though they did it all from memory and didn’t bother exploring the manual. I ended up standing in front of the table and doing guided demos for most of the time. First Shot, Maniac Mansion, and Unicone attracted attention. Nobody bothered with the “demo” booklet, even with encouragement. I’m still glad I made the demo book: the full-color screenshots made it something you could flip through in seconds, and get a glimpse without having to wait for software to load.

I had stacks of the mousepads on the table. At first I was concerned that if I gave away the mousepads for free that they would disappear quickly, and wouldn’t provide much promotional value, so I had intended to maybe sell them at cost, and even made a little for-sale sign for it. I figured out within the first few hours that this wasn’t going to be a problem. I took down my for-sale sign and just arbitrarily handed mousepads to people that seemed even remotely interested in programming. At the end of the last day, I ran around the floor looking for coders I admired by reputation, and used mousepad gifts as excuses to say hi.

I had many good conversations with many people with a wide variety of interests and backgrounds, and I handed out many business cards. Greetz to all the new newsletter subscribers!

Expo highlights

Many of the Commodore exhibits were colocated together in a common section. There ended up being so much diversity in the exhibits that you almost couldn’t tell they were related by platform. I was delighted that my table was next to the brilliant CityXen, who were showing off “Whackadoodle,” their C64-powered whack-a-mole game with giant colorful light-up arcade controller, along with a miniature version with custom handheld controllers.

June of the excellent Nybbles & Bytes was also in my area, demoing and distributing her unique C128 game, Nybbles: Legend of the Drunken Snake. When you first start playing, Nybbles looks like a traditional snake game, until just moments later you eat something unusual and things get utterly wild. The game uses two displays, and manipulates both the VIC-II and the VDC in ways I have never seen before. I waited to the end of the show to buy one to give others a chance, and I did indeed end up with one of the last copies to be distributed on floppy disk. Be sure to subscribe to the Nybbles & Bytes YouTube channel for future updates and technical details about the game.

Right around the corner, I met Craig of BitBinders, maker of 1581 clone floppy disk drives. I was especially impressed by his unique dual drive units, available in both vertically and horizontally arranged variants. I bought one of the horizontal units immediately. Craig already knew about the MEGA65, and we discussed the un-produced Commodore 1565 external drive, and how a modern clone would make a great MEGA65 accessory (along with the expansion board that provides the 1565 mini-DIN connector).

There isn’t enough space to show all the photos of cool and unusual computers I saw throughout the show, but I had such a strong reaction to this one I have to include it. I’ve wanted a Heathkit Hero 1 robot kit all of my life, having only known it through advertisements in magazines. This is the first time I’ve ever seen a Hero in person. The Hero Jr., on its 40th anniversary, was sharing a table with two Androbot Topo robots.

VCFMW is as much a swap meet as a share-out, and about half of the show floor was for sale. Many exhibitors had new and vintage items for sale, and VCFMW also held an auction of unusual items donated by exhibitors to help fund the event. What really gives the convention a pervasive electric air is the ominous entity known as the Free Table. People leave stuff to give away, and other people take stuff they like, a waxing and waning of trash and treasure throughout the convention. The table is largely unsupervised, which gives the added thrill of worrying that something that isn’t free might get taken. (This has happened.) The table this year was well labeled, with a useful partition between the free table and the next table over, so it was pretty chill.

I knew I was flying home, and I’m kind of at my limit for hardware anyway, so pretty much nothing on the free table interested me. I saw some ’90s-era Microsoft software in original boxes pass across the table. My big finds were all books, where at least one person was shedding a nerd’s bonanza of famous titles on computer science and programming. I grabbed what I could carry, and left behind some of my favorite books just because I know I already owned them. I was glad to see the good ones eventually found new owners.

Of course, with the bundles of mousepads, booth decor, and equipment, my luggage was already quite full and quite heavy. The books pushed my checked bag over the weight limit, and ended up costing me a $100 heavy bag fee. So not exactly free. Still a decent haul.

I owe huge thanks to Jim Happel (jim_64 on Discord) for making my VCFMW trip possible. Jim encouraged me to make the trek in the first place, and provided logistical, technical, and moral support throughout the experience. Jim also introduced me to many excellent people in the community whom I’ve known only by reputation online and I now consider friends. This was such a good time, I’m eager to visit the other annual shows around the country as time and budget allows, with my MEGA65 in its carrying case.

Thanks to everyone for your kind words and feedback on EasyAsm v0.1. I’ve only received a couple of bug reports—which just means you’re not trying hard enough to break it! I hope to start a revision as soon as I’m through this very busy month. I’m working on the draft of this year’s community survey, I’m dropping off a kid at college, and I still have the Portland Retro Gaming Expo in a couple of weeks.

Special thanks to all of my supporters, who are making my promotional tours and other projects possible. If you like what I’m doing, please consider becoming a supporter. Visit: ko-fi.com/dddaaannn

Cheers!

— Dan

There’s tons of new stuff for you to download and try this month! kibo has launched a new implementation of a classic graphic adventure game engine capable of playing Maniac Mansion. The group Megastyle has released several new MEGA65 titles. And I’m launching a project of my own: an on-device assembly language programming tool for the MEGA65, called EasyAsm.

Much to discuss, let’s get started!

SCUMM v2 player, by kibo

You can now play the LucasArts graphic adventure-comedy game Maniac Mansion directly on your MEGA65!

kibo made a new implementation of the SCUMM v2 game engine for the MEGA65 capable of playing the classic game, which he calls "MegaSPUTM." This hugely impressive project uses the game data files from the Amiga version, and supports full color graphics, digitized sound, and multiple input devices.

To play Maniac Mansion, you need to acquire the original game data files. If you own the disks, you can use Amiga disk management tools to extract the .LFL files. MegaSPUTM works with both the English and German versions of the data files.

The full procedure takes a few minutes. I got it up and running like so:

1. Download kibo’s SCUMM v2 engine from Filehost. Expand the .zip archive to produce D81 disk image files mm1.d81 and mm2.d81.

2. Retrieve the .LFL files from the rooms/ folder of the first disk of Maniac Mansion for the Amiga. If your media is in the form of an ADF disk image, there are several tools you can use. I found this cute browser-based ADF reader, which does everything locally on your computer and doesn’t require uploading data to a remote server. It’s a bit obnoxious that you have to select and “download” each .LFL file individually, but it works, and doesn’t require installing anything.

3. Use a D81 disk image tool to place the .LFL files from the first ADF onto mm1.d81. Here too you have your choice of tools. I like droid64, a Java UI application. If you use DirMaster and possibly some others, you may need to rename the files to use lowercase .lfl before adding them to the disk. (droid64 will lowercase it in transit.)

4. Repeat steps 2 and 3 for the 2nd game disk and mm2.d81.

5. Transfer mm1.d81 and mm2.d81 to the root of your MEGA65’s SD card.

Now on the MEGA65, MOUNT and BOOT the mm1.d81 disk image. Crank those speakers, and use a joystick or a mouse!

The original Maniac Mansion game included a printed booklet entitled “Nuke’m Alarms Owner’s Disarmament Quick Reference Guide,” which was needed early in the game. Similar to SCUMM VM and Disney's own re-release of Maniac Mansion, this is not needed when playing the game with MegaSPUTM.

C programmers, don’t miss the source code, which is chock full of examples of how to do common and interesting things on the MEGA65 in C.

New titles from Megastyle

The group Megastyle has not one, not two, but three releases for the MEGA65 this month!

Mega Invaders (itch.io link), an homage to Space Invaders, is a MEGA65 original with all of the nostalgic arcade game graphics and sounds you crave. Be sure to switch to PAL video mode before running the game. Joystick in port 2.

Omega Race (itch.io link) is a direct port of the VIC-20 space war game to the MEGA65. Nearly all of the VIC-20 code is intact, with only small patches required to get it to run.

In Skramble, also a VIC-20 port, you fly over a landscape, destroying enemies. Check out the blog article about the original game for the impressive technical details of how an unexpanded VIC could render such large levels.

Don’t miss all the great C64 and Amiga titles in Megastyle’s catalog. Their Empire Strikes Back remake is one of my all-time C64 faves.

Snake65, by piramania

Snake65 by piramania is a modern take on a classic. It features six levels of challenging snake gameplay and charming music, and is written entirely in BASIC 65. Use W, A, S, and D on the keyboard as controls.

Mondrian Simulator, by Drex

Mondrian Simulator, by Drex, is a MEGA65 demo that generates artwork in the style of abstract artist Piet Mondrian. Press S to start a meditative slideshow.

MEGA65 Command Line Tools v1.0

The MEGA65 project includes a collection of command-line tools for development and testing, using a JTAG adapter to remotely control a MEGA65 from a PC. These tools have recently acquired new features for transferring files, ROMs, and programs over Ethernet, as well as a revised tool for core management. The M65Connect desktop application uses these tools behind the scenes, and I use these tools regularly as part of a cross-development workflow.

You can now download a formal release package of the latest command-line toolkit, version 1.0. Get it for Windows, macOS, and Linux. The tools in this package:

• m65 : A multi-tool for testing, debugging, and interacting with the MEGA65 over a JTAG/UART serial adapter.

• mega65_ftp : Transfer files to and from the MEGA65 SD card, via Ethernet or JTAG/UART.

• etherload : Send programs and ROMs to the MEGA65’s memory over Ethernet for testing.

• coretool : Convert MEGA65 bitstreams to cores, and manage core metadata. Requires Python 3.

• romdiff : A binary patch generator, used for producing ROM patches.

Mac users, remember to remove the “quarantine” attribute of the tools before using them: xattr -d com.apple.quarantine m65.osx

New list of alternate cores

Looking for alternate cores available for the MEGA65? Boris Schneider-Johne has taken over maintaining the cores list from sy2002, and it now has an easy-to-remember address. Visit cores.mega65.org to be redirected to the new list. Thanks to Boris for preparing and maintaining this documentation!

September conferences

A quick update on those September conferences in the USA: I still plan to be at the Vintage Computer Festival Midwest, September 7-8 in Schaumburg, Illinois. For the first time in the show’s history, VCFMW received more talk proposals than available slots, and my proposal was not selected this year. I’m grateful that they have a presentation track at all, with a full-time volunteer staff to make quality recordings for YouTube. I have confirmed that we’ll have a table—and we might even have a real Commodore 65 next to the MEGA65!

I splurged on getting some fun booth display items printed professionally, something I’ve always wanted to try. The cloth banner and table signage turned out very nicely. I also placed a bulk order of 45GS02 CPU quick reference mousepads.

I, my MEGA65, and my mousepads will also be at the Portland Retro Gaming Expo, September 28-29 in Portland, Oregon. Come say hi, if you can!

Introducing EasyAsm

EasyAsm is a new assembly language programming tool for the MEGA65. EasyAsm runs entirely on the computer, with no need for a separate PC. It is designed to work with the existing MEGA65 environment, to give you as much control and understanding of the computer as possible, and to take advantage of the MEGA65’s existing programming workflow. EasyAsm provides a powerful subset of the syntax and features of the Acme cross-assembler, so that you can use it with the assembly language programming examples in the documentation and in this Digest, as well as for larger programs.

• Download EasyAsm from Filehost.

• See the Github repo for full documentation and source code, and to file bug reports and feature requests.

• Note: Assembling to disk requires a recent ROM beta version, 920401 or later. This will also work in the upcoming v0.97 MEGA65 platform release.

I was inspired to write EasyAsm while playing with vintage on-device assemblers for the Commodore 64. Many of these used the C64’s built-in BASIC line editor for entering assembly language source code, giving the programmer a familiar environment for managing code without the overhead of a proprietary text editor application or file management system. I realized that not only was this possible on the MEGA65, the MEGA65 could do it better and more intuitively thanks to its powerful memory management architecture, and a little-known feature of the BASIC: Edit mode.

An important note

Save your work to disk, early and often.

Writing a program for a microcomputer using the microcomputer itself comes with the inherent risk that a bug in your program will interfere with your programming environment. EasyAsm preserves your source code in memory while you are testing your program, but this cannot be guaranteed to work if the program does something unexpected.

By design, EasyAsm does not force you to save your work to disk before testing your program. Please remember to do this yourself.

With this announcement, I am releasing the first version of EasyAsm, which I’m calling “version 0.1.” I have tested it to the best of my ability, but it may still have bugs, including bugs that may lose data. If you find any bugs, please report them!

A canonical first program

To start an EasyAsm session, mount and boot the EASYASM.D81 disk image:

MOUNT "EASYASM.D81"
BOOT

Try entering the following program at the OK prompt. To enter the blank line on line 20, type 20 then press Shift + Space, then press Return.

10 !TO "SIMPLE", RUNNABLE
20
30   INC $D020
40   RTS

Type LIST to see the listing.

Before doing anything else, save this source file to disk:

DSAVE "SIMPLE.S"

Next, press the Help key to open the EasyAsm menu.

Select option #1: Assemble and Test. (Press the 1 key.) EasyAsm assembles the program, then runs it. In this case, the program you entered does two things: it changes the color of the border (inc $d020), then ends the program (rts).

Type LIST again. The source code is in memory, and you can continue to make changes to the program.

Let’s make a small improvement. The register at hexadecimal address $D020 controls the border color, but this is not obvious from the program listing. It’d be better to assign a label to this value, so it’s easier to see what’s going on. Insert the label definition with line 25, and replace line 30:

25 BORDER = $D020
30   INC BORDER

Save the source file to disk again, this time using the @ symbol to tell DSAVE to replace the existing file.

DSAVE "@SIMPLE.S"

Press Help then 1 to assemble and run the program again, to confirm that it still works.

Using Edit mode

Edit mode is very similar to the usual BASIC mode. You can type any BASIC command at the prompt, and it’ll do it right away. The main difference is that when you type a numbered line, instead of treating it as BASIC code, Edit mode treats it as PETSCII text. The DSAVE and DLOAD commands also have special behavior in Edit mode, operating on sequential files (type SEQ) instead of program files (type PRG). You can use Edit mode to write any kind of text file, like a (very) simple word processor. With EasyAsm, you can use it to write assembly language programs.

Editing works just like in BASIC. When you enter a new line, the program updates based on the line number, either inserting the line in sequence or replacing an existing line of that number. To delete a line, enter just the number, then press Return. All of the built-in tools for line editing, such as the AUTO and RENUMBER commands, are available in Edit mode. See the User’s Guide for information about these commands.

Type DIR to see the list of files on the disk. Notice that the SIMPLE.S file you created is of type SEQ.

Type NEW to clear program memory. Type LIST again to confirm that the source code is no longer in memory. Then re-load the source file:

DLOAD "SIMPLE.S"

Type LIST. The source file is the same—but the line numbers have changed!

1000 !TO "SIMPLE", RUNNABLE
1010
1020 BORDER = $D020
1030   INC BORDER
1040   RTS

This is a notable difference between Edit mode and BASIC mode: Edit mode does not include the line numbers when it saves the file. This is usually what you want when editing a text file, and for EasyAsm, the line numbers don’t affect how the program is assembled. However, it does mean that if you try to organize your code using groups of line numbers like you might in a large BASIC program, that organization effort is not saved between sessions.

You’ll want to get familiar with the RENUMBER command, which can insert a range of unused line numbers in the middle of your source code. For example, to renumber all lines from 1030 onward so that they start at number 2000 counting by 10s, thereby leaving a gap of available line numbers between 1030 and 2000:

RENUMBER 2000,10,1030-

EasyAsm enables Edit mode automatically when you boot the disk. To disable Edit mode and return to BASIC mode, use this command: EDIT OFF To re-enable Edit mode: EDIT ON

Remember that when you're in BASIC mode, the prompt says "READY," and when you're in Edit mode, the prompt says "OK." Take care to notice which mode you are in before typing in lines of a program, and before loading or saving source files. If you type a line of assembly language source while in BASIC mode, it will attempt to interpret the line as BASIC code, and produce incorrect results. And if you try to DSAVE the source file while in BASIC mode, it’ll save as a PRG file.

Assembling to disk

With the SIMPLE program’s source code in memory, press Help to open the EasyAsm menu. Now select option #2: Assemble to Disk. EasyAsm assembles the program, but instead of running it, it creates a new PRG file on disk, named "SIMPLE". You specify the name of the program file using the !to directive in the code.

10 !TO "SIMPLE", RUNNABLE

Type DIR to see the SIMPLE program file of type PRG alongside the SIMPLE.S source file of type SEQ.

I like to use a .S suffix for source code filenames, then omit the suffix for the program name. Take care to not use the same name for the source file and the program file, so that EasyAsm does not overwrite your source file with the program file.

Let’s try out the new program. Switch back to BASIC mode, then load and run the SIMPLE program, like any other program:

EDIT OFF
DLOAD "SIMPLE"
RUN

The program changes the border color, then exits.

In a previous Digest, we used the Acme cross-assembler to make a program like this, using a lengthy preamble to produce a runnable program:

!cpu m65
!to "hello.prg", cbm

* = $2001

!8 $12,$20,$0a,$00,$fe,$02,$20,$30,$3a,$9e,$20
!pet "$2014"
!8 $00,$00,$00

	inc $d020
	rts

This would work in EasyAsm just as well: EasyAsm supports the cbm output type similar to Acme. But EasyAsm has a feature that makes this easier. When you tell the !to directive to make a runnable file, EasyAsm generates this preamble for you, including setting the program counter. In fact, this cbm listing and the runnable version you typed produce exactly the same output.

The PRG file contains your program and only your program. Give it to your friends so they too can change the colors of their borders!

How to stop a running program

When you assemble-and-test your assembly language program, EasyAsm attempts to recreate the memory layout that your program will see when it runs from disk. To do this, it first copies your source code out of program memory, so it can replace it with the assembled program for testing. EasyAsm watches for the program to exit using the rts instruction, then copies the source file back into program memory so you can continue to edit it.

That’s nice, but it’s not always possible—or even desired. A typical machine code program never exits. A broken machine code program might get stuck before it can exit.

Try entering a slightly different program:

10 !TO "FOREVER", RUNNABLE
20
30 LOOP:
40   INC $D020
50   JMP LOOP

Assemble and run the program. This program changes the border color repeatedly, in an infinite loop. It does not exit.

To interrupt this program and return to BASIC, hold Run/Stop and press Restore. The program stops, and the MEGA65 Monitor starts. Type X then press Return to exit the Monitor and return to the OK prompt.

Now type LIST.

Uh oh, there’s something wrong with the first line! EasyAsm did not see the program exit with the rts instruction, so it didn’t get a chance to restore the source file. The assembled instructions are still in program memory, having overwritten the source.

When this happens—and it will happen often—use menu option #9 to tell EasyAsm to bring back the source file. Press Help, then press 9. Type LIST again to see the restored source.

How EasyAsm uses memory

EasyAsm tries to maintain a minimal memory footprint while you are editing your source code, and while your program is running. This allows you to use all the tools at your disposal for editing, and allows your program to use most of the computer, while still retaining a useful on-device workflow.

Of course, EasyAsm has to live somewhere. This is what EasyAsm needs:

• EasyAsm reserves the memory ranges $1E00-$1EFF (256 bytes of bank 0) and $8700000-$87FFFFF (1 megabyte of Attic RAM). If your program overwrites any of this memory, you will need to reload EasyAsm, and any stashed source code data may not be recoverable.

• EasyAsm reserves the right to overwrite $50000-$5FFFF (all 64KB of bank 5) when you invoke EasyAsm. Your program can use this memory while it is running, but the state of this memory may change when EasyAsm is running. Overwriting this memory may inhibit EasyAsm’s ability to return to the OK prompt on rts.

EasyAsm will refuse to assemble to addresses $1E00-$1EFF when assembling to memory, or when assembling a runnable program to disk (because the bootstrap routine may use it in the future). This restriction does not apply when assembling to disk in cbm mode.

If your program needs to use $1E00-$1EFF for its own purposes, that’s entirely fine. Just be aware that it will interfere with the EasyAsm workflow.

What’s next for EasyAsm?

I’m fairly confident that I could have used this initial version of EasyAsm to write many of the programs I’ve written for the MEGA65 so far. There are a few features I want to add to really make it feel like a complete assembler:

• !binary: embed a file of binary data into a program (such as graphics or sound assets)

• !source: use multiple source files to describe a program (such as with reusable libraries), and to produce programs larger than Edit mode’s 44 KB memory limit for a single source file

• Inspect an annotated source listing with program counter and byte values next to the original source lines (Acme’s “report” feature)

• Inspect a list of label definitions (Acme’s “symbol list” feature)

I have a roadmap of other feature ideas that I’m considering, though they’ll take more substantial work and I want to see if anyone actually uses EasyAsm first. 😇 To me, the most important of these would be macros, a feature of Acme and other assemblers that makes programs easier to write, test, and manage. It's possible to write substantial programs without macros—the MEGA65 ROM source has no macros in it at all—but macros are a powerful way to organize code, reuse common structures, and mitigate some of the fragility of the low-level language.

As clever as Edit mode is, it would be nice to have a more modern IDE-like text editor as an option. I have plenty of ideas and opinions, and would love to try implementing them. That said, I intentionally designed EasyAsm so that it could be integrated into other projects, so someone else could implement supplemental tools.

I wrote EasyAsm from scratch in pure assembly language. I learned a lot about assembly language from this experience, and will be milking this for content writing about this in future episodes of the Digest.

I included a few sample programs on the D81 disk image based on previous Digest and blog articles. Try loading their source files and assembling them. The longest file on the disk right now is my assembly language implementation of Robot Finds Kitten, 35 KB of source that assembles in six seconds.

Want to see continued development of EasyAsm, or my other projects like this Digest? Please consider becoming a patron. Visit: ko-fi.com/dddaaannn

I hope you try EasyAsm, and I hope it makes it easier to get started with assembly language programming. Let me know how it goes!

— Dan

I feel like painting today. Let’s paint!

Oh, uh, but first…

The Silent Enigma

The Silent Enigma is a new demo by Gurce, based on the song by Anathema. Gurce wrote the demo in BASIC 65 with the Eleven IDE, with assembly language helper routines in Mega Assembler and Acme, and an extended version of grim-fandango’s MEGAPLOT library.

The current version of the demo requires customized versions of the MEGA65 core and ROM to run on MEGA65 hardware. Gurce discovered a need for a new feature of the KERNAL for combining BASIC and machine code routines, and also discovered a core bug while getting it to work. We’re working on getting these improvements into the core platform. In the meantime, Gurce is distributing modified core and ROM files with the demo.

Check out retroComb’s video debuting The Silent Enigma, along with an interview with Gurce. And don’t miss the Eleven and assembly language source files included on the disk!

My talk at PaCommEx NW is online

My talk about the MEGA65 at Pacific Commodore Expo Northwest 2024, Lessons from My First Two Years with the MEGA65, is now on YouTube. My thanks to Robert Bernardo for producing the event, to Stephen Jones and SDF.org for sponsoring, and to everyone who attended. We had three MEGA65s on the floor this year, including a live unboxing of a freshly delivered unit!

C64 core v5.1 released

The C64 core for the MEGA65, one of the best things you can do for your favorite computer, has a new update. Version 5.1 adds support for the R6 mainboard, the board in all MEGA65s being delivered this year, and can take advantage of the R6 board’s bidirectional expansion port lines for Kung Fu Flash, MSSIAH, and freezer cartridge support. This update also includes improvements for all mainboards, including the ability to share the MEGA65’s Real-Time Clock with GEOS, using an appropriate driver.

Don’t forget that the MEGA65 has a new feature that can select the C64 core automatically when a C64 cartridge is installed. If your MEGA65 was delivered this year, your firmware is already up to date with this feature. If you have an older MEGA65, you can update to the v0.96 release in “slot 0” to get this feature. See the User’s Guide, 2nd edition, for upgrade instructions.

See the C64 core release notes for details on all of the changes.

retroCombs MEGA65 Video User’s Guide

retroCombs is producing a video series based on the MEGA65 User’s Guide, 2nd edition. Steven is going chapter by chapter, reviewing the material, and presenting it in an entertaining and easy-to-understand fashion. It’s the perfect video companion to the Guide, and a useful resource in its own right, with additional tips not mentioned in the book. Steven just released the video for chapter 4, and intends to complete the series for the entire book.

Subscribe to retroCombs to make sure you don’t miss a video!

Canvas

I need a canvas to paint on. Something 320 pixels wide and 200 pixels tall is good enough to start. I just want to use the 32 built-in colors for now, so a bit depth of 5 is plenty. (Five binary bits can express up to 32 values: 2 x 2 x 2 x 2 x 2 = 32.) I’ll use screen number 0.

SCREEN 0,320,200,5

Yes, that’s fine. I can’t see what I’m typing now because the text is behind the painting, but I can hold Run/Stop and tap Restore to get back to the text screen.

Blank canvases are intimidating. Whenever I buy a new notebook, I always scribble nonsense on the first page, so I’m not afraid to make mistakes on the other pages. I’ll take a swipe with some white paint (color 1).

PEN 1
LINE 20,30,300,180

I can specify locations on the canvas using numbers, one for the distance in pixels across from the left (the X coordinate), and one for the distance down from the top (the Y coordinate). With a 320 x 200 screen, coordinate X=0 Y=0 is the top-left corner, and X=319 Y=199 is the bottom-right corner. I drew my line from the position X=20 Y=30 to X=300 Y=180.

The 32 colors of the built-in palette are listed in the MEGA65 User’s Guide, 2nd edition, appendix E. The first 16 of these are also written on the fronts of the number keys on the keyboard from 1 to 8, in two rows: colors 0 through 7 are the top row (“Blk” through “Yel”), and colors 8 through 15 are the bottom row (“Orng” through “L Gry”).

I need to switch back to the canvas to see my white line. I’ll set my screen 0 to be both the canvas I’m drawing on and the canvas I’m looking at.

SCREEN SET 0,0

I notice that typing SCREEN 0,320,200,5 again will not switch back to the existing canvas, it’ll open a new blank one. Here’s a way to clear an already-opened canvas, by filling it with color #6 (blue):

SCREEN CLR 6

Flipping back and forth between the text screen and the canvas is a bit cumbersome. I think I’ll put all of my painting commands into a BASIC program. This way, the MEGA65 can recreate my picture by following my painting instructions, and I can save my program to a floppy disk.

10 SCREEN 0,320,200,5
20 PEN 1
30 LINE 20,30,300,170

DSAVE "LINE"

RUN

I can press Run/Stop + Restore to get back to text mode, make changes to the program, and RUN it again to see the result.

If I wanted to give this program to someone else, they might enjoy being able to exit back to text mode by pressing a key. Here’s a simple way to do that:

9998 GETKEY A$
9999 SCREEN CLOSE 0

In addition to lines, BASIC has commands for drawing dots, and drawing shapes of several kinds, both filled and unfilled. I’m just messing around, changing the numbers to see how they change the picture.

40 PEN 2
50 DOT 4,4
60 DOT 5,5
70 DOT 6,4
80 DOT 7,5
90 DOT 8,4

100 PEN 3
110 BOX 180,10,240,50
120 BOX 200,30,260,70,1

130 PEN 4
140 CIRCLE 50,150,24
150 CIRCLE 70,130,24,1

160 PEN 5
170 ELLIPSE 180,150,50,20
180 ELLIPSE 160,130,50,20,1

190 PEN 6
200 POLYGON 250,100,40,40,5
210 POLYGON 270,120,40,40,5,,,,1

Of course, the User’s Guide has more information on how these commands work, including some additional interesting features.

Here is a simple picture I made.

5 BORDER 0
10 SCREEN 0,320,200,5
20 PEN 27:BOX 0,0,319,30,1
30 PEN 28:BOX 0,31,319,60,1
40 PEN 29:BOX 0,61,319,90,1
50 PEN 30:BOX 0,91,319,120,1
60 PEN 0:CIRCLE 220,280,200,1
70 BOX 200,60,240,60,230,90,210,90,1
80 BOX 200,48,240,48,250,60,190,60,1
90 BOX 210,42,213,42,213,48,210,48,1
100 PEN 7:BOX 222,65,227,65,226,72,223,72,1
110 PEN 11:CIRCLE 213,36,4,1
120 CIRCLE 223,33,3,1
130 CIRCLE 232,31,4,1

Computer art

Wherever there’s a number in a computer program, there could also be some computation that produces a number. This can turn math formulas, variables, and flow control structures into their own kind of computational paintbrush.

I want to try a simple grid pattern with regularly spaced lines. Instead of writing out all of the coordinates for each line, I’ll have the MEGA65 figure it out for me.

5 BORDER 0
10 SCREEN 0,320,200,5
20 PEN 1
30 FOR X=0 TO 319 STEP 20
40 LINE X,0,X,199
50 NEXT X
60 FOR Y=0 TO 199 STEP 20
70 LINE 0,Y,319,Y
80 NEXT Y

I can tell the computer how to calculate a number. Or, I can just let the computer pick a number at random. The computer can use its own imagination to paint a picture, in accordance with my instructions. (well actually computers don’t have imaginations and random numbers aren’t really random and whatever it’s fun)

5 BORDER 0
10 SCREEN 0,320,200,5
20 PEN RND(1)*32
30 LINE RND(1)*320,RND(1)*200,RND(1)*320,RND(1)*200
40 GOTO 20

BASIC 65 has some mathematical functions that can help paint interesting pictures, if I can remember enough geometry.

5 BORDER 0
10 SCREEN 0,320,200,5
20 FOR Z=0 TO 4
30 PEN RND(1)*32
40 R=RND(1)*40+20
50 CX=RND(1)*200+60
60 CY=RND(1)*80+60
70 FOR A=0 TO 2*π STEP 2*π/30
80 LINE CX,CY,CX+COS(A)*R,CY+SIN(A)*R
90 NEXT A
100 NEXT Z

Those symbols on line 70 are the Greek letter pi (π), which I typed with Shift + up-arrow. In BASIC 65, this is the geometric constant pi, defined as the circumference of a circle divided by its diameter. Someone check my math.

Graphing calculator

I keep my MEGA65 on my desk and sometimes just use it as a simple calculator, typing a question mark ? followed by an arithmetic expression at the READY. prompt to get a quick answer. I wonder if I could make the MEGA65 into a graphing calculator.

1 DEF FN Y(X) = SIN(X*9)+1.5
2 XL = -3 : XH = 3
3 YL = -1 : YH = 4
4 REM ======================
5 BORDER 0
10 SCREEN 0,320,200,5
20 REM ==== DRAW AXES
30 PEN 12
40 IF 0 < XL OR XH < 0 THEN 70
50 V = 0:L = XL:H = XH:SC = 320:GOSUB 1000:XC = C
60 LINE XC,0,XC,199
70 IF 0 < YL OR YH < 0 THEN 100
80 V = 0:L = YL:H = YH:SC = 200:GOSUB 1000:YC = 199-C
90 LINE 0,YC,319,YC
94 IF XC > 351 THEN XC = 351
95 IF YC > 192 THEN YC = 192
100 CHAR 0,YC+1,1,1,2,STR$(XL)
110 CHAR 39-LEN(STR$(XH)),YC+1,1,1,2,STR$(XH)
120 CHAR XC/8+1,0,1,1,2,STR$(YH)
130 CHAR XC/8+1,191,1,1,2,STR$(YL)
140 REM ==== DRAW FUNCTION
150 PEN 7
160 PX = 0
170 V = FN Y(XL):L = YL:H = YH:SC = 200:GOSUB 1000:PY = SC-C
180 FOR X = XL TO XH STEP (XH-XL)/160
190 V = X:L = XL:H = XH:SC = 320:GOSUB 1000:NX = C
200 V = FN Y(X):L = YL:H = YH:SC = 200:GOSUB 1000:NY = SC-C
210 LINE PX,PY,NX,NY
220 PX = NX : PY = NY
230 NEXT X
999 END
1000 REM ==== SCALE V TO C WITHIN RANGE (L,H) BY SC
1010 C = (V-L)/(H-L)*SC
1020 IF C > SC THEN C = SC
1030 IF C < 0 THEN C = 0
1040 RETURN

Huh… That’s interesting…

I think I got the gist of this right. The first few lines define the function to be plotted, and the domain (XL to XH) and range (YL to YH) to use for the graph.

The subroutine starting on line 1000 scales a value V to screen coordinate C within value range (L,H) scaled by SC. For example, to convert an X value to a horizontal screen coordinate, I set V to the X value, L to XL, H to XH, and SC to 320 (the pixel width of the screen). The subroutine returns with C set to the horizontal screen coordinate.

190 V = X:L = XL:H = XH:SC = 320:GOSUB 1000:NX = C

I use this subroutine for every such conversion. Importantly, I need to invert the vertical coordinate that comes back from this, because math graphs go up as Y values increase, but screen coordinates go down. So PX = C, and PY = SC-C.

To keep this simple, I only draw a zero-axis if the zero is within the range/domain, and I don’t bother with tick marks. I use the CHAR command to print the range/domain values close to the zero-axis lines, if appropriate, making sure they stay on screen.

To draw the function itself, I calculate a starting point based on its value for the leftmost point on the screen, FN Y(XL), then loop over 160 evenly spaced points between XL and XH. For each iteration, I draw a line from the previous point to the next. PX/NX and PY/NY are the previous and next horizontal and vertical screen coordinates.

Real graphing calculators are pretty sophisticated. They need to be to produce something useful under all circumstances. For example, I just allow a graph that goes off the top or bottom of the screen to squash up against the edge. The LINE command doesn’t mind receiving fractional coordinates, but it will complain if I give it values outside of the screen. This could be improved by calculating exactly where the graph crosses the edge. But I’m painting here, not building something useful.

Also my sine graphs have a bit of a cowlick in some spots, for some reason. I’m guessing this is hitting up against the range limits of BASIC 65 floating point numbers. Math is hard. 🤷 Moving on…

Paintbrush

Painting with code is fun, but this computer can do more than use hand-entered numbers or numbers derived from math and randomness. I can also write a program that changes numbers interactively based on keys I press on the keyboard. Here’s the simplest version of this idea:

10 SCREEN 0,320,200,5
20 X=100:Y=100
30 PEN 1
40 DOT X,Y
50 GETKEY A$
60 IF A$=CHR$(17) AND Y<199 THEN Y=Y+1
70 IF A$=CHR$(29) AND X<319 THEN X=X+1
80 IF A$=CHR$(145) AND Y>0 THEN Y=Y-1
90 IF A$=CHR$(157) AND X>0 THEN X=X-1
100 GOTO 40

This operates similarly to our Robot Finds Kitten experiment from a while back. The program maintains a cursor position in the X and Y variables. It waits for a keypress, then compares it to the PETSCII codes for the cursor keys. After it confirms the cursor position won’t leave the screen, it changes the cursor position, then draws a dot. I can move the dot around the screen, and it leaves a trail, like an Etch-a-Sketch.

I could also make this controllable with a joystick, with almost no changes:

10 SCREEN 0,320,200,5
20 X=100:Y=100
30 PEN 1
40 J=JOY(2)
50 DOT X,Y
60 IF J=5 AND Y<199 THEN Y=Y+1
70 IF J=3 AND X<319 THEN X=X+1
80 IF J=1 AND Y>0 THEN Y=Y-1
90 IF J=7 AND X>0 THEN X=X-1
100 GOTO 40

Whoa! Uh, slow down there, partner:

55 SLEEP 0.01

This only supports four directions of movement, and actually feels like it sticks when I accidentally press the joystick in a diagonal direction. The JOY() function returns different values for diagonals. (See the User’s Guide.) This should work.

60 IF (J=4 OR J=5 OR J=6) AND Y<199 THEN Y=Y+1
70 IF (J=2 OR J=3 OR J=4) AND X<319 THEN X=X+1
80 IF (J=8 OR J=1 OR J=2) AND Y>0 THEN Y=Y-1
90 IF (J=8 OR J=7 OR J=6) AND X>0 THEN X=X-1

It’d be nice if I had more control over the paintbrush behavior. Maybe if it doesn’t draw unless I press the button?

50 IF J AND 128 THEN DOT X,Y:J=J AND 127

JOY() returns a value 0 through 8 representing the joystick direction, plus 128 if the fire button is pressed. I’m using a bitwise AND both to test the button on its own, and to erase the button part of the value for the rest of the comparisons.

OK that works, but now I can’t really see what I’m doing. Before, it was always drawing, so I could usually see where it will draw next when I move. Now it’s only drawing when the button is pressed. I need some kind of cursor on the display that doesn’t draw into the image itself.

On Commodores, that’s what sprites are for. We covered sprites, yeah? I’m just going to use the built-in arrow sprite for now:

15 SPRITE 0,1

45 MOVSPR 0,X+24,Y+50

Remember that the sprite coordinate system is not the same as the screen coordinate system inside the border. The upper corner for a sprite is X=24, Y=50, so I need to add these values to the MOVSPR command.

That’s pretty good… Looks like there might be a bug in sprite coordinates over bitplanes. We’ll have to look into that.

That arrow cursor reminds me, I could also write this to use the mouse. This simplifies the code quite a bit because the KERNAL does its own range checking on the mouse position. My program just needs to read the mouse position, check for the button press, and draw a dot there if it is pressed. I still need to offset the mouse coordinates when I draw, this time in the other direction because X and Y are set to sprite coordinates by the RMOUSE command.

10 SCREEN 0,320,200,5
20 MOUSE ON,1
30 PEN 1
40 RMOUSE X,Y,B
50 IF B THEN DOT X-24,Y-50
60 GOTO 40

That’s neat! The dots are a bit spread apart though. I wonder if I can combine this with the technique in the graphing calculator to get a smoother line while the button is pressed.

10 SCREEN 0,320,200,5
20 MOUSE ON,1
30 PEN 1
40 PX=-1
50 RMOUSE X,Y,B
60 IF B<>128 THEN PX=-1:GOTO 50
70 X=X-24:Y=Y-50
80 IF PX=-1 THEN 100
90 LINE PX,PY,X,Y
100 PX=X:PY=Y
110 GOTO 50

Hmmm…

41 SPRITE 0,1,1

51 GET A$:IF A$<"1" OR A$>"9" THEN 60
52 PEN VAL(A$)
53 SPRITE 0,1,VAL(A$)

Maybe…

90 CIRCLE X+RND(1)*10-5,Y+RND(1)*10-5,RND(1)*5,1

And what about…

42 SC=1

61 SC=SC-1
62 IF SC>0 THEN 70
63 SOUND 1,RND(1)*65535,5
64 SC=50

Oh, here’s an idea…

90 LINE PX,PY,X,Y
91 LINE 320-PX,PY,320-X,Y
92 LINE PX,200-PY,X,200-Y
93 LINE 320-PX,200-PY,320-X,200-Y

That was fun!

Did I forget to include screenshots of my paintings? Ah, well. I suppose you can always just type these in and see what happens.

If you liked this one, please consider supporting the Digest with a contribution. I hope to continue making more of these, and your support goes a long way to making that possible. Visit: ko-fi.com/dddaaannn

Happy painting! See you next month.

— Dan

The Summer of MEGA65 begins! The latest delivery batch is in progress, and many preorder holders are receiving their new favorite computer.

If you’re new to this Digest, welcome! Here you’ll find news about the MEGA65 and community projects, and interactive feature articles of things you can try for yourself. Read the Digest while next to your MEGA65 and PC for the best experience.

Also, every Digest has a read-aloud audio edition. Click the audio player at the top of the email or website, or subscribe to “Dan’s MEGA65 Digest” in your podcast player. I don’t know how many people listen to it, but I enjoy making it.

In this Digest, we’ll start taking a look at the MEGA65 KERNAL, the main operating system of the computer. We’ll build off of last month’s discussion of interrupts and the CPU memory map, and try writing a MEGA65 version of a classic KERNAL extension: a desktop time-of-day clock.

Let’s get started!

Batch #3 is arriving!

MEGA65 home computers are now arriving with their new owners! Trenz Electronic has begun sending out the third manufacturing batch, and will continue to fulfill pre-orders steadily. Congrats and welcome to everyone receiving a new bundle of joy!

Back in January, we were able to confirm with Trenz that this manufacturing batch will be large enough to cover all preorders placed up to that point. I continue to use that as a conservative estimate. New preorders placed in the last few months may need to wait a bit longer—or maybe not. For all we know, Trenz may be able to make quick work of another batch and get everyone taken care of. Rest assured that everyone involved in this project wants you to have a MEGA65 as soon as possible.

Of course, you can still order the MEGA65 if you haven’t already. Tell your friends!

MEGA65 at the Pacific Commodore Expo Northwest, June 22-23, 2024

If you’re near Seattle, Washington, USA this month, I will be presenting the MEGA65 at the Pacific Commodore Expo Northwest, June 22-23, 2024. Admission is free. The space is cozy and filled with Commodores, and this year we have access to additional space for presentations. I’ll have my MEGA65 at a table all weekend for people to try.

I gave a talk on the MEGA65 at last year’s PaCommEx NW that went reasonably well, despite being hastily planned. Here’s hoping that I’ll have this year’s talk figured out in time. 😬

MEGA65 at the Vintage Computer Festival Midwest, September 7-8, 2024

I’m working up plans to be at the Vintage Computer Festival Midwest, September 7-8, 2024, at the Schaumburg Convention Center in Schaumburg, Illinois near Chicago. This large show attracts enthusiasts from all over the USA and Canada, and is a regular pilgrimage for collectors, computer clubs, YouTubers, and makers of modern retro computers and peripherals. Admission is free.

This year, I’ll be collaborating with Jim Happel (jim_64) on a MEGA65 table. I’ve also applied for a speaking slot, though those won’t be announced until next month, so, fingers crossed. 🤞

MEGA65 at the Portland Retro Gaming Expo, September 27-29, 2024

My MEGA65 and I will be at the Portland Retro Gaming Expo, September 27-29, 2024, in Portland, Oregon, USA. PRGE is one of the largest vintage video gaming shows in the Pacific Northwest, and this year they’re doing a home computing exhibition. Come for the interactive volunteer-run computer exhibits, then stay for the weekend of talks, playable arcade games, and the vendor floor. I’m not doing a talk at this one, but I’ll have my own table in the home computing area.

PRGE is a ticketed event at the Oregon Convention Center. If you’re visiting from out of town, get your hotel rooms reserved early—and make sure to leave time to explore Portland!

Lala The Magical (preview)

Majikeyric is previewing a new game for the MEGA65! Lala the Magical (preview) is an adorable puzzle platformer, with parallax scrolling areas and tons of enemies and collectibles. It’s based on the PC DOS game by the Mojon Twins.

In the ancient ruins (province of Badajoz) lives Lala with her teacher. She is learning magic but still has a long way to go.

“Tell me about the Sky Palace” – asks Lala, and her teacher tells her again about the three Power Gems hidden inside. “I’d love to see them”, but Lala’s teacher would say no… “It’s too dangerous, and powerful magic is required to traverse the palace”.

You can play the preview with a joystick. Sound, music, and polish are in progress. I’m looking forward to the final product!

Wonder Boy core

muse continues his series of arcade cores with Wonder Boy. This colorful side-runner will have you running, jumping, and even skateboarding across the landscape, collecting fruit and dodging creatures.

This core is available for both R3 (2022) and R6 (2024) MEGA65s. Be sure to use the correct version for your system, and follow the installation instructions.

Arcade cores use the MEGA65’s FPGA to fully recreate arcade game chipsets with a high degree of accuracy. Thanks to muse for his continued dedication to the arcade core library!

The role of the KERNAL

In computer architecture, the kernel is the center of a computer’s operating system. It manages access to hardware such as the keyboard, storage devices, and peripherals, as well as other common facilities. Programs—including the rest of the operating system—access these facilities by interacting with the kernel.

The Commodore KERNAL has played this role in Commodore 8-bit computers all the way back to the Commodore PET. The proper name, spelled with an “A” and all uppercase, is credited to an honest misspelling of the word “kernel” by developer Robert Russell that made its way into the VIC-20 programmer’s manual. While the KERNAL has evolved substantially across the line all the way up to the Commodore 65, its role in the computer and many of its key features and interfaces have remained largely the same since 1977.

In total, a Commodore computer’s operating system consists of the KERNAL, the BASIC interpreter, and the screen editor. The machine code for the operating system is etched into a ROM chip, wired to be the first thing the CPU sees when it wakes up. If the KERNAL detects that a C64-style cartridge is connected, it passes control to the cartridge. Otherwise, the KERNAL starts the screen editor, from which the user can load and run programs, type other commands, or start programming in BASIC. These three components tend to share some responsibilities, and the distinctions between them can be a bit blurry in some places, but that’s the general idea.

(There’s an interesting historical exception to the start-up procedure. The Commodore 64 was designed with support for cartridges made for the Commodore MAX, aka “Ultimax” or “VC-10.” An Ultimax cartridge connects directly to the 6510 chip’s I/O lines in a way that causes the CPU to go directly to the cartridge for its first instructions. The Ultimax did not have its own operating system: it relied on the connected cartridge for everything.)

Programming with the KERNAL

There are three main ways the KERNAL participates in the execution of programs: KERNAL subroutine calls, the KERNAL IRQ handler, and vectors.

KERNAL subroutines

A program can call subroutines in the KERNAL code to perform tasks and interact with the KERNAL’s systems. Here’s a simple machine code program that writes a short message to the screen by calling the KERNAL subroutine BSOUT:

bsout = $ffd2

    lda #'H'
    jsr bsout
    lda #'I'
    jsr bsout
    lda #13
    jsr bsout

The BSOUT routine writes a single character to the current output device, which by default is the screen editor. The program sets the accumulator to the character to be written as a PETSCII code, then calls BSOUT with the JSR instruction to address $FFD2. The subroutine does all of the work to write the character, then returns.

The screen editor does a lot of work here. It maintains a text cursor—the same one that you type with at the READY prompt—that has a position on the screen, and a draw state including the text color and other attributes. When it receives a character from the program via BSOUT, the screen editor figures out what changes to make to screen and character attribute memory, moves the cursor position, and scrolls the screen up if the text runs off the bottom. (Other PETSCII codes change the draw state or cursor position in other ways.)

The screen editor is a full-fledged built-in application that behaves like an input/output terminal. Your program writes to and reads from this terminal using KERNAL subroutines.

The KERNAL subroutine jump table

$FFD2 is not actually the memory location of the BSOUT subroutine. Instead, the KERNAL keeps a JMP instruction at that address that goes to the actual subroutine code. Each KERNAL subroutine available to programs has one of these, in a fixed memory location called a jump table.

The jump table provides a critical layer of compatibility across different versions of the KERNAL. Your program needs an explicit address to where it can jump, to invoke the subroutine. When the KERNAL developers inevitably need to relocate the subroutine code to a different address in a new version of the operating system, they can just update the address in the jump table, and your program (and everyone else’s) will continue to run correctly because the jump table itself doesn’t move.

I recently added an appendix to the MEGA65 Compendium describing all of the KERNAL subroutines and how to use them, including jump table addresses, CPU register arguments, and example programs. Check it out, and let me know what you think!

The KERNAL raster IRQ

As we covered in detail in last month’s Digest, you can program the VIC video chip to tell the CPU when its raster beam is at a given vertical location on the screen. This triggers an interrupt that causes the CPU to call a special kind of subroutine known as an interrupt handler. A typical use of the vertical raster beam interrupt is to have a chunk of program code that gets called many times per second at regular intervals. This allows the program to be organized as if it is two programs running side by side: a main program that runs normally, and a short secondary program kicked along by the interrupt.

The KERNAL uses this raster interrupt in this way. It installs an interrupt handler that pays regular attention to KERNAL subsystems while the user’s program is running. The KERNAL IRQ handler drives behaviors of the screen editor such as blinking the cursor and checking for special keyboard combinations like Mega + Shift, and behaviors of BASIC such as sprite move animations (from the MOVSPR command) and music playback (from the PLAY command).

Most programs can just take for granted that the KERNAL is doing its own thing with the raster IRQ. As we saw last month, only one IRQ handler can be installed at a time, so a program that wants to take over the IRQ handler must disable the KERNAL. But the KERNAL has a way it can share its IRQ handler with a program, so they can both play…

KERNAL vectors

The KERNAL generously offers programs the ability to replace or extend some of the KERNAL’s own subroutines. In these cases, when the KERNAL wants to call one of its own subroutines, it looks up the address in a table. This table is initialized to the address of the KERNAL’s version of the subroutine, so without changes, everything behaves normally. A program can replace that address with an address of its own, so the KERNAL calls the program’s routine instead. This indirect address is called a vector, because of how it points to where the KERNAL will go.

A program can replace a KERNAL routine by re-pointing a vector, but this is a heavy task in most cases. Much more common is to extend the existing KERNAL routine with additional functionality. It works like this:

1. Read the address of the original KERNAL routine from the vector table.

2. Write that address into a JMP instruction at the end of the program’s custom routine.

3. Re-point the vector to the beginning of the custom routine.

Now when the KERNAL calls the vector, control goes to the custom routine. The custom routine does some custom things, then jumps to the KERNAL’s original routine. The KERNAL routine still does the heavy lifting, and the custom routine just adds a bit of extra functionality.

This is how the KERNAL can share its IRQ handler. In the middle of the KERNAL’s IRQ handler, it calls a vector that points right back at the rest of the IRQ handler. A program can use the vector to insert its own routine that gets called as part of the KERNAL’s raster IRQ. This way, the program can combine the KERNAL IRQ and its custom IRQ routine, all running alongside its main program code.

Custom vectors remain installed when your program returns to BASIC. This allows a program to extend KERNAL behaviors used by BASIC and the screen editor. The custom IRQ vector is especially fun for this. A game written in BASIC can invoke a small amount of machine code to install an IRQ vector that plays a SID music file, and this music plays in the background while BASIC runs the rest of the game. You could even listen to SID music while writing your BASIC program, with the playback routine running alongside the screen editor!

Note that Run/Stop + Restore will reset KERNAL vectors. There are ways to prevent this, but we won’t cover them here for now. In general, this is a good thing, so you can get the system back to normal when a bug in a vector routine gets out of control.

The VECTOR accessor

The KERNAL keeps its vector table in its own private memory location. To read from or write to the vector table, a program calls a KERNAL subroutine that copies the table to or from the program’s memory. The full procedure for installing an extension vector routine is:

1. Call VECTOR, telling it to copy the vector table to program memory.

2. Copy the original vector address from the table into a JMP instruction at the end of the custom routine.

3. Write the address of the custom routine to the program’s copy of the vector table.

4. Call VECTOR again, telling it to copy the vector table from program memory into KERNAL memory.

Some Commodore programmers are accustomed to reading and writing custom vector addresses directly from internal KERNAL memory, without using the VECTOR routine. For the MEGA65, it is important for programs to use the VECTOR accessor routine, and to not depend on the internal KERNAL memory address. Just like how the jump table protects your program from KERNAL subroutines jiggling around between ROM versions, the VECTOR accessor protects your program from the KERNAL vector table jiggling in the same way.

We’ll try an example below. See the entry for VECTOR in the “KERNAL Jump Table” appendix of the Compendium for a complete explanation, along with a description of the vector table.

A bit more about the MAP

Last month, we briefly considered the CPU memory map, just enough to understand that the KERNAL assigns itself into the $E000-$FFFF address range so it can take over the IRQ handler address stored at $FFFE-$FFFF. We ditched the KERNAL by zeroing out the memory map, so all 16-bit addresses referred to RAM in the MEGA65’s first (well, zeroth) 64K memory bank.

I will continue to avoid a complete description of the MAP register—see the “Memory” chapter of the Compendium for that—but it’s worth knowing a bit more about how the KERNAL uses MAP when integrating with it using jump table entries and vectors.

Mapping 16-bit addresses to 28-bit addresses

Recall that the CPU sees 64KB of memory at a time, using 16-bit addresses $0000 to $FFFF. The MEGA65 has a much larger 28-bit address space, $000.0000 to $FFF.FFFF. The memory map assigns 8KB regions of the 16-bit space to parts of the 28-bit space, and a program can reconfigure this map with the CPU instructions map and eom.

There are actually a few ways the CPU can read and write memory using full 28-bit addresses without changing the map. Crucially, the CPU can only execute machine code instructions via 16-bit addresses. In other words, to execute code somewhere in the MEGA65’s memory, the memory map must have an 8KB region mapped to that location. Instructions like JMP use the 16-bit address into the memory map to find that code.

Two KERNAL maps

When the MEGA65 starts, it runs BASIC, the screen editor, and the KERNAL all together to power the familiar READY prompt, blinking cursor, program line editor, and library of BASIC commands. The operating system code that powers all of this lives in bank 3. There’s a lot of it, so in this mode, most of the memory map points to bank 3. Specifically, $2000 to $BFFF refer to $3.2000 to $3.BFFF, and $E000 to $FFFF refer to $3.E000 to $3.FFFF.

If the operating system is hogging most of the 16-bit addresses, where does our program code live? The KERNAL has two tricks up its sleeve, one for BASIC, and one for machine code.

A BASIC program lives in RAM in bank 0, starting at address $0.2001. The BASIC interpreter uses the CPU’s ability to read from 28-bit addresses to access BASIC program code. The machine code for the interpreter lives in memory starting at $3.2000, and is mapped in to 16-bit addresses starting at $2000. The interpreter itself reads the BASIC code from MEGA65 RAM directly using 28-bit addresses starting at $0.2000. (You’ll get used to it.)

A typical standalone assembly language program, the kind we start with the RUN command, starts with a short BASIC program that consists of a SYS command and the address of the beginning of the machine code, such as $2014. The machine code lives right next to the BASIC starter code, in bank 0 from $0.2014 onward. The CPU can’t execute this machine code when the BASIC memory map is active. So how does SYS get to it?

The answer: SYS changes the map. In the new map, only $E000 to $FFFF are mapped to $3.E000 to $3.FFFF. This is the KERNAL, without the BASIC interpreter or the screen editor.

In both maps, the unmapped region $C000 to $DFFF connects to I/O registers and whatnot, using features of the memory system that we won’t discuss here. See the “Memory” chapter for details.

So what?

Understanding how the KERNAL uses the memory map is important when writing software that depends on the KERNAL.

If your machine code program is a game or demo that doesn’t need the KERNAL for anything, it can map out the KERNAL, take over the interrupt handlers, and run the whole show. The tradeoff is, if you want to do something like read a file from disk, you’ll have to provide your own driver routines that interface directly with hardware registers.

If your program calls KERNAL subroutines, or if it installs vectors but does not return to BASIC, the SYS map will work just fine. The KERNAL routines live in $E000 to $FFFF, and this is present in both the BASIC map and the SYS map. The KERNAL’s internal memory is in the $0000-$15FF region, in bank 0.

If your program installs vector routines then returns to BASIC, those routines must live in a region that’s accessible from the BASIC map, not just the SYS map. This means your vector routines must live within $1600 to $1EFF.

The vector routines themselves can do something fancy like disable interrupts, change the map, do something with code elsewhere in memory, then restore the map and re-enable interrupts before continuing on. See that “Memory” chapter again if you want to try to figure that out.

Project: a desktop clock

It’s 10 o’clock at night, the kids and spouse have gone to bed, and you finally have a bit of time to play with your MEGA65. You flip through the User’s Guide, scroll through some old Digests, and decide to try a little BASIC program. You type a few lines, run the program, get a satisfying result, then write some more code. Everything is going great. Then you look up and it’s 3 o’clock in the morning! And you have an important work meeting in five hours! If only you had a little clock display in the corner of the MEGA65’s screen, you wouldn’t be in this mess.

Let’s try extending the KERNAL with an IRQ routine that prints the current time of day in the corner of the screen. This program has two parts: an installer that sets up the IRQ vector to point to a clock printing routine, and the clock routine itself.

To keep the memory management simple, we will assemble everything starting at address $1600, leaving out the BASIC preamble of a traditional program assembled to $2001. This complicates the user instructions a bit: the user must load the program with the BLOAD command, and start it with SYS $1600. But this turns out to be somewhat convenient. If the user resets the KERNAL vectors with Run/Stop + Restore, they can re-install the clock by running SYS $1600 again.

Here’s the full listing:

!cpu m65
!to "clock.prg", cbm
!symbollist "clock.lst"

* = $1600

vector = $ff8d
scrnptr = $d060
attrmem = $d800
rtc = $fd7110    ; RTC registers at $0ffd7110
rtc_mb = $0f

    ; Read vector table into memory
    sec
    ldx #<vectable
    ldy #>vectable
    jsr vector

    ; Copy the iirq vector to custom_irq's
    ; jmp instruction
    lda vectable
    sta custom_irq_return+1
    lda vectable+1
    sta custom_irq_return+2

    ; Write custom_irq address to iirq
    lda #<custom_irq
    sta vectable
    lda #>custom_irq
    sta vectable+1

    ; Install updated vector table
    clc
    ldx #<vectable
    ldy #>vectable
    jsr vector

    ; Return to BASIC
    rts

custom_irq:
    lda #rtc_mb
    sta $ff
    lda #^rtc
    sta $fe
    lda #>rtc
    sta $fd
    lda #<rtc
    sta $fc

    ldx #0     ; X: output buffer position
    ldz #2     ; Z: 2=hours, 1=minutes,
               ;    0=seconds
-   lda [$fc],z
    cpz #2     ; Hours value needs truncation
    bne +
    and #$7f
+   tay
    ; Convert Binary Coded Decimal (BCD)
    ; to two screen codes
    lsr
    lsr
    lsr
    lsr
    clc
    adc #48
    sta clock_buf,x
    inx
    tya
    and #$0f
    clc
    adc #48
    sta clock_buf,x
    inx
    inx         ; Skip over colon
    dez
    bpl -

    ; Copy clock_buf to the screen
    lda #72     ; column of clock display
    ldx #0
    ldy #0
    ldz #0
    adcq scrnptr  ; screen memory address,
                  ;   plus column offset
    stq $fc       ; $fc-$ff = where the clock
                  ;   will go

    ldz #7
    ldx #7
-   lda clock_buf,x
    sta [$fc],z
    dez
    dex
    bpl -

    ; Reverse white
    ldx #7
    lda #33
-   sta attrmem+72,x
    dex
    bpl -

custom_irq_return:
    jmp $0000
custom_irq_end:

clock_buf:
    !byte 48,48,58,48,48,58,48,48  ; 00:00:00

vectable:
    !fill $30

Things to notice:

* = $1600 : The installer assembles to address $1600, with the IRQ routine immediately following. The assembler creates the file clock.prg with this starting address. The user can load it with BLOAD "CLOCK". Note that DLOAD "CLOCK" will not load it to the correct address and should not be used.

sta custom_irq_return+1 : The jmp $0000 instruction at the end of the custom IRQ routine assembles to three bytes, one for the jmp instruction and two for the address. The installer copies the original KERNAL IRQ vector to the address portion of this instruction.

$0ffd7110 : The Real-Time Clock can be read from hardware registers starting at $0FFD7110. There are six byte registers: seconds, minutes, hours, day-date, month, year (from the year 2000). Each value is a two-digit Binary Coded Decimal (BCD), where each 4-bit nibble represents one decimal digit. This might seem like a crazy way to store a number, but it’s quite useful when the end goal is to display it as a decimal number. To read the left digit alone, shift right four times: lsr…. To read the right digit alone, mask out the upper four bits: and #$0f.

and #$7f : The hours value needs its top bit masked out for some reason.

adcq scrnptr : The address of screen memory where the clock should be drawn is calculated by adding 72 to the starting address of screen memory, read from the VIC SCRNPTR register ($D060-$D063). This is a 28-byte pointer, and using the Q virtual register to calculate column 72 allows this to support any text screen configuration, including 80x50 mode. Of course, on a 40x25 screen, an offset of 72 would put it on the second row. This could be improved by detecting the screen width. See the SCRORG KERNAL routine for one way to do this.

sta attrmem+72,x : To make the clock stand out, it is drawn with character attributes for reverse mode and a white color. The VIC makes the first 2KB of attribute memory visible at $D800, which is sufficient to reach the top half of the screen. See the “Memory” chapter for an explanation of attribute memory. (Naturally, the “72” in this statement would also have to change to support the clock on the first row in 40-column mode.)

Here’s a pre-assembled version of the clock program if you want to play with it:

• clock.d81

A reminder of the instructions:

1. To load the clock: BLOAD "CLOCK"

2. To start the clock: SYS $1600

3. Run/Stop + Restore stops the clock. SYS $1600 again to bring it back.

Did you enjoy this Digest? Consider supporting the Digest with money! Visit: ko-fi.com/dddaaannn

Oh, and be sure to send me a photo of your MEGA65 set-up! I might feature it in a future issue.

Cheers!

— Dan

To do this effectively, we’ll introduce an important programming paradigm supported directly by a feature of the CPU, called interrupts. To get that to work, we’ll also take a brief look at how to uninstall the KERNAL operating system by changing the system’s memory map.

Any news?

Trenz Electronic is busily assembling new MEGA65s, still on track for delivering the next batch in the next few weeks. The Discord and Forum64 board have been quieter than usual, with everyone starting new projects or resting up from previous ones. I can’t wait for the rush of new people joining and asking questions!

If you have a project in progress that you’d like to see featured in the Digest, let me know! You can also announce your project in the #announcements channel on the Discord, and upload your work in progress to Filehost for others to try. Beginners welcome! Some of the coolest stuff we’ve seen for the MEGA65 has been written in BASIC by people like you just trying things out.

The time keepers

Every computer contains a component that generates a clock signal, a fast and precisely timed electronic pulse that drives the digital devices in the computer. Like turning the crank of a music box, these pulses advance the internal mechanisms of each device through their various stages to perform computations, and to generate signals of their own. The clock signal also synchronizes the devices with each other, so they can communicate with one another over their electronic connections.

MEGA65 programs can take advantage of three specific devices driven by the system clock to execute code with precise timing: the CPU, the VIC video chip, and the CIA chip.

The CPU

The CPU uses the clock signal to perform the machine code instructions of a program. Each instruction requires a certain number of cycles to perform, where each cycle takes a fixed amount of time based on the clock. For example, the lda #$ff instruction, which loads the byte value $ff from the program code into the accumulator register, takes two CPU cycles to complete. The cycle cost of an instruction depends on the instruction and addressing mode, but it’s typically between 1 and 6 cycles, and as many as 14 cycles for fancier operations like the 45GS02 Q-register instructions.

In its default MEGA65 mode, the MEGA65 CPU performs instructions at 40.5 million cycles per second, or 40.5 megahertz (MHz). The MEGA65 can also underclock its cycle rate to emulate a Commodore 64 (1 MHz), Commodore 128 (2 MHz), or Commodore 65 (3.5 MHz).

In theory, you can analyze the duration of a section of machine code by looking up the cycle costs of each instruction and adding them together. Commodore 64 programmers sometimes do this to optimize small sections of code, especially for advanced video effects that require precise coordination between the 1 MHz CPU and the VIC video chip. This is less necessary with the MEGA65’s 40.5 MHz CPU, which outpaces most of the signal frequencies that a program might care about.

A program can pause for a period of time by executing instructions and ignoring the results, simply to burn through cycles. This could be a series of instructions in memory, a loop with a counter, or a loop that exits when a hardware register changes. This technique is known as busy-waiting because the CPU can’t stop executing instructions: it has to twiddle its thumbs to keep busy—and also to figure out when to stop waiting and continue the program.

Try these examples of busy-waiting in BASIC:

5 REM -- PAUSE BRIEFLY BY DOING NOTHING IN A LOOP
10 BORDER 0
20 FOR A=1 TO 20000
30 NEXT A
40 BORDER 1

5 REM -- WAIT FOR JOYSTICK FIRE BUTTON, PORT 1
10 BORDER 0
20 IF (JOY(1) AND 128)=0 THEN 20
30 BORDER 1

The VIC

The VIC video chip uses the system clock to generate a video signal with the precise timing expected by the display hardware. Such protocols are derived from old cathode-ray tube (CRT) displays that draw the entire screen with a beam of electrons. This raster beam sweeps across the screen in a fixed pattern of horizontal rows, or raster lines, from left to right, top to bottom. The video signal controls the intensity of the beam, and the beam leaves pixels in its wake that form the complete image. Once it reaches the bottom, the beam returns to the top of the screen, and the process repeats, many times per second.

The MEGA65 connects to modern VGA analog or HDMI digital displays. Internally, it attempts to recreate the display parameters of one of two vintage analog video modes, either PAL or NTSC, so that vintage software that depends on these parameters will run properly. The PAL video mode draws 312 raster lines 50 times per second, also known as a refresh rate of 50 Hz. NTSC draws 262 lines 60 times per second, or a refresh rate of 60 Hz. A full image consists of two interlaced sets of lines, so the actual image size and frame rate is twice as many lines and half the frequency: PAL video is 625 lines tall with a frame rate of 25 Hz.

Synchronizing a program’s behavior with the raster beam is a powerful way to perform advanced visual effects. By changing VIC control parameters at specific times during the drawing of the screen, a program can break away from some of the VIC’s numerical limitations. This is the basis for one of the most coveted of Commodore graphical techniques, called sprite multiplexing, where the VIC’s eight hardware sprites are reused in different parts of a single screen.

The CIAs

The Complex Interface Adapter (CIA) chip is a multi-purpose chip that manages device and serial communications, and also has a high-precision countdown timer feature. Each CIA chip contains two timers, and the MEGA65 (like the Commodore 64) has two CIA chips, each wired up a bit differently. The CIA counts pulses at a rate of 1 MHz, and your program can set a timer interval up to 65,535 of these pulses, for a delay of up to approximately 0.065 seconds. For example, to set a timer for 1/60th of a second, your program would set the timer value to 16,666.

We’ll save a complete discussion of the CIA chip for another time. For now, suffice it to say that you can use both busy-waiting and interrupt-based techniques with the CIA high-precision timers.

Other clocks

There are two other kinds of clock that are worth knowing about, but are less useful for high-precision timing. Each CIA chip contains a time-of-day (TOD) clock that counts tenths of seconds, seconds, minutes, and hours, up to a 24-hour period. In the Commodore 64, this clock powers the TI and TI$ BASIC variables, and is reset to midnight when the computer is switched off. The MEGA65 contains a separate battery-backed Real-Time Clock (RTC) chip that can remember the time of day and calendar date even when power is disconnected. BASIC 65 uses the RTC chip for the TI$ and DT$ variables, and it uses the CIA TOD clock for the TI variable.

Just to complete the picture, here’s a simple BASIC program that busy-waits on the TI special variable for three seconds. Notice that the TI variable’s value changes over time, even though the BASIC program itself isn’t changing it.

5 REM -- WAIT 3 SECONDS
10 BORDER 0
20 T=TI
30 IF (TI-T)<3 THEN 30
40 BORDER 1

Finding the beam

The VIC video chip generates a signal for the raster beam to draw onto the display, expecting the raster beam to follow a fixed pattern on a regular interval. The VIC keeps track of where the raster beam is located, and a program can access this information by reading a hardware register.

One way to synchronize a program’s behavior with the VIC’s raster beam is to busy-wait on its location. You can do this from BASIC 65, with the VSYNC command:

10 BORDER 0
20 VSYNC 100
30 BORDER 1
40 VSYNC 200
50 GOTO 10

VSYNC pauses the BASIC program and busy-waits for the raster beam to reach a given vertical position (or raster line). The vertical position number can be between 0 and 311 in PAL video mode, or 6 and 261 in NTSC mode, where smaller numbers are further up the screen. Try adjusting the numbers on lines 20 and 40 in this example program. (Beware that there’s currently a bug that causes VSYNC to hang with a value less than 6 in NTSC mode.)

Here is an equivalent program in assembly language. Because the raster beam vertical position can be larger than 255, it takes up more than one byte of space across two register addresses. Bit 7 of register $D011 is high (1) if the raster beam is beyond line 255.

vicii_rcl = $d012
vicii_rch = $d011  ; bit 7
border = $d020

loop:
    lda #0  ; black
    sta border

    lda #100
-   cmp vicii_rcl
    bne -
    bit vicii_rch
    bmi -  ; rch is high, not our stop

    lda #1  ; white
    sta border

    lda #200
-   cmp vicii_rcl
    bne -
    bit vicii_rch
    bmi -  ; rch is high, not our stop

    jmp loop

$D011/$D012 are the VIC-II raster position registers. Indeed, this example will work on a Commodore 64 as well as the MEGA65. The MEGA65’s VIC-IV is also capable of doubling the vertical resolution of the screen, a mode known as “V400,” which uses twice as many raster lines. You can see this mode in action by activating the 80x50 text mode: press Esc then 5. (Press Esc then 8 to return to 80x25 text mode.) In V400 mode, the $D011/$D012 VIC-II registers and the VSYNC command continue to use the raster position as if it were in the non-doubled mode, so the bottommost VIC-II raster position in PAL video mode is still “312,” even if V400 is active. If you want the actual mode-specific VIC-IV raster position, an 11-bit value, see the FNRASTERLSB register at $D052 (lower 8 bits) and FNRASTERMSB at $D053.0-2 (upper 3 bits).

Note that while the raster vertical position corresponds to pixel Y-coordinates, the beam starts well above the top edge of the usual background area inside the colored border—because the raster beam also draws the border! The outermost raster positions are outside of the visible area.

Visualizing time

The ability to synchronize our program with the raster beam gives us a clever way to visualize the duration of a section of program code—using the border color! Try this:

10 N=30
20 DIM FB(N):FB(0)=0:FB(1)=1

60 FOR I=2 TO N
70 FB(I)=FB(I-2)+FB(I-1)
80 NEXT I

This program allocates an array of 30 numbers, then fills it with the Fibonacci sequence. To see this in action, run the program, then type: PRINT FB(5)

We can get a sense of how fast this code runs using a combination of VSYNC and BORDER, like so:

10 N=30
20 DIM FB(N):FB(0)=0:FB(1)=1

30 BORDER 0
40 VSYNC 100
50 BORDER 1

60 FOR I=2 TO N
70 FB(I)=FB(I-2)+FB(I-1)
80 NEXT I

90 GOTO 30

The Fibonacci code is the same, but now it runs repeatedly in a loop. For each repetition, the program changes the border color to black, synchronizes to raster line 100, changes the border to white, then performs the Fibonacci fill. When control loops back to line 30, the border is changed back to black. In other words, the border is only white for the time it takes to fill the array. The height of the white bars in the border represent how far the raster beam travels during the fill operation. The VSYNC command makes sure this happens when the raster beam is at the same spot on the screen every time, to hold the white bars steady.

Try changing N in line 10 to another number, such as N=5 or N=40. This changes the size of the array, and therefore changes the amount of time it takes to fill it with Fibonacci numbers.

Caution: This next step causes the screen to flicker. Change line 10 to N=80, then run the program. Press Run/Stop to stop the flickering.

Why does the screen flicker when N=80? Here’s what’s happening:

1. The raster beam reaches position 100, the border changes to white, then the Fibonacci algorithm runs while the raster beam travels.

2. In the time it takes to calculate 80 Fibonacci numbers, the raster beam reaches the bottom of the screen, returns to the top, then goes just beyond position 100.

3. The Fibonacci fill completes, and the program changes the border back to black—but by now the raster beam has made it all the way through the screen and has drawn an entirely white border.

4. The program waits for the raster beam to reach 100 again, which requires the raster beam to travel through almost a full screen with the border color set to black. With each screenful alternating between black and white, the border flickers.

Visualizing code duration using the border color is especially helpful when writing games and demos. To animate graphics smoothly, a game must update all of the screen data in less than the time it takes to draw a single screen, so the updated data is ready for the next pass of the raster beam. If the border flickers, it means the computation is taking up more than one screen’s worth of raster travel, and the programmer has some work to do.

Wherefore interrupts?

A typical machine code program is a sequence of instructions performed one at a time by the CPU in the order the instructions are given. Branching instructions can change the flow of control to other instructions in memory, but otherwise the CPU just marches down the list.

An interrupt is an event in a computer that needs immediate attention from the software. The event can come from a peripheral, such as a key press or incoming serial communication, or an internal programmable device that isn’t the CPU, such as the VIC or CIA chip. (As a special case, an interrupt event can also be triggered directly by the software with the brk instruction, but we’ll ignore this for now.)

When an interrupt occurs, the CPU completes the current instruction (however many cycles are remaining), stops executing the program, then calls a software routine called an interrupt handler. A typical interrupt handler does a small amount of work to respond to the event, then resumes the main program where it left off.

Interrupts allow a program’s code to be organized as if it were two programs: a main program that runs as if it is unaware that special events are occurring, and a short program that runs whenever a special event occurs. Without interrupts, a program would have to be written in such a way as to check for the special condition periodically, in between doing everything else it needs to do. This can delay the program’s ability to respond to the event, or even cause it to miss the event entirely.

Here’s a quick demonstration in BASIC of what could go wrong in this scenario. The program loop does some “work” that takes time, in this case an empty loop, but imagine it’s doing something important. Once the program has a free moment, it checks to see if the fire button of the joystick in port 1 is pressed; if not, it goes and does some more work. It’s pretty difficult to get this program’s attention with the fire button. Only by holding the button down will it eventually notice and respond.

10 BORDER 0
20 REM -- DO SOME "WORK"
30 FOR A=1 TO 50000
40 NEXT A
50 REM -- CHECK FOR FIRE BUTTON IN JOYSTICK PORT 1
60 IF (JOY(1) AND 128)=0 THEN 30
70 BORDER 1

You can imagine a hypothetical computer that triggers an interrupt when the fire button is pressed, halting the “work” to respond immediately. Because interrupts are built into the hardware, only a few kinds of events are wired into the CPU interrupt system. A typical program would use one of the timing sources (VIC or CIA) to trigger an interrupt at fixed intervals many times a second, and the interrupt handler would check for things like joystick input and react accordingly. This is how the KERNAL moves sprites or plays music concurrently with a BASIC program, or blinks the cursor while waiting for keyboard input at the READY. prompt. The steady drumbeat of interrupts allows the program (or the KERNAL) to respond to user input quickly, and progress animation and music smoothly.

Custom interrupt handlers are exclusively the domain of machine code programs. While BASIC programs benefit from how the KERNAL uses interrupts, they can’t use interrupts directly. In most cases, the best a BASIC game program can do is keep the game loop logic short and fast, so it can respond to joystick input as soon as possible. So maybe don’t loop 50,000 times between checks for the fire button.

BASIC 65’s sprite COLLISION feature behaves like an interrupt handler, but it’s actually implemented by the BASIC interpreter, not the CPU’s interrupt system: the interpreter just checks for sprite collisions before executing each BASIC statement.

IRQs and NMIs

The 6502 family of CPUs supports two kinds of interrupt: an interrupt request (IRQ), and a non-maskable interrupt (NMI). Some events trigger IRQs, and others trigger NMIs.

The difference between IRQs and NMIs is that certain CPU operations can temporarily disable IRQs, and a program can disable and re-enable IRQs as needed, while NMIs cannot be disabled. Disabling IRQs is like putting a “Do Not Disturb” sign on a hotel room door: it says that the main program is working on something that should not be interrupted, and interrupt requests should be ignored for the time being. NMIs are more like a hotel fire alarm: they must be handled immediately, no matter what. Both kinds of interrupt are necessary for a fully functioning system, but most programs can get away with only dealing with IRQs.

The following are possible sources of IRQ interrupts in the C64 and MEGA65:

• VIC raster beam location

• VIC sprite collision

• Timers on CIA #1

• The brk instruction

The following are possible sources of NMI interrupts in the C64 and MEGA65:

• Timers on CIA #2

• RS-232 serial communication

• Pressing the Restore key

Yes, pressing the Restore key triggers the NMI handler! This is how Run/Stop + Restore works: the KERNAL’s NMI handler tests whether both keys are pressed, then resets BASIC and declines to continue the interrupted program. This works even if the program has disabled IRQs.

The CPU supports one interrupt handler for IRQs and one handler for NMIs. It’s up to the handler code to figure out the specific cause of the interrupt, and react appropriately.

The address of each interrupt handler is stored as two bytes, in little-endian order (low byte first), at a fixed 16-bit address: the IRQ handler address is stored at $FFFE-$FFFF, and the NMI handler address is stored at $FFFA-$FFFB. The MEGA65’s default memory map installs KERNAL ROM code in this location, and the KERNAL uses its own interrupt handlers, so you can’t just POKE new addresses here. One way that a program can install custom interrupt handlers is to uninstall the KERNAL, by changing the memory map.

It is possible to leave the KERNAL in place and ask it to call custom code during its own IRQ handler. We’re still formalizing and documenting KERNAL integration techniques, so this is best left alone for now when writing MEGA65 programs. This is probably the most popular KERNAL integration technique on the C64, so we’ll try to finish this soon. (Hint: use the “VECTOR” KERNAL routine.)

For the rest of this Digest, we’ll focus on the raster beam IRQ, and assume that the program will uninstall the KERNAL to install its own handler. We’ll save other interrupt types for another time.

Interrupt handlers

When the CPU encounters an IRQ, it finishes the current instruction, then pushes the 16-bit address of the next instruction onto the stack (two bytes). It also pushes the CPU flags onto the stack, as a single byte. It then disables IRQs, then jumps to the address stored in the IRQ vector.

The first thing the interrupt handler needs to do is preserve any additional CPU state that might get clobbered by the rest of the handler. The main program expects everything about the CPU to be just as it left it, including the values in other registers. For example, if the handler needs to use the accumulator (and it probably does), it needs to push the previous accumulator value to the stack beforehand, and restore it afterward.

For most kinds of IRQ interrupt, the device that triggers the interrupt stays in the “interrupt” state until it is told that the interrupt is handled. The program must interact with the device via a hardware register to acknowledge the interrupt, so that it doesn’t re-trigger once the interrupt handler resumes the program. Remember that an IRQ can have multiple causes, so if your program enables more than one cause, it will need to determine the cause and handle it appropriately.

When the interrupt handler is complete, it calls the rti instruction to resume the paused program. This restores the CPU flags and next code address from the stack (thereby re-enabling interrupts), and continues where it left off. This is kind of like how jsr jumps to a subroutine and rts returns from it, with minor differences. For example, normal subroutines don’t stash and restore the CPU flags.

irq_handler:
    ; Preserve the Accumulator, X, Y, and Z registers
    ; on the stack.
    pha
    phx
    phy
    phz

    ; Test for and acknowledge the IRQ cause...
    
    ; Do something fun...

    ; Restore the CPU registers, pulling them off the
    ; stack in the reverse order they were pushed.
    plz
    ply
    plx
    pla

    ; Resume the program
    rti

Enabling and disabling IRQs

The CPU keeps track of whether IRQs should be handled or ignored using the “IRQs disabled” CPU status flag (I). To disable IRQs, a program calls the sei instruction (“set IRQ disabled”). To re-enable IRQs, a program calls the cli instruction (“clear IRQ disabled”). I know, this set/clear definition feels like a double-negative; just think of how interrupts being enabled is the default case (0 or clear), and being disabled is the special case (1 or set).

The CPU will automatically disable IRQs when calling either the IRQ or NMI interrupt handler, so an IRQ handler can’t re-trigger while it is executing, nor can a handler be interrupted by something else. Interrupts get re-enabled automatically when the rti instruction restores the previous status flags from the stack. It’s possible to get fancy with this, and some advanced techniques make unusual exits from the interrupt handler or manipulate the stack.

Interrupts are also disabled automatically while updating the 45GS02 memory map registers. This is important because memory map adjustments require several instructions, and interrupting these instructions could be disastrous if the incomplete memory map leaves either the interrupt handler code or handler vectors in an inconsistent state.

This is an important hint for how a program and its interrupt handlers can communicate with each other. If the main program is updating the state of the system, and it’d be bad if the interrupt handler sees the state only partially updated, the main program should disable interrupts (sei), update the state, then re-enable interrupts (cli). Remember: with interrupts enabled, the handler could be called between any two instructions, including between an lda and an sta. Modern-day programmers might compare disabling interrupts to a “global lock” on memory and CPU state, albeit a simple one.

Setting up hardware interrupt handlers

Let’s try disabling the KERNAL and setting up our own interrupt handler. This requires a few steps.

We’re not going to cover memory mapping in detail in this issue. To learn more about it, download the latest version of The MEGA65 Compendium and check out the “Memory” chapter. For now, we just need to know a few things:

1. The MEGA65 has an address space of 28 bits, with addresses numbered from $000.0000 to $FFF.FFFF. Some of these addresses go to memory, some go to hardware registers, and some are unassigned.

2. The CPU sees 64KB of the MEGA65’s memory at a time, using 16-bit addresses numbered from $0000 to $FFFF.

3. The CPU maintains a memory map that assigns 8KB chunks of the 16-bit address space to the 28-bit address space. A program can adjust this memory map using CPU instructions.

The MEGA65 KERNAL ROM code lives in the 28-bit address space from $2.0000 to $3.FFFF. While the KERNAL is running, it switches between a few memory maps to do various things. Most importantly, when interrupts are enabled, the 28-bit addresses $3.E000 to $3.FFFF are mapped to 16-bit addresses $E000 to $FFFF, which includes the IRQ and NMI vectors as well as the handler routines that they point to.

To take this over for our own purposes, we need to reset the memory map so that $E000 to $FFFF points to RAM at $0.E000 to $0.FFFF. The memory map consists of eight bytes of information. Without going into detail, we can accomplish our task by setting four of these bytes to zero. To do this, set the A, X, Y, and Z registers to zero, then use the map instruction, followed by the eom (“End Of Map”) instruction:

    lda #0
    tax
    tay
    taz
    map  ; Disable IRQs and update the MAP register
    
    eom  ; End MAP adjustments, re-enable IRQs

The map instruction transfers A, X, Y, and Z to the first four bytes of the MAP register. Simultaneously, the map instruction also disables IRQs (similar to sei). After the first map and before the eom, the program can call map a second time to set the second four bytes of the MAP register if needed, or otherwise set up any additional state needed by IRQ handlers in the new memory map. The eom instruction signifies that the MAP setting is complete, and re-enables IRQs.

The map and eom instructions are specific to the 65CE02 CPU on which the 45GS02 is based, so you'll want to use an assembler that supports them, like Acme assembler. If your assembler of choice only supports CPUs up to the 65C02, you can use the aug instruction for map, and nop for eom. If your assembler only supports 6502 instructions, get a better assembler.

The KERNAL keeps the VIC raster interrupt active for its own purposes, so we need to either disable this or set it up the way we want. In general, it’s a best practice to disable all sources of interrupt that your program doesn’t recognize when installing custom interrupt handlers.

Let’s use the gap between map and eom to install our own interrupt handlers, and disable the KERNAL’s raster interrupt. Even though we’re not discussing NMIs for now, we need an NMI handler because we’re replacing all of the KERNAL’s handlers. (We’ll look at a more thorough way to do this another time.)

hw_nmi_vec = $fffa
hw_irq_vec = $fffe
vicii_irqmask = $d01a
ciaa_d = $dc0d
ciab_d = $dd0d

    lda #0
    tax
    tay
    taz
    map  ; (disables interrupts)
    
    ; Set the NMI handler vector
    lda #<nmi_handler
    sta hw_nmi_vec
    lda #>nmi_handler
    sta hw_nmi_vec+1
    
    ; Set IRQ handler vector
    lda #<irq_handler
    sta hw_irq_vec
    lda #>irq_handler
    sta hw_irq_vec+1
    
    ; Disable all VIC IRQs
    lda #0
    sta vicii_irqmask

    ; Disable all CIA IRQs, and acknowledge any pending timers
    lda #$7f
    sta ciaa_d
    sta ciab_d
    lda ciaa_d
    lda ciab_d

    ; Set up the interrupts we care about...
    
    eom  ; (re-enables interrupts)

    ; Main program...
-   bra -  ; (Just an empty busy-loop for now.)

irq_handler:
    pha

    ; Test for and acknowledge the IRQ cause...

    ; Do something fun...

    pla
    rti

nmi_handler:
    rti

Raster interrupts

The VIC chip can trigger an IRQ when the raster beam is at a requested position. Setting this up requires two simple steps.

First, the program must tell the VIC what raster position to use. As with the BASIC 65 VSYNC command, the range of this value depends on the video mode: 0 to 311 for PAL, and 6 to 261 for NTSC. The program sets the desired location with the lower eight bits in register $D012, and the ninth bit as bit 7 of register $D011.

Astute readers may notice that this is the same register we used to read the raster position for busy-waiting! The VIC is clever enough to re-use this register location in this way: when you read the register, it returns the current raster position. When you write to the register, you set the raster interrupt position.

The second step is to set a flag that says the program wants the VIC to trigger the raster IRQ. Set bit 0 of register $d01a to 1 to enable the raster IRQ.

vicii_rcl = $d012
vicii_rch = $d011  ; bit 7
vicii_irqmask = $d01a

    ; Enable raster interrupt at position 200
    lda #200
    sta vicii_rcl
    lda vicii_rch  ; clear bit 7 of $d011
    and #$7f
    sta vicii_rch
    lda #$01
    sta vicii_irqmask

Within the IRQ handler, you can confirm that it was the raster IRQ that triggered the interrupt by testing bit 0 of register $D019. To acknowledge the interrupt and prevent the IRQ handler from re-triggering, write a 1 to this bit. This is another register that has unusual read and write behavior: reading it tests the IRQ trigger status, and writing a 1 to a bit “unlatches” the trigger.

vicii_irq = $d019

irq_handler:
    pha

    ; Test for raster IRQ
    lda vicii_irq
    bit #$01
    beq +  ; not raster IRQ

    ; Acknowledge raster IRQ
    lda #$01  ; write a 1 to bit 0
    sta vicii_irq

    ; Do something fun...

+   pla
    rti

I promised to limit this discussion to raster interrupts, but it won’t take more than two sentences to discuss the VIC-II’s other interrupt capabilities. The VIC can also trigger an IRQ when a sprite collides with the background, or with another sprite. To use these, simply use bits 1 and 2, respectively, of the $d019 and $d01a registers. Oh, and the VIC also uses an IRQ for managing input from a light pen, but I don’t have one of those so I can’t tell you anything about it.

As mentioned earlier, the VIC-IV uses twice as many raster lines in V400 mode as otherwise, but maintains the non-doubled raster line count in the $D011/$D012 registers. The raster vertical position IRQ uses the same value range, regardless of the V400 mode. There is not currently a way to set a more precise raster IRQ in V400 mode.

Racing the beam

In the time that it takes the raster beam to draw a single line, a 1 MHz Commodore 64 can execute about 64 cycles worth of instructions. (Check my math: PAL draws 312 lines 50 times per second; the C64 executes 1 million CPU cycles per second; 1,000,000 / (312 x 50) = 64.1. NTSC draws 262 lines 60 times per second; 1,000,000 / (262 x 60) = 63.6.) Just eyeballing the IRQ handler I wrote above, which doesn’t even do anything useful, it looks like I’ve already spent 26 cycles. A typical C64 interrupt handler will not complete until the raster beam is on the next line.

With high-speed C64 graphics programming, if each CPU cycle represents 1/64th of a line, every cycle matters, and getting the code to synchronize with the raster beam position can be challenging. Remember how I said that when the CPU receives the interrupt request from the VIC, it finishes the current instruction before calling the handler? The current instruction could have several cycles remaining, and the raster beam will have advanced across the screen for some distance before the handler is called. Moreover, the interrupt could be happening at any time during any instruction, so the runoff is likely to vary every time. On a C64, a simple raster IRQ handler that changes the background color results in a flickering fringe at the transition point. C64 programmers can use complex techniques to synchronize the CPU with the raster beam, typically by setting a raster interrupt just before the line that is needed, then performing tests and busy-waiting for very specific amounts of time to account for minute differences between C64 models and other conditions.

The MEGA65 doesn’t have that problem. At 40.5 MHz, the MEGA65 executes approximately 2,600 cycles per raster line, or less than a pixel per CPU instruction. In most cases, the small amount of cycle slop just before the interrupt handler is called won’t impact a program. A bit of fringing can still appear if you’re changing the border color, because the border is so close to the beginning of the raster line. In this case, just be sure to change the border color as early as possible in the handler routine.

Also note that if the interrupt handler exits before the beam has left the line that caused the IRQ to trigger, the VIC won’t re-trigger the IRQ for the same line. The VIC only triggers a vertical raster interrupt at the beginning (left-most position) of the line.

Raster chaining

If you want the raster IRQ to trigger once per frame in the same location, you can just leave the IRQ mask bit set, and leave the raster location registers alone. This is handy for simple game loops that stay in sync with the screen refresh.

Earlier, we were discussing special effects like multi-color borders and sprite multiplexing that involve changing VIC parameters at multiple raster positions. To do this with interrupts, you set the next raster position within the interrupt handler. After the handler returns, the VIC is ready to trigger it again at the new position. Of course, this means that your handler must test which position triggered the interrupt. It can do so by reading the raster position, as before.

Another option is for the interrupt handler to also update the IRQ handler vector address to point to a different routine to be called for the next raster interrupt. This avoids having to test the raster position. As long as all of the raster handlers correctly advance the raster interrupt position and handler address, you can set up distinct handlers for each raster position.

Here’s an example of using the first technique to draw the white border bar from 100 to 200:

vicii_border = $d020

irq_handler:
    pha

    ; Test for raster IRQ
    lda vicii_irq
    bit #$01
    beq +  ; not raster IRQ

    ; Acknowledge raster IRQ
    lda #$01  ; write a 1 to bit 0
    sta vicii_irq

    ; White border bar from 100 to 200
    lda vicii_rcl
    cmp #101
    bcs ++

    ; This is the raster interrupt for line 100.
    ; Set the raster interrupt position to 200.
    lda #200
    sta vicii_rcl
    lda #1  ; white
    sta vicii_border
    bra +

    ; This is the raster interrupt for line 200.
    ; Set the raster interrupt position to 100.
++  lda #100
    sta vicii_rcl
    lda #0  ; black
    sta vicii_border

+   pla
    rti

The VIC-IV raster X position

The traditional VIC-II raster position register and corresponding IRQ trigger are based on the vertical position of the beam, how far up or down the beam is. If you’re careful to consider the video mode, you can think of this as a raster Y coordinate, in correspondence with the VIC screen coordinates.

The MEGA65’s VIC-IV has an extra trick up its sleeve: it also reports and can trigger the IRQ on the raster horizontal position, as a raster X coordinate. This works similarly to the VIC-II vertical position: you can read the X position from a register, write an X position to this register to set the IRQ trigger, and enable and acknowledge the IRQ by setting bits in other registers.

To protect backwards compatibility, this IRQ is behind a master switch for all MEGA65-specific IRQ triggers that is off by default. To unlock new MEGA65 IRQs (currently just this one), set $D07A bit 6. The X position is a 14-bit value, readable at $D050 (lower eight bits) and $D051.0-5 (upper six bits). You write the IRQ trigger position to the same register. To enable the raster X IRQ, set bit 4 of $D01A. To acknowledge the raster X IRQ in the request handler, write a 1 to bit 4 of $D019.

This IRQ will trigger whenever the raster beam reaches the requested horizontal position, once for every raster line when this is enabled. To target a specific raster X-Y coordinate, leave the horizontal IRQ disabled, trigger a vertical IRQ for the Y coordinate, then in that handler, enable the horizontal IRQ for the X coordinate and return. The next interrupt will be at the requested position on the line. Remember that the beam travels while the handler is executing, so keep it tight.

Playing SID music

Let’s end with a musical experiment!

SID files are the Commodore community’s method of creating and preserving music designed to be played by a Commodore 64 through its SID sound chip. Perhaps surprisingly, a typical SID file isn’t just data about the musical notes to be played, like a piano roll for a player piano. Instead, it contains 6502 machine code—the player mechanism itself! (I guess the SID is the piano? You get it.)

The playback code consists of two subroutines. One subroutine initializes the SID chip, and is expected to be called once before starting the song. The other subroutine plays the actual music, and is expected to be called many times per second, with precise timing. This makes it easy for a game or demo to play the SID file simply by loading it into memory, calling the initialization routine, then calling the playback subroutine from an interrupt handler. The music plays concurrently with whatever else the program does.

The complete SID file specification has matured over multiple generations to cover many interesting cases. For our simple experiment, we can note just a few things: the file header tells us where in memory to load the file, and also provides the addresses of the initialization routine and the playback routine in memory when loaded appropriately. SID files expect a C64 memory map, so getting arbitrary SIDs to play on the MEGA65 can be tricky. (When you play a SID via M65Connect—did you know you can play SIDs via M65Connect?—it uploads a tiny player routine that runs in GO64 mode, which gets around this issue.)

Here’s an easy one to try that works with the MEGA65 memory map:

• Download Frogger.sid.

• Download FROGGERSID.d81 (contains frogger.sid).

If we open Frogger.sid in a hex editor and compare it to the SID file format spec, we can see:

• It’s a PSID file (not an RSID), version 2.

• The data region starts at offset $7C in this file.

• The load address is in the first two bytes of the data region, and not the header. This address is $5000.

• The initialization routine starts at $5000.

• The play routine starts at $59F0.

• The play routine expects to be called 60 times per second.

It seems like we should be able to load this file starting at address $5000 - $7C = $4F84, then call the subroutines at $5000 and $59F0 appropriately. Let’s forget about interrupts for a second and try this in BASIC!

10 BLOAD "FROGGER.SID",P($4F84)
20 SYS $5000
30 BORDER 0
40 VSYNC 100
50 BORDER 1
60 SYS $59F0
70 GOTO 30

This program loads the SID file such that the data region starts at $5000, calls the initialization routine, then runs the main loop in lines 30-70. The loop uses VSYNC in two ways: it makes sure that we’re calling the play routine as often as the screen updates, and it uses the border timing trick to see how long the playback routine takes to execute. If you want to use this tune in a BASIC game, the white bar tells you how much runtime is available for game logic and graphics.

Maybe this tune sounds familiar! And if you’re in PAL mode, maybe it sounds a bit too slow. If your display supports it, open the Freezer (hold Restore for one second then release), press V to switch video modes, then press F3, then re-run the program to hear the difference. The song plays as originally intended in the NTSC video mode, which updates the screen 60 times per second, and slower in the PAL video mode, at 50 times per second.

Music playing at the wrong speed is very familiar to Commodore enthusiasts sharing game software between the USA and Europe, where the two different video standards were used. Many C64 games use the raster interrupt for every aspect of their game loop including music playback, because it’s much more convenient to use a single interrupt for all timing purposes than to try to accommodate different intervals for graphics and music. One fix for this would be to use both a raster IRQ (50 Hz or 60 Hz, depending on video mode) and a CIA timer IRQ (set to 60 Hz), and write the interrupt handler to detect which device triggered the IRQ and perform either graphics or sound updates accordingly.

If you’d like to try playing this SID file from assembly language, I recommend using the feature of your assembler to include frogger.sid as binary data into your program, then have the program start by copying the data into the correct memory location. Everything else should look similar to the interrupt handling code from earlier. In a later Digest, we’ll revisit the subject of interrupts, and look at how to use the CIA chip to play music correctly in either video mode.

By this time next month, new MEGA65s may be on their way to their new homes! Huge thanks to everyone who has been reading this Digest in anticipation of future ownership. The new User’s Guide contains everything you need to get started, and don’t miss my MEGA65 Welcome Guide with photos and additional tips. Join the Discord and let us know it arrived safely, and don’t forget to register for ownership status in both the Discord and on Filehost.

Everything I do for the MEGA65 project, including this Digest, is made possible by supporters like you! If you’d like to support the Digest, visit: ko-fi.com/dddaaannn.

Happy computing!

— Dan

I’ve been dealing with a family thing (not tragic, just time consuming) and haven’t been able to finish the feature article I planned for the April issue of the MEGA65 Digest. So instead, I’m going to push that article to the next issue, and just drop you a quick note. I’m also going to skip the audio issue for this month. (The audio issue for March was enough for two. 😅)

There has been a quiet burble of activity in the MEGA65 community as we all await the next delivery batch, including some promising incremental improvements to the audio system, and bug fixes for advanced graphics features. Only a couple of projects have proper announcements, but they’re fun and I don’t want to delay them!

Pascal65

The MEGA65 speaks a new language! TwoBitRetro has just launched the first public beta of Pascal65, a compiler and IDE of the Pascal programming language. The MEGA65 is just the first target. Ken says he intends to support other Commodore 8-bits in the future, as well as the Commander X16. The project is open source.

Download the beta, check out the beta release notes and the 0.25 update notes, read the documentation, and follow the dev blog for updates.

program hello;

var name: string;

begin
  write('What is your name? ');
  readln(name);
  writeln('Hi, ', name, ' nice to meet you!');
end.

mega65.h for llvm-mos

The llvm-mos SDK, the LLVM backend for 6502-family microcomputers capable of compiling languages like C and C++, now includes header files for using MEGA65 features. This provides a common way to use the VIC-IV, SID, CIA, hardware math, and the Hypervisor from C and C++ programs. Check out this example visual demo in C++. These headers are also usable with the CC65 and Calypsi compilers.

Many thanks to wombat for his continued development and advocacy work bringing MEGA65 support to the llvm-mos project!

Tell me what you think!

I want to hear from you! If you’re waiting for your MEGA65 to ship, what are you most looking forward to learning more about? If you’re already enjoying your MEGA65, what topics could the Digest cover that would make your experience more rewarding? If you’re still considering a purchase, what interests you about retro computing, and how are you hoping the MEGA65 or this Digest will scratch that itch?

You can send me e-mail, or leave a comment on my Ko-fi page. I’m considering doing the Community Survey again this year, too, so keep an eye out for that.

Thanks all! Back soon!

— Dan

[Did you know: All issues of the Digest have an audio version! Search for “Dan’s MEGA65 Digest” in your favorite podcast app, or check out the audio player at the top of each issue. — Dan]

There are two methods for making sound and music with the MEGA65, as it is currently implemented. The first method is the four SID chips, programmable devices that generate waveforms with requested parameters using analog electronic components. We took a dive into the SID chips back in—November 2022?? How long have I been doing this?? …

The MEGA65 can produce sound another way. Pulse-Code Modulation (PCM) describes a waveform as a sequence of values over time, literally the shape of the desired waveform as a series of high and low numbers, as if drawn on a graph. The computer feeds these numbers into a device called a Digital-Analog Converter (DAC) that produces the waveform in that shape, as if rapidly changing the position of a speaker membrane according to each value. The MEGA65 has four DACs, and these waveforms are mixed with the rest of the audio system to produce the stereo audio output of the computer.

With PCM, a computer can reproduce real-world sounds captured by a microphone, such as human speech or musical instruments. Today, we take this extremely for granted: modern computers generate pretty much all sound using PCM waveforms. We used to call this “digitized sound,” in contrast with “synthesized sound.” Now we just call it “sound.” While PCM gives a computer program much more control over the generated sound, the trade-off is memory: relative to the memory sizes of 1980’s computers, PCM sound data takes a huge amount of space, depending on the length and quality of the sounds.

In this issue, we’ll look at how to control the MEGA65’s DACs to play digitized sound, as well as techniques for wrangling sound data for use in your programs. As usual, we’ll spend a bit too much time nerding out on theory and file formats.

Are you ready? Here we go.

Featured Files

Bomb’em All by btoschi, an explosive action game for two to four players. Drop bombs, pick up items, and break through walls while trying to trap your opponents in the blast zone. The game supports the Four Fun joystick adapter for four joysticks, or can be played with a mix of joystick and keyboard controls.

BASIC Star Galactica by jim_64, a space battle adventure. Destroy the Cylons and protect the fleet—and the future of humanity. Don’t miss the downloadable, printable disk label and manual.

fredrikr has prepared the fourth in his series of text adventure game bundles for the MEGA65, featuring modern classics from the interactive fiction community. This pack includes a variety of games released from 1995 to 2023, all playable on the MEGA65 thanks to the Ozmoo Z-machine player. (See the Digest from October 2022 for more on Ozmoo and MEGA65 adventure gaming.)

Another arcade core from muse! In Ghosts’n Goblins (1985), you are brave knight Sir Arthur, on a quest to save the Princess Prin-Prin. Don your armor—and take care not to lose it—while fighting waves of zombies, giants, demons, and other monsters. This classic from Capcom is considered one of the best video games of all time—and one of the most difficult. As with the other arcade cores, you will need to find the game ROM online, and follow the instructions to install it.

In Stranded, a graphical adventure game by Magnus Heidenborn, your boat has crashed and washed ashore a deserted island. Magnus wrote Stranded for the Commodore 64, specifically the modern TheC64 clone. Gurce ported it to the MEGA65, and added original music. I especially appreciate the novel keyboard-based linear travel and exploration mechanic, which works around common issues with point-and-click adventure games. Check it out!

Expansion board progress

Paul is making progress on the MEGA65 expansion board project. As we reviewed in a previous issue, this project intends to produce an internal hardware expansion that adds component video output, a Commodore user port, a tape port, and a port for the never-released 1565 external floppy drive that was originally intended for the Commodore 65. The goal is for these expansion boards to be made entirely out of printed circuit boards (PCBs) and common components with open source designs, so anyone can order and assemble one from any PCB fabricator.

The latest prototype includes a way to connect an ESP32 wireless Internet module (!), and routes a path for the optional JTAG adapter to a firmly mounted microUSB port accessible through the back of the computer. It also completes the 1565 disk drive port. Hopefully someday we’ll be able to make a modern recreation 1565 drive with a plastic case that matches the MEGA65.

KLF is gonna rock you

Here is a visual representation of the waveform of the first few notes of “3 am Eternal” by The KLF, performed by soul singer P. P. Arnold:

Storing and replicating this waveform exactly as it was performed would require a device and a storage medium that could capture the infinitesimal changes of air pressure in the listener’s ear over time. Digital storage media is neither infinite nor infinitesimal, so we have to make some tradeoffs when digitizing audio. How can we represent this waveform as a collection of numbers, then use those numbers to reproduce an approximation of the waveform on a loudspeaker?

Sample rate

Pulse-code modulation describes the height of a waveform measured periodically, or sampled, over time. We can’t measure every infinitesimal point in time, so we have to choose a sample rate that says how often we take a sample. For audio, a typical sample rate is on the order of kilohertz, or thousands of times per second. A smooth curve in the original waveform is approximated by a stair-step pattern in the digitized waveform.

The sample rate for digital audio is a lot like the screen resolution of a digital image. The actual image of an object as seen by the eye could have infinitesimal detail, but to capture it and represent it on a screen, it must be digitized into pixels. The smaller and closer together the pixels, the more detail can be captured and represented. You can think of sample rate as the “horizontal resolution” of the waveform.

Bit depth

We can’t measure the height of each waveform sample infinitesimally either, so this too needs a digital compromise. For example, we could store each sample as 8 bits (one byte) of data. This would give us 256 possible values for the sample. If the measured sample is between two adjacent values, it gets rounded—or quantized—to the closest value. The number of storage bits per sample is the bit depth of the sample (or sample depth). You can think of bit depth as the “vertical resolution” of the waveform.

Sample depth can also be understood by analogy with digital images. Each pixel of an image is stored with a digital value that represents its color. The number of possible colors it can use is limited by the bit depth of the color value. Naturally, the more colors the computer can use for a pixel, the more accurately it can represent the original image.

Signed vs. unsigned samples

Conceptually, an audio waveform is a variance in the regular air pressure of a silent room, wiggling positive and negative in a pattern until stabilizing back to zero. You can see the middle line on these waveform diagrams where this level lies. Based on this, waveform samples could be represented as a signed number, with some negative numbers and some positive numbers around a baseline of zero. Or, it could be represented as an unsigned number, where the baseline is the middle value of a range of positive numbers.

A signed 16-bit sample has a range of -32,768 to +32,767. It is usually stored as a two’s complement value, $8000 (-32,768) up to $FFFF (-1), then $0000 (0) up to $7FFF (32,767). An unsigned 8-bit sample has a range of 0 to 255, where 128 is the baseline of the waveform. It is stored simply as its byte value, $00 (0) to $FF (255). If you’re messing with sample data, you need to know both its bit depth and whether it is signed or unsigned to interpret it correctly.

Size vs. audio quality

Both sample rate and bit depth explain how the amount of data relates to the quality of the reproduction of the original sound. The faster we sample, the more samples we collect, and the more accurate the data is to the original sound. The higher the bit depth of the sample, the more memory is required for each sample, and the more accurate the sample is to the waveform.

Before there were large hard drives, fast Internet transmission speeds, and data compression algorithms tuned for audio, digital music could only be practically distributed on optical fixed-storage compact discs (or “CDs,” as we called them). We purchased these discs at retail establishments with names such as “Tower Records,” and ordered them from printed catalogs to be delivered to our home via postal service from Columbia House at an introductory cost of 10 discs for 1 penny. A typical audio CD stored 74 minutes of uncompressed stereo sound data, using a sample rate of 44.1 kHz and a depth of 16 bits.

We can calculate the amount of sample data on an audio CD with a simple multiplication: 74 minutes x 60 seconds per minute x 44,100 samples per second x 2 bytes per sample x one sample for each stereo channel (2) = 783,216,000 bytes, or almost 747 MiB. Old-timers may remember that a CD-ROM, which uses the same type of disc for storing computer files, has a capacity of 650 MiB. CD-ROMs use the rest of the space for error correction and addressing, so computers can find files and make sure they read them correctly. When an audio CD player reads a sample incorrectly, it just pretends nothing happened and keeps going, so it can use more space for samples.

For perspective, at CD quality, the MEGA65’s 8 megabytes of Attic RAM can contain 45 seconds of audio. As we’ll soon see, we’re actually limited to 64 kilobytes at a time, which would last us 0.35 seconds at 44.1 kHz 16-bit. We’ll need to make some tradeoffs in quality and duration to make practical use of digitized sound.

The following are the durations of 64 kilobytes of sample data at various sample rates and bit depths:

• 4000 Hz, 8-bit: 16.384 seconds

• 4000 Hz, 16-bit: 8.192 seconds

• 8000 Hz, 8-bit: 8.192 seconds

• 8000 Hz, 16-bit: 4.096 seconds

• 11025 Hz, 8-bit: 5.944 seconds

• 11025 Hz, 16-bit: 2.972 seconds

• 16000 Hz, 8-bit: 4.096 seconds

• 16000 Hz, 16-bit: 2.048 seconds

MEGA65 Audio DMAgic

Imagine we had a way to control the speaker membrane directly from a MEGA65 program using a hardware register. What would the program have to do to play back a short digitized sound? The program would write each PCM sample to the register, and it would have to do it at a consistent rate that matches the sample rate. If the sound was digitized at 8 kHz, this program would have to write sample data to the register 8,000 times per second, at even intervals. This is entirely possible with a 40 MHz CPU, but getting the timing right would be a significant programming challenge, especially if the program does other things besides play the sound.

Thankfully, the MEGA65 can help us with this. Reading a series of values from one memory location and writing them to another is the bread and butter of the Direct Memory Access (DMA) chip, a purpose-built chip in the Commodore 65 that the development team called “DMAgic.” DMA is typically used to copy one region of memory to another location very quickly, or fill a region with a value. Normally it does this as quickly as possible. The MEGA65 has enhanced DMAgic with a mechanism for playing audio samples to the DAC at a programmable sample rate, controlled with hardware registers. Your program can even do other things while the sample is playing: playback happens concurrently with program execution.

Because sample timing is managed for us by audio DMA, we don’t need to worry about our program being fast or accurately timed. You can even use audio DMA from BASIC!

Audio DMA specs and techniques

For audio DMA to work its “DMAgic,” a few things must be true:

• The CPU must be running at 40 MHz. (This is the default.)

• Sample data must be in main memory, not Attic RAM.

• Samples must use a bit depth of 16, 8, or 4. Values can be signed or unsigned.

• The playback region cannot exceed 64 KB.

At first glance, this seems a bit limiting, but it’s actually quite powerful with a few tricks. For example, while sample data must be in the first 384 KB of main memory during playback, your program can store its samples in the 8 MB of Attic RAM, then use a DMA copy operation to install it in main memory to be played.

4-bit samples are stored in an interesting way: the DMA must advance through memory by at least one byte per sample, so 4-bit samples use either the top four bits or the bottom four bits of each byte, and you tell audio DMA which bits to use when you play the sound. This means you can have two 4-bit sounds stored in the same bytes, one in the top bits and another in the bottom bits.

When you play a sound, you can tell audio DMA to stop at the end, or loop back to the beginning automatically and continue playing. Looping is great for short repeating waveforms, or long repeating patterns like drum beats or atmospheric sounds.

With a bit of cleverness, you can play sample data larger than 64 KB by taking advantage of the looping feature. Your program can copy new sample data into the memory region as the sound is being played, so when the playhead loops back to the beginning, it starts playing the new data.

Your program specifies the sample rate to use the play the samples. If you want the samples to sound like the original recording, you play the samples at the rate they were digitized. You can also play the samples at a slower or faster rate to change the pitch and speed of the sample, like spinning a record player at a faster or slower speed. —Oh, uh, records were another way to distribute music before CDs, as analog waveforms etched into grooves on vinyl discs. Sounds were reproduced mechanically by vibrating a needle called a stylus, by running it across the etched groove at a steady speed. Because retro is cool, vinyl album sales have seen a rapid resurgence recently that is expected to grow in 2024, while sales of CDs have dropped in favor of online music streaming.

A synthetic example

Before we figure out how we get recorded sound data into the MEGA65, let’s try out the audio DMA system with some made-up numbers. We’ll use BASIC here, but the procedure is the same in assembly language: we’re just writing to memory and registers. (Try porting this example to assembly language!)

The waveform

To start, let’s draw a simple “sawtooth” waveform into some memory. This will just be the numbers 0 to 255 across 256 bytes of memory, which we will play looped.

10 FOR X=0 TO 255 : POKE $50000+X,X : NEXT X

Channel registers

Each of the four audio DMA channels has 16 bytes of registers. Channel 0’s registers are at addresses $D720 to $D72F, channel 1’s are at $D730 to $D73F, channel 2’s are at $D740 to $D74F, and channel 3’s are at $D750 to $D75F. I’ll refer to each register by its offset $0 through $F. Just know that the registers have the same layout for all four channels.

Switch off channel 0 while we’re setting it up, by writing a 0 to register $0:

20 POKE $D720,0

Enabling the audio DMA system

The audio DMA system must be enabled before it can be used. This is a global setting, address $D711 bit 7:

30 SETBIT $D711,7

Sample addresses

The starting address of the sample is a 24-bit value, across registers $1 to $3. We also want to set the channel 0 playhead, a 24-bit value across registers $A to $C. (Remember, these are all Little Endian.) The starting address is used for looping: when the playhead reaches the end, it’ll jump back to the start address.

40 POKE $D721,$00:POKE $D722,$00:POKE $D723,$05 : REM SAMPLE STARTS AT $5.0000
50 POKE $D72A,$00:POKE $D72B,$00:POKE $D72C,$05 : REM SET PLAYHEAD TO BEGINNING

The end of the sample is stored as a 16-bit value equal to the lower 16 bits of the last address, in registers $7 to $8. In our case, the end address is $5.00FF, so the register value is $00FF.

60 POKE $D727,$FF:POKE $D728,$00

Channel volume

Each audio DMA channel gets two volume settings, with the ability to pan the channel’s output to the Left DAC or the Right DAC in different proportions.

Channels 0 and 1 are considered “left” channels, and channels 2 and 3 are considered “right” channels. The $9 register in each channel’s register bank sets the volume of the signal that it outputs to its device, either the Left DAC or the Right DAC. The register value is between 0 and 255, with 255 being the loudest.

Another set of volume registers allow for each channel to also output to the opposing DAC. Registers $D71C and $D71D set the output of channels 0 and 1, respectively, to the Right DAC. Registers $D71E and $D71F set the output of channels 2 and 3, respectively, to the Left DAC.

This can get a little confusing because the user can subsequently pan the Left DAC or the Right DAC using the Audio & Volume tool in the Freezer, and can even flip the stereo field entirely. If you want to experiment with this, I recommend opening the Freezer tool and setting the “Left Digi” volume up in the left output channel and all the way down in the right output channel, and the “Right Digi” volume down in the left and up in the right, so you can hear clearly through stereo speakers which DAC is being used.

Let’s just set channel 0 to output evenly to both DACs for now. This sawtooth wave is a bit obnoxious, so I'm using a low volume level:

70 POKE $D71C,$22 : POKE $D729,$22

Headphone warning: If you are listening to your MEGA65 with headphones connected directly to the 3.5mm jack, I recommend reducing the master volume in the Audio & Volume tool while you are testing digital audio samples. Incorrect sample data or erroneous register values could cause unexpectedly loud sounds. I prefer to use a set of speakers with an independent volume knob set to a low setting. (Headphones tend not to have their own volume control.)

Sample rate

The sample rate (frequency) is stored as a 24-bit value in registers $4 to $6. This one is a bit weird, but it’ll make sense, I promise.

The value is the 24-bit proportional value of the frequency relative to the CPU speed. For example, if the sample rate is 16 kHz, then the register value is 16 kHz divided by 40 MHz (a ratio), multiplied by 2 to the 24th power minus 1 (the largest 24-bit value). Watch those units when doing the math! The CPU is much faster than the sample rate, so you should get a very small ratio.

Here are the register values for some useful sample rates, pre-calculated for your convenience:

• 4 kHz : 1,662 ($00067E)

• 8 kHz : 3,324 ($000CFC)

• 16 kHz : 6,648 ($0019F8)

• 32 kHz : 13,296 ($0033F0)

For our experiment, we actually want to do something special with the frequency. We have a very short sawtooth waveform, capable of playing a musical note. The middle “A” key on a piano would play this pattern 440 times per second (440 Hz). We have 256 samples, so to achieve a middle A pitch, we need a sample rate of 440 x 256 = 112640 Hz = 112.64 kHz. Proportional to the 40 MHz CPU speed, the 24-bit value is: 47,244 decimal, or $00B88C (that’s “zero zero Baker eight eight Charlie”).

Someone check my math.

80 POKE $D724,$8C:POKE $D725,$B8:POKE $D726,$00 : REM SAMPLE RATE 112.64 KHZ

Sample sign, bit depth, looping, and playback

Finally, we can trigger the sample, with a few last settings in register $0. This register uses the following bits as flags:

• Bit 7: Play it.

• Bit 6: Loop it. We want this to loop our very short sawtooth wave.

• Bit 5: Set this to 0 if the sample value is signed. We’re using unsigned values in this example, so we set this to 1.

• Bits 1-0: The bit depth: 11=16 bits, 10=8 bits (our choice), 01=upper 4 bits, 00=lower 4 bits.

90 POKE $D720, $80 + $40 + $20 + $02
100 GETKEY A$ : REM WAIT FOR A KEYPRESS
110 POKE $D720,0 : REM SWITCH IT OFF! SWITCH IT OFF!

Try it out!

Run this to hear the tone. It’s a bit obnoxious, so press a key to switch it off. If you accidentally press Run/Stop with the sound still playing, use POKE $D720,0 to disable the sound.

You can experiment with different waveforms by writing different values to $5.0000-$5.00FF. Try these:

10 FOR X=0 TO 255 : POKE $50000+X,255*(SGN(X-128)+1) : NEXT X

10 FOR X=0 TO 255 : POKE $50000+X,X-(X-128)*(X>128) : NEXT X

10 FOR X=0 TO 255 : POKE $50000+X,127*SIN(X/255*3.1415)+128 : NEXT X

Converting audio files to raw PCM data

This little experiment to play triangle, sawtooth, and sine waveforms is fun, but not particularly impressive considering that the SID chips can already generate these waveforms on their own. To unleash the true power of audio DMA, we need PCM sample data for more interesting sounds. The MEGA65 does not have a built-in audio digitizer (at least not yet), so we must turn to our trusty modern computers.

There are many ways to record, produce, or otherwise acquire sound files with a modern computer and an Internet connection. Your computer’s operating system probably includes a free sound recording or editing program, and so does your mobile phone. Sound editing software like Audacity is free, and you can also download free sound files from FreeSound.org. Whatever software you’re using, be sure to edit your sound file to trim it to just the length you want your MEGA65 program to play.

Audacity

Our goal is to convert the sound file to raw PCM sample data at an appropriate sample rate, and at a bit depth supported by the MEGA65 audio DMA. Audacity can do all of this in a single export step:

1. File menu, Export Audio.

2. Format: “Other uncompressed files”

3. Channels: Mono

4. Sample Rate: 8000 Hz or higher, or select “Other” and enter any rate in Hertz

5. Header: “RAW (header-less)”

6. Encoding: “Signed 16-bit PCM” or “Unsigned 8-bit PCM”

7. Click Export.

Remember that sample rate and bit depth affect data size and sound quality, so choose wisely.

Other modern sound production software may not have all of the same export options. Some of the more expensive software packages on my computer can’t believe I would ever want to export at a sample rate lower than 44.1 kHz. If your software doesn’t export raw PCM sample data, or doesn’t offer the desired sample rate or bit depth, export a .wav file with high quality settings, then use Audacity for the final conversion to raw PCM data with the desired parameters.

It’s important to use the highest quality settings for every processing step until the last one. Because each digital audio file is an approximation of the original waveform, the conversion tool has to use some math to assume the gaps between the samples when converting from one sample rate to another. The more data that goes into that process, the better.

While preparing this Digest, I had occasional issues with Audacity trying to boost the volume of my samples, causing clipping of the signal in some cases that added loud pops to the final sound effect. Notably, this clipping only happened on real hardware and not in Xemu, so be sure to test your samples.

ffmpeg

Audacity is fine, but I like command line tools so I can automate build workflows. The tool for this is ffmpeg, an essential free media conversion tool for video and audio. It’s similar to how we used ImageMagick to convert still images back in a previous Digest. ffmpeg is available for all platforms. On a Mac using Homebrew, install this with: brew install ffmpeg

ffmpeg accepts most audio files as input, including .wav files. Specify the input file with the -i parameter. It’ll detect everything it needs to know about the input data from the file itself.

For the output file, we want something special, so we need to tell it what we want. The -f option selects the bit rate, selected from this list:

• s16le : signed 16-bit Little Endian

• u16le : unsigned 16-bit Little Endian

• u8 : unsigned 8-bit

To convert the file to a different sample rate, use the -ar option, and provide the value in Hertz. To convert a stereo sound to monophonic, specify -ac 1.

ffmpeg -i klf.wav -f u8 -ar 8000 -ac 1 klf.raw

You now have a raw PCM data file. Assuming it’s small enough, you can now copy this to a D81 disk image, and transfer the disk image to your MEGA65. See a previous Digest for more information on how to manage files and disk images.

Playing the digitized sound

The BASIC program above can be modified to play an arbitrary sample file. Replace line 10 with a BLOAD command that loads your sample file to address $50000:

10 BLOAD "KLF.RAW",P($0050000)

You will need to adjust the sample length (line 60) and the sample rate (line 80) as appropriate for your data. You might want to remove the loop flag ($40) from the playback command (line 90). Only include the “unsigned” flag ($20 on line 90) if the sample data is unsigned.

Can you hear the sound, but it’s noisy or crackling? Double-check the “unsigned” bit. Using the unsigned bit when the sample data is signed (and vice versa) will cause transitions from negative to positive values to pop, in a bad way.

What about 4-bit sample data?

None of the audio processing programs I tried offer export of 4-bit samples. How can we make 4-bit samples, to take advantage of this feature of audio DMA?

Compared to something as complex as re-sampling at different sample rates, converting from an unsigned 8-bit sample to an unsigned 4-bit sample is quite easy. We just lop off the lower four bits, equivalent to dividing by 16. Here’s a simple Python program that does this:

INPUT_FILE = 'klf_8b.raw'
OUTPUT_FILE = 'klf_4b.raw'

data_input = open(INPUT_FILE, 'rb').read()

with open(OUTPUT_FILE, 'wb') as outfile:
  for i in range(len(data_input)):
    samp = int(data_input) // 16
    outfile.write(samp)

This takes the file klf_8b.raw containing unsigned 8-bit samples and produces the file klf_4b.raw containing unsigned 4-bit samples, with each sample in the lower four bits. We can modify our playback program to use this by setting the appropriate flags in the $0 register:

90 POKE $D720, $80 + $20 : REM PLAY IT ONCE, UNSIGNED, 4-BIT LOW

Audio DMA requires that each sample be at separate memory locations, so merely converting a sample from 8-bit to 4-bit doesn’t actually save any space. The space savings comes from storing two 4-bit samples on top of each other, and telling audio DMA to play either the bottom four bits or the top four bits. We can modify this Python script to store two samples together in this way:

INPUT_FILE_ONE = 'klf_8b.raw'
INPUT_FILE_TWO = 'rockyou_8b.raw'
OUTPUT_FILE = 'klf_4b.raw'

data_one = open(INPUT_FILE_ONE, 'rb').read()
data_two = open(INPUT_FILE_TWO, 'rb').read()

# Pad the shorter sample with zeroes, so they are the same length
if len(data_one) < len(data_two):
  data_one += b'\x00' * (len(data_two) - len(data_one))
elif len(data_two) < len(data_one):
  data_two += b'\x00' * (len(data_one) - len(data_two))

with open(OUTPUT_FILE, 'wb') as outfile:
  for i in range(len(data_one)):
    samp_one = int(data_one[i]) // 16
    samp_two = int(data_two[i]) // 16
    result = samp_two * 16 + samp_one
    outfile.write(bytes([result]))

This takes the two 8-bit sample files klf_8b.raw and rockyou_8b.raw, converts them both to 4-bit, then writes them to a single file klf_4b.raw with klf in the lower bits and rockyou in the upper bits.

To tell the playback program which sample to play, set bits 1 and 0 of $D720 accordingly:

90 POKE $D720, $80 + $20 : REM PLAY IT ONCE, UNSIGNED, 4-BIT LOW

90 POKE $D720, $80 + $20 + $01 : REM PLAY IT ONCE, UNSIGNED, 4-BIT HIGH

I have a vivid memory of hearing The KLF’s “3 a.m. Eternal” played on my childhood Amiga 500. Like the MEGA65, the Amiga can play short digitized sounds over four audio DACs. Most Amiga owners didn’t have enough memory to store several minutes of digitized sound, so another kind of music was born. A MOD file encodes music as short digitized sounds played in a pattern of frequencies and timings, saving memory by re-using samples throughout the song. The KLF’s music was largely sample-based and repetitive to begin with, and they even produced some of it on home computers like the Apple II and Atari ST. MOD files can come close to reproducing the original songs within the memory limitations of a vintage computer.

Your MEGA65 includes a MOD player on the Intro Disk, called “Manche,” that uses audio DMA to play sound samples. I found one person’s attempt at a MOD of “3 a.m. Eternal” and was able to play it in Manche on my MEGA65. I can’t say this particular MOD is my favorite remix, but it’s been fun to revive this memory.

Here are a few MOD arrangements of KLF songs for you to enjoy:

• Download: 3ametern.mod

• Download: whattime.mod

• Download: doctorin.mod

Put these in the root of your SD card, then start Intro Disk #1. Open the Music menu, select Manche, and press Return to run the program. Within Manche, press F1, type one of the filenames, then press Return to load the file. Press Space to start playback.

I also made this demonstration disk with the waveform generator program from this issue, as well as a program demonstrating the same sound at different sample rates and bit depths.

• Download: KLF.D81

This Digest is made possible with support from justified ancients, like you! To contribute, visit ko-fi.com/dddaaannn.

See you next month!

— Dan

For the MEGA65 delivered in 2022…

If you own a MEGA65 delivered in 2022, sign in to Filehost with the account you used to redeem your owner code, then download MEGA65 release v0.96 for “R3” boards. If you don’t yet have a Filehost account, register for one, then select “Redeem Code” from the user menu and enter the nine character code printed on the piece of paper that was included with your MEGA65. This gives you access to the release packages “with ROM,” and a few other things.

Download The MEGA65 User’s Guide, 2nd edition PDF, and follow the instructions in the chapter, “Upgrading the MEGA65.”

You will want to update the factory core in slot 0 to this release. Please see the “NOTE” in the User’s Guide about upgrading an R3A MEGA65 for the first time: there’s a little trick required to start the flasher from the v0.96 core in slot 1 to flash the v0.96 core to slot 0. Don’t worry, it’s easy, just don’t miss the note. For a more detailed version of these instructions with photos, see Visual Guide to Flashing Slot 0 without JTAG.

Lastly, download M65Connect v2.3 for Windows (Intel), for Windows (ARM), for macOS (Universal), or for Linux (Intel). This powerful desktop application includes new features and enhancements for transferring files between your PC and your MEGA65, with support for a new feature in the v0.96 release: file transfer over Ethernet. See the User’s Guide for more information, as well as the new M65Connect section of the Wiki.

For Xemu users…

If you don’t yet own a MEGA65 and use the Xemu MEGA65 emulator, you can upgrade the MEGA65 ROM to the release v0.96 version, ROM 920395. Download the ROM 920395 diff files, then follow the instructions in the ROM FAQ to construct the mega65.rom file. The M65Connect app includes a built-in ROM patching tool for this purpose. See also the Xemu MEGA65 Quickstart.

The release v0.96 ROM requires a recent version of Xemu, dated December 2023 or later. If you haven’t updated Xemu in a while, get the latest “stable” version.

The MEGA65 User’s Guide, 2nd edition PDF has been fully updated with information about recently added features to BASIC 65.

For DevKit owners…

Release v0.96 is available for the MEGA65 DevKit. Download and install the mega65r3 release package, as above.

An important note for this case: the v0.96 core flasher does not yet work on the DevKit. You can use the v0.95 core to flash the v0.96 core (such as in slot 1), but be sure to keep the v0.95 core around (such as in slot 0) for flashing other cores.

This shortcoming will be resolved in the next few months with a follow-up release.

For Nexys dev boards…

The v0.96 release is not yet available for FPGA development boards, such as the Nexys. This will be addressed in a follow-up release. Please continue to use v0.95 for now.

For those who are about to rock…

The MEGA65s that will be delivered in June 2024 will have this release installed at the factory. We plan to do another release before then, so you’ll want to check for newer versions and upgrade shortly after receiving your computer.

Reminders of other things you can get

As I mentioned in the previous newsletter, you can now purchase the MEGA65 User’s Guide, 2nd edition, in print form. Orders so far have been arriving on doorsteps all over the world, and it turned out great! Don’t miss the UG2 FAQ that answers a few anticipated questions.

The 45GS02 Quick Reference mousepad and poster are still available. I added this article to Filehost with a few action photos.

More MEGA65s will ship in June of this year, and they will include a massive new Intro Disk software bundle (registered owner version). Download this for your own computer and copy all of the files to your SD card. This is a superset of the software that was included in 2022, including updated versions of previous titles.

What’s new?

Notable changes in the MEGA65 firmware from release v0.95 to v0.96 (see the core changelog for a complete list):

• Ethernet file transfer support; use the new M65Connect app (or command line tools), and see the User’s Guide, 2nd edition, for instructions

• New core selection and flashing menu, capable of flashing slot 0 without a JTAG adapter

  • Can configure core slots to be selected automatically when different types of cartridges are connected, so a C64 cart can auto-boot into the C64 core instead of the MEGA65 core

  • Core file selector supports long filenames

• New hardware typing event queue, enables faster and more accurate typing

• Improvements to the chipset, Freezer, SD card utility, and Configuration utility

  • Fixed mouse handling in port 2

  • Configuration utility now prompts to power cycle on exit, to avoid confusion

• Support for the upcoming R6 main board (and intermediate test versions R4 and R5)

Notable changes in the MEGA65 ROM from release v0.95 to v0.96 (see the ROM changelog for a complete list):

• Screen editor and KERNAL use the new hardware typing event queue, for faster and more accurate typing

• 80 x 50 text mode: press ESC then 5 (press ESC then 8 or 4 to select 80x25 and 40x25)

• Default sprite images, including a mouse pointer in sprite slot 0

• GO64 mode now displays a custom banner instead of the C64 banner, so it’s easier to distinguish between GO64 mode and the C64 core

• Support for booting MEGA65 cartridges, based on the MEGA65 cartridge protocol

• Run/Stop-Restore now restores the character set

• Improvements to the Monitor, Renumber, BASIC commands, DOS

• For this release only: the ROM will detect whether it is being run with an older core or Xemu version, and halt with a message. Be sure to use the v0.96 core or a recent version of Xemu with this ROM.

What’s next?

A big blow-out party! Or maybe just some rest and relaxation. It’s been a long haul, with some heroic efforts from the development and testing team in the last few weeks. Everyone has chipped in to make this release and the next delivery batch of MEGA65s the best as they can be.

The core team will proceed with working on a follow-up release, currently expected to be called v0.97 and released in a few months. This will include some clean-up tasks that were deferred from v0.96 to hit the batch #3 delivery schedule, including full support for DevKits and Nexys boards.

As for ROM development, there’s exciting news! We’ve been focusing primarily on bug fixes over the last year, mostly to ensure we’re making the best use of the very limited space we have for new ROM code. The next ROM beta test will include the results of a project I’ve been working on to make more code space available for new features. I have taken this opportunity to implement a bunch of features requested by the MEGA65 community over the last two years, and these will also be included in the next beta. Remember that beta releases may have bugs, so thanks in advance for your patience, and your bug reports! Stay tuned to the Discord for an announcement, very soon.

And one last obligatory plug: My contributions to the MEGA65 project, including this newsletter, are made possible with support from retro computing enthusiasts like you! Please consider a monthly donation. Visit ko-fi.com/dddaaannn.

Thanks all! Back again in March with another full issue.

— Dan

Spaceships. Aliens. Marios. Goombas. Bullets. Fireballs. Mouse pointers, text cursors. Any of these could be a sprite, a feature of a computer graphics system dedicated to things that move. The sprite capabilities of the Commodore 64’s VIC-II chip super-charged video games and user interfaces beyond a single screenful of character text or a bitmap image. The MEGA65 includes support for VIC-II hardware sprites, and has sprite-related BASIC commands that make them easy to use in your programs.

In this Digest, we’ll review the VIC-II sprite system’s capabilities, try out the sprite features added to Commodore BASIC for the C128, C65, and MEGA65, and step through a development workflow for using sprites in BASIC games. And we’ll try putting these pieces together to make a simple arcade game.

But first…

The User’s Guide, 2nd edition, now available

You can now buy a spiral-bound printed copy of the MEGA65 User’s Guide, 2nd edition!

This new edition has been updated substantially from the 1st edition printing from two years ago. It covers the upcoming v0.96 release, with instructions for new features like Ethernet file transfer, and revised information on important topics like upgrading the firmware and using disks. The BASIC reference has been updated with corrections, polish, and material on new features. And there are handy new appendices on screen codes and system colors.

Whether you have the 1st edition and want to upgrade, or don’t yet have a MEGA65 and just want a useful book to go with Xemu, getting the 2nd edition in print is a great way to enhance your MEGA65 experience.

I wrote a FAQ with more information, including what’s happening with the manuals bundled with new MEGA65s. Let me know if you have any questions.

Release testing update

The v0.96 release package has been in public testing for a month, and we’ve been chasing down issues and polishing it up for factory installation on all of the new MEGA65s. This process should be complete a week or so after you read this. Many thanks to everyone who has contributed to the testing effort!

What happens next: the v0.96 release package will be made official and sent to Trenz for the factory installation on new machines. It will be declared the new stable release for R3A and R6 mainboards, and made available on Filehost. Everyone with the “retail” MEGA65 will be encouraged to upgrade.

DevKit and Nexys board owners will need to wait, just a bit. In order to meet the assembly schedule, we have had to defer preparing new cores for these boards until after this release. The plan is to immediately start work on these deferred tasks, and issue a v0.97 update within a couple of months that includes support for these boards. You’re always welcome to help test along the way, just be aware of known issues with slot 0 flashing on the older boards.

Upgrade party at lydon’s place! 🎉

New Intro Disks!

Gurce has put a ton of work into preparing the new software bundle for the SD card that will ship with the new MEGAs. Current owners are familiar with the “Intro Disk” menu that starts when you first switch on the computer, as well as other bonus goodies that come on the pre-installed memory card. The new bundle includes all of that and much more, a total of 191 (one hundred and ninety one!) menu entries. And that’s not even counting the disk menus themselves, with useful information and musical accompaniment. This compilation starts all new MEGA65 owners off with plenty to do on their first day. Huge thanks to Gurce for his meticulous work on this project, and of course to everyone who has written software for the MEGA65.

You can download the new software bundle on Filehost. (There’s a separate download for registered owners with a more complete version of GEOS.) If you don’t yet have a MEGA65, you can try it out in Xemu—or save it as a surprise for when your MEGA65 arrives!

New on Filehost

Don’t miss these new titles on Filehost:

Rocket Delivery Service, by fredrikr, a new game for one or two players. Navigate your rocket man to pick up and deliver packages, for cash! Each player can use a joystick, or player one can use the keyboard while player two uses a joystick. Written entirely in BASIC!

MJoergen and sy2002 are updating their vintage platform cores for use on the new R6 mainboard. The ZX Spectrum core v1.2 is now available, and there is a beta test version of the C64 core v5.1 (link goes to Discord) to be released soon. The C64 core update also includes a few fixes for all mainboards, and support for using the MEGA65’s Real-Time Clock with the Commodore 64 version of GEOS.

muse has yet another arcade core, and he keeps picking my favorites! Elevator Action (1983), a spy thriller set in a multi-level top secret facility. Infiltrate the building from the roof, avoid the armed goons, collect the secret files, and escape through the parking garage. As with the other arcade cores, you must locate the arcade ROMs yourself, so be sure to follow the installation instructions. Hold the button to jump.

Amiga fans: geehaf has published an ADF disk image utility that can use the MEGA65’s physical floppy drive to make Amiga disks from ADF files, and vice versa. This is a beta release of the tool, so take care to back up important data.

Exploring sprites

The hardware sprites of the VIC-II chip should be familiar to anyone who has written a program for the Commodore 64. The Commodore 64 Users Guide that came with the machine included a chapter on sprite graphics with a type-in demo. C64 programmers may also remember drawing out pictures on graph paper, hand-coding them into decimal numbers, typing them into DATA statements, and messing about with dozens of arcane POKE statements. In later computers and later versions of BASIC, Commodore added a BASIC sprite subsystem with access to most of the VIC-II’s sprite features, driven by a new set of commands. No POKE-ing necessary.

From here on, when I say “sprites,” I’m referring to the built-in sprite features of the VIC-II chip that have carried forward from the Commodore 64 to the MEGA65. Experienced game programmers would want me to point out that the general term “sprite” could apply to any kind of moveable graphics object, and there are, in fact, other ways to accomplish sprite-like effects on the MEGA65. We’ll have to cover those in later issues of the Digest.

The best way to get to know Commodore sprites is to try out the commands! The new v0.96 release version of the MEGA65 ROM includes pre-defined sprite images for a mouse pointer and a simple line pattern, so you can get started without drawing any graphics. If you’re using the previous release, you can still switch on the sprites, you’ll just see a blob of pixels that represents uninitialized memory contents.

Getting a sprite onto the screen

The VIC chip can keep track of up to eight sprites at a time, numbered 0 through 7. Each sprite has a set of modes and flags, including a flag to enable or disable the sprite. You manage these flags with the SPRITE command.

To turn on sprite 0:

SPRITE 0,1

Nothing appears to happen because the sprite starts located off the screen. Let’s move it roughly to the middle of the screen so we can see it (X=160, Y=120):

MOVSPR 0,160,120

While many of BASIC 65’s sprite commands originate with BASIC 7 and the Commodore 128, there are subtle differences. For example, on the C128, sprites are numbered 1 through 8. I won’t describe every difference here, just be aware that they’re not exactly the same on both computers.

Pixels and colors

In the default sprite mode (sometimes called “high resolution” mode), each sprite is 24 pixels wide and 21 pixels high, using a single sprite-assignable color for each “on” pixel (bit 1) and treating each “off” pixel (bit 0) as transparent. This is encoded as three bytes per row (8 bits per byte x 3 bytes = 24 pixels), for a total of 63 bytes (21 rows x 3 bytes per row) per sprite image.

You can set the color of a sprite with the SPRITE command. You can omit any argument you don’t want to change by specifying just a comma. The color value refers to the palette entry, in this case the default system palette. To turn sprite 0 red (palette entry 2):

SPRITE 0,,2

On the MEGA65, you can change the system palette using the PALETTE COLOR command. Each palette entry can be any of 4096 possible colors, with a red, green, and blue component each between 0 and 15. This changes the palette entry for all uses of the color on the screen, not just sprites. To replace the red color at entry 2 with a bright green:

PALETTE COLOR 2,12,15,4

To restore the default palette:

PALETTE RESTORE

Multicolor mode

If you’re willing to use a lower sprite resolution of 12 double-wide pixels per row instead of 24 single-wide pixels, you can set a sprite to multi-color mode, for two more additional colors. The two new colors must be shared by all sprites that are in multi-color mode. In this mode, sprite pixels are encoded as bit pairs: 00 for transparent, 10 for the sprite color, and 01 and 11 for the two shared colors.

Let’s try setting sprite 0 to multi-color mode, using a value of 1 for the seventh argument to SPRITE:

SPRITE 0,,,,,,1

If you’re using a ROM beta version, the default mouse pointer image of sprite 0 might not look that impressive in multi-color mode. Try enabling sprite 1 and moving it to the middle of the screen, then put it in multicolor mode. The default image of sprite 1 is designed to illustrate multicolor mode, with a repeating pattern of 00, 01, 10, and 11 bit pairs. (If you’re using release v0.95’s ROM 920377 or earlier, you’re in luck: the garbage data that’s usually there typically has an interesting combination of bit pairs.)

To set the two shared colors for the multicolor sprites, use the SPRCOLOR command, with the two palette entry numbers:

SPRCOLOR 4,5

Double width, double height

Each sprite can be displayed normal size, double width, double height, or both double width and double height. The double modes don’t give you more pixels: instead, they stretch the existing sprite design in the requested dimension.

These modes can be selected per sprite, and are the fifth and sixth arguments to the SPRITE command, respectively. Try the combinations of 0 and 1 for these arguments:

SPRITE 0,,,,1,1

Sprite priority

Each sprite can be set to appear above the character or bitmap layer, or below it. When above, you can see the character or bitmap through the sprite’s transparent pixels.

Use the cursor keys to move the text cursor to where the sprite is on the screen, then type some characters underneath it. On a blank line, set the fourth argument to SPRITE to 0 or 1, and see what happens:

SPRITE 0,,,1

When sprites overlap each other, lower numbered sprites are always in front of higher numbered sprites. This order cannot be changed. Use SPRITE to make sure two sprites are active, then use MOVSPR to locate them so that their images overlap.

SPRITE 1,1
MOVSPR 1,160,120

Overlapping sprites is a common way to draw a high resolution graphics object using more than one color: just use more than one sprite to represent the object, and allow pixels of lower sprites to shine through the transparent pixels of upper sprites.

Location, location, location

A sprite can be located at any pixel location on the screen. A sprite’s location is specified as coordinates on the screen, where the sprite’s top-left corner is placed at that location. Coordinates extend to locations under the screen border, and a sprite that overlaps the border will be obscured. This allows a sprite to glide off the screen smoothly until it disappears. (Note that double-width sprites won’t fit completely under the left border.)

To place a sprite exactly in the top-left corner of the screen just inside the border, set its coordinates to X=24 Y=50. If a sprite is in its normal display mode (with its double-width double-height features turned off), you can place the sprite’s bottom-right corner exactly at the bottom-right corner of the screen with coordinates X=321 Y=229.

The VIC-II sprite coordinate system is independent of the resolution of the underlying screen mode. The MEGA65’s default 80-column text screen is actually 640 pixels wide. VIC-II sprite coordinates refer to the same locations regardless of the MEGA65 screen resolution. If you switch to the 40-column text mode, the sprites will remain where they are.

Sprite coordinates are the same for both NTSC and PAL video modes. Even though these modes use different dimensions for the full screen, the dimensions inside the border are the same.

We’ve already seen how the MOVSPR command can set a sprite to specific coordinates. This command has several other useful features. To move a sprite to a relative distance from its current location, use a + or - and an offset for the coordinate value (X, then Y):

MOVSPR 0,+20,-10

The MOVSPR command can animate the movement of a sprite at a given speed. This animation happens asynchronously to BASIC program execution, similar to the PLAY command for music: the animation occurs in the background while the rest of your code continues to run. To move a sprite from one coordinate pair to another, use the TO keyword, and provide a speed as a number of pixels per frame. Remember that PAL mode refreshes 50 frames per second, while NTSC mode refreshes 60 frames per second, so the movement speed differs based on video mode.

MOVSPR 0,100,100 TO 250,200,5

Note that the sprite needs to hit the end coordinate almost exactly for the sprite to stop. If the speed is not a multiple of the differences between the starting and ending coordinates, the sprite might overshoot its destination and wrap around the screen until it finally lands where it was told. If there’s a chance of this, you may need to resort to a loop that tests RSPPOS() and stops the sprite with another MOVSPR command when it is close enough.

A sprite can be set to move continuously, with no fixed end coordinate. To do this, provide an angle as a number of degrees, with 0 degrees being “up” and proceeding clockwise, so 90 is right, 180 is down, and so forth. Follow this with a # symbol and the speed.

MOVSPR 0,135#1

The sprite will continue to move at this angle and speed until you set its speed to 0 with another MOVSPR command, or until you switch it off with the SPRITE command.

MOVSPR 0,0#0

When a moving sprite leaves the screen, it will continue to move until its position wraps around to the other side of the screen. If you want to test the position of the moving sprite, such as to stop its motion after it is off screen, use the RSPPOS() function. This takes the sprite number, and an argument identifying the parameter to return: 0 for the X position, 1 for the Y position, 2 for the speed.

Here’s a short program that starts the sprite moving to the right, then stops it either when a key is pressed or the sprite leaves the screen:

10 SPRITE 0,1
20 MOVSPR 0,100,100
30 MOVSPR 0,90#1
40 GET A$
50 X=RSPPOS(0,0)
60 IF A$="" AND X < 345 THEN 40
70 MOVSPR 0,0#0

Collision detection

The VIC chip can report when two sprites have non-transparent pixels on top of each other, or on top of the character or bitmap layer. Your program can use this to detect collisions between sprites, or between a sprite and the background, such as to know when a player’s bullet hits an alien ship, or when the player’s ship crashes into a mountain.

BASIC 7 on the Commdoore 128 introduced an interesting mechanism for handling sprite collisions. To tell BASIC that you care about sprite collisions, you use the COLLISION command to indicate the type of collision (1 = sprite on sprite, 2 = sprite on background), followed by a line number of your BASIC program. At some later point, when the VIC detects the requested collision type, BASIC will stop whatever it is doing and jump to the given line number as if it were a GOSUB subroutine. Your code at this line number should do whatever it needs to do to react to the collision, then use the RETURN command to resume where the program left off.

Your handler subroutine is called for any collision of the requested type. Your code will need to use other tests to determine which collision took place. The BUMP() function reports which sprites were involved in a collision since the last call to BUMP(). You can also use the RSPPOS() function to test individual sprite locations to further determine where the collision took place. See the User’s Guide for information on these functions.

Try to guess what this program does, then type it in and run it:

100 SCNCLR
110 X=0
120 SPRITE 0,1
130 MOVSPR 0,100,100
140 MOVSPR 0,90#1
150 CURSOR 70,6
160 PRINT "XXX"
170 COLLISION 2,220
180 GET A$
190 IF A$="" AND X=0 THEN 180
200 MOVSPR 0,0#0
210 END
220 PRINT "BLAMMO!"
230 X=1
240 RETURN

The VIC’s built-in collision detection is not always the most reliable way to detect game events. Depending on the shapes of your sprites and other factors, you may prefer a different method to detect collisions, such as by testing sprite positions relative to a hitbox. To do this, instead of a COLLISION handler, you’d make repeated tests of RSPPOS() in your game’s main loop.

Another caveat: There is a known issue with the VIC-IV core where sprite collisions are not detected with bitmap graphics (the BASIC 65 SCREEN system). Collisions are limited to sprite-to-sprite and sprite-to-text for now. Of course, there’s quite a bit you can do graphically in text mode using PETSCII graphics, and custom character sets with the CHARDEF command.

Other sprite features?

If you grew up with a Commodore 64, these sprite features probably feel quite familiar. The C128 sprite commands, and the C65 and MEGA65 additions, are handy, but the sprites themselves mostly look like they did on the VIC-II.

For the VIC-III video chip in the Commodore 65, Commodore added no new features to sprites. Sprite colors use the VIC-III system palette, and you can adjust the colors of the system palette to any of 4096 possible colors. Otherwise, they’re basically the same as they’ve always been.

The MEGA65’s VIC-IV adds advanced sprite features, such as a full-color mode with actual-size pixels, four palette banks, a 64-pixel width monochromatic mode, variable pixel height, and high resolution sprites that use the actual pixel width and coordinate system of a 640-wide (80-column) display. BASIC 65 does not yet support any of these features with the BASIC sprite commands. You can adjust VIC-IV registers directly with POKE statements, but this may interfere with the behavior of the BASIC commands. I’m currently working to extend BASIC 65 with official support for VIC-IV sprite features, so stay tuned for updates!

Managing sprite image data

Playing with the built-in sprites is fun and all, but for our own programs, we obviously want to draw our own sprite images.

Using the Sprite Editor

Did you know that the Commodore 128 has a built-in sprite editor? The C128’s SPRDEF command opens a sprite editor that directly manipulates the BASIC sprite image data in memory. For whatever reason, Commodore removed SPRDEF for BASIC 10. The good news is, the MEGA65 has its own sprite editor, “SpritEd,” built into the Freezer.

Hold Restore for one second then release to open the Freezer, then press S to start the sprite editor. This utility edits sprite image data at the BASIC sprite locations in memory.

A word of warning. SpritEd is currently unfinished software. Up to platform release v0.95, SpritEd crashes the machine if you press the Up Arrow key. I discovered this while writing this article, and I committed a fix to prevent this that will be in release v0.96. I recommend upgrading to release v0.96 before doing any serious work in SpritEd.

SpritEd is missing a bunch of its intended features, such as the ability to load and save images to disk. Even without these features, it is about as useful as the C128’s SPRDEF tool, and can edit sprite image data in memory. We’ll see how to get sprite image data from memory into your program in the next section.

Press the Help key for a list of keyboard controls. Briefly, these are as follows:

• To select a drawing tool: P for single pixels, L for a line, X for a box, Shift-X for a filled box.

• Press Space to draw with the selected tool. Del uses the tool with the background component, such as to erase a pixel.

• To erase the entire sprite: Ctrl+N.

• To select a “component” (color) to draw with: + and - rotate through the choices. In monochrome mode, this is just the background (transparent) and foreground. In VIC-II double-width multi-color mode, there are two additional components for the shared sprite colors.

• To change the color of the currently selected component: 0 through 9, A through F assigns one of the sixteen palette entries to the component.

• To select other sprites: comma (,) and period (.) rotate through the eight sprites.

• To change the sprite mode: * rotates through monochrome, VIC-II multicolor, and VIC-IV multicolor modes. Remember that BASIC does not yet support VIC-IV multicolor mode directly, so this last mode won’t be useful until we finish the new features.

• To see what your sprite looks like when expanded horizontally or vertically: use H and V to toggle these modes.

SpritEd supports drawing with a mouse connected to port 1. I discovered a small bug where the mouse can’t draw in the rightmost column, which should be easy to fix in a future version.

To exit SpritEd, press F11 to make sure the current sprite is saved to memory, then press F3 to exit back to the Freezer menu. Each sprite image is saved to memory automatically when you flip between the sprites, so F11 is only necessary on the current sprite, if it was modified. (That feels like something else we can improve pretty easily. Just know that’s how it works for now.)

Storing sprite image data on disk

The gorgeous sprite graphics we created in SpritEd are now in memory, but they’ll disappear forever if we don’t get them out of memory and onto disk. BASIC 65 makes this easy: SPRITE SAVE "filename" saves all eight sprite images to a file on disk. SPRITE LOAD "filename" loads them back in.

This provides a POKE-free workflow for managing sprites for BASIC programs:

1. Create sprite images in the SpritEd utility. Press F11, then F3 to exit back to the Freezer menu, then F3 again to resume BASIC.

2. Execute the SPRITE SAVE "filename" command to save all eight sprite images to a file.

3. Then in the program, use the SPRITE LOAD "filename" command to load these images.

Animating sprite images

For a game like Space Invaders, a ship can be a single sprite image whose only animation is to move around the screen, such as with the MOVSPR command. For a game like Pac Man, the player sprite should open and close its mouth, which means updating the sprite’s image data. We can’t exactly load a new Pac Man from disk each time he opens and closes his mouth, so we need another way to update sprite data within the program.

The SPRSAV command copies sprite data between sprite slots and BASIC string variables. It takes two arguments: the source and the destination. One or both of these can be a number between 0 and 7 to refer to the sprite image. If the other is a named string variable, the variable is used as either the source or destination.

For example, to copy the image data from sprite 2 to the string variable C$:

SPRSAV 2,C$

To copy that image to sprite 5:

SPRSAV C$,5

Combined with SPRITE LOAD, you can use SPRSAV to load all of your sprite patterns into string variables, then store them back into sprite slots during game play as needed.

You can also use string variables and SPRSAV along with disk operations as an alternative to SPRITE LOAD. For example, you can store more than eight patterns in a single file. Each pattern is 64 bytes in length. See any good reference on disk commands for more information.

Putting it together

Sprite Attack is a simple game I wrote to demonstrate how the sprite features can be used together. Get it here:

• Sprite Attack: spratk.d81

Try it out with a joystick in port 2. It’s written entirely in BASIC, so type LIST to see the program listing. A few notes:

• I used SpritEd to draw eight multicolor sprites: the player’s spaceship, the player missiles, the space alien death ray, four frames of an explosion animation, and the space alien itself. I exited SpritEd and the Freezer, then used the command SPRITE SAVE "SPRATK.DAT" to save the sprite data to disk. The program starts by loading this file with SPRITE LOAD.

• I keep the player’s X position in a variable so I can fine-tune the speed that the player moves. Pixel locations are always integers, but sometimes you want a sprite to move in non-integer increments, such as 1.8 pixels per frame. The variable holds the non-integer location, and this value is rounded to the nearest pixel when I pass it to the MOVSPR command.

• The game loop tests for joystick movement, adjusts the variable, and updates the player location with MOVSPR. Because the player only moves left and right, I use +0 as the Y coordinate argument to MOVSPR so that I don’t have to remember the ship’s vertical position after initializing it.

• I use the VSYNC command to synchronize gameplay with the frame rate. This makes it easier to tune the movement speeds, and it prevents the sprites from “tearing” by making sure the location doesn’t change while the sprite is being drawn.

• Player missiles use the movement animation system. The RSPPOS() with a second argument of 2 returns the current speed of a sprite, so I can test whether the missiles are moving. If the button is pressed and the missiles aren’t moving, I set their position to just above the player ship and set them moving in an upward motion, then I activate the missiles sprite. I also test once per loop if the missiles have gone off the top of the screen, and if so, I stop their motion by setting their speed to zero.

• The alien also uses movement animation. If the space alien is ever stationary (speed is 0), the program chooses a new random location, and calls MOVSPR with the current location as the origin and the random location as the destination. This gives the alien an evasive behavior that still gives the player a chance to target it with missiles.

• A collision handler detects when the missiles are in contact with the alien. When the alien is hit, the routine moves the explosion sprite to the alien’s location, disables the missiles sprite, then moves the alien sprite to another random starting point above the screen. It plays out the explosion animation using SPRSAV to copy in the explosion patterns we saved into string variables earlier, pausing between each frame. This causes all gameplay to pause while the explosion finishes. A more sophisticated game would handle explosion animations in the main game loop, so other events like player movement can take place during the animation.

This game is a little unfair—to the alien. Try extending this program to have the alien shoot back at the player, using its death ray in sprite 2.

VIC hardware sprites and the BASIC 65 sprite commands are a fun and easy way to code video game graphics. Combine them with PETSCII graphics to draw level maps, backgrounds, and informational displays, and you have all of the elements of a great looking game. Be sure to share your games with other MEGA65 owners by uploading them to Filehost!

There are some advanced sprite techniques I wanted to mention here, but they’ll have to wait for another issue. You can help make more issues possible by supporting the Digest on Ko-Fi.

As always, happy coding!

— Dan

It’s time! We have a shipping schedule for the next batch of MEGA65 computers, and a candidate for the next platform release. Everyone is invited to help with testing, so let’s get to it!

Shipping update!

Trenz Electronic has announced that the next batch of MEGA65 computers will ship on June 1st, 2024.

We currently expect that all preorders up to this point will be included in this batch. If you need to make adjustments to your preorder before then, contact sales@trenz-electronic.de.

Once we clear the preorders, remaining stock will become available for purchase in the Trenz Electronic store, while supplies last.

Please bear with us while we work through any last minute issues that might change these estimates. And thank you so much for your patience! I can’t wait for you to receive your MEGA65!

v0.96 release candidate now available to test!

To make the new delivery schedule, we need to hand over the gold masters of the next release of the MEGA65 firmware and system software, as well as the updated User’s Guide, to Trenz Electronic by January 31st. Release v0.96 of the firmware, ROM, and system software will be installed at the factory on all MEGA65s about to ship. Of course, it will also be available as a free upgrade for all existing MEGA65s. This next release has a ton of new features and bug fixes—and we need testers!

If you have a MEGA65, you can install the release candidate on your machine to help test. If you don’t have a MEGA65 yet, you can still help by testing the new version of the ROM with an updated version of the Xemu emulator.

Testing the release candidate on a MEGA65

To begin, be sure to back up your SD card, or use an alternate SD card, before proceeding with testing. I usually just move the SD card to my PC, then copy all of the files from the SD card into a folder on my desktop. This doesn’t back up the configuration or Freeze states, but personally I don't keep important freeze states around long term. Alternatively, you could also use a disk imaging utility to back up both the hidden configuration partition and the files partition.

If you’re using a fresh SD card for testing, remember to prepare the card first using the MEGA65’s SD Card Utility. Insert the card in your MEGA65, hold the Alt key while switching on the computer, then select the utility from the menu and follow the prompts. This erases all data on the card.

Here’s how to get the files for the release candidate:

• Release v0.96 RC core and system software. Select the latest build that begins with mega65r3-r-0.96, such as mega65r3-r-0.96-build-5.7z. The “r3” refers to all MEGA65s delivered up to this point. The MEGA65s shipping in June will be known as “r6.” Yes, we’re skipping R5 after all: we found one small non-electrical change needed for the board during R5 testing.

• Release v0.96 RC ROM. Sign in with your Filehost account with your owner code redeemed to access this. Download the most recent version: 920391.bin.

• MEGA65 command line tools: Windows, Mac, or Linux. These will be bundled with, and be the basis for, an upcoming version of the M65Connect app, and are generally useful on their own for the new Ethernet file transfer feature.

• The MEGA65 User’s Guide, 2nd edition (PDF).

Unpack the mega65r3-r-0.96-build-5.7z archive. Transfer the .cor file to the root of your SD card. Open the sdcard-files folder, and copy its contents (.M65 files) to the root of the SD card as well.

Rename 920391.bin to mega65.rom, and transfer it to the root of your SD card.

Install the SD card in your MEGA65. With the power switched off, hold No Scroll then switch on the computer. This opens the core selection menu. Hold the Ctrl key and press a number to select an appropriate core slot for the new core, then follow the prompts to select the .cor file and flash the core. See the User’s Guide for more information about upgrading cores.

Using both the release candidate and the previous stable release with one MEGA65

I recommend keeping both the release candidate and the previous stable release installed during testing. If you find any issues with the release candidate, it will be important to determine if those issues also exist with the previous stable release, or if they are new issues introduced by a recent change.

Choose one or the other to be the default for your computer. Flash the core you wish to be the default to core slot 1, and name the default ROM as mega65.rom on the SD card. For the non-default release, flash the core to slot 2, and name the ROM file as mega652.rom. To start the non-default release (whichever one you chose), hold No Scroll while switching on the computer to open the core selection menu, then press and hold the number 2 until you see the READY. prompt (and probably a bunch of 2’s). This selects core slot 2 and also selects mega652.rom.

There’s one tricky bit with a dual installation: you can only have one set of system software on the SD card. I have not had any issues running the new system software with the previous stable core and ROM, so my recommendation is to go ahead and use the release candidate system software as the system files on your SD card.

It’s important to note that the release candidate ROM only works with the release candidate core. If you accidentally select the release candidate ROM (version 920391) and the previous stable release core, typing won’t work correctly and you’ll see the cursor disappear. If this happens, switch off the computer, hold No Scroll while switching it back on, then select a matching core and ROM. You can use the previous ROM (version 920377) with the new core, just not the other way around.

You can confirm that you’re running the release that you intend with the new MEGAINFO utility. Open the Freezer—hold the Restore key for a second, then release—then press the Help key. This is a feature of the new system software, and it works with either release as long as the new release’s system software is on the SD card.

Testing the candidate ROM in Xemu

If you do not have a MEGA65, you can still help test the ROM in the Xemu emulator. Get these files:

• Release v0.96 RC ROM patch. Follow the instructions in the ROM FAQ to put together the MEGA65 ROM 920391 using the free C64 Forever download from Cloanto.

• Xemu “next” release. Look at the bottom of the page for “The ‘future next stable’ still unstable (“next” branch) builds” for your platform. Download and install.

• The MEGA65 User’s Guide, 2nd edition PDF.

Run xmega65, and when prompted for a ROM, use the new ROM.

Just as the release candidate ROM (version 920391) depends on the release candidate core, it also depends on the “next” version of Xemu. If you try to use the new ROM with the previous stable version of Xemu, you will notice problems with typing.

What to test

This release is the culmination of 15 months of improvements and fixes across the board. Changes to the ROM are listed in the ROM change log. Changes to the core are numerous and we’re still assembling the core change log, but here are a few notable features:

• Ethernet file transfer. See the updated User’s Guide or this wiki page for instructions on how to transfer files between your PC and the MEGA65 using just an Ethernet cable. Notice that this requires flipping a small switch on the mainboard, so you will need to open your MEGA65’s case.

• Hardware accelerated typing. You should notice that typing at the READY. prompt and in most apps is more accurate, especially for fast typists. This should not affect MEGA65 software in any other way.

• Improvements to mouse handling, with smoother motion and support for mouse and paddles in port 2.

• Coming soon: New core flashing capabilities—and a way to flash slot 0. The special core slot 0 controls aspects of the MEGA65 boot process, and it is intentionally more difficult to flash so you always have the factory-installed MEGA65 core available. With this release, there will be a new way to update the core in slot 0 to claim the benefits of improvements made to the boot process. As of this writing, this feature is not yet in the release candidate. Stay tuned to the Discord for an announcement of when and how to test this.

• Coming soon: Configurable cartridge booting. Flashing this core to slot 0 enables the ability to configure the boot process to use a specific core when a type of Commodore cartridge is connected. This is primarily so you can assign C64 cartridges to the C64 core, instead of the less capable GO64 mode of the MEGA65 core and ROM. This change also introduces a new cartridge signature and boot protocol for MEGA65 cartridges, though you’ll need an EasyFlash 1CR cartridge and a test image to test it.

In addition to testing new features, we want to know about anything that worked in the last stable release and appears to have stopped working in the new release candidate (called “regressions” in software engineering parlance). This includes, but is not limited to:

• Your favorite MEGA65 games, apps, and utilities

• BASIC commands and features

• The core menu, core flashing, configuration, “on-boarding,” and the SD card utility

• The Freezer, and features accessible from the Freezer menu

• Procedures and information described in the User’s Guide, 2nd edition

• Anything that worked in GO64 mode with the previous stable release

How to report issues

There are two ways to report any bugs you find. We have an active thread on the Discord for collecting release candidate bugs. Look for the platform-testing forum. Alternatively, you can file issues directly to the Github repo for the core, the repo for the ROM, or the repo for the User’s Guide. If you’re not sure where the bug goes, file it in the core repo, and we’ll triage.

If you find something that doesn’t look right, try to reproduce it in the previous release. File a bug either way, and make sure to note whether this only happens in the release candidate, or if it happens in both versions.

Many thanks to everyone who is available to test! We’re on a tight schedule, so anything you can do before the end of January would be a huge help.

About that User’s Guide…

Every MEGA65 includes a printed version of the MEGA65 User’s Guide, a book that includes set-up instructions, common procedures, an introduction to BASIC programming, and a BASIC command reference. We printed a large quantity of the 1st edition, and everyone who has received a MEGA65 so far has this edition. We can’t afford not to use the remaining stock, so we will be including copies of the 1st edition with some MEGA65s that will ship in June.

The User’s Guide has been revised with new material on new features like Ethernet file transfer, and a renewed focus on non-developer activities like using virtual disk images and upgrading the firmware. The entire Guide has been polished with corrections, and the BASIC reference has been updated to include the most recently added features. We’re calling this the “2nd edition,” and we will be printing new Guides to include with MEGA65s after the stock of the 1st edition is depleted.

Do you want a printed copy of the 2nd edition? I know I do! I’m working on setting up the User’s Guide, 2nd edition with a print-on-demand service, so anyone who wants an updated printed Guide can get one. Whether you have the 1st edition and want to upgrade, or you’re just enjoying Xemu and want a book to go with it, you’ll be able to order a copy.

I’ll share the link to the purchase page in the next issue of this Digest. We’re using the release testing period to catch any last minute bugs in the Guide, and to make sure it matches the new slot 0 flashing procedure when it is finished. In the meantime, you can always download the latest draft PDF of The MEGA65 User’s Guide. (And report bugs!)

The 8-Bit Guy, and me!

YouTuber David Murray, aka “The 8-Bit Guy,” made a video about the Commodore 65 last December, borrowing Bo Zimmerman’s vintage C65 prototype to try it out. At the end of the video, David mentioned the MEGA65, mostly to say that he knew about the project but didn’t know anything about it. There were multiple attempts to get a review unit to David that fizzled out for one reason or another. When I saw that, I thought to myself, what can I do to help? I suppose I could… just go down to Texas and bring my MEGA65 with me. So I did!

Behold, the 8-Bit Guy’s video about the MEGA65, with special guest, me!

David is a co-founder of the Commander X16 project, a retro fantasy hardware project with similar interests to the MEGA65. Based on the 65C02 CPU, the X16 has a Commodore-like architecture and uses a Commodore-derived KERNAL and BASIC, while updating other aspects of the design to use readily available components and interfaces. Check out the X16 FAQ for details, and give the in-browser emulator a try.

Many thanks to David for hosting me and for appreciating the MEGA65. Thanks also to my Ko-fi supporters and to the MEGA65 team who helped make this possible.

Yes, your support of this Digest on Ko-fi is already making new things happen! If you would like to support the Digest and my involvement with the MEGA65 team, please visit: ko-fi.com/dddaaannn

Back again next month with more news, and more fun things to do with your favorite computer. Cheers!

— Dan

Our robotfindskitten adventure continues! In part 1, we introduced the robotfindskitten experience, and described tools and techniques for building an rfk game in BASIC 65. In part 2, we started building a similar toolkit in assembly language, starting with KERNAL routines, memory access techniques, and screen memory registers. This month, we complete the toolkit, and I present my own attempt at an assembly language version of the game.

But first, a whole bunch of new stuff!

R5 main board in testing!

The new R5 main board test units have arrived and Paul has started the “bring-up” process, adapting the FPGA core to the design changes. With some minor corrections to the assembly, this should resemble the main boards that will ship with new MEGA65s going forward, including all pending pre-orders. Many thanks to Paul, Trenz Electronic, and the hardware testing team for the work they are doing.

Unicone, by deathy

deathy has another new game release! In Unicone, you are chasing a unicorn that poops ice cream. Move your ice cream cone left and right to catch falling ice cream scoops dropped by the unicorn. A fun game in the tradition of Kaboom! (or its lesser known ancestor, Avalanche), Unicone features high resolution graphics, sampled sounds, a wide variety of control schemes, and a unique ice cream balancing mechanic for extra challenge in later levels. Download Unicode from Filehost.

Want to see how it works? deathy has generously released the C source code to Unicone using an open source license, and the assets using a Creative Commons license. The code builds with the Calypsi C cross-compiler, a modern retro development suite by hth313 that recently added support for the MEGA65’s 45GS02 CPU. Check it out!

The Ghosts of Blackwood Manor, by Stefan Vogt

Stefan Vogt, the author of the adventure games Hibernated and The Curse of Rabenstein, has a new adventure out for multiple platforms including the MEGA65. The Ghosts of Blackwood Manor is an interactive horror game with three possible outcomes, and each outcome fills out the story.

And of course, Ghosts is getting another gorgeous boxed release from poly.play! Pre-order the boxed release, and get it digitally right now for a donation of your choice.

Gurce’s BASIC 65 Dev Vlogs

Gurce has been doing a series of live stream development vlogs coding a game from scratch in BASIC 65, using the Eleven programming environment. The game, currently titled “Way of the Imploding Foot” (or just “MegaFoot” for short), is a side-view fighting game, featuring low resolution block character graphics, animated fighting characters, and parallax scrolling.

You can start with episode 1, and subscribe to find out about new live streams. Also check out the Github repository for the game, or just try the latest D81 disk image. When browsing the repo, be sure to locate the .ELPC files (such as FOOT.ELPC), which contain the code in Eleven syntax viewable as a text file on a PC.

Gurce is welcoming contributions on this project! If you’d like to try implementing a feature in BASIC using Eleven, let Gurce know on the Discord.

Discord upgrade!

The MEGA65 Discord is the MEGA65 community’s real-time meeting spot, a great place to ask questions, show off your projects, and meet other MEGA65 enthusiasts. Thanks to MEGA65 Discord moderator KiDra, the Discord now has a fresh new structure and some really cool new features! Here are just a few highlights:

• New section layout. Channels and resources are now organized in sections based on how you engage with the project, such as regular use, programming, and platform development. Click or tap a section title to collapse sections you use less often.

• Discord forums. Sections now include Discord forums in addition to text chat channels. Forums are especially useful for asking technical questions: each question stays visible in a list, and answers and discussions stay organized by topic. Once you have the answer you need, you can close the discussion, and it stays in Discord search history for others to find.

• Voice/video rooms. Sometimes it’s just easier to talk, you know? Hop into a voice room to start an audio or video chat. Show off your work, collaborate on a project, or just hang out.

• The Pin-Board. All of the most important community resources in one well-organized section! Announcements, official project status, and links to resources.

• Events. Want to organize a club meeting, schedule an online conference, or throw a party? Let everyone know by posting an event! Everyone will be able to express interest in your event and request an automated reminder when the event draws near.

• Self-service posting roles. To help keep the announcements and events channels clean and on-topic, we ask that anyone who wishes to post to them read a brief description of how they are used, in the #role-setup channel. Acknowledging the description grants permission to post, automatically.

• Starred posts. Did someone post something you think more people should see? Give it a ⭐️ reaction emoji! If enough people star the post, it will be advertised in the #starred-posts channel. This works from any public channel.

• Project channels. These discussion channels for specific MEGA65 projects by the community can be used for collaboration, on-going user support, or just dev logging and rubber ducking by the project developers. Want a channel for your project? Propose one in the #signup channel.

We will continue to evolve and improve the Discord based on the needs of the community. If you have any feedback or questions on the new layout and features, feel free to discuss it in the #mega65 channel, or contact anyone on the admin team. Thanks again to KiDra for setting all of this up!

Bad Apple… in BASIC?!?

As a follow-up to MEGApple, MirageBD’s high fidelity Bad Apple demo for the MEGA65, Nobato has a new version, this time in BASIC65! Bad Basic65 Apple Demo comes on multiple D81 disk images and can swap disks automatically from the SD card. The music is an original SID arrangement, using BASIC65 PLAY statements.

Boot B65APPL1.D81 to start. It takes a few minutes to load and decompress data into upper RAM—this is all in BASIC, remember—but once it begins, it runs smoothly, start to finish.

Don’t miss the Little Bad Basic65 Apple bonus disk, also included in the archive!

45GS02 assembly language mousepads and posters

A couple of weeks ago, I mentioned that I designed a 45GS02 assembly language quick reference, and you can purchase this design as a mousepad or a poster. Many thanks to everyone who has ordered a mousepad or poster so far! Proceeds go to supporting this Digest and my other work on the MEGA65 project.

I especially like how the mousepad turned out. It’s fun to look at, I can keep it on my desk as a mousepad, and it’s actually useful as a quick reference for MEGA65 assembly language programming. I just used it a couple of days ago to remind myself how the stack-related instructions work.

I’m using Zazzle to make and distribute these. They ship worldwide, and the shipping rates seem reasonable, only about 10 euros to ship the mousepad to Germany. I’ve had one report that there were technical issues trying to pay with PayPal. They also support credit cards. If you have issues, let me know, and I can try to figure it out.

The mousepad is a perfect companion for our robotfindskitten project. Speaking of which…

Finishing robotfindskitten in assembly language

To complete our robotfindskitten program in assembly language, we need to accept keyboard input, generate random numbers, de-duplicate choices, pause to animate the (very simple) ending sequence, and select from the list of item descriptions.

Accepting keyboard input from the KERNAL

A common way for a program to accept keyboard input is another KERNAL routine, getin at $FFE4. This loads a PETSCII code into the Accumulator if a key has been pressed, or 0 if not. This isn’t necessarily the best method for using the keyboard as a game controller, because it includes typing features like key repeat. But it’s easy to use, and for rfk, the built-in key repeat is reasonable behavior.

getin = $ffe4
; ...

-   jsr getin
    beq -
    cmp #17
    beq cursor_down
    ; ...

cursor_down:
    ; ...

In older versions of the ROM, the getin routine uses CIA registers to scan the keyboard. With the latest beta test version of the core and ROM that I mentioned last month, getin uses a new typing event queue implemented in hardware for greater accuracy. Your program will get the same result from either version: the pre-conditions and post-conditions of getin have not changed.

A program that doesn’t use the KERNAL can access the new hardware registers directly, or can implement its own keyboard scanner based on the CIA chips. See a Commodore 64 reference for information on how to do that.

getin also supports features like the function key macros and input redirection, which don’t apply to a game but could come in handy for other types of programs. getin and chrout are both part of the KERNAL’s input-output system, of which the screen and keyboard are only two possible devices.

Chaos

We need a way to select randomized locations and appearances for the items. In BASIC, we used the RND() function for this purpose. What can we do from assembly language?

The MEGA65 has a dedicated hardware register that produces random values. To use it, a program must loop to wait for a “not ready” flag to clear, then read the generated random number from a register. The act of reading the number restarts the process, setting the “not ready” flag while it works on a new number. Internally, the number generator is using a fluctuating oscillator to generate values, and it needs a brief amount of time between reads to produce good results.

random = $d7ef
random_ready = $d7fe  ; bit 7
; ...

-   bit random_ready
    bmi -
    lda random
    ; A is a random number between 0 and 255

Important note: If you test your software in the Xemu emulator, be sure to use the “next” branch release. As of this writing, the random number register implementation is not in the latest stable release, and the ready-wait loop will never exit.

The distribution of values returned by this register is even across all possible byte values 0 to 255. Because this distribution is over a range sized by a power of two, you can reduce the range to a smaller power of two by ignoring some of the bits. For example, to get a random value from an even distribution of 0 to 63, use the and instruction to set the upper two bits to 0:

    and #%00111111
    ; A is a random number between 0 and 63

If the range size is not a power of two, it is feasible to simply “re-roll” for a number within the desired range. This causes all picks outside the range to be distributed evenly across the desired range, so it does not skew the results. Of course, this can take an arbitrary number of tries to roll a value in range, so you can speed this up by combining both techniques: get a number 0 to 255, zero out the unused bits, then test whether the result is in range and re-roll if not.

-   bit random_ready
    bmi -
    lda random      ; 0 to 255
    and #%01111111  ; 0 to 127
    cmp #80
    bcs -
    ; A is now a random number between 0 and 79

To get a random number larger than 255, fetch two random numbers and treat them as a single 16-bit number. You can use similar techniques to narrow the range.

Another option is to implement a pseudorandom number generator in your own code. Such algorithms range in power and complexity and can be difficult to get right, but applications like simple games can often get by with something as simple as a linear-feedback shift register (LFSR). Pseudorandom number algorithms generate a sequence of numbers based a starting number, known as the seed. It can be an advantage during testing to use a known seed to get a predictable result. For the final program, you can use another source of randomness, such as the hardware random number register, to determine the seed.

If you’d like to try this, read the Wikipedia page on LFSRs carefully. See also this video from Retro Game Mechanics Explained on how the game Super Mario Bros. 3 nerfs its card shuffling algorithm by misusing an LFSR, apparently accidentally.

Avoiding duplicates

When we discussed random selection in BASIC last month, we put in some extra effort to store all previous choices in an array, and re-rolled the dice when we accidentally chose an already-selected character, location, or description. This ensured that no two items would be placed on the same location, which would not only appear as fewer items on the screen but might cause the kitten to be hidden by another item. Depending on how it was implemented, the robot might touch the location and only see the Non-Kitten Item even if the kitten was also at the same location. Ensuring diverse characters and descriptions also maintains variety in the gameplay, to avoid the disappointment of seeing the same description more than once in a game.

The assembly language version of this isn’t different, it’s just a bit more cumbersome than in BASIC. I allocated some array-like memory within the program’s memory space for this purpose, like so:

num_items = 20  ; max 127
item_description: !fill num_items*2
item_screen_code: !fill num_items
item_x: !fill num_items
item_y: !fill num_items

(Alternatively I could have put this on the base page, or elsewhere between $1700 and $19FF, which is available for program use.)

I wrote three assembly language routines that detect whether the value at position X is equal to the value at any position 0 through X-1, the idea being that as I fill the array from position 0 upward, I can check each item against the previous items. I needed three routines because each value is stored in a different way: characters are stored as one-byte screen codes, descriptions are stored as two-byte addresses (which we’ll see more of later in this article), and coordinates are stored as coordinate pairs in two separate lists.

Here’s the simplest of the three routines I came up with that checks for duplicate screen codes:

addrl = $00
addrh = $01
vall = $02

is_unique_byte:
    ; Y,Z: starting address of byte set
    ; X: index of last item
    ; Returns: Carry Set if item at X appears elsewhere in the set
    cpx #0
    beq @is_unique
    sty addrl
    stz addrh
    txa
    tay
    lda (addrl),y
    sta vall
-   dey
    lda (addrl),y
    cmp vall
    beq @is_not_unique
    cpy #0
    bne -
@is_unique
    clc
    bra @end
@is_not_unique
    sec
@end
    rts

A few notes:

• The routine accepts the starting address of item_screen_code in the Y and Z registers. I could have hard-coded the address into the routine, but this way I could potentially re-use it with a different array, or in another program.

• It uses the Carry flag as the return value, where Carry is set if a duplicate is found. The routine is not responsible for choosing new random values or updating any memory. It’s important to separate responsibilities between routines to make code easier to write, test, and re-use.

• It uses base page variables and indirect indexing (via the Y register) to access the array and remember the value under test. 6502-style CPUs have very few registers, so programs must rely on the base page (or the stack) to wrangle variables.

• With the Acme assembler, a symbol whose name starts with an @ character is a “cheap local:” it is only valid between two global symbols (such as is_unique_byte). This way I can re-use these symbol names in my other duplicate test routines.

These routines were challenging to get right! The algorithm isn’t complicated, but one errant instruction can cause all kinds of havoc. I found it useful to insert a brk instruction early in my program so that it would open the MEGA65 Monitor. From here, I would test these routines by writing values into the arrays, setting the registers, calling the routines, and inspecting the Carry flag.

To do this, I needed to determine the raw addresses of the routines and the arrays assigned by the assembler. You can tell Acme to generate a report of all of the addresses it used throughout the program, using the -r command line argument:

acme -r rfk_report.txt rfk.asm

The monitor commands r and m inspect registers and memory, respectively. To update values, you can move the cursor up to the lines that these commands print, change a value, then press Return. (Remember that addresses and values are in hexadecimal.) To call a subroutine, use the j command. See my tutorial on the MEGA65 Monitor, as well as appendix M of the manual, for more information.

Avoiding other bad choices

There are two more cases of bad item placement worth considering, at least briefly.

The robot also appears on the playfield along with the items. We need to make sure that an item doesn’t land on the robot’s starting position. My solution is crude but effective: I put the robot in the upper left corner of the playfield, then limit item placement to be within a one-tile border. This way, there is never an item where the robot starts, and the robot can move unimpeded around the entire edge of the playfield.

With items placed entirely at random within the border, it is possible, however unlikely, that four items might surround a fifth item. And if that fifth item is the kitten, then the robot will never be able to find it! Tragedy! I admit, I did not bother to solve for this edge case in my implementations, but it’s worth thinking about how this might be solved. One way is to test a chosen item location for surrounding items, and re-roll if a bad case is noticed. A complete solution would have to handle extremely unlikely cases like 19 items forming a wall around the kitten, and would probably involve path finding algorithms or other magicks.

A simpler solution is to only place items on odd numbered rows and columns. For example, within an 80-column width, pick a number from 0 to 38, double it, then add one. This produces a column coordinate from 1 to 77 and guarantees at least a one-space gap between items. Do the same for the row coordinate, and the robot is assured a clear path to every item.

Calm

One of the responsibilities of the CIA chips is to keep track of time. For coarse-grained timing, the CIA has a built-in “time of day” clock that counts up by tenths of a second. If your main loop executes faster than ten times per second, you can count upwards by tenths of a second simply by testing for when register $DC08 changes. The bottom four bits are a “binary-coded decimal” value between 0 and 9, representing the tenths-of-seconds value of the CIA’s clock. This can be a bit crude because you might be testing the register just before it ticks, so the actual delay might be off by as much as one tenth of a second.

todtenths = $dc08

wait_briefly:
    lda todtenths
    sta last_todtenths
-   lda todtenths
    cmp last_todtenths
    beq -
    sta last_todtenths
-   lda todtenths       ; Wait two ticks to pause between 1/10th
                        ; and 2/10ths of a second
    cmp last_todtenths
    beq -
    rts

last_todtenths: !byte $00

You can achieve a more precise wait loop delay using a feature of the VIC video chip. The VIC uses a finely-tuned high speed mechanism to describe the entire screen to a connected display many times per second, one line at a time from top to bottom, known as the raster scan. The current raster line number is stored in the RC register, as nine bits: bits 0 through 7 are at address $D012, and bit 8 of the number is stored as bit 7 at address $D011. In the same way that you can wait for the CIA TOD tenths register to change, you can wait for these register values to change for much shorter durations.

wait_very_briefly:
    ; Wait for bit 8 of the raster count to flip negative then positive,
    ; for a delay between 1 and 2 frames.
-   bit $d011
    bpl -
-   bit $d011
    bmi -
    rts

The tricky bit (because there’s always a tricky bit) is that the number of raster lines and the rate at which the screen is drawn differs depending on the video mode of the MEGA65. Back in the day, PAL and NTSC were competing standards for analog video signals, used for both transmission and rendering on cathode ray tube (CRT) displays. Commodore sold computers with different VIC chips in different regions to be compatible with the technical standard used in the region for televisions. As a result, Commodore games that used raster-based timing ran differently depending on which VIC chip was in the machine. A game might animate slower or faster than was intended, or it might play music at a different speed. In other cases, a game would only function correctly with one kind of VIC chip, and just trip over itself when running with mismatched VIC timing.

The MEGA65’s VIC-IV chip can generate PAL-like or NTSC-like video signals, as separate modes. Some MEGA65 owners are using displays (vintage or modern) that only support one of the modes. I asked everyone about their display modes in the 2023 survey, and 81% of the MEGA65 owners that responded have their video mode set to PAL by default, vs. 18% set to NTSC. Modern digital displays can often support both modes, but only 56% of owners were confident that their display could do this. A program can force the MEGA65 into one mode or the other using registers, but it’s best to leave it in the mode selected by the user in the configuration or Freezer menu.

The upshot is this:

• In PAL mode, the RC register counts up to 312 raster lines, at a rate of 50 times per second (50 Hz).

• In NTSC mode, the RC register counts up to 263 raster lines, at a rate of 60 times per second (60 Hz).

The actual image size is twice this many lines, fully refreshed at half these rates. The full image is drawn interlaced, with odd lines and even lines alternating with each refresh. 50 Hz or 60 Hz is the refresh rate; 25 Hz or 30 Hz is the frame rate.

It is possible for a program to achieve precision timing independently of video mode using the CIA chips and a system feature known as interrupt handling. Interrupts can also be used for raster-based timing. High speed games are most likely to use raster-based interrupts for timing because it makes it easier to control screen updates, and they will either live with the consequences of the different video modes, or use sophisticated techniques to work around them. Interrupts are a big topic, so we’ll leave that for another Digest.

robotfindskitten doesn’t need precise timing for anything, so raster timing is overkill in this case. I use CIA TOD tenths to add a simple delay to my found-kitten experience, and otherwise rely exclusively on keyboard events (and delays introduced by the key repeat handler) to drive the gameplay logic.

Data

We’re almost done! We have all the tools we need to display messages, choose and place items, animate the robot, move the robot based on keyboard input, and check for item interactions and the win condition. We just need a way to store, select, and display the 400+ possible item descriptions.

We’ve already seen how to add the bytes of a text message to the program in Acme, and to assign a label to its address:

message: !pet "\"I pity the fool who mistakes me for kitten!\", sez Mr. T.",0

What we need is a way to select from a table of messages by an index. For my robotfindskitten implementation, I used a Python script that reads the NKI descriptions from a text file, and generates !pet directives for all of them, with labels such as i1, i2, and so on. The script also generates an address look-up table with all of the generated labels in it. This puts the starting address of each description into memory at regular two-byte intervals. The program can find the description for a given index by multiplying the index by two (the asl instruction will do the trick), adding it to the address of the lookup table (nki_table), then reading the description start address from that location. Each description ends with a 0 byte, so the message printing routine knows where to stop.

nki_desc_count_mask = $01ff
nki_desc_count = 401

nki_table:
!16 i0,i1,i2,i3,i4,i5,i6,i7
!16 i8,i9,i10,i11,i12,i13,i14,i15
; ...

i0: !pet "\"I pity the fool who mistakes me for kitten!\", sez Mr. T.",0
i1: !pet "That's just an old tin can.",0
i2: !pet "It's an altar to the horse god.",0
; ...

Here’s the full procedure for assigning a unique description to a Non-Kitten Item, using the techniques we’ve discussed:

1. For each item, use the random number register to generate 16 bits (two bytes).

2. Apply a bitmask to cut down this 16-bit value to a 9-bit value, the smallest mask that would account for the maximum number of descriptions (512 > 401).

3. Compare the result to the actual maximum number of descriptions, and re-roll until the selected number is within range. This is the description index.

4. Multiply the index by two to get the offset into the lookup table. Add this to the lookup table’s starting address.

5. Read the description starting address from the lookup table at that location.

6. Store the description address in the item_description array, then test whether it is a duplicate. If so, start again from step 1.

Using tools and scripts to generate data embedded in a machine code program like this is an essential skill, especially for games. Some assemblers have powerful directives that make embedding and manipulating data easy, such as Acme’s !binary directive that pulls in binary data from a file. Kick Assembler’s inline scripting capabilities are especially impressive. I find it useful to know a modern scripting language like Python so I can write my own data conversion tools that generate either assembly code or binary data that can be embedded in my programs.

If you don’t want to write your own scripts to generate the NKI description table, you can borrow the source code for my version, linked below.

The final robotfindskitten program

Here are my final versions of robotfindskitten for the MEGA65, in both BASIC and assembly language:

• rfk-bas.prg : robotfindskitten in BASIC 65; BASIC source code in petcat format

• rfk-asm.prg : robotfindsktiten in MEGA65 assembly language; assembly language source code for the Acme assembler

I don’t claim that either of these are the best possible versions of this program. If you find ways that either of these can be improved, or if you have used different designs or techniques in your program, please let me know!

Whew! That’s a whirlwind of programming topics for three Digest issues. Hopefully this is enough for you to get started writing a robotfindskitten of your own, or extending these ideas to making other kinds of games. For example, you could add a system of walls or a maze generator to make locating items more challenging. Or, you could add other non-player robots that move when the player does, attempting to interfere with the search. Maybe when a non-player robot encounters an item, the item gets relocated on the playfield! It’d be a much less zen experience, but more like a game.

Huge thanks to everyone who has jumped in to support the Digest on Ko-fi so far! We’re off to a good start to funding the Digest through 2024. If you would like to become a supporter, visit: https://ko-fi.com/dddaaannn

See you next year!

We’ve all received a lot of email in the last week, so here’s the super-short version with two links to save some time:

1. New MEGA65 45GS02 Quick Reference mousepads and posters now available! Order this week and get 25% off! Use code ZCYBERDEAL23 during checkout.

2. Support my work on the MEGA65 and the Digest with Ko-fi!

Continue reading for photos and details!

New MEGA65 mousepads and posters!

During my recent experiences learning about MEGA65 assembly language, I’ve been wanting some kind of quick reference for all of the instructions supported by the 45GS02 CPU, something that sits on my desk that I can glance at to remind me of how it works. I originally thought it’d be fun to make a coffee mug, but as I iterated on a design, it became clear that it’d take several mugs to fit all of the instructions! So I wondered, what about a mousepad?

After some careful layout work and a heap of technical troubleshooting, I landed on this design, and I think it’s pretty snazzy:

I tried the same design as a 20" x 16" poster, and it’s pretty good too:

I’m happy to announce that you can now get a MEGA65 45GS02 Quick Reference mousepad and poster of your own, just in time for the holidays! Get one for yourself, and one for that special someone in your life that writes MEGA65 assembly language programs.

Features of the design:

• Every 6502, 65CE02 (4510), and 45GS02 instruction and addressing mode, color-coded by CPU

• Status register side effects

• Branch instruction flag behaviors

• CMP instruction flag behaviors

• Q virtual register layout

• MAP register layout and call pattern

• A fun colorful design that’s a joy to have on your desk or wall!

• Mousepad is also a mousepad!

Most of the cost goes to printing and distribution, by Zazzle. All remaining proceeds support my work on the MEGA65 and the Digest.

This week only, use code ZCYBERDEAL23 during checkout and get 25% off! This is Zazzle’s holiday promotion. I think the code is applied automatically. You’ll figure it out.

Here’s the store link again: https://www.zazzle.com/store/m65digest

Support the MEGA65 Digest in 2024

I have been writing the MEGA65 Digest monthly newsletter since August of 2022, fifteen full issues to date, with one more planned for this calendar year. I’m extremely grateful to have had the opportunity to donate my time to the MEGA65 project in this and other ways in the last year and a half.

Some members of our community have reached out to me to inquire about supporting my efforts through patronage. Several folks even figured out how to contribute through Substack without my ever having asked! (I think Substack asks on my behalf without my knowing, but still, that’s amazing!) Huge thanks to everyone who has contributed so far.

I am humbled to announce that you can now support the Digest and my other MEGA65 work through ko-fi.com. Ko-fi supports PayPal and Stripe as payment methods, which includes Apple Pay and major credit cards. I’m at a point where a small monthly contribution can make a big difference.

Important note: The email Digest will always be free for all. I consider the newsletter to be an essential community resource, especially for project announcements. Your contributions will benefit everyone. (My open source code contributions will also be for everyone, but I assume that goes without saying. 😅)

I am considering what fun things we can do with supporter exclusives or early access. In particular, I might re-tool the audio version of the Digest as a bonus feature, or as something else entirely. We can discuss it in the Ko-fi comments.

I will continue to welcome contributions via Substack. That’s not everybody’s favorite option and I have considered migrating to another email newsletter provider. For now, I’ll try to mention anything supporter-exclusive in both places.

A huge thank you again to everyone who has supported my efforts so far, and to everyone able to offer support going forward.

The ko-fi link: https://ko-fi.com/dddaaannn

My to-done list

Wistfully reviewing my time here so far, here are some of the things (well, most of the things) I’ve been able to do in the last year or so thanks to everyone’s support:

• Wrote the MEGA65 Welcome Guide

• Wrote 15+ issues of Dan’s MEGA65 Digest, email newsletter and audio podcast

• Assembled and distributed the Real-Time Clock replacement part for batch #1 and batch #2 owners affected by the RTC issue

• MEGA65 documentation maintainer and author since late 2022

• Wrote the new Memory chapter

• Revised the User’s Guide for a 2nd edition, including all-new chapters and a revised and tested BASIC reference, to accompany the upcoming v0.96 release

• MEGA65 ROM maintainer since version 920377

• Tested and merged ROM contributions from the development branch

• Implemented the “undo Home” feature; blog write-up

• Implemented 27 ROM bug fixes and changes, several core and Freezer fixes and changes

• Completed the new hardware keyboard scanner in the MEGA65 core (originally started by Paul), and upgraded the ROM to use it from the KERNAL and screen editor

• Wrote a semi-automated integration test driver capable of running everything uploaded to Filehost on a real MEGA65 to test outcomes with ROM and core changes

• Implemented the MEGA65 Files bot, currently available via Mastodon and RSS

• Wrote additional tutorials on MEGA65 programming

• Wrote and hosted the MEGA65 Community Survey 2023

• Gave a talk about the MEGA65 at Pacific Commodore Expo Northwest 2023

• Other minor projects: symbols source generator, BF interpreter, Welcome FAQ, ROM FAQ, a weird detour I took with GNU Autotools that didn’t amount to anything, some unimplemented designs I won’t otherwise mention

Lots of ideas for 2024, looking forward to it! And thanks again!

— Dan

Last month’s Digest introduced robotfindskitten, a programming exercise that unites several major concepts of game programming: updating the display, reading user input, generating random values, timing events, and including and manipulating large amounts of static game data. I offered examples of each of these tasks in BASIC 65, and proposed that these could be used to make a robotfindskitten experience for the MEGA65.

In this issue, I want to start reviewing these topics again in assembly language. Without BASIC’s help, the program will need to turn to hardware registers and low-level programming techniques to achieve similar effects. Some of these topics are too large for a single newsletter, so we’ll take this in two parts. I’ll try to keep things simple by limiting this to just the needs of a robotfindskitten program. Applications that require higher speed or more memory may need more sophisticated techniques.

This month’s Digest will focus on using the KERNAL, printing messages, and drawing characters to the screen—barely scratching the surface of the MEGA65’s graphics capabilities. Next month, we’ll finish robotfindskitten in assembly language with random values, user input, item descriptions, and a simple animation delay.

Shipping update

The work continues to finalize the new R5 main board hardware for the next delivery batch of computers. Getting the test hardware has taken longer than anticipated, and we are now expecting manufacturing lead times to put the batch #3 delivery in early 2024.

Importantly, the team has decided to proceed with the full verification process for the new design, and not skip any steps just to accelerate the schedule. The MEGA65 is manufactured in small volumes in a not-for-profit operation, so we can’t afford to rush the process and risk having to re-make and replace hardware. We want every computer delivered to be as high in quality as possible.

Some pre-orders have been pending for a very long time now, and we thank you for your patience! If you have a pending pre-order and need to make changes, contact Trenz Electronic customer support.

Tristam Island

Tristam Island, by Hugo Labrande, is a new text adventure game for multiple platforms, including the MEGA65. You can get the deluxe boxed edition, from publisher poly.play for 35 EUR. The deluxe edition includes the game on 3.5" floppy disk and on microSD card, a hint book, immersive props such as a rock sample and a postcard, and more. You can also get the digital-only edition for $3.99 USD.

Thanks to Hugo for the great game and for supporting the MEGA65, and to poly.play for publishing fun collectible boxed software for our favorite platform!

Updated ZX Spectrum core

Did you know that you can turn your MEGA65 into a ZX Spectrum? You can, with the ZX Spectrum core! This core just received a major overhaul to use the MiSTer2MEGA65 framework, and now works with modern displays.

Download the ZX Spectrum core from Filehost, then follow these detailed instructions for set-up and enjoyment. The core expects certain files in specific locations on the SD card, and uses ESXDOS v0.8.8 (not v0.8.9) for SD card access. It can load .tap and .trd files.

Once again thanks to sy2002 and MJoergen for their amazing work on setting up the MEGA65 for retro core success!

More arcade cores!

muse continues the great work of porting arcade game cores to the MEGA65. Bombjack (1984) (installation instructions) and Bosconian (1981) (installation isntructions) are both available.

The complete list of alternate cores for the MEGA65 so far:

Ports and enhancements by MJoergen and sy2002:

• Commodore 64 v5

• ZX Spectrum v1.0

• Game Boy v0.8

Ports and enhancements by muse (shoestring):

• Galaga v0.5.1

• Bosconian v0.5.0

• Xevious v0.5.0

• Bombjack v0.5.0

Along with a MEGA65 development core in slot 1 and a factory-installed stable core in slot 0, that’s more cores than there are core slots on a MEGA65! Just keep the .cor files on your SD card and flash them as needed.

Conference talks

MEGA65 enthusiasts have been giving talks at computer conferences this year, and several of them now have video online. Check these out!

• Oliver Graf (lydon) at Vintage Computing Festival Berlin 2023

• Jim Happel (jim_64) at Commodore Retro eXpo 2023

• Dan Sanderson (dddaaannn) at Pacific Commodore Expo Northwest 2023

If you have given a presentation on the MEGA65, even just to your local computer club, and there’s video online, please let me know so I can feature it here!

robotfindskitten in assembly language

Let’s take a look at how you might implement robotfindskitten in MEGA65 assembly language. This month will focus on using the KERNAL API and manipulating the display. Next month, we’ll cover the remaining topics to get a robotfindskitten program working, similar to what we did in BASIC last month.

As before, I’ll be using the Acme assembler. Here’s a reminder of the starter code for an assembly language program that assembles to a PRG file that can be loaded and run. The !8 ... values describe a BASIC bootstrap program that invokes the first assembly language instruction.

!cpu m65
!to "rfk.prg", cbm

* = $2001

!8 $12,$20,$0a,$00,$fe,$02,$20,$30,$3a,$9e,$20
!pet "$2014"
!8 $00,$00,$00

start:
    ; Program code will go here.

Introducing the KERNAL

Every Commodore computer has a built-in operating system powered by machine code etched into the computer’s Read Only Memory (ROM). You see this code running as soon as you turn on the computer: the READY prompt, the blinking cursor, and the BASIC interpreter and all of the BASIC commands are all built-in code. Included in this code is a collection of machine code routines and subsystems for accessing hardware such as the keyboard, screen, and disk drives. In computer architecture terms, these routines are known as the kernel, the centerpiece of the system used by other components. Commodore employee Robert Russell originally misspelled the word “kernel” as “KERNAL” in the documentation, and this became a nickname for the software. For the sake of tradition, I’ll continue to refer to the Commodore kernel as the KERNAL, using uppercase letters.

A program can call KERNAL routines by way of a jump table, a list of jmp instructions built into the ROM at a fixed memory location. Each jmp instruction redirects to the actual location of the routine elsewhere in memory. The jump table exists to give programmers peace of mind that each jmp instruction will stay at a consistent address for all future revisions of the KERNAL. When changes in the KERNAL code inevitably push an internal routine to a new location, the jump table is updated accordingly, so programs that use the routine continue to function without needing an update.

Here’s a useful example. The KERNAL maintains a system for printing PETSCII codes to the screen. As we’ve seen before, these codes manipulate a cursor that determines the location of the next printable character, and maintains other properties such as the text color and display attributes. The BASIC PRINT command uses this system to display strings of codes and characters. Machine code programs can also access this system using a routine called chrout (also called bsout in some documentation), available via the jump table entry at $FFD2.

chrout = $ffd2

    lda #147      ; clear the screen
    jsr chrout

    lda #65       ; the letter "A"
    jsr chrout

The chrout routine has a pre-condition that the PETSCII code to print is in the accumulator (CPU register “A”). The effect of calling the routine is to print the PETSCII code at the current cursor position. If the code is a printable character, it plots the character, moves the cursor, and performs other effects like scrolling the display as needed. If the code is some other PETSCII code, such as code 147 to clear the screen and move the cursor to the top-left corner, that code takes effect.

The jump table is part of the Application Programming Interface, or API, of the KERNAL. The API definition also includes the pre-conditions and post-conditions of each routine, and other important behavioral characteristics about what the routine does. All KERNAL jump table entries designed for the C64 and C128 are valid on the MEGA65—with some changes. While neither the C65 nor the MEGA65 have introduced new table entries, future versions of the MEGA65 ROM could extend the table further without changing any of the existing entries.

It’s important to remember that the MEGA65 ROM is an active construction zone, and only some of the KERNAL APIs borrowed from previous Commodores are considered officially supported for now. Some things that C64 programmers may be used to aren’t official APIs, even if they appear to function today. When the dust has settled on the major bug fixes, the MEGA65 team will formalize more of the KERNAL API surface, adding documentation about supported features to the manuals and building automated tests to ensure that the APIs work properly. The KERNAL jump table is officially supported, as are certain specific facts about the memory layout, such as $2001 being the start address for BASIC programs.

Once a machine code program is running, it is not obligated to use the KERNAL. In fact, many games and larger utilities jettison the KERNAL entirely, installing custom interrupt handler routines, defining a custom memory map, and manipulating the computer entirely through hardware registers. For such a program, the only API surface is the hardware itself, and there is no need to integrate with the KERNAL except to launch the program. If the program does use KERNAL routines and systems, it must honor the KERNAL’s documented pre-conditions, and stay out of its way.

Printing a short message using the KERNAL

The following code uses the KERNAL chrout routine to clear the screen and print a short message:

    lda #147       ; clear the screen
    jsr chrout
    
    ldx #0
-   lda message,x  ; read a byte from message, offset by X
    beq +          ; if it's a zero, we have reached the end of the message
    jsr chrout     ; output the byte
    inx            ; increment X
    bra -          ; loop back
+   rts

message:
!pet 14,"robotfindskitten",0   ; Acme directive to generate PETSCII
                               ; bytes

This example uses the “X indexing” addressing mode to access characters in the message stored in program memory. lda message,x takes the address of the message, via the assembler symbol message, and adds the value in the X register to it. The X register is one byte, with a range of possible values of 0 to 255. This limits the length of the message to 254 PETSCII codes and one 0 byte to indicate the end of the message.

There’s another way to print short messages, using another KERNAL routine. The primm routine at $FF7D will print a null-terminated message, with the message bytes immediately following the jsr instruction. It’s like having a PRINT command for assembly language!

primm = $ff7d

    jsr primm
!pet 14,"robotfindskitten",0

    ; Program continues...

It seems like a magic trick for the message bytes to be sitting in the middle of the code like this. How does the CPU know to skip over the message to the next instruction? The primm routine is quite clever. When the CPU encounters a jsr instruction, it remembers the address just after the instruction, so it can pick up where it left off when the subroutine exits with the rts instruction. The primm routine assumes that this address is the starting byte for the message and starts printing. When primm finds the 0, it updates the return address to just after the 0, then issues the rts. The CPU is blissfully unaware that primm has been messing with the return address and proceeds to execute the rest of the program. Pretty slick!

Note that primm is also limited to messages of 254 characters. To print a longer message, we need a different strategy.

Printing longer messages

In the code above, message is a symbol whose value is determined by the assembler and inserted into the code where the word appears. Wouldn’t it be great if we could update the value of the message symbol as the program executes, like a variable? The value of message is written into the machine code, and this code is just bytes in memory. One option is to update the address bytes within the code by writing to the appropriate memory locations, then execute the code. This technique, known as self-modifying code, is quite common, and not that difficult with a bit of care.

The following routine accepts the low byte and high byte of the message address in the Y and Z registers, and prints the message until it encounters a 0 byte. It relies on the knowledge that the lda $0000,x instruction assembles to three bytes: one for the instruction code, and two for the address. It uses the X register as before, but this time it tests whether X wraps around from 255 to 0, then increments the high byte of the address and continues printing. This gives us a maximum message length of 65,535 characters, which is more than enough.

    ldy #<intro_message
    ldz #>intro_message
    jsr print_long_message

; ...

print_long_message:
    ; Y,Z = address
    sty .load_selfmod+1
    stz .load_selfmod+2
    ldx #0
.load_selfmod
    lda $0000,x
    beq .end
    jsr chrout
    inx
    bne .load_selfmod
    inc .load_selfmod+2
    bra .load_selfmod
.end
    rts

intro_message:
!pet 147,14,5,27,"8"  ; clear, lowercase, white, 80x25
!pet "robotfindskitten in MEGA65 assembly language",13
!pet "Based on the game by the illustrious Leonard Richardson (C) 1997, 2000",13
!pet "Press Return to start.",0

Changing the cursor location

Another useful KERNAL routine for printing is the plot routine, at $FFF0. plot can do two things: it can either move the cursor to given coordinates, or it can report the coordinates of the cursor’s location. You use the carry flag to choose between the two actions. To move the cursor, clear the carry flag (clc), then set the X register to the column number and the Y register to the row number.

plot = $fff0

    clc
    ldx #12
    ldy #1
    jsr plot

To ask plot to report the current location, set the carry flag (sec) before calling it. Instead of changing the cursor position, plot will overwrite the values in the X and Y registers with the current cursor location.

A word of caution: When the KERNAL print system prints a character in the bottom-right corner of the screen, it assumes that more text needs to appear on the following line, and scrolls the text display to make room. When plotting characters for game graphics, this probably isn’t what you want. A simple albeit unsatisfying way to avoid this issue is to never print a character in the bottom-right corner.

Accessing screen memory

You could make a robotfindskitten game using just the KERNAL print system: use plot and chrout with PETSCII codes to draw items, and erase and draw the robot character as it moves across the screen. Most games don’t use the KERNAL print system to plot characters at all. Instead, they write directly to screen memory, color memory, and registers in the VIC-IV chip. This avoids issues like the KERNAL scrolling the text display, at the expense of doing other things manually, such as calculating memory locations for screen coordinates, and managing character attributes and colors.

If your program uses the KERNAL print routines, it’s best to let the KERNAL manage screen memory as much as possible. The KERNAL uses internal variables to keep track of some screen properties, and these need to be consistent with its own understanding of the state of the video hardware. If you change the screen mode or relocate screen memory via VIC-IV registers without telling the KERNAL, actions performed by PETSCII codes, such as clearing the screen, may not function correctly.

Handling screen memory is an essential skill for assembly language programmers. It’s also a deep topic. So let’s limit this discussion of screen memory to a few salient facts. To tell the KERNAL to set the screen mode to 80 x 25 text, print the Escape + 8 key sequence with chrout, as if you were typing it at the READY prompt:

    lda #27  ; Escape
    jsr chrout
    lda #'8' ; PETSCII "8"
    jsr chrout

If you’re not using the KERNAL, you can select the screen mode with flag registers at location $D031. To get 80 x 25, clear the V400 register (bit 3) and set the H640 register (bit 7). Without the KERNAL, you will need to write your own message printing routines that write directly to screen memory; you can’t use chrout.

The starting address of screen memory is in a VIC-IV register known as SCRNPTR, a 28-bit value stored at $D060-$D063, least significant byte first. The KERNAL will set this when you print the escape sequence for the screen mode. If you’re not using the KERNAL, you can set this to any address you like in the first 384K of memory by writing its address into the registers.

The KERNAL’s preferred memory location for a 40 x 25 or 80 x 25 screen is address $0800. Strictly speaking, this is not a documented fact: a program that relies on the KERNAL’s setting must read it from SCRNPTR, and never assume its value. For propriety, the examples below will read the SCRNPTR value instead of assuming it, but—at least for now—I’m also relying on the fact that the address is within bank 0 (addresses $0000 to $FFFF) so we can use 16-bit addressing modes and don’t have to worry about accessing upper memory. Note that this won’t work with 80 x 50 text mode, because the KERNAL relocates screen memory to bank 1 for this mode.

As with BASIC’s T@&() special array, screen memory contains screen codes that represent the characters in the character set. The codes are organized in columns then rows, from top-left to bottom-right: the first 80 bytes are the top row, the next 80 bytes are the next row, and so on, for 80 x 25 = 2,000 bytes.

The following example uses the self-modifying code technique to store a value in screen memory. The sta instruction can only operate on 16-bit addresses, so it uses the lower two bytes of SCRNPTR, and assumes the upper bytes are zero (an address in bank 0).

scrnptr = $d060

    ; Use self-modification to write to the (16-bit, bank 0)
    ; SCRNPTR address
    lda scrnptr
    sta store_screen_selfmod+1
    lda scrnptr+1
    sta store_screen_selfmod+2

    lda #1     ; Screen code for the letter A
store_screen_selfmod
    sta $0000

Color memory

In the regular text mode, color memory stores the foreground color and attributes for each character on the screen, organized in the same way. One way to access color memory is starting at address $D800.

There’s one issue, though. By default, only the first 1K of color memory is visible here, from $D800 to $DBFF. That’s not enough for all 2,000 characters of a 80 x 25 display! This is solved by yet another of the MEGA65’s many modes. The CRAM2K register, bit 0 of $D030, swaps the registers from $DC00 to $DFFF with the remaining color memory. To do this, it hides other hardware registers normally at those locations, such as the CIA chip registers. The KERNAL expects to see the registers here and not color memory, so you must clear the bit before calling KERNAL routines. (The KERNAL IRQ is smart enough to stash and restore your CRAM2K setting, so you do not need to disable interrupts. That’s a topic for another time.)

cram2k = $d030
color_mem = $d800

    lda #%00000001  ; Enable CRAM2K
    tsb cram2k
    
    lda #5          ; Paint the A green
    sta color_mem

    lda #%00000001  ; Restore registers
    trb cram2k

From coordinates to screen memory addresses

Given screen coordinates of column X and row Y, the offset into screen memory for that coordinate is Y times 80, plus X. The CPU doesn’t have an instruction that can multiple any two numbers, but it does have a quick and easy way to multiply a number by two: it can shift the bits of a number to the left, using the Arithmetic Shift Left instruction (asl). If it’s not clear that shifting the bits of a number to the left multiply it by two, write out a binary number, then write a zero at the end. For example, the binary number %0110 is 2 + 4 = 6 in decimal. Write a zero at the end, and it becomes %01100, which is 4 + 8 = 12 in decimal. Just as writing a zero at the end of a decimal (base ten) number multiplies the number by ten, writing a zero at the end of a binary (base two) number multiplies it by two.

Using a combination of left-shift and addition operations, we can calculate the screen memory address for a given set of coordinates in three steps:

1. Calculate the row offset from the Y coordinate, stored in a memory variable (row_offset), using bit shift and addition operations to multiply Y by 80.

2. Add the base address and the row offset, stored in the address part of a sta ...,x instruction (self-modifying code).

3. Use X-indexing with the X coordinate, to determine the final address and set the screen code.

row_offset: !byte 0,0

plot_char:
    ; Pre-condition:
    ; - A is the screen code
    ; - X register is the X coordinate
    ; - Y register is the Y coordinate
    
    taz         ; Stash the screen code in Z, so
                ; we can use A for other things
    
    lda scrnptr
    sta store_screen_selfmod+1
    lda scrnptr+1
    sta store_screen_selfmod+2

do_plot:
    ; - Z is the value to store in memory

    ; Calculate Y * 80 into row_offset memory variable
    lda #0
    sta row_offset+1 ; reset row_offset's high byte
    tya
    sta row_offset   ; store the row number as row_offset's low byte
    asl              ; x2
    asl              ; x4
    adc row_offset   ; x5
    sta row_offset
    asw row_offset   ; x10
    asw row_offset   ; x20
    asw row_offset   ; x40
    asw row_offset   ; x80

    ; Add row_offset to store_screen_selfmod+1
    lda store_screen_selfmod+1
    clc
    adc row_offset
    sta store_screen_selfmod+1
    lda store_screen_selfmod+2
    adc row_offset+1  ; add with carry
    sta store_screen_selfmod+2

store_screen_selfmod:
    stz $0000,x

    rts

To update color memory, the only difference in this routine would be to use a different base address, and set CRAM2K while updating memory. I added a do_plot label above so I could share the common code between the two routines.

color_char:
    ; Pre-condition:
    ; - A is the color
    ; - X register is the X coordinate
    ; - Y register is the Y coordinate

    taz        ; Stash the color code in Z, so
               ; we can use A for other things

    lda #<color_mem
    sta store_screen_selfmod+1
    lda #>color_mem
    sta store_screen_selfmod+2

    lda #%00000001  ; Enable CRAM2K
    tsb cram2k

    jsr do_plot
    
    lda #%00000001  ; Restore registers
    trb cram2k

    rts

Base Page Indirect Addressing

Each machine code instruction that accesses memory can operate in one or more addressing modes, ways for the CPU to figure out what address to use. We’ve seen three addressing modes in the examples so far:

Immediate mode: use the value given in the instruction. This example loads the number 7 from the instruction into the accumulator:

    lda #7

Absolute mode: use the 16-bit address given in the instruction. This example loads the value stored at address $20CF into the accumulator:

    lda $20cf

Absolute X-indexed mode: take the given 16-bit address, then add the value from the X register to it, and use that as the address. This example sets the X register to $2F, then loads the value stored at the address calculated as $20CF plus the value in the X register ($20CF + $2F = $20FE) into the accumulator:

    ldx #$2f
    lda $20cf,x

The X register can contain a value from 0 to 255, which limits the range of the X-indexed addressing mode. Earlier, I used self-modifying code to get around this problem, allowing for performing calculations on the entire address. The following example rewrites the 16-bit address portion of an instruction that’s using absolute mode addressing, then executes the modified instruction:

    lda #$cf
    sta .selfmod+1
    lda #$20
    sta .selfmod+2

.selfmod:
    lda $0000

Writing the address directly into an instruction like this is only really practical if only one instruction needs the address, and the modifying code knows exactly which address to modify. In many cases, it’d be better if we could store the address in one memory location like a variable, then tell the instructions where to find it.

Base Page Indirect Addressing mode can do exactly that. This example stores a 16-bit address at memory location $10-$11, then accesses it using the Y register as an index:

    lda #$cf
    sta $10
    lda #$20
    sta $11
  
    ldy #0
    lda ($10),y

So why didn’t I do this earlier? Well, there’s a catch: the address must be written to the base page, a region of 256 bytes that gets special treatment. Commodore 64 programmers know this as the zero page, within the addresses $0000 to $00FF. The CPU uses special forms of its instructions to access these addresses faster and with more compact code than absolute 16-bit addresses, so the base page is a great place to put variables. It’s so useful, in fact, that the KERNAL claims all of the zero page for its own use. If your program uses the KERNAL, you must protect the zero page so that it’s the way the KERNAL left it by the time you call a KERNAL routine.

With the original 6502 CPU, the base page is always at address $0000 (hence the name “zero page”). The 65CE02 CPU (on which the MEGA65’s 45GS02 is based) adds a feature that lets you use any 256-byte page of the first 64K of memory as the base page. The B register holds the top two nibbles (two hexadecimal digits) of the address of the base page. Your program can stake out its own base page and set the B register to that location to use it. I recommend page B = $16 ($1600 to $16FF), which is reserved for use by your program.

You must change B back to $00 before calling a KERNAL routine. The base page being set to $00 is a pre-condition of all KERNAL routines. (The B register is preserved along with other registers during interrupt handling, so you don’t have to worry about confusing the KERNAL IRQ.)

To set the B register, put the desired value in the accumulator, then use the tab instruction (Transfer A to B). If you need to read the B register, transfer it back to the accumulator first, with tba. The requirement to go through A to set or read B sometimes requires a bit of register wrangling.

Another register consideration to keep in mind: Base Page Indirect Addressing always uses an index register. The lda instruction supports using the Y or Z registers as indexes for this mode. If you just want to use the address directly, you must set the index register to 0.

Here’s another version of the long message printer using Base Page Indirect addressing, preserving the zero page for the KERNAL and using page $16 for the program’s base page. Try to follow which register has which value:

print_long_message_2:
    ; Y,Z = address
    lda #$16   ; A = $16
    tab        ; B = $16
    sty $00    ; $1600-$1601 = the message address
    stz $01
    ldy #0     ; Y = 0
.loop
    lda ($00),y  ; Load a character from the message address + Y
    beq .end     ; If the value is 0, end.
    tax          ; Stash the character in X so we can use A to set B.
    lda #0       ; A = 0
    tab          ; B = 0
    txa          ; A = the character
    jsr chrout
    lda #$16      ; A = 16
    tab          ; B = 16
    iny          ; Y = Y + 1
    bne .loop    ; If Y hasn't rolled over to 0, continue.
    inc $01      ; Y rolled over, so increment the high byte of
                 ; the message address.
    bra .loop    ; Continue.
.end
    lda #0
    tab
    rts

This is not necessarily better than the earlier version using self-modifying code, especially with all the register flipping required. But it illustrates the use of base page variables as address pointers.

The 45GS02 CPU has another Base Page Indirect addressing mode, and it’s super useful: 32-bit Base Page Indirect Addressing lets you use a 32-bit address instead of a 16-bit address. With the Acme assembler in MEGA65 mode, this is indicated using square brackets instead of parentheses. Only the Z register is supported as the index in this mode.

    lda #$16
    tab

    ; Store the address $0001.F800 at base page address $00-$03
    lda #$00
    sta $00
    lda #$F8
    sta $01
    lda #$01
    sta $02
    lda #$00
    sta $03

    ; Store the value 7 at $0001.F800
    lda #7
    ldz #0
    sta [$00],z

Notice that other addressing modes do not support 32-bit addresses, so we can’t use the self-modifying code method to access upper memory, at least not in the same way. We can adapt the second version of the printing routine to be able to print long messages from anywhere in the MEGA65’s memory with minimal changes, but we can’t adapt the first version as easily.

Earlier, I made a potentially unsafe assumption that the KERNAL used an address between $0000 and $FFFF for SCRNPTR in 80 x 25 mode, and I just ignored the upper bytes of the SCRNPTR address. With 32-bit base page indirect addressing, I don’t have to do that: I can just copy the entire address from SCRNPTR to a four-byte base page variable, then use 32-bit indirect addressing to access screen memory.

Incidentally, upper memory addresses $1.F800 through $1.FFFF are another way to access the first 2K of color memory, with no need to set the CRAM2K flag. In my implementation of robotfindskitten, I use base page $16 for variable storage, and base page indirect addressing for plotting characters with the full four-byte SCRNPTR address and for plotting colors to 1.F800. I set the B register to $16 at the beginning of the program, and wrap my KERNAL calls to set B to $00 before the call and set it back to $16 afterward.

As you can see, there are multiple ways to accomplish certain tasks. For high speed applications, you may need to make your choices based on the amount of CPU time each operation takes, measured in CPU cycles. Instruction cycle counts are listed in the manual. robotfindskitten is not speed critical, so I just went with what made my code easiest for me to understand.

That’s a good start. With the KERNAL output routines and screen memory access, we have the tools to replicate BASIC’s PRINT, T@&(), and C@&() facilities in assembly language. Next month, we’ll look at another important KERNAL facility for accepting keyboard input, and some snazzy MEGA65 hardware features for generating random numbers and measuring time. We’ll close by designing data structures to access all of the item descriptions, and prevent two items from landing on the same place on the screen.

For comparison and enjoyment, here’s my BASIC version of robotfindskitten. It’s faithful to Leonard Richardson’s version, which is not particularly creative of me, but hopefully it serves as a useful reference implementation.

• rfk-bas.prg : robotfindskitten in BASIC 65; BASIC source code in petcat format

Happy coding! See you next month.

— Dan

A new month, a new feature, a new game, a new demo, and a coding exercise that really brings the room together. Let’s dig in!

Available to test: New keyboard scanner

We’re getting closer to having a complete release candidate, with features being finalized and bug fixes piling in. There’s one new feature that’s near and dear to my heart, and I’m thrilled to be able to share it with anyone up for early beta testing.

The very first thing I noticed when I got my MEGA65 is how the typing experience felt nostalgic. Even with the new mechanical key switches and the 40 MHz CPU, the ability for the computer to recognize key presses felt exactly like a Commodore 64 did back in the day: sluggish and imprecise. I like nostalgia as much as anybody, but I type much faster today than I did when I was nine years old. I wished my MEGA65 could handle fast typing more like a modern computer, so I could enjoy on-device composition without slowing myself down. It was one of the first feature requests that I filed with the MEGA65 team.

Paul and company started working on an idea for fast typing, and an early version of the chipset support required made it into the core last year. The feature wasn’t wired up to the KERNAL ROM, and only a few built-in applications used it. I brought it up again with the team this summer, and we had many design discussions and tried several ideas. I learned a bit of FPGA coding, and even built a high-speed Linux PC just to build and test new cores and ROMs.

I’m proud to present the all-new MEGA65 hardware-accelerated keyboard scanner. Using the latest development core and ROM beta release, you can now enjoy a typing experience that is more accurate and more reliable for fast typists throughout the BASIC screen editor and many applications. These changes will be in the v0.96 release, and you can test it today and file any bugs you find. I also wrote a test plan and detailed description of how it works.

I plastered this all over the instructions, but I'll repeat it here: the latest ROM beta versions (920387 or later) require the latest development core. If you use the newer ROM with an older core, typing won't work. You *can* safely use older ROMs with the newer core, so you can revert to the legacy keyboard scanner at any time if you encounter any issues just by going back to an older ROM (920386 or earlier). Also, the latest ROM betas will not work with the Xemu emulator until emulation for the new core feature has been added (hopefully soon), so stick with 920386 or earlier in Xemu for now.

For me, the difference with the enhanced typing quality is like night and day. On-device programming and other typing applications are much more usable, and I just enjoy using the computer much more, confident that I won’t have to struggle with missed keystrokes. Try it out, and let me know what you think!

Classy, by deathy

Classy, by deathy, is a new match-3 game for the MEGA65. Careful with this one: it’s addictive! A joystick in either port or the keyboard sets you on your tile swapping journey. If the game is still running, it means you still have moves remaining. Keep looking!

MEGApple, by MirageBD

The MEGA65 gets its Bad Apple!!

MEGApple is MirageBD’s MEGA65 version of the popular demo challenge: recreate the shadow-art music video of the Japanese pop song, “Bad Apple!!” The original video was a collaboration of animators on the Japanese website Nico Nico Douga, based on the pop remix by nomico of a track from the video game Touhou Fantasy Land: Lotus Land Story. Over a decade later, it persists as a popular meme to recreate the music video in unusual media, including (but not limited to) retro computers.

To run MEGApple, download and expand the archive, then copy the files to the root of your SD card. Start your MEGA65, then type: MOUNT "MEGAPPLE.D81":RUN "*" The program on the D81 disk image loads the data from the other larger files.

Xevious, new arcade core by muse

muse has a new arcade cabinet core for us! Xevious (1982) and Super Xevious (1984) are early vertical scrolling shooter games by Namco. Fly your Solvalou starship over the planet’s surface to stop the Xevious forces by both land and sky. muse’s version supports a one-button joystick with a clever adaptation: press the button quickly to shoot at airborne enemies, and hold the button to drop bombs on turrets.

As with the Galaga core, the installation instructions include searching for and downloading the original Xevious ROM files, running a Python script to validate the files and prepare a folder that you copy to your MEGA65’s SD card with the path /arcade/xevious, then installing the core in an available core slot. See the Discord announcement for additional notes.

robotfindskitten

“Yet another zen simulation.” — robotfindskitten.org

In robotfindskitten, you are a robot, who finds a kitten.

robotfindskitten was originally written by Leonard Richardson in 1997 for DOS, as his submission to the robotfindskitten contest put on by the webzine “Nerth Pork.” It took first prize. There were no other entries, but there didn’t need to be. The theme had found its perfect expression on the first try.

In the decades that followed, many have made their own versions of the simulation, on many interactive platforms. And now, it is your turn.

Richardson’s version depicts the robot with a single colored ASCII character on a monospaced field that spans the screen. The field is populated sparsely with other colored ASCII characters that represent many Non-Kitten Items (NKIs), and one kitten. To the robot, all items, including the kitten, appear as random colored characters. The operator uses cursor keys to move the robot around the field. When the robot comes into contact with an item, a message is printed describing the item. If the item is the kitten, the experience ends in joyful celebration.

You can play robotfindskitten in your browser. Or, you can install a version for a modern terminal for Linux (sudo apt install robotfindskitten) or macOS (brew install robotfindskitten) or many other platforms. (Some versions are survived only by their archived screenshots.) Or you can build the Linux version from source. Or you can check out the Ultimate robotfindskitten Fan Site, by Leonard himself.

Or you can make your own. Here are some techniques that you might use to rise to this challenge in BASIC 65. Next month, we’ll look at how to do similar things in assembly language.

Display

You will need to control what is displayed on the screen, so the operator can see the robot and the items.

To clear the screen of all text, you can use the SCNCLR command. To set the color of text to be printed (from 0 to 31): COLOR number. Similarly, to change the color of the border or background: BORDER number or BACKGROUND number. To set the position of where the next text will be printed: CURSOR column, row. To print a string of text at the current cursor position: PRINT string.

One word of caution with PRINT: if the string you are printing extends beyond the right edge of the screen, the screen below that point will scroll down by one line. This probably isn’t what you want in this exercise, so take care with the length and position of your strings.

To plot a single character at a set of coordinates, you can assign the screen code of the character to the T@& array, and its color to the C@& array. These are two dimensional arrays, with the first index referring to the column and the second index referring to the row. T@&(0,0)=1 plots the letter A to the leftmost topmost position. (1 is the screen code for the A character. Notice that screen codes are not PETSCII codes.) C@&(0,0)=5 paints it green. You can read screen codes and colors from these arrays as well: IF T@&(0,0)=1 THEN ... and so forth.

Recall that PETSCII codes in strings give you further control of the display via the PRINT command. PRINT CHR$(14) switches the display to the lowercase character set. Be aware that not all PETSCII graphics characters are available in the lowercase set.

Here is a short program that clears the screen, switches to lowercase, and plots all of the available screen codes:

100 COLOR 1
110 SCNCLR
120 PRINT CHR$(14)
130 FOR R=0 TO 3
140 FOR C=0 TO 63
150 T@&(C,R)=R*64+C
160 NEXT C
170 NEXT R
180 CURSOR 0,5

Input

To accept keyboard input, use either GET variable or GETKEY variable. These both take a variable name as their parameter. Given a string variable (such as A$), the key being pressed is loaded into the variable as a single-character string. Given a number variable (such as A), it is loaded as a PETSCII code. GETKEY pauses until a key is pressed. GET will not wait: if no key is pressed, it assigns an empty string or a zero, and moves on. If you want GET or GETKEY to provide the PETSCII code as a number, be sure to use a byte type variable, so that the number is in the range 0 to 255: GET K&.

10 GETKEY K&
20 PRINT K&
30 GOTO 10

Alternatively, you can accept joystick input using the JOY() function. The function takes the port number as an argument (1 or 2), and returns a number 0 through 8 indicating the state of the joystick. 0 says the joystick is centered. All other numbers indicate a direction, starting with 1 for “up” and going clockwise: 2 for “up-right,” 3 for “right,” and so forth.

Chaos

The items are assigned random characters, colors, and positions, so you’ll need a way to generate randomness. The RND() function generates numbers using a pseudo-random number generation algorithm. The function takes an argument that determines the “seed” for the algorithm. For most purposes, an argument of 1 suffices: RND(1). The function evaluates to a random fractional number between 0 and 1. To generate numbers within a range of integers, multiply the result by the size of the range, then take the INT() of the result to lop off the fractional part. INT(RND(1)*80) generates a random integer between 0 and 79.

If you want the range of possible values to start at a value other than zero, do the inner multiplication by the size of the range, then add the starting value. INT(RND(1)*77)+1 generates a random integer between 1 and 77.

The following program plots randomly colored random characters when one of the cursor keys is pressed. See if you can figure out what the variables CL, CH, RL, and RH do.

100 SCNCLR
110 CL=0:CH=79:RL=0:RH=24
120 GET K&
130 IF K&<>17 AND K&<>29 AND K&<>145 AND K&<>157 THEN 120
140 IF K&=17 THEN RL=12 : REM CURSOR DOWN
150 IF K&=29 THEN CL=40 : REM CURSOR RIGHT
160 IF K&=145 THEN RH=12 : REM CURSOR UP
170 IF K&=157 THEN CH=40 : REM CURSOR LEFT
180 C=CL+INT(RND(1)*(CH-CL))
190 R=RL+INT(RND(1)*(RH-RL))
200 T@&(C,R)=INT(RND(1)*256)
210 C@&(C,R)=INT(RND(1)*16)
220 GOTO 110

Like the Commodore 64, a positive argument generates a new number based on the previously generated number. Unlike the Commodore 64, the algorithm is initially seeded from the MEGA65’s Real-Time Clock during boot, so you are unlikely to see the same sequence twice with RND(1).

Tip: For RFK, you probably want to prevent randomly selected values from repeating. A simple way to avoid this is to keep track of previously selected values, such as in an array, and scan the array each time a new value is chosen. If it’s in the array, restart the process to pick another value. Once a unique value is found, add it to the end of the array. In my version, I used this technique to avoid two items from appearing at the same location, and to ensure that each item uses a unique PETSCII character and a unique description.

Calm

To animate the joyful celebration at the end, you’ll need a way to pause between frames of an animation. The SLEEP seconds command pauses the program for the given number of seconds. The number can be fractional.

10 FOR X=1 TO 5
20 PRINT CHR$(211);
30 SLEEP 0.6
40 NEXT X
50 PRINT

Data

Each Non-Kitten Item in robotfindskitten gets assigned a description at random when the item is created. One way to put a large list of descriptions in a BASIC program is with DATA statements. These statements don’t do anything when encountered by control flow. Instead, they make values available to the READ statement, which finds the next unread value and puts it in a variable.

A traditional BASIC technique is to read the number of elements from the first DATA statement, DIMension an array of that size, then READ that many elements into the array. The program can then access any string from the array by its number index. This is a bit wasteful. It keeps two copies of the list in memory: one in the BASIC program listing, and another in variable memory. It also introduces a delay at the beginning of the program to load all of the elements into the array. The primary advantage is that each element can be accessed instantly by index.

In BASIC 65 (and BASIC 7 for the Commodore 128), there’s a better way: use sequential line numbers for the DATA statements, then use the RESTORE command to set the READ pointer to a given line number. RESTORE accepts a number expression for the line number, so you can select a string programmatically by number.

10 READ N
20 K=INT(RND(1)*N)+1
30 RESTORE 1000+K
40 READ NK$
50 PRINT NK$
60 GETKEY A$
70 GOTO 20
1000 DATA 5
1001 DATA "THAT'S JUST AN OLD TIN CAN."
1002 DATA "IT'S AN ALTAR TO THE HORSE GOD."
1003 DATA "A BOX OF DANCING MECHANICAL PENCILS. THEY DANCE! THEY SING!"
1004 DATA "IT'S AN OLD DUKE ELLIGTON RECORD."
1005 DATA "A BOX OF FUMIGATION PELLETS."

A DATA statement has a special syntax to allow for string values that contain almost any character: values are separated with commas, and a value that starts with a double-quote contains every character (including commas) up to the next double-quote. This requires special handling if you want a string value to contain a double-quote character. Because NKI descriptions only use letters, numbers, and punctuation, one solution is to use a special character as a substitute for double-quotes, then replace it in code:

41 FOR I=1 TO LEN(NK$)
42 IF MID$(NK$,I,1)="£" THEN MID$(NK$,I,1)=CHR$(34)
43 NEXT I

1000 DATA 6

1006 DATA "IT'S A DVD OF £CROUCHING MONKEY, HIDDEN KITTEN£, REGION ENCODED FOR THE MOON."

You can use the original list of 406 NKI descriptions, or write your own. The truly patient can type all of these into DATA statements by hand, a zen experience of its own. Or you can use one of these that I made for you:

• nkis_upper.bas / nkis_upper.prg : uppercase character set

• nkis_lower.bas / nkis_lower.prg : lowercase character set