Step 1: Write a 6502 assembler

The Honeylisp assembler is written in Fennel, which is a Lisp dialect that compiles to Lua. My goal in writing it was that the input to the assembler would be simple lists, making Fennel into a super-powerful macro assembler basically for free. 6502 assembly is treated as simple data, a kind of embedded DSL that can trivially be generated by simple Fennel functions.

Step 2: Integrate into a text editor

The Honeylisp environment runs on top of lite, a very small and extensible programmer's text editor written in Lua. It's trivial to add new commands that trigger whatever kind of interactive build process I want. It's also straightforward to extend to create custom UI; I put together the bones of a simple tile editor in an evening. I ended up porting lite to the love2d runtime to allow me more flexibility in how I could build these custom editors.

It is also a fairly straightforward matter to add hot code reloading, though it requires a bit of forethought to take full advantage of it. When I put together the tile editor, I could make changes to it, hit Alt-R, and those changes were immediately live. It's cool to be able to use your editor to live-edit your editor.

Step 3: Integrate into an emulator

Back in July, I came across this video of Dagen Brock talking about an Apple IIgs emulator project he was working on that had an interesting property. Instead of integrating a debugger into the emulator, he decided he would implement a socket-based debugging interface that anyone could write a front-end for. Any external program could use this to gain full control of the emulated computer – read and write memory, set registers, set breakpoints, anything.

It turns out this idea kind of languished, and he never quite got to polishing up and releasing his debugger. But this emulator, GSPlus, exists, and it gave me the core idea at the heart of Honeylisp – if I can arbitrarily read and write memory, and I have the ability to augment my assembler, then I can do anything. I can take snapshots and jump back and forth between them, recovering from hard crashes. I can push code updates while the game is running; I just need to be able to specify an appropriate “merge point”. I can map variables from one version of the program to another, so even if data moves around in memory, I can compensate. I can put breakpoints on memory I know should be read-only, to catch wild pointer accesses. I can implement a REPL entirely on the PC side; assemble tiny snippets of code and trigger them. I can integrate with my tools, so making changes to a graphical tile in my editor instantly updates the screen of my emulated Apple II. The possibilities are truly vast.

Step 4: Integrate with hardware

One of the pretty unique features of the Apple II is that it comes with a built-in machine language monitor, complete with a mini assembler and disassembler. It turns out that this can trivially be controlled over a serial port to do things like... write arbitrary memory. So I can plug my laptop directly into a stock Apple II, type IN #1, and then run a single command to bootstrap my environment. In fact writing arbitrary memory in response to serial port commands is not very complicated, and many of the magical abilities I imagine for my environment can be done directly on real hardware.

Step 5: Write a game

There is no point in investing all of this effort into software development tools if you don't plan to develop any software. I intend to port my MS-DOS game Neut Tower to the Apple II using this system. Neut Tower was written using a hand-rolled Forth system; I've built a simple Forth-like stack VM to allow for non-performance-critical code to be written compactly. Because my assembler is so easily extensible, I can also easily use simple Fennel code to generate VM bytecode, which means I can do without a huge amount of the overhead of a full Forth as all of the compiler-y bits live on my laptop. This VM can also be the basis of my interactive REPL, which will be much nicer to write than little assembly snippets.

Step 6: Tell people about it

It's fairly early stages for all of these steps – I have a good start in all of them, but there is still lots of work to be done. I'm really excited about this project, though, and I want to talk about it! Hopefully this blog will be a useful place to do that. I'm looking forward to continuing to share my progress.

#lisp #honeylisp #retrocomputing #apple2 #neuttower

I wrote a game on an MS-DOS 286 PC, using only tools I built myself or tools that were available during the era where they were still selling 286 PCs. It's called Neut Tower and you can play it on your MS-DOS PC, in DOSBox, or in your browser. As part of this project, I implemented a Forth system, and built most of my game and its tools using it.

My motivation at the start of the project was this: I was enjoying using my 286. I liked the single-tasking workflow; there were no distractions. I was downloading games and apps and it was fun! So I figured I'd take the next step and write a little game or something.

When I was a teenager, I had a 286, and I tried to learn low-level programming on it because my options were “low-level programming” and “BASIC”, and I had hit my limit with BASIC. Assembly might as well have been Martian to me, but I got a book about C, and I got a book about game programming, and I sort of got some stuff working. But mostly the stuff I tried to do myself from scratch, or port from other sources, didn't work, and I didn't know why. Eventually I also got access to a 486, and then a Pentium, and the internet, and djgpp and Allegro, and suddenly I had an embarrassment of nice graphics and sound libraries and tooling, segment:offset addressing didn't matter, and I never had to worry about trying to understand how Mode X worked ever again.

Twentyish years later, I wanted to learn all the stuff that never quite clicked for me. I wanted to dig into how everything worked, to make sense of the tutorials that once baffled me. I wanted to really understand it all. So I started writing little prototypes, and pretty soon, yeah, I had a cool EGA graphics engine, with two way scrolling of a tilemap and 16x16 sprites drawn on top, running at a decent speed on actual hardware. Everything fell into place one tiny experiment at a time.

With the hardware programming side of things, I learned that my teenage understanding hadn't really been all that far off the mark – my problems weren't so much that I didn't understand the tutorials and resources that were available to me, it was more that I was simply bad at debugging my beginner code, and didn't have the tools or the patience to fix it. With 20 years of professional programming experience under my belt, and a wealth of resources on the internet that explained how things worked in depth, this was no longer an issue.

