EasyAsm. Dan’s MEGA65 Digest for August 2024.

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!

MEGA65 News

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 BASIC 65: 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

This loads EasyAsm into memory, then returns to a blinking cursor. This is still your usual command prompt, but something is different: instead of the cursor blinking below the word READY, it blinks below the word OK. This is how you know the MEGA65 is in Edit mode.

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. Personally, I’d love the experience of building a nice text editor, and I want to try it someday. I intentionally designed EasyAsm so that it could be integrated into other projects, so anyone else’s programming tools could use it.

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