Cosmic Snake by Frank Lindsey is a bit of an unusual VIC20, not at least because it isn't a snake game, it is a not a bad Centipede (or is it Millipede ? or is it Caterpillar ?) style game.
In a recent video, TFW8b played all the games in the "Centipede Type Games" category on the Penultimate Cartridge
He did think it might be BASIC, so when it exited to BASIC at the end, he tried to list it.
The listing was full of "magic characters" and corrupted the display.
I was intrigued, so had a look at the listing.
It starts with some REM statements full of the aforementioned magic characters, this is line 9, the least magic of them all.
By line 100, it has returned to standard BASIC, including some SYS commands to call code in the 4000-500 range. That is where the BASIC program is on an unexpanded VIC20, starting at 4097 ($1001).
The BASIC code ran on until line 820.
What Is Going On?
Putting machine code in REM statements was a common trick used on the ZX81, but I can't remember seeing it used in Commodore BASIC before.
A simple example is the code to read the joystick port on a ZX81, as described in the post on the Minstrel Joystick Interface for RC2014 and Minstrel 4th
A REM statement is a place to add comments (or REMarks) to the code, it is purely there for readability and does not affect the game, other than making it slightly slower as the code has to be skipped by the BASIC interpreter.
It can be (ab)used as a place to store machine code.
You type a line, almost always at the very start of the program, as that location in memory is normally fixed. This line will contain a REM statement and sufficient characters for your machine code program (one character = one byte of code).
1 REM ......
You then POKE directly into memory where that line is stored, either by adding lines of code
10 POKE 16514,175
20 POKE 16515,71
etc.
or by directly typing in the POKE commands
POKE 16514,175
POKE 16515,71
etc.
Or if there is a lot of code, you can write a short loader program to get the user to type the bytes in and then poke them into RAM and then SAVE the program. Some of these loader programs ever computed a checksum to make sure you got it all correct.
Once you have entered the code, the REM statement now shows the magic characters, which are simple the character representations of the bytes of code.
Some of these are keywords, so you end up with things like the <= operator and the TAN keyword in the above example, both of which represented by a single byte.
In the ZX81 world, you then call that code with USR 16514 (or whatever is the address of the routine to call).
Onto the VIC20
There is a good reason why I have not seen this done in Commodore BASIC before, on the PET or VIC20.
Because of the structure of the BASIC program, you cannot have any zero bytes in your code. When the BASIC program is loaded, each line is parsed and if necessary, relinked, and when it finds a zero, it assumes it is the end of the line, so crops any code after that.
Just think about that for a moment.
You cannot have any zero bytes in your code.
That means none of these type of instructions can be used, as they all assemble to code which contains a $00 byte.
LDA #$00
LDA $1400
JMP $1600
STA $9600,X
BRK
You have to be careful about variable and function locations to avoid any addresses ending in $00, adding padding or moving things around to avoid those locations. You also need to find other ways to end up with $00 in a register if you need it.
There are various other ways to get some assembler code on those machines, including placing the code into an area of RAM above the BASIC program, and saving them as a combined unit, so they get loaded together and the routines can be run by using the appropriate SYS 1234 style commands.
You can also store short sections of code in DATA statements at the end with code which are then READ and POKEd into a suitable area of RAM (e.g. the cassette buffer).
That is slow and inefficient, taking up to four bytes plus trimmings for each byte of code. This is normally only used for very short routines, such as this one from Tornado.
I was intrigued to see how the code in Cosmic Snake got around this, so started to reverse engineer it.
Code Layout
The code starts with the REM statements, of variable length, on line numbers 0, 1, 2, another line 2, 4, 5, 7, 8, 9, 10, yet another line 2 and finally line 12.
Line numbers don't actually have to be sequential, or unique, but it gets very confusing if they are not. See for example directory listings you get back from LOAD "$",8 on a Commodore disk drive.
Those are program listings, LOADed and LISTed like any other program.
After the REM statements, there is a short BASIC program with odd gaps, 100-125 in gaps of 5, then 200, then 300, 305 and then up to 700, 705, up to 720, then 800-820 also in 5s.
This is sprinkled with SYS calls, jumping into the code in the REM statements at various points.
The BASIC code is mostly doing things that can be a bit of a pain in assembler, such as the title page and high scores etc.
Storing Machine Code in REM Statements
The format of a line in Commodore BASIC is fairly simple:
- 2 bytes with the address of the next line
- 2 bytes for the line number
- 1 or more bytes of program code, not including zero
- 1 zero byte indicating the end of the line
Each of the lines fit into that format. I will show line 9 as that is one of the clearer ones.
>C:1601 73 16 09 00 8f 58
It starts at address $1601. The first two bytes are $73 and $16, meaning the next line starts at $1673 (the 6502 is little-endian, so the first byte is the lest significant, or the little end).
Next is the line number, $09 and $00 make $0009 or line 9.
Then the code starts, $8F is the BASIC token for REM. Whatever follows between the $8F and the next $00 will be skipped over by the BASIC interpreter.
There is a single padding character, $58 or "X", which is used throughout the program. I suspect the original code was written with lines like
9 REM XXXXXXXXXXXXXXXXXXXXXXX
and the code was POKEd into the memory, or assembled there using an assembly monitor.
Inside (line) Number 9
We are now at $1607, which is a place where the code calls this routine, using SYS 5639 (the decimal equivalent).
; $1607 - sys5639 -
.C:1607 A9 01 LDA #$01
.C:1609 8D 07 15 STA $1507
.C:160c 8D 08 15 STA $1508
.C:160f AE 08 15 LDX $1508
.C:1612 BD 26 15 LDA $1526,X
.C:1615 C9 01 CMP #$01
.C:1617 F0 06 BEQ $161F
.C:1619 EE 07 15 INC $1507
.C:161c 20 49 15 JSR $1549
.C:161f EE 08 15 INC $1508
.C:1622 AD 08 15 LDA $1508
.C:1625 C9 06 CMP #$06
.C:1627 D0 E6 BNE $160F
.C:1629 60 RTS
The code completes with an RTS and control is returned to BASIC.
This is called from line 125:
125 geta$:sys5639:fork=1to10:sys6315:next:ifa$=""then125
This appears to be waiting for a key to be pressed. I think this is the title animation, which includes a "cosmic snake" moving around the title.
Quite a nice touch, especially for an unexpanded VIC20 game.
Directly after that routine is another padding character, another X, which shows up as a CLI in assembler.
.C:162a 58 CLI
(one of my few gripes about the 6502 is CLI - CLear Interrupt disable bit, in other words, enable interrupts which seems the wrong way around. SEI is SEt Interrupt disable is similarly backwards. Other than that, the 6502 is great and far better than any other processor I might have a rather large box full of ...)
Another routine follows at $162B, which is called from elsewhere in the code, not directly from BASIC.
; $162B
.C:162b A2 01 LDX #$01
.C:162d A9 01 LDA #$01
.C:162f 9D 08 15 STA $1508,X
...
.C:1665 A9 09 LDA #$09
.C:1667 8D 0D 17 STA $170D
.C:166a 60 RTS
After that, there are seven bytes of padding, again $58 / CLI / "X", presumably to allow the code to grow during development, or the code was originally longer but was shortened at some point.
.C:166b 58 CLI
.C:166c 58 CLI
.C:166d 58 CLI
.C:166e 58 CLI
.C:166f 58 CLI
.C:1670 58 CLI
.C:1671 58 CLI
And finally you are allowed a single $00 to indicate the end of the line (which the disassembler interprets as a BRK)
.C:1672 00 BRK
Line 10 follows durectly after at 1673
; $1673 - line 10 remx etc.
>C:1673 72 17 0a 00 8f 58
That continues up to line 12, and that links to line 100, which is actual BASIC code.
; $1964
; 100 print"{clr}":poke5697,6:sys4224:sys4248:sys5765
>C.1964 87 19 64 00 99 22 93 22 3a 97 35 36 39 37 2c 36
>C:1974 3a 9e 34 32 32 34 3a 9e 34 32 34 38 3a 9e 35 37
>C:1984 36 35 00
The numbers in the SYS commands are stored as characters ($9E $35 $37 $36 $35 at the end is SYS5765).
That means there would never be zeroes there, only $30 which is "0", not $00. It also explains why BASIC can be quite slow to parse these lines each time as there is a lot of converting 4 or 5 character strings into numbers.
Reverse Engineering
I have disassembled all the code and various blocks of non-code which is either padding or variables or character data. I have not carried out a full reverse engineering to work out what all the code does.
Ed: Well, not at the time I wrote this anyway ....
I did spot a few interesting things.
I found a few occurrences of things like:
.C:18c8 A2 01 LDX #$01
.C:18ca CA DEX
.C:18cb 8A TXA
This loads X with $01, then decrements it to get $00, and then transfers it into the accumulator.
Normally this would have been just LDA #$00 but that would have been assembled as $A9 $00, and the $00 would have be detected as an end of line marker.
This is the End ...
When looking through the binary file in a hex editor (as you do ....) I was interested to see it did not end with three zeroes, as a pure BASIC program normally would.
The first zero is the end of line marker for the last line, the next would be the address of the next line, and $0000 indicates the end of the program.
Looking at the code, line 820 is the last line, and I found that ended earlier in the file, ending at $1C75.
But the file goes on for another 211 extra bytes at the end?
It doesn't seem to be valid code or text or anything, although the strings "$0000" and "BRK" indicate this could be left over memory from the assembler? It seems like there is every form of zero, as if breaking free from the previous limitations.
The files does contain 3,400 bytes exactly (in decimal), so maybe that was a save from the assembler / monitor program, rather than a standard BASIC save?
Looking through the code, I can't see any references to $1C75 - $1D49, so maybe it is just garbage at the end of the file as you sometimes get with a "save slightly more than the file size, just to be sure" option.
I tried removing them, and cropping the file so it finished at the end of the code as it should, and it seems to run fine with no difference, so I will ignore it.
Ironically, after all the work to get the zero-free code into REM statements as part of the BASIC program, the author has managed to demonstrate a more viable alternative of placing code into the area after the BASIC program, where you can use $00 without recrimination. (just be careful about where BASIC stores its variables and heap etc.)
Reconstructing the Code
I decided to try to recreate the program from BASIC and assembly sources, to see how it would work.
Yes, I know I could have been down the roller disco with the cool kids, but instead I was at home reverse engineering a 45 year old computer game....
I now have a BASIC program that is the same size and matches from line 100 onwards, but with all the REM statements full of X's.
My God, it's full of stars ....
Now all I need to do is add in the assembler code, the character data and various bits of padding which I think are variables?
I can do that with ACME assembler as it allows me to insert a binary file (the PRG of the BASIC program) and also to overwrite bits of it by adding code with the .ORG directive setting the location within the file.
...
Well, that wasn't too bad.
I now have two source files.
- A BASIC program which contains the REM statements full of Xs and the rest of the BASIC code
- An assembler files containing all the reverse engineered code
I have done it this way so the assembler file contains just the assembler code, and does not need to recreate all the BASIC line framework.
The assembler file also has several sections which contain short runs of non-padding bytes. They don't make viable code as far as I can tell.
Some are referenced in the code, so they could be variables or data, or they could just be random padding (for example to an extra byte to move a function from $1600 to $1601 so it can be used in a JMP or JSR call)
As it stands, this builds from BASIC and ASM sources a binary identical file (other than the random data at the end, which does not affect the game or get referenced)
I have not commented most of the assembler, I would need to go through and work out how it all works.
The next step would be going through and turning the literal function and variables addresses into labels and trying to work out what they all do, and looking for system addresses like the VIC chip and known zero page addresses etc.
But that is a job for another day
Ed: Well, I wasn't planning to, but I have now almost completed a fully commented disassembly of the code, a full dissection of which will follow in a later blog post
Adverts
The VIC20 Penultimate Cartridge +3 DCR is available now from the Future Was 8 bit.
All Tynemouth products are still available direct from me, and I can ship worldwide.
Including the limited edition 10th anniversary recreation of the very first Penultimate Cartridge:
International shipping is a bit complicated at the moment, so if you want to order from outside the UK, please contact me using the contact link at the top of this page.
See here for more information:
Sorry to have to do this, and I know this is going to affect sales, but please understand it is the only option I have right now.
Stop Press!
I am going to do another batch of Mini PET 40/80s with keyboard, with a few updates.
These are pre-order now, shipping worldwide in November. £450 kit / £500 built.
Available exclusively from me, contact me using the link at the top of the page to get a price for shipping and any duties, based on your address.
The Mini PET 40/80 internal PET replacement boards are also available now, £350 kit / £375 built.
Again contact me if interested.
Patreon
If you enjoy posts like this, you can support me via Patreon, and get access to advance previews of blog posts, and exclusive posts. Paid Patreon supports will be getting the third part shortly, and maybe a forth part three will follow if there is any interest
You also get progress updates on new projects and other behind the scenes updates, as well as access to my Patreon only Discord server for even more regular updates, and to discuss your own projects.