Then I started to write a game loop in C, and didn't really like it. I knew in the back of my head that, for what I wanted to do, I really wanted some kind of scripting language. And I remembered Forth existed.

In my 20s, obsessed with both the world of programming languages and the world of embedded systems, it was inevitable that I would learn about Forth – it's a particularly uncommon blend of small and powerful, that could run directly on hardware, that people who loved it really loved. I'd tried seriously to learn it but couldn't really wrap my head around it – the weird postfix syntax, the confusing levels of meta. Why could I not use IF statements at the REPL? How was I supposed to remember all these finicky rules? I filed it away as “interesting, but not for me.”

This project was the perfect opportunity to revisit that evaluation. Forth fit the bill exactly – it was a tool that could be built quickly, using minimal resources, and made to do what I wanted, AND I already had a hazy half-remembered foundation from decades ago. I dove headfirst into it.

Relearning Forth was an altogether different experience. It turned out that once I built one myself, I understood it completely. The design of Forth is to write as little code as you possibly can, to make the computer do only as much work as it needs to. When I had to write it all myself, I had to decide – is it worth building this language feature, or can I do without it? Usually I could do without it. Usually there was a tinier way to do it. The code that I had to write wasn't really all that much uglier or worse for it, once I got used to the constraints. And I had proven designs I could pilfer; there are lots of existing open-source Forth implementations to get inspiration from. There are guides for building Forth systems. Doing Forth is not learning an existing language set in stone, it is building a language to solve your problem, and sharing ideas about useful building blocks. Chuck Moore, the inventor of Forth, hated its standardization; thought the goal of portability was absurd, thought everyone should change it as they needed, to fit their problem. He is still trying out new ideas, rebuilding, simplifying, making a system uniquely his own.

So why do I think all this is important enough to write about?

When I was a kid, I had this persistent idea in my head, that computing was a skill I could work at, get better at, and that doing so would allow me to accomplish things that were impossible for me without it. “Once I got good enough”, I could make a computer game, by myself. I could draw the graphics, I could write the code, I could make the music, I could design it all. I could make it and I could put it out into the world and it would be mine, start to finish. Every time I learned something new about computers, got some new piece of software, I gained abilities. I could do things I couldn't do before. My vision of computer literacy is that everyone has this experience, that everyone can learn the skills they want, is provided with the tools they need, to make their imagination real. I have never really let go of this idea.

I'm still trying to find ways to make it true, still trying to explore the different ways that computing can be empowering. Retrocomputing is one avenue for that – people in the past had a lot of good ideas that didn't catch on. And while emulators are wonderful, running them inside a modern computing system makes it harder to experience what using an old computing system really felt like.

When I show people my setup, they are often curious about the qualitative difference between old tools and modern tools; it must be so much harder, right? And... for me, it's really not! I write bugs at about the same rate; I fix them at about the same rate. There are many things I can't do because of resource constraints, but that keeps the scope manageable and makes for an interesting challenge to find cool stuff I can do. The biggest thing I miss is having a second editor that I can use to look at & edit code while my game is running — I have often resorted to taking a photo of some code with my phone so I can read it while I have the game up.

And I gain really valuable things from the constraints. The biggest thing is that there's no alt-tab away from the work – it's so much easier to focus without a web browser instantly at my fingertips. (I'm procrastinating at work writing this right now!) The resource constraints mean I have to focus ruthlessly on solving the problems I have, not the problems I imagine I'll have – there's no perfect, elegant, general solution if I think hard enough, there's only adding things and cleaning up what I've got, one small piece at a time. And I can take workflow seriously as one of those problems! When I'm fed up with the tools that are available for DOS on a 286 (and this happened multiple times!), I make my own that work the way I want, and I'm able to integrate them seamlessly into my engine. I'm able to intentionally craft my environment to be comfortable. I'm no artist, but multiple people have complimented my art – partly, the secret is that 16x16 sprites and tiles can only look so good with a fixed ugly 16-colour palette, so I'm able to focus on broad colour and style choices. But really, if you put me into my ugly, limited pixel editor that's two pages of code but instantly shows me what my sprite looks like in my game, I will mess around until I'm happy. Put me in front of Photoshop with 16 million colours and I will go crazy from decision fatigue; I'll avoid making more art, and I'll get myself stuck.

So for me, the tradeoffs are incredibly worth it. I've spent decades trying to make games as a hobby; I've put out reams of junk – failed prototypes, bad joke games, quick jam games, failed engines, half-finished tools. I've tried every way of making games that I can think of; coding engines from scratch, using Unity, Godot, Love2D, Klik & Play, Game Maker, Twine, Construct, Adventure Game Studio, pygame, Allegro. Some approaches I've had more success with than others, but I've not ever been as happy with anything I've made as I am with Neut Tower. Not as a retrocomputing exercise — as a game.

Neut Tower is done, for now, and I am taking a break from it. (Perhaps someday I will return to it to create the next two episodes.) I'm quickly finding myself using all of these lessons and starting to build some tools for myself in Linux. I don't quite know what they'll turn into yet, but I'm looking forward to finding out, one small piece at a time.

#neuttower #retrocomputing #essays #forth