thomblog

Using nginx as a forward proxy for gemini

2026-05-04T00:00:00+10:00

Accessing gemini without SSL support

The gemini ‘smallweb’ protocol relies on SSL support for security, encryption, etc. The content of these gemini capsules is almost entirely text-only, ideal for browsing on limited or old hardware, such as my Amiga. Although SSL support is possible on more powerful Amigas, mine can’t actually load the SSL library and use a network connection simultaneously, so I wanted a solution to get gemini capsules displaying without SSL. My solution is to use nginx as a forward proxy. The Amiga (or other device) sends an unencrypted request to the proxy, which then wraps it in a warm security blanket and posts it out onto the internet, and then unpackages the secured return traffic for the Amiga too.

Stream

nginx doesn’t really ‘support’ gemini, but it has a generic ‘stream’ module that can handle weird traffic. My local nginx.conf now includes this

stream {
    # DNS resolver
    resolver 1.1.1.1;

    # Import the JS module
    js_import gemini from gemini_proxy.js;
    #gemini_host variable will contain the name of the host we want to connect to
    js_set $gemini_host gemini.get_host;

    server {
        listen 8888; # Old machines connect on this port

        # Use the imported javascript to sniff the hostname from the incoming request
        js_preread gemini.preread_gemini;

        # Proxy the request to the host on the standard gemini port
        proxy_pass $gemini_host:1965;

        proxy_ssl on;
        proxy_ssl_server_name on;
        proxy_ssl_protocols TLSv1.2 TLSv1.3;
        proxy_ssl_verify off; 
    }
}

And the helper js file gemini_proxy.js

var host = '';

function preread_gemini(s) {
    s.on('upload', function (data, flags) {
        if (data.length > 0) {
            // Find the Gemini URL in the raw text payload
            // Matches 'gemini://domain.com' or just 'domain.com'
            var match = data.match(/gemini:\/\/([^\/\:\r\n]+)/) || data.match(/^([^\/\:\r\n]+)/);
            if (match) {
                host = match[1];
                s.log("Extracted Gemini Host: " + host);
                s.done(); // Stop prereading and move to next phase
            }
        }
    });
}

function get_host(s) {
    return host;
}

export default { preread_gemini, get_host };

Since the stream module can’t tell where the traffic is supposed to go (it’s just a random stream after all), the javascript scans the incoming stream and tries to locate the destination url. This is used to populate the $gemini_host variable in nginx, which then allows the proxy_pass directive to.. proxy.

Security and safety considerations

Lol no. Don’t host open proxies unless you understand all the implications, even if it’s just for gemini.

Unneccessary?

Karl Jeacle, the author of AmiGemini hosts a public proxy free for everyone to use. He even supplies a python script to run your own if you don’t want to connect to his instance. However, I already have an nginx instance running on my network and thought this would be an ideal use for it. But if you’re in the highly normal situation of running an Amiga without SSL and using it to browse Gemini capsules, and you don’t have an nginx instance, his proxy is probably the best bet.

Acknowledgements

I needed assistance extracting the server name from the stream, and got help from Sid (why do you not have a blog?). Then while writing up this blog post he informed me that the javascript was AI generated. Amazing. Now I’m sullied and impure. I don’t like to use AI, and now I’ve used it by proxy.. to build a proxy?

January 2026

2026-02-01T00:00:00+10:00

Untitled project

Started the year by producing a devlog for my ongoing untitled project. I’ve decided to reduce the focus on flying since making this devlog, I think precision flying is too inaccessible for the other planned gameplay aspects. I still want to do something specifically for my custom HOSAS (Hands On Stick and Stick) dual joystick setup .. but I’d like to release something that other people can actually play first ^_^.

Monster Summoner

Despite my promise to avoid gamejams, I made a ‘small game’ for CGA Jam. There’s a ‘high resolution’ graphics mode ‘0x06’ supported by the CGA hardware, 640x200 pixels. It’s only 1 bit, so you’re limited to a fixed black background and one foreground colour. The resolution makes drawing a challenge - the pixels are 2.4 times taller than they are wide. Just trying to get aseprite to display anything in this pixel ratio is a challenge, and all kinds of strange errors occurred with visual garbage and glitches being left when I adjusted zoom levels, or even pixels appearing in the wrong place when drawing. So I mostly stuck to the reasonably functional ‘double height pixel’ mode, which isn’t quite as stretched but comes close. Cloanto Personal Paint on the Amiga actually supports a 640:240 pixel mode that comes close, but the mouse I have for the Amiga isn’t great, so I mostly stuck to Aseprite.

I failed to get a working gcc cross compiler for ia16 (16 bit 8086 family CPUs), so I went with OpenWatcomV2. This worked out pretty well once I managed to find some reasonably up to date documentation. It was my first time writing 16bit C in a while, and I repeatedly made the mistake of assuming 32bit sizes for integers and getting confused when numbers over 32767 (maximum value for a signed 16bit integer) would act strangely. Drawing to the screen in mode 0x06 is fairly simple, every pixel has one corresponding bit, but the memory area is divided into two sections, one for even scanlines and another for oddscanlines. So it was interesting enough without being a challenge to wrangle like some of the more complicated planar graphics modes out there.

Fairly pleased with how the game turned out. If I’m honest it was entirely a vehicle to draw some 1bit pixelart, the game is just a rationalisation. You can play the game here in your browser, but I recommend downloading it and playing in dosbox.

Amiga

When I was a child, I wrote a lottery number generator in Amiga Basic for our Amiga 500. My parents won some money with the numbers it output. I’ve a significant amount of time and a not insignificant amount of money fixing up my Amiga 1200, so I figured it was time to cash in on karma and wrote a lottery number generator in 68000 assembly, so my new Amiga can tell me the winning numbers and make me rich enough to be able to maintain the machine in the future. Also I really wanted a ‘small’ project to get familiar with developing on the Amiga. Nowadays most people write code on their modern PCs and then ‘cross compile’ to the Amiga, testing their code on a software emulator. This lets them use all the futuristic conveniences of the 2020s. But I wanted to do as much as possible on the Amiga itself. There’s plenty of options for developing on the Amiga, but after a little research I went with the highly recommended Asm Pro.

Opening a window and writing text to it is weirdly easy. You just ‘open a file’ with a filename like ‘RAW:0/0/280/200/Lottery”, and a window is created at the top left of the screen, 280 pixels wide and 200 tall, titled ‘Lottery’. Then any characters you write to the file appear in the window. Easy, though somewhere I’m occasionally outputting the wrong number of linebreaks. My Amiga has a realtime clock on an expansion board, so I read the current date from that and use it to seed my Random Number Generator. Then I read out six numbers, check there are no duplicates, and print them to the screen. The actual RNG code could really be run anywhere - it’s completely deterministic and would give the same result if you went through all of the steps manually with pen and paper - but where’s the fun in that? So far this lottery generator has generated a line with three correct numbers and won me $9.15, nearly enough to cover the cost of the tickets I’ve bought so far, haha.

Obviously it could be made to look a lot nicer, but it served as a ‘first project’, much better than the typical ‘hello world’. Sometime in the future I’d like to write a game or three for the Amiga, but that’ll have to wait awhile.

Reading

Over January I read a whole bunch of the ‘Dungeon Crawler Carl’ series. I’m conflicted about these books. Some snobby part of me wants to look down on their ‘game inspired’ elements. Carl and his sentient talking cat Donut are forced to fight for their lives in a dungeon world filled with ridiculous pop culture references, memes and puns. They have a video-game like interface for their inventory, levelling up, boosting stats and so on. So it reads somewhere between a ‘gameplay walkthrough’ and a typical adventure novel. There’s an underlying current of subverting the system and rebellion, hinting at the possibility of overthrowing the powers that are forcing them to participate in the story - I think this is the main motivation keeping me reading.

Music

Album of the month is Takuya Nakamura’s ‘Pleasure Seekers’. He does a lot of jungle/garage adjacent stuff with a good amount of jazz mixed in. I love it, especially his live sets where he pulls out a trumpet and improvises over his live mix.

Setting up a 16 bit DOS development environment in Arch Linux

2026-01-19T00:00:00+10:00

This is a guide on one way of setting up a modern development system for 16 bit MS-DOS systems. It will support 32 bit protected mode too, but there’s many other options for that.

My environment

I’m setting this environment up from a 64bit x86_64 Arch linux machine.

Open Watcom v2

Current available scripts for configuring a gcc toolchain to target 16 bit DOS wouldn’t work for me. Some seemed to have dependencies on older versions of gcc on the host. I spent an evening failing to make any of them work.

Instead, I’m now using open watcom v2, an open source fork of the venerable watcom tools. OW2 supports a cross compiling to a range of targets, including 16 bit real-mode MSDOS.

Build process

This largely follows the open watcom official guide

Clone the OW2 repository

$ git clone https://github.com/open-watcom/open-watcom-v2

Copy and modify the supplied setenv script

$ cp open-watcom-v2/setenv.sh ./
$ vim setenv.sh

Modify the OWROOT variable to point to the root of the local copy of the open-watcom repository, i.e:

export OWROOT=/home/voxel/Src/Extern/open-watcom-v2

Despite having dosbox installed and on the default path, the open-watcom build wouldn’t succeed unless I also set OWNOWGML=1 to disable using dosbox to build the documentation.

Additionally I set the following:

export OWGUINOBUILD=1
export OWDISTRBUILD=0

Next, run the build script, and have it populate a rel directory with the built assets.

$ build rel

This took about 20 minutes to run, and resulted in the subdirectory rel being created with the compiled watcom system.

To ‘install’ watcom, I copied rel to where I keep such toolchains.

$ sudo cp -r rel /opt/watcom

Finally, I created a setvars script to configure environment variables when I’m working with watcom.

$ vim /opt/watcom/setvars.sh

#!/bin/sh
export PATH=$PATH:/opt/watcom/binl:/opt/watcom/binl64
export WATCOM=/opt/watcom
export INCLUDE=/opt/watcom/h

Using watcom to build MSDOS compatible COM files

Create a test file hell_world.c

#include <stdio.h>

int main(){
  printf("HELL WORLD\n");
  return 0;
}

Then, ensuring the environment variable script has been activated, compile and link a com file in one step.

$ . /opt/watcom/setvars.sh
$ wcl -bcl=com hell_world.c
Open Watcom C/C++ x86 16-bit Compile and Link Utility
...
    wcc hell_world.c  -bt=com
Open Watcom C x86 16-bit Optimizing Compiler
...
hell_world.c: 7 lines, included 810, 0 warnings, 0 errors
Code size: 19
    wlink @__wcl_00.lnk
Open Watcom Linker Version 2.0 beta Jan 19 2026 16:01:50 (32-bit)
...
loading object files
searching libraries
creating a DOS .COM executable

To test, the file can be ran in dosbox.

Amiga restoration project

2025-11-28T00:00:00+10:00

As mentioned back in September, I bought an Amiga 1200 in unknown condition from ebay. This page simply documents the steps I took to get it working. I also have an ongoing thread on the fediverse about this process. There’s also a much more nicely written and entertaining Amiga restoration on Console’s blog.

Amiga 1200

I received an Amiga 1200 rev 1D.4, with an installed spinning-disk harddrive, and a MBX-1200z expansion card, which has a floating point processor, realtime clock, and 2MB of RAM fitted. No power supply, peripherals or cables were included.

For power, I ordered a modern replacement from Retrokit.com.au. I’ve seen some reports since that this design of power supply is unreliable, or might even damage the computer in the long term, but many other people seem to be using them without issue.

Video signal problems

Once I had the Amiga and a power supply, I was ready to start testing. Power LED lit up when I supplied power, but I couldn’t get a video signal on the first screen I tried. I only have cables for testing the composite ‘tv’ video output, and there’s not many screens around that still have sockets for such a connection. I managed to temporarily get an old portable flat panel display to show .. something:

First thing I did was replace all of the barrel capacitors on the board. This is a strongly recommended step for Amigas of this era; the capacitors are old enough that they’re basically guaranteed to leak. If not already, then soon.

Sensitive areas of the board near the surgery sites were decorated with flimsy filmy Kapton tape, which didn’t feel like it would offer much in the way of protection, but apparently it works because it did a fine job of stopping surrounding components from melting under the deadly breath of my heat gun. The old capacitors did not surrender easily. I heated them to melt the solder holding them in place, but the same heat also caused these leaky bois to hiss, spit and in a couple of cases loudly pop at me. Eye protection mandatory. Ventilation also recommended, the leaking electrolyte has a horrible fish smell and is probably not recommended for breathing. Replacement capacitors, which I’m assured should never leak, went on fairly easily.

Unfortunately the recap didn’t make any difference to the composite video problem, but I’m actually glad it didn’t work immediately. I wanted a hardware project and expected this kind of problem when I placed the order. This was an opportunity to use my oscilloscope to explore the board, measuring each point of the video system that I could get to with the probes. The excellent amigapcb.org has interactive diagrams of the circuit board, making tracing the routes between pads and components fast and easy.

Eventually I found that the ‘LUMA IN’ signal needed by the composite video encoder chip was not being received. There’s a ‘delay line’ designed to generate the signal based on the the ‘LUMA OUT’ signal from the same chip, and nothing was coming back from the delay line.

I experimented with shorting the LUMA_OUT to LUMA_IN pins on the encoder to bypass the delay line and see if I could get something recognisable on the screen..

The dead delay line components are basically unobtainium, but some research revealed wise masters have devised an upgrade that replaces the current encoder and delay line with a single (available!) encoder that has its own internal delay. I ordered a replacement from utsource.net.

More surgery later, and I now have working composite video output :)

Booting Workbench

When I bought my PSU I also included a Compact Flash to IDE adapter, letting me use a CF Card as an internal harddrive on the Amiga. Plugging the CF card into my desktop PC, I was able to install a copy of the Workbench 3.0 operating system and a few pieces of software, directly from an emulator. Plugging this into the Amiga seemed to work first time.

Kybrd Prblm

But almost no keys on the keyboard were registering. Removing the connector, cleaning it and replacing it didn’t help. The end of the keyboard ribbon connector looked like the conductor had turned black with corrosion. Later I learned that this is actually a layer of conductive carbon that’s supposed to be there. I trimmed back the ribbon and managed to get about 2/3 of the keys working.

Rather than attempt to fix broken traces on a flimsy membrane, I opted to buy a replacement from a local distributor. It arrived quickly and installation was quick and easy.

Now all keys are working, except for the Right ‘A’ button, which acts as a modifier key like alt or shift. Haven’t worked out the problem yet.

Audio

Audio output was functional at this point, but the volume seemed to wander up and down (mostly down), sometimes barely audible. I reflowed the solder of the replacement surface mount capacitor I had added nearest to the audio outputs, and the problem was immediately fixed. Hooray for easy fixes!

File system corruption

About this time I started noticing that large files seemed broken somehow. Any large program seemed to not work. Some would crash, others just error out. It took me a while but I found a more comprehensive guide which recommends limiting the maximum transfer size per write to a partition. An arcane setting easily overlooked. I guess there’s some kind of buffer issue or bug that this works around.

Since setting this parameter and (re)installing workbench 3.1, I’ve had zero of these mysterious corruption issues.

Networking

Next up I wanted to get the Amiga on the network. While it’s decidedly underpowered for browsing modern websites, having networking makes moving files on and off of the machine much easier and quicker.

The A1200 has a PCMIA slot, a cross-platform standard for small expansion cards. The most popular compatible networking cards are fairly expensive due to demand, but during my research I found a newly released driver for the xircom range of PCMIA network devices. These are much less in demand and I was able to buy one for about $10.

One issue I didn’t anticipate is that some PCMIA devices are actually ‘two units tall’. The plastic shell of the device made it too large to physically fit into the slot in the Amiga, despite the actual connection fitting when the case was removed from the Amiga.

I didn’t want to cut a hole in the Amiga to accomodate the card, so instead I trimmed the shell of the network card. I told the driver author about this and I think he was somewhat horrified: ‘I just bought a pcmia extender on ebay…’. Sorry Neil.

Finally I can log into IRC and hassle my friends in #DosGameClub and let them know how much better IRC is on the Amiga (:. File transfer also works.

Future

Currently I’m awaiting an adapter to let me plug a vga cable into the 23 pin Video output port. It might allow me to get a better quality picture than composite, but relies on being connected to a compatible monitor. I don’t have high hopes that my monitors will support the 15Khz signal, but I could get lucky. The alternative is to try and find an older supported monitor, or use some kind of signal processor to transform the signal into something my monitors do support. Those are expensive and I really don’t want More Devices being plugged in if I can help it.

I also have an 8MB stick of RAM in the post to slot into the expansion port. Currently there’s only 2MB of expansion RAM, and I’d like more for games and graphics creation later on.

October and November 2025

2025-11-27T00:00:00+10:00

Been busy, been tired.

Trip

The latter half of October was spent on a multi-stop trip: Turkiye, Germany, Greece. I don’t think anyone enjoys looking at other people’s holiday snaps, but I’m going to post a few anyway :p.

Turkiye

We stayed a few days in the Faith district of Istanbul, dodging crowds, cats, trams and highly motivated hawkers. Incredible historical architecture and food. The Blue Mosque interior is pretty amazing (and impossible to photograph when you’re in a throng of tourists).

We ducked down into the Basilica Cisterns. Some of the pillars are made of repurposed Roman material, like this Gorgon’s head.

Germany

A quick trip to Leipzig and Halle to visit some good friends. Probably a strange observation but I was really surprised by the intensity of economic activity, there are so many shops and businesses operating. Also some great historical architecture. Leipzig zoo was fun, and a lot of good chocolates were eaten.

Greece

The primary purpose of the trip was to attend a family gathering on the isle of Corfu. I saw relatives I haven’t seen in over ten years, and we had a memorial for my grandmother who died not so long ago.

Listen, I have my interests and old payphones are among them, don’t judge me.

Gamedev

I do love game jams, probably too much. It’s appealing to start afresh, work maniacally for an intense period, and then effectively abandon the game at the end of the jam. But this isn’t conducive to creating quality work, especially not of a commercial standard. As of November I’ve resolved to temporarily retire from jams and focus on a longer term project. It has been difficult. I’ll have a dedicated update later, but so far I’ve managed to force myself to spend time only on gameplay programming and avoid any work on art assets, which has resulted in some very professional looking placeholder textures, like this one for a climbable chainlink fence.

Reading

My trip included plenty of opportunities for reading. Everything I read was great.

Valor’s Choice - Tanya Huff. Not too ashamed to admit that I’ve read this more than once previously and I didn’t even realise until I got a few chapters in. Solid military scifi.
Stainless Steel Rat - Harry Harrison. Some classic 50s scifi. Pretty predictable but highly enjoyable cheesy space-rogue adventures.
Blindness - José Saramago. This one was great. Well outside of my usual reading zone, I really enjoyed the unusual writing and tone. A somewhat hopeful post-apocalyptic survival story.
The Light Brigade - Kameron Hurley. A time hopping military scifi story that could have come straight from Philip K Dick. Read through it in two solid blocks. A little grim but I couldn’t put it down.

Fails

The TTGO I mentioned previously died an ignoble death and no longer powers up. It seems the usb connector used for power was particularly fragile. Not sure I can salvage it, the connector has inaccessible solder pads underneath, which means heatguns in confined spaces.

September 2025

2025-10-01T00:00:00+10:00

Another monthly update!

Game Dev

I’ve been working on a ‘shoot-em-up’ editor and engine for Dosember Game Jam. The editor runs in DOS, which has made it a little more interesting to work on, but also means progress has been slower than it might have been if I’d targeted contemporary operating systems only. Not much to show yet but I uploaded a demonstration video to mastodon:

There won’t be too much time to work on this over the next few weeks, but the jam runs all the way through to the end of November, so there should be a shooty-dossy game before the end of the year.

After some months presumed lost in the post, ‘68000 ASSEMBLY LANGUAGE PROGRAMMING’ arrived in my mail box. This is fortunate timing because this month I also finally gave in to the urge to buy a:

Broken Amiga 1200

Yeah! I’ve wanted a real Amiga (which uses a 68000 family processor) for ages. But I’ve had perfectly good emulation - especially on the MisterFPGA. However, the USB controller on my Mister board died recently and I’ve been unable to repair it. So finally I gave in and placed a bid on an ‘untested’ A1200 on ebay. ‘Untested’ can mean a lot of different things on online auctions, but it’s best to assume that the item definitely does not work. I won the auction and received an Amiga that turns on, but the composite and RF video sockets do not put out a valid signal:

Instead there’s a rapidly rolling out-of-sync signal with the wrong colours. This is OK though, I wanted a hardware project, and repairing the Amiga is already underway. I’ll document my repair progress in another post soon.

TTGO VGA

Another delayed mail item, a little ESP32 devboard arrived. It’s unusual for having a VGA port for video output, and two PS/2 ports for old style keyboard and mouse connections. I set mine up as a very low power DOS emulator. It draws almost no power, and can only run very old software with modest requirements. It also only cost about AU $15, which is great for a tiny computer.

It needed a case to keep it safe so I took an existing model and designed a deco-inspired grill for it. I’m pleased with how it turned out, but unfortunately I managed to bend the micro-usb connector severely out of shape when unplugging the power cable :(.

Played

This month I finished an ongoing campaign of Carrier Command 2 against some AI fleets.

Carrier Command 2

Really this is a ‘multiplayer first’ game, the single player experience being initially overwhelming and then quickly becoming too easy. The player commands a carrier (surprise!) with limited resources. An archipelago of islands is populated with resources and factories that can be captured to produce additional air, sea and land units with which to combat ambient defences and opposing factions. Fuel and various types of ammunition need to be produced too and delivered to where they’re needed. Your logistics lines are at least as important as your combat units. The land units are fairly redundant though, air units being more useful in almost every situation. However, I found that it’s possible to start the campaign with a limited loadout, where the carrier starts with no aircraft available. This forces you to make use of the land units with naval support for conquering the initial islands, making the starting phases of the game more challenging. Unfortunately the AI players seem to suffer no such limitations, and have access to aircraft and unlimited cruise missiles from the outset. Still a great game regardless.

Beyond All Reason

Toward the end of the month one of my brothers organised a few rounds of ‘Beyond All Reason’, an open source descendent of the real-time-strategy game ‘Total Annihilation’. TA got a lot of play-time in our family home and is definitely one of my preferred RTS - not a mad micromanagement rapid-fire clickfest like Starcraft, but not so slow and long a campaign as to drag a match out all day. It’s an impressive example of open source gaming, cross platform online multiplayer all developed and hosted by the community. My only real complaint has always been the ugly user-interface. Fun to play against a sibling, but I don’t think I’d have much fun in single player.

Other Media

This month I bought ‘Book of Madness (狂気)’ by Onryō. Dark Drum and Bass, a bit minimal but with really good production. The label ‘Zodiac Music’ has a pretty strong musical identity - by which I really mean many of the tracks are very similar to eachother. Case in point: this album initially released with track 3 accidentally replaced by a duplicate of track 2, and I didn’t even notice until they fixed it. I love it regardless, dark dnb is my ‘productivity’ music. I get a lot done when the drums are drumming at 170bpm.

August 2025

2025-08-27T00:00:00+10:00

Inspired by ratrogue’s dev log, I decided to have a go at logging some of the things I work on, play and watch.

Game Dev

Watched The Anti-Compulsion Loop Series: Gradius Origins Review. The first third talks in great detail about the design decisions and limitations of the original Gradius games. The video is targeted at STG/shmup fans and makes a lot of assumptions about familiarity with various mechanics and terminology, making it hard to recommend to a general audience.

Wrote a partial NES / famicom game inspired by the Tachikoma robots from the Ghost In The Shell manga / movies. Thought this would be interesting because Tachikoma designs are more about their movement and personality than static visual appearance, so I put some effort into procedural animation. Not a total success and certainly not a complete game, but I’m pleased with how the player character moves and animates.

Played

Bought and played through the excellent Touhou Luna Nights, a pixel-art platforming metroidvania where the protagonist can slow and stop time and throw hundreds of knives. Time control is needed to solve a few puzzles, and normally passable water becomes completely solid when time is stopped, serving as a barrier or floor. As the game progresses you encounter enemies and puzzles that only move or attack while time is slowed. Elements of bullet hell reflect the touhou origins, and the humour is particularly good. I’d recommend this to anyone, though maybe it’s a little too difficult for some?

I also reinstalled Warzone 2100, an older RTS that is still kept updated as a community supported open source project. An absolutely ridiculous tech tree lets you research and design varied vehicles and weapon combinations that support many different play styles, many more than is typical for the genre. There’s a good mix of difficulty options too, though the AI is pretty poor in certain respects.

Other Media

Started watching ‘Neon Genesis: Evangelion’ with my son. Not sure how appropriate it really is for a 10 year old child but so far we’ve both enjoyed it. I’ve started the series a few times previously but never made it beyond the third episode.

Found a list of recommended sci-fi novels and grabbed a bunch at random on my ereader. For the first time in the five or so years I’ve had it, I have had cause to delete books. Some of the recommendations were clearly AI generated - meandering conversations that repeatedly loop back and make no sense whatsoever. The AI coverart should have served as a warning. Felt like I took some psychic damage just trying to read these. Of the ‘probably written by humans’ books I tried, ‘Neural Wraith’ by K.D. Robertson was best. An attempt at a detective noir story that had a small cast of human males and thousands of feminine robots whose descriptions largely centred on their breast size. For some reason that is never fully explained, all of the female robots are in the city are in love with the protagonist. But there was a passable story in there too. My main takeaway is that the list or recommendations is garbage.

In music, I preordered ‘Smoke and Fire / Summer of Love’ by Oversight, a jazzy drum and bass single that’s a bit more bright and cheery than my usual dnb listenings.

bloggpt, a rant

2025-03-24T00:00:00+10:00

It is not news to anyone that the web is filled to the eyeballs with shit. This may always been the case, but never before was the effluent so endless in quantity and miserably poor in quality. Image diffusers and Large Language Models - so called ‘AI’ - have created a vast new source of meaningless fecal content to pollute the information streams. Every social media site is filled with images and text generated in exchange for not inconsiderable amounts of electricty - all to try and farm enough traffic to generate advertiser revenue. So pervasive is the rot that even my closest friends use these AI ‘tools’, and at least one family member goes to great lengths to try and discover ways of monetising them. In my immense privilege, I use a moderated, private mastodon server for most of my social media interaction. I see little AI content unless I go looking for it - besides a few petty fraudsters trying to pass off generated art as their own, using it to try and solicit donations from the unwary. But elsewhere: tumblr, instagram, search results - these places I see more AI content than human.

A small grace is that as the web becomes increasingly polluted with machine generated feculence, the source from which the AIs are trained becomes increasingly corrupt. In the 1990s, beef farmers in the UK recycled some of the less desirable cow parts back into the food supply for their herds. This cannibalism resulted in ‘mad cow disease’ infecting the food supply and potentially the people that ate it. Likewise with AI, as the corpus on which they feed fills with AI content, their ability to generate coherent content rapidly reduces. Image diffusers either generate garbage or pictures that congregate on specific styles despite user instructions. LLMs generate poorer quality text filled with ‘tells’, words increasingly common in AI generated content like ‘delve’ and ‘hitch’. ‘Pre-AI’ datasets, consisting of mostly human generated content free of generative taint, are valuable commodities.

Why am I talking about this here? Blogs are one of the continuing sources of longer-form human generated content. Clearly there are blogs written by AI, or perhaps co-written, but there are still a good number of people continuing to blog their thoughts, notes, gamedev environment configuration instructions and other important human generated text. My own humble blog is free of AI content, and while it may not be the most important writing humanity has produced, it’s infinitely more valuable than anything ever output from chatgpt.

A cursory glance at the website access logs for any public blog will show that automated scrapers account for much (if not most) of the traffic any given blog receives. ‘Bots’ have always crawled sites - you wouldn’t have much in the way of search engines without this. But the search engine ‘web spiders’ were primarily indexing the content of websites to see if it had anything relevant for web search results. The current generation of crawlers want only to copy every image and sentence on a website into a training set. Whether that is to sell to model trainers or to build their own AI, the result is the same. Your words are taken and put into a giant statistics table that someone hopes to sell access to, and to burn kilowatts of electricity to make it happen. These crawlers also seem to ignore requests to not index your site via the venerable ‘robots.txt’ standard that was somewhat respected by the web spiders of yore.

Over on mastodon, there’s a culture of providing comprehensive alt-text, written descriptions of any images or non text media uploaded to the platform. This helps improve accessibility by providing a non graphical alternative for blind users, or potentially a low-bandwidth option for users on connections too slow or unstable for transferring photos of your cat. Image diffuser training relies on exactly these types of descriptions. The more accurate, detailed and explicit the text description of an associated image, the more valuable it is for the purposes of training an AI to generate fake versions of those visual subjects.

To use the web in the last 20 years was to feed the advertising algorithms. Every link clicked, text entered, momentary hesitation when scrolling past a photo - every recordable interaction fed into a program designed to sell you to advertisers. Now every contribution you make online is potentially fed into a vast hellish data lasagne to be fed to coal burning demon AI. This is the new cost of interacting with online communities and you can’t avoid it. I won’t stop blogging because I’m afraid an AI will give inaccurate instructions on configuring a raspberry pi as a dreamcast development machine. I won’t make my mastodon photos inaccessible to a blind person just to spite the seller of a dataset.

Inconveniencing real people for a small chance at causing a rounding-error of difference to an AI isn’t worth the cost to me.

DARIUSBURST Chronicle Saviours Dual Screen on linux

2024-12-01T00:00:00+10:00

(The author’s impression of Tux the penguin visiting Darius space).

DARIUSBURST CS

I’ve been playing a lot of shoot-em-up games lately. One I tried in the past and bounced off of was the Darius series. But I revisited it this week with fresh eyes and am really enjoying it. Giant robo-aquatic bosses firing missiles and lasers at your space in 32:9 widescreen. The game is designed to work on a ‘dual screen’ setup, two standard 16:9 monitors side by side. This works OK in Windows - assuming you have exactly two monitors. I have three and this causes the game to try and display the game in the wrong resolution. Easily fixed by going into the windows settings and completely disabling the third monitor. Not ideal.

Linux

But obviously I don’t want to boot windows if there’s any reasonable alternative. The game runs OK under linux - in single screen mode. Setting the game configurator to Dual Screen gives only a triple screen resolution

and for some unknown reason Window Mode offers a selection of lesser resolutions which do work - but don’t fill two screens.

But no amount of tweaking the minimal exposed options can make the dual screen mode work fullscreen. Starting in ‘Full Screen - Dual Screen’ mode just draws a double screen’s worth of pixels onto a single screen, and no amount of command line requests to resize the window to cover two screens had any effect.

I’m running the steam version of the game via proton, which is valve’s flavour of wine, a windows compatibility layer for linux. This means that we can make configuration changes to the wine environment used by a particular game, assuming we can work out where it is. Steam in linux installs wine environments to ~/.steam/steam/steamapps/compatdata/[steam_app_id]/pfx. One easy way to find the steam app id is to look at the url of a game in the steam store. In this case it is 377870.

Ensuring the game is not running, I launch winecfg for Dariusburst with

WINEPREFIX=/home/voxel/.steam/steam/steamapps/compatdata/377870/pfx winecfg

Navigating to the Graphics tab, we can choose to ‘Emulate a virtual desktop’ and set the desktop size to 3840x1080, the resolution of two 1920x1080 monitors side by side.

Now when launching the game, the full screen resolution is detected as 3840x1080 - a double screen.

I can now launch the game and play across two monitors, without having to disable the third as I do in Windows, hooray.

Maybe I should work on reorganising those wires next?

Dreamcast homebrew engine part 1

2024-10-22T00:00:00+10:00

Dreamcast

Released in Japan 1998 / elsewhere 1999, the Dreamcast was Sega’s last home game console. It was designed with 3D games in mind, excels in that regard, but was quickly eclipsed by the Playstation 2 and ultimately had a very short commercial lifespan. I love a doomed underdog, and when I first became aware of its homebrew scene a few years ago, I knew that Dreamcast development lay in my near future. I’ve made a few prototypes already, but for various reasons they have been indefinitely postponed. There is an actively maintained open source ‘operating system’ named Kallistios that enables new software to be developed for the console without having to use the copyrighted official software development kit from Sega. Coupled with forums filled with technical discussions, a recently revamped wiki and multiple busy Discord servers (boo), there’s a wealth of resources for understanding the system’s workings and how to develop for it.

Dreamdisc 24

This December will see the ‘Dreamdisc 24’ gamejam, a community event where all Dreamcast developers are invited to create a game, some of which will end up on a physical compilation disc. I have been known to participate in a gamejam or two (it’s basically my entire personality), so I’m excited to participate. In preparation, I’ve been implementing a game engine - a framework on which multiple different games coule be built.

Homebrew engine

Though the engine I put together for Dashy No Blast was reasonably sophisticated, I was using an opengl abstraction layer named GLDC rather than working with the lower level Power VR graphics api that Kallistios exposes. When I recently returned to Dreamcast development and tried to rebuild Dashy no Blast with the latest Kallistios and GLDC updates, I was met with only a black screen on the Dreamcast. Initially I assumed I was failing to initialise something properly, and despite a few hours of investigation was unable to draw anything to the display. Eventually I discovered that a recent Kallistios update made a breaking change that prevented GLDC from working - but before learning this I had already started exploring rendering 3D on the system without opengl.

Here’s a mighty triangle running on an emulated dreamcast, my first baby. All 3D images on the Dreamcast are created from triangles - often hundreds or thousands of them - so being able to output a single triangle to the screen is an important step. This confirms that I’m able to draw in 3D without using OpenGL. In theory, I can draw more triangles and at a faster rate if I use the Kallistios PVR api directly, without the slightly more generalised OpenGL layer performing calculations in the middle. In practice there is probably quite a lot of optimisation needed to get from an initial naive approach to a system that parallels the performance of the dreamcast OpenGL implementation. But for now the next step was loading and displaying a more complicated mesh, with textures:

(Embedded video of a room rotating not supported here)

Z Culling

If you look closely in the video above you may notice pieces of the floor turning black. Any geometry that extends offscreen needs to be ‘clipped’ to prevent errors and chaotic triangle soup from being drawn all over the screen. Here’s an example of when culling isn’t working:

‘Illegal’ triangle data in the stream sent to the graphics chip is discarded, leaving holes that invalidate the meaning of subsequent data, leading to unpredictable results. My ‘easy’ solution for now is to cull any triangle that is has one or more corners with a Z coordinate behind the camera. Culled triangles are never sent to the PVR graphics chip, preventing this problem from occurring - but at the cost of not being able to draw geometry that can be behind the view. This can mean holes in floors, missing walls, and other incomplete geometry if the camera is too close.

It is only possible to submit ‘so many’ triangles to the PVR each frame. Exceeding this number can slow the framerate of the game if the scene is not ready to be drawn when the next frame must be drawn. If any of the submitted triangles are not visible, due to being offscreen to the left or right, or perhaps too far into the distance, then there’s no point in sending them to the PVR. Rendering a tall skyscraper 90’ to the right of where the camera is looking is useless if it can’t be seen. Instead the triangle budget could be spent on more detail for the objects that are onscreen. To limit the number of wasted triangles sent to the PVR, another type of culling is needed.

Bounding sphere visibility culling

Let’s say we want to draw this spaceship scene. The engine transforms the position of the ship and all of its triangles by the camera projection matrix. This operation converts from ‘3D space inside the game’ to ‘2D space on the screen’. If the camera is at the coordinates 0,0,0 and the ship is located at 0,0,50 then if the camera is facing the right direction, the ship will be drawn at an appropriate scale for being ‘50 units’ distant. If the ship were moved to 0,0,100 then the distance from the camera to ship is 100 and we would expect a reduction in the size of the ship drawn to the screen. Likewise adjusting the X and Y coordinates would move the ship around the screen horizontally and vertically respectively. Too far in either of these directions, and the ship would be ‘offscreen’ and invisible to the viewer.

My engine creates an imaginary sphere containing each object to be drawn to the screen. Before the somewhat expensive operation of calculating the transformed position of every triangle, the engine calculates the screen position of where the sphere would be by transforming the position of the ship and calculating the screen size of the sphere. Then it is a simple matter of 2D maths to check if this position overlaps the visible area of the screen.

The yellow rectangle represents the visible screen space. Any spheres that are contained or overlap this rectangle will have their contents drawn to the screen, as is shown with the green onscreen sphere. The red offscreen sphere does not intersect the screen rectangle, and so is culled and not sent to the PVR graphics chip, saving triangles.

This system is not perfect - in this example the ships are long but not tall. A sphere that slightly overlaps at the top or bottom of the screen will still send wasted triangles in this example, but it is a good approximation and cheap to test. If I write a game that would benefit from more precise culling, I could extend the spheres to support being squashed on some axes, or using multiple small spheres instead of a single large one.

To be continued

The engine contains a Level Of Detail system to save triangles by drawing simplified versions of meshes at long distances where details are not visible, limited gltf file format support, audio with dynamic pitch and volume, and a rudimentary ‘cel-shading’ like style with model outlines. If there’s anything to be said about those or other features, I’ll add a part 2 in the near future. Until I decide on what game I’d like to make for the Dreamdisc-24 jam, I can’t be sure what else the engine will need.

Deathloop 256 NES/Famicom STG shooter

2024-09-18T00:00:00+10:00

Alakajam 20

This weekend was the 20th tri-annual 48 hour Alakajam gamejam. Participants suggest themes, the community takes a vote, and the theme most (dis)liked by all is revealed at the start of the 48 hours. Games are written from scratch and submitted before the time is up - developers working alone for the solo category or in arbitrary sized teams for the team category. My entry (which you can play here) is a NES game.

NES Famicom

Released in 1983 in Japan, and other countries soon after, Nintendo’s ‘Family Computer’ or ‘Entertainment System’ is a limited machine with 2KB of work RAM, 2KB of video RAM, 54 colours, and a 6502 family processor clocked at a stately 1.79MHz, probably about 1 thousandth the speed of the device you’re using to read this. It’s awesome. I have an ongoing game project for this console, with a plan to produce a small run of physical cartridges - which means I’ve deliberately targeting the minimum spec for a game cartridge to keep cost and difficulty of hardware development to a minimum. But commercial releases for the console were not always so constrained - it’s possible to add special chips that allow for extra memory, super graphics capabilities and much more - all within the game cartridge. So for this gamejam I decided to give myself the luxury of Nintendo’s top of the line mapper - the extra control chip on the cart - and use the ‘MMC5’. Most notably, this chip lets the cart exceed the normal 8KB of stored graphics by many, many times.

Vertical scrolling

(Embedded video not supported here)

The NES can scroll the screen in any direction - but that moves the entire screen as a single chunk, as shown here in another of my NES jam games, Windstorm Reef. My interest for this jam was creating a vertical parallax effect, scrolling the screen vertically, but at different speeds to give an illusion of depth. While it’s possible to dynamically change the vertical scroll of screen regions in realtime, it’s very difficult to do accurately, especially if you have gameplay happening simultaneously and using the CPU’s very limited time.

So instead of ‘actually’ scrolling the screen, I leveraged the MMC5’s ability to access large amounts of graphical memory and drew versions of the background in each state of being scrolled.

Here are four ‘frames’ of the background, stored in a 4KB ‘page’ of CHR (CHaRacter) memory. Overall the vertical scrolling effect uses 64 frames, with each of the frames contains all of the graphics needed to make a frame of the background image when repeated:

The NES ‘thinks’ that it’s drawing the same background every frame and has no concept that any ‘scrolling’ is happening. Instead, the MMC5 mapper chip is instructed to page a section of video memory. When the graphics ‘PPU’ processor is ready to draw the pixels for the background, it looks up the correct values to draw by first checking the ‘nametable’ to get a tile index, and then grabs the pixels for that tile from character ROM. This lookup happens via the MMC5, which I’ve programmed to ‘point’ to a different window of the background tile library each frame.

We can examine what the console ‘sees’ in video RAM in realtime using the Mesen emulator’s Tile Viewer debug tool:

(Embedded video not supported here)

By rapidly flicking through the different pages of character rom, the background tiles appear to animate. Putting it all together, the end result is pretty good:

(Embedded video not supported here)

I also tried to implement a small amount of horizontal perspective, but I’m unhappy with how it turned out. Not smooth enough and too subtle an effect. You can see this for yourself if you play the game and move left and right. This was a real time waster in the jam, I nudged the pixels by hand for 7 perspective angles, for a total of 448 frames. I didn’t expect it to take more than half an hour so didn’t really consider an automated solution. If I revisit this type of effect, scripting as much of the process as possible will be my first step.

Gameplay

A scrolling background does not a game make. The theme for the jam was ‘In a loop’, so my entry is a ‘shoot em up’ or ‘STG’ (ShooTing Game) where the play is stuck in a series of loops. Usually in STGs a viable strategy is to shoot a few enemies and dodge the rest. In this game, you must defeat every enemy that appears onscreen to progress. Missing one or more enemies causes the loop to repeat - and being destroyed by an enemy causes the player to ‘loop down’ to the previous loop. It’s a simple mechanic and works well enough, but in the current implementation severely lacks variety. There’s only a single enemy type and only eight different enemy attack patterns. In order to allow for a gradual increase in difficulty, the enemies do not even fire at the player until more than halfway through the game’s 8 loop waves. But once they do, the difficulty climbs quite rapidly.

Firin mah’ lazer

I’m a big fan of ‘special attacks’ in this genre of games. Choosing when to use your special weapon can add a lot of tactical depth to what might otherwise be a very shallow game. Time limited, my special laser is very overpowered and suffers some bugs, but I’m happy with how it looks. Unfortunately, when the lazer stretches the full screen height, it consumes all of the limited number of sprites the console is able to draw to the screen, but when it works correctly, it looks cool!

Assembly

I wrote this game using only assembly, the lowest level human readable representation of machine code. I really enjoy working at the bare metal level and giving the machine direct instructions, rather than writing in a higher level language and hoping the compiler produces something close enough to what I want. It’s not the fastest way to develop a game, but I’ve done a few NES assembly jam entries now and am pretty happy with how much I’m able to achieve in a short timespan. I could have produced a more fully featured game using a high level language - but would it have run on a console from 1983?

Conclusion

You can play Deathloop-256 in your browser or download it for use in an emulator here. It’s simple but quick to try out, and I hope you at least enjoy the cool scrolling background - I do :D.

Demonic Foundations, MSDOS puzzle/board game

2024-08-18T00:00:00+10:00

Dos Game Jam

Last weekend I was feeling a bit despondent over not having made an entry for Dos Games July 2024 Jam, a periodically repeating jam with a nice community. The project I’d started for the jam had fizzled out, equally disintersting to develop and to play. So started drawing the game I’d like to make for the jam ‘if I had time’. A few hours later I had this mockup:

Someone once explained the boardgame of Santorini to me, and the mockup was my approximation of that concept, but set in some kind of pixellated hell. It’s a fairly simple concept - two players face off against eachother, each turn moving one demon, adding one tile to a stack. Demons can climb up to one step higher than their current position, and you win if your demon stands on top of a stack three tiles tall. Seems simple, enough so that I felt like I could manage to turn the game around within the week still remaining.

Development environment

I recently built a new desktop machine and so used it over my normal raspberry pi setup - but there’s nothing used during this jam that wouldn’t work perfectly well there.

Text editor: vim
Graphics editor: krita (for sketching), aseprite
Audio editor: audacity
Test emulator: dosbox
Cross compiler: i586-pc-msdosdjgpp-gcc

Writing the game

I’ve written a few games for MSDOS both 16 and 32bit. Given that I wanted ‘nice graphics’ this time, I didn’t choose to limit myself in terms of graphics hardware. The game requires VGA graphics, though targeting the limited palettes of CGA, EGA adapters would definitely increase the ‘dos-feel’ of the game. I used the Allegro 4 library to handle all the low level details like initialising graphics modes, sound driver etc. Initially I was quite conservative with memory use and redrawing the screen - but once I decided I wanted a scrolling background I was having to redraw much of the screen every frame, so I just decided to redraw everything every frame. This reduces performance on pre-pentium machines I’m sure - possibly into the realms of unacceptable framerates.

But once I was committed to redrawing everything each frame, there was no reason to keep anything stationary. So I added ‘bounciness’ to the stacks of tiles, animated the movement of the demons, and added a dynamic camera that scrolls the map a little as you move the mouse - which also allows me to make the playfield slightly too large to fit onto the screen.

(Embedded video not supported here)

Taking the time to configure a nice debugging setup wasn’t part of my schedule, instead I relied on the time honoured and ever hated method of literring problem areas with print statements to output important state information to the console. This bit me when it came time to writing the computer opponent. There’s still a couple of bugs in its behaviour that I haven’t taken the time to analyse - I’m fairly certain stepping through with a debugger would make short work of that. I’m not a fan of using gdb from the command line, I should take the time to learn one of the gui frontends for it.

Cut content

I’d originally planned on adding multiple computer personalities to play against, with differing strategies. The ingame portraits were designed with those in mind, and would definitely be near the top of my todo list if I return to expand upon this game later. A short ‘campaign’ where you play against increasingly difficult opponents to reach the final boss of hell would be good too. Adding unique powers to each character is another option - I think some versions of Santorini do this as well - allowing for slightly asymetric play as each player has a different unique skill.

Results

You can download Demonic Foundations here. You’ll need a dos emulator, I didn’t take the time to make a web build that runs in the browser. People can download the game and play it on their own machines instead. I think it adds something to the DOS emulation experience, but it also reduces the number of people that will play my game - something I can live with.

Doing a graphics-focussed jam was great. Drawing little pixellated demons and portraits was definitely the highlight for me - but losing to the AI for the first time was also a highlight. So proud of my stupid little machine demon. Let me know if you play it!

Quokka Wokka, a small GBA game

2024-08-04T00:00:00+10:00

Using the environment configured in the previous post, I’ve created a small game as an entry to the game boy advance gamejam gbajam24, Quokka Wokka.

This was my first time writing a GBA game, and there was quite a lot to learn. I used the tonc library to do most of the heavy lifting, but I still needed to understand how to working with the GBA video memory, making sure data was in the right format and the right place in memory. I opted for a fairly simple, straightforward game to try and limit the development difficulty, not wanting to combine learning a new platform with trying to perform complex programming. So, Quokka Wokka is a 2D ‘single screen arcade platformer’ where you play as a Quokka that needs to clear each screen, avoiding touching the enemies, throwing your babies as weapons, and eating as many leaves as possible.

Gameplay

The goal is to clear each room of enemies. There are two ways to do this - throw your babies at an enemy to stun them, and then run into them to send them flying across the screen. When they land they’ll turn into delicious fruit. The other method is to collect all the small leaves on each map - which triggers the ‘Bonus Game’ inspired by Rodland, turning all enemies into giant harmless leaves that can be touched to create bonus letter pickups - collect all six letters to get an extra life.

The Quokka is an Australian marsupial largely known for being willing to sacrifice its children while fleeing from predators, physically dropping them as it runs away. I’m not sure that throwing one at a crab would stun it very effectively, but there’s some basis in reality here.

Graphics

The graphics were drawn in Grafx2 and Aseprite. Aseprite is definitely a more fully featured editor, but Grafx2 is much snappier on limited hardware like my Raspberry Pi, as well as being much easier to install and get running.

For simplicity, I kept most of the graphics in a single spritesheet. The GBA can hold more than this in graphics memory, especially when using ‘4bit’ palettised graphics - but again to keep things simple for myself I used ‘8bit’ colour support - all graphics take up twice as much memory but share a single large palette. If I were to develop this into a full game I’d start by switching to ‘4bit’ graphics to allow for swapping palettes at runtime, and allowing for a greater variety of sprites to be visible onscreen at once.

Music

I tried to find a musician to contribute music for the game, but the responses were from people that were unfamiliar with the formats the game would need. I can’t fault anyone, but I increasingly see musicians drop links to their portfolios in the discussion boards for popular gamejams, even when their music is produced entirely through a modern workflow incompatible with the target platform for the games. GBA music is bbest created as a ‘.mod’ or similar format - small audio samples packaged with a midi like sequence of notes telling the machine when to play each sample, at what pitch and volume etc. It’s not trivial to go from a modern ‘Digital Audio Workstation’ to the spartan limiations of a tracker. A musically talented family member did try, but it’s a lot to learn! So in the end I created the music using Milkytracker, and although it’s not a great soundtrack, it turned out better than I feared.

Programming

Writing in C feels like a holiday after being down in the 6502 assembly mines. Though it won’t net me the best possible performance for the machine, C gets pretty close, and the game is so simple that it’s not really a concern. If I wanted 3D, some very fast matrix maths or similar, then I’d look to peppering in some assembly. Libtonc is not just a library of useful functions, it’s also a well documented api with an extensive tutorial. I had to re-read some sections on how videoram is mapped and interpreted when things didn’t behave how I expected, and I had some interesting effects when I pushed the sprite hardware the wrong way. Definitely a library and workflow I’d like to use again :)

(Embedded video not supported here)

Hardware

I grabbed some cheap ‘pirate carts’ from aliexpress. It was a bit of a gamble as not every cart is compatible with my cartridge flasher (the device I use to copy my game from the development machine onto the cartridge, which can then be inserted into the game console). A ‘blank’ cart sells for around $30, but these ‘game reproductions’ only cost $4 each, and work great. The same can’t be said of my printer, which has decided to no longer output blue ink, causing the sticker label to be quite pink. I have modded this Game Boy Advance to use a backlit screen, which means I haven’t been able to check how readable the graphics are on the ‘unlit’ display the original GBA shipped with. Hopefully someone will let me know if it’s unplayable.

Summary

Quokka Wokka is a short, easy game. As a ‘full game’, it would need more bosses, a lot more maps, and perhaps a few extra gameplay mechanics. I think it’s more suited to platforms a little older than the GBA, where less gameplay complexity is expected.

I enjoyed making something simple while learning about the workings of the GBA. It’s a lot more powerful than I realised, and writing a game for it in C, rather than the assembly I work with for the original Game Boy and NES, made the process fast.

Developing GBA games on Raspberry Pi

2024-05-28T00:00:00+10:00

This is a log of how I set up a GBA development environment on a raspberry pi. It’s not intended to teach game development, just the process of installing and configuring the tools so I can refer to it later.

Why

At the time of writing, ‘GBA JAM 24’ is running. Entrants create a new game compatible with the handheld Game Boy Advance console from 2001. I’ve never made a game for this platform before, and I’d like to give it a try! Currently my only ‘desktop computer’ is a raspberry pi 4, so that’s what I’ll be using. More information on my hardware setup is available here if you’re interested.

DevKitPro

The very good people at DevKitPro maintain a free toolchain of cross compilers and libraries targeting multiple platforms, including the Game Boy Advance. This handles most of the difficult configuration and setup for us, and reduces the scope of my own work to ‘making the game’ rather than having to spend a long time creating special compilers and so on. They provide a fairly straightforward Getting started guide.

Though not available directly from the debian repositories that I’m using on my raspberry pi, devkitpro make their own debian compatible repository available. We just need to configure apt to use it.

# wget https://apt.devkitpro.org/install-devkitpro-pacman
# chmod +x ./install-devkitpro-pacman
# sudo ./install-devkitpro-pacman

This configures the repository and installs devkitpro-pacman, the devkitpro package manager tool - which we can now use to automatically install everything we need for gba dev

# sudo dkp-pacman -S gba-dev

This installs gba compilers, libraries, examples, a debugger and probably more.

Hell(o) World

As a special treat we’re going to actually use the tools this time. In a new terminal window (to ensure the new devkitpro environment vars are set), create a folder for the project and add this Makefile (borrowed from the devkitpro examples). There’s quite a lot of configuration to the devkitpro environment and the Makefile handles it all on our behalf. Finally create a c source file.

# mkdir hell_world
# cd hell_world
# vim main.c

Edit in your favourite editor:

#include <gba_console.h>
#include <gba_video.h>
#include <gba_interrupt.h>
#include <gba_systemcalls.h>
#include <stdio.h>

int main( void ){
    irqInit();
    irqEnable( IRQ_VBLANK );

    consoleDemoInit();

    iprintf("\x1b[10;10HHell World!");  

    while( 1 ){
        VBlankIntrWait(); 
    }
}

Finally, from within this project directory, run Make

# Make
main.c
linking cartridge
built ... hell_world.gba
ROM fixed!

This gives us hell_world.gba, ready to run in an emulator or on a real Game Boy Advance if you have a method of putting it onto a cartridge.

Webgen blog generator

2024-05-22T00:00:00+10:00

Why

I have a tendency to ‘rebuild’ my computing devices, sometimes the hardware, more often the software stack. A few times a year I’ll reinstall windows, linux, freebsd, depending on the mood and what I need to get done. This also involves reinstalling the various tools I need, graphics packages, editors and so on.

Annoyingly, this also means rebuilding whatever tools I’m using for managing websites. In particular I find it frustrating to set up tooling for my own personal sites. Ideally publishing to the web shouldn’t involve anything more than the most basic text editor and a web browser, but there are usually reasons why this isn’t ideal. As soon as you want features like links between pages, tags, any kind of hierarchy or organisation, the workload multiplies. These are all possible manually, but better to be done quickly and accurately by the machines. Hopping around between processor architectures and operating systems, I run into compatibility problems. “This version of web publishing software isn’t available for your operating system. This version of ‘dependency’ doesn’t work on your processor type” etc. So I decided to make a simple, portable site generator that will work everywhere I could possibly want to use it, and work fast. This last requirement is particularly important to me as I’m currently doing all my work from a very modestly powered raspberry pi ‘tiny computer’, where visual content editors tend to be a bit slow and unwieldy.

Webgen

I didn’t even waste time on coming up with a nice name. This is a ‘website generator’, webgen. I bashed it out over two evenings, sticking to the C programming language. C isn’t ideal for easy text processing, but the results are fast and can be compiled on any almost device from the last 30 years (probably?). I’m quite sure it won’t work in a very ram restricted environment, but being simple and self-written, I can fix any problems I encounter in restricted future environments. There’s also nothing in the way of server-side requirements, no special executable code that needs to run on the server as with PHP, ASP, node, and nothing that has to run in the client browser such as javascript. Just C parsing markdown and generating HTML.

Including Markdown

I was previously using Publii to edit my site. Before that Hugo and Pelican. All of these supported markdown files, a simple way of annotating text that can be later converted to html. But annoyingly, if the author was unfortunate enough to misplace (or delete in anger) the original markdown documents, there was not a good way to turn the generated site pages back into markdown documents. For this reason, when Webgen publishes a website, the original markdown files are included in the output. If i were to lose the local verion of my site data, or want to switch to some other site generator with markdown support, I would only need the content of my published site directory, which includes all the media and markdown files needed for any other generator to build a site.

Webgen: closed source??

Even though I’ve written Webgen to be ‘fast and scrappy’ there are parts of the code that are honestly just a little too embarrassing to share. Perhaps I’ll clean it up and put it somewhere, but more likely not. It’s a tiny tool that does one job. This page (or feed!) that you’re reading was generated with it, at least originally, and if you’ve read this far then webgen has obviously worked well enough. Perhaps I could open source it under a ‘no feedback permitted’ license ;)

Baking unsigned 8bit vertex lighting in Blender 4

2024-02-17T00:00:00+10:00

Now this is some real niche material. I have been experimenting a little with Dreamcast era OpenGL again, and wanting to incorporate some lighting effects. Here’s a little unlit area from my prototype game ‘Dashy No Blast’

Here’s the textured mesh without any lighting, shown in Blender.

By adding some lights to the scene and switching to ‘Rendered’ view, we get something like this:

The goal is to now approximate this light and shadow by ‘baking’ the light to the vertex colour of the scene. We need to add vertex colour attributes to each mesh that we want to light.

Next, in the Render inspector tab, we configure Cycles to perform a Combined bake, using lighting and diffuse, with the output set to ‘Active Color Attribute’.

Then, by clicking ‘Bake’, the lighting will be calculated and baked to the vertex colours. To see this, we can configure viewport shading to colour the scene with ‘Attribute’, which shows the baked vertex lighting. Looks okay, but there is a hidden problem!

When creating the colour attributes, I used the ‘Color’ data type. For some reason, this type allows colour values outside of the normalised range 0.0 to 1.0. Note here in the Blender spreadsheet viewer that the selected vertex has a red value of 1.082.

This causes problems later - my pipeline converts these values to 8 bit unsigned ‘byte’ values, in the range 0 to 255, where an input value of 1.0 should result in an output of 255. An input of 1.082 results in an output of 20, because 1.082 * 255 = 275 point something, but an unsigned byte only holds a maximum value of 255 before it overflows back to zero. In practice this resulted in my illuminated orange window losing most of its red and looking like this:

So we recreate or convert the colour attribute data, using the ‘Byte Color’ instead of ‘Color’ data type

Reinspecting one of my problem green vertices in the spreadsheet view, we now see that the red value is back in the valid range as 1.0.

This results in a more orange window when displayed ingame, as desired.

One final note: the ambient light level can be adjusted from the World inspector’s ‘Surface’ dropdown. Remember to bake the light after changing this to see any difference.

Sketching

2024-02-07T00:00:00+10:00

Since buying a small wacom drawing tablet, I’ve been using it to draw (shock!). Primarily I’ve been preparing to create art assets for a games project: box and cover art, promotional materials etc. But for fun, and to try and improve my drawing skills to the point where I’m able to illustrate to an acceptable level, I’ve been sketching.

Here’s a ‘Tachikoma’ from the Ghost In The Shell series. It was a quick sketch (my go-to excuse for anything low quality). Composition issues aside, my main disappointment is the waviness of the lines. Drawing ‘smooth’ lines is quite difficult with the drawing tablet, and I’m sure it’s mostly a user problem, rather than poor hardware. There are software options to help smooth out lines as you draw them, but they add different disadvantages, such as making the pen ‘lag’ somewhat as the input is smoothed. Illustration of a pig

The problem is even more apparent here, especially on the Pig’s back. I wanted a continuous smooth curve, but after ten attempts or so I settled on this wonky attempt as ‘good enough’.

This illustration of my son is one of the first things I drew after receiving the tablet. Only now do I notice that the line quality is even worse than newer attempts, so perhaps I’m improving after all.

Finally for comparison, a sketch from just before receiving the drawing tablet, instead drawn using a mouse. Pretty rough lines even though I used line smoothing settings in Krita. It also took me much longer to draw than the sketches I’ve done with the tablet.

Configuring a wacom graphics drawing tablet under Hyprland

2023-11-15T00:00:00+10:00

I bought a second hand wacom tablet to try a different way of drawing, but the default configuration was not what I wanted. This is a log of how I configured it to work under the Hyprland window manager in Linux.

The hardware

The tablet I bought was a used CTH-480, but I imagine the process is similar for anything compatible with the linux wacom driver. This particular tablet works with both a stylus and finger ‘touch’ input, and can distinguish between these input methods. Also it’s a nice size for sitting between the two halves of my split keyboard.

Default configuration

If you’re using a single monitor, the tablet probably works fine without any additional configuration. Touching the top left of the tablet registers an input at the top left of the screen, and touching the bottom right of the tablet registers as the bottom right of the screen. However, if you have two or more monitors, then the tablet input will be scaled to match the total display space of your screens. So for me using a three monitor setup, the tablet input corresponded to three screens width, making any kind of precise control very difficult.

Trying an alternate driver: OpenTabletDriver

Briefly I experimented with an alternative to the wacom driver, OpenTabletDriver. This had the advantage of having a straightforward gui to configure the various options, but without a lot of extra configuration didn’t detect whether I was using the stylus drawing-tip or the style eraser. Plus it uses dotnet which felt like overkill for an option that didn’t automagically solve all my problems.

Configuring Hyprland

The Hyprland documentation lists some options for configuring tablet input peripherals. Instead, I want only the tablet stylus input to be mapped to a single screen, ignoring the extra space the other two provide. By setting the ‘output’ variable to the name of one of the monitors, the ‘output space’ of the tablet would be mapped to that display.

So first we identify the monitors

$ hyprctl monitors | grep Monitor
Monitor DP-3 (ID 0):
Monitor DVI-D-1 (ID 1):
Monitor HDMI-A-1 (ID 2):

Also the identifier for the tablet

$ hyprctl devices
Tablets:
    Tablet Pad at 544c238492d0 (belongs to 0 -> )
    Tablet at 544c40ffcea0:
        wacom-intuos-pt-s-pen

In my case HDMI-A-1 is the monitor I want to use for drawing, so we edit the Hyprland config file vim ~/.config/hypr/hyprland.conf, adding the following per-device input configuration:

device:wacom-intuos-pt-s-pen {
    output=HDMI-A-1
}

Edit 2025-05-07: Since I last configured Hyprland, the configuration format for devices seems to have changed. The device name is now a property of the device and the equivalent declaration is now:

device {
    name=wacom-intuos-pt-s-pen
    output=HDMI-A-1
}

This configuration takes effect immediately upon hyprland.conf being saved.

Setting up a Game Boy development environment on a Raspberry Pi

2023-03-22T00:00:00+10:00

This is a log of how I set up a Game Boy development environment on a raspberry pi. It’s not intended to teach you Z80 assembly, game development, or anything else.

Why

The Game Boy was a popular handheld gaming machine and there are many functional devices still in circulation, not to mention the legions of clones and emulators capable of playing the Game Boy library. Even modest hardware can emulate the Game Boy and gain access to thousands of games, many of which are still enjoyable even today. This results in an enduring audience of players and developers, so making the platform a viable target for publishing games to even in 2023.

Developing for the Game Boy possibly requires even less capable hardware than playing the games, but probably any device capable of viewing this blog post is vastly more powerful than is required to develop for this platform.

The hardware

I’m using a Raspberry Pi 4 with 8GB of RAM as my development machine, running ‘RaspberryPiOS’, which is Debian Linux. I’ll be deploying games to a real Game Boy via a cartridge writing system and compatible cartridges.

I also have a Game Boy Color to hand, and developing for either the colour or original monochrome Game Boy is largely an identical process. Both use a custom Z80 family microprocessor, and many Z80 assemblers can output compatible machine code.

Software

To make Game Boy games, the following is needed:

A text editor, to write the code,
An assembler, to convert Z80 assembly to machine instructions,
A graphics editor, to draw the visual elements of the game. This can be done on paper and bytecode manually calculated, but I’d rather have the computer do that for me.
An audio editor, for creating sound effects and music. Again this can be done manually but it’s a lot easier with some good tools.
An emulator to test the game, preferably with a good debugger.
Flashing software to write the games to a physical cartridge.

Text editor

You can use whatever editor you like, but I’m using vim. VSCODE (or its free and open source alternative ‘CODE’) are also great choices that I’ve experimented with. Z80 Syntax highlighting is probably available for many programming focused editors.

Assembler and toolchain

The RGBDS suite provides a complete toolchain for assembling Game Boy roms, as well as processing common formats of graphics files into something usable on the game console.

RGBDS isn’t available in the Debian aarch64 repositories, so I’m building it from source.

$ git clone https://github.com/gbdev/rgbds
$ cd rgbds
$ make
$ sudo make install

Graphics Editor

Aseprite or other popular modern pixel focused graphics editors can be made to work on a Raspberry Pi, but I’ve decided to go with Grafx2, a free and open source editor inspired by Deluxe Paint, which is the first ‘serious’ graphics program I ever used. Any tool that can work with indexed graphics formats (where the image file contains a limited palette that all pixels index into) should work.

Grafx2 is available in the Debian repositories, but I built from source for a more up to date version.

$ sudo apt install libsdl2-dev libsdl2-image-dev libsdl2-ttf-dev
$ git clone https://gitlab.com/GrafX2/grafX2
$ cd grafx2/src
$ make release API=sdl2
$ sudo make install API=sdl2

Audio Editor

In the past I’ve used the nice Carillion Game Boy music/sfx editor and driver, which is fun because you’re making the music and sfx on an actual game boy, so you get an accurate representation of how things will sound. It’s not the quickest workflow however, and I’m going to try hUGETracker for this setup, which will let me compose on the raspberry pi.

$ sudo apt install lazarus
$ git clone --recursive https://github.com/SuperDisk/hUGETracker
$ cd hUGETracker
$ lazbuild --add-package-link src/rackctls/RackCtlsPkg.lpk
$ lazbuild --add-package-link src/bgrabitmap/bgrabitmap/bgrabitmappack.lpk
$ ./setup-linux.sh
$ cd src
$ lazbuild hUGETracker.lpi --build-mode="Production Linux"

As of 2023-03-22 this threw some errors about DisabledFontColor being undefined in tracker.pas, so I commented out lines 1178 and 1188 in tracker.pas and rebuilt without issue.

hUGETracker will error out if you try and launch it without its expected collection of bundled files in the right places, so next download the x86 version and unzip it somewhere.

$ cd Downloads
$ wget https://github.com/SuperDisk/hUGETracker/releases/download/v1.0.0/hUGETracker-1.0.0-linux.zip
$ unzip -d hUGETracker hUGETracker-1.0.0-linux.zip

Finally copy our freshly built hUGETracker to the downloaded release, overwriting the incompatible x86 executable

$ cp ~/Src/External/hUGETracker/src/Release/hUGETracker ~/Downloads/hUGETracker/

Finally we can run our aarch64 hUGETracker build.

Emulator

I’m using Mesen2, which I set up previously for the Raspberry Pi previously for NES development

Building a test ROM

Now that we have the tools, let’s make some salad. Grab the GB standard definitions file and write your Game Boy code, this example borrowed from https://daid.github.io/rgbds-live

; Simple example to show how to load initial graphics data into VRAM.
; This is only applicable during initial start of your rom, as it disables the LCD
; to get full access to VRAM. This will make the screen white during this time.

INCLUDE "hardware.inc"

SECTION "graphics", ROM0
graphicTiles:
  ; Graphics data, below contains 3x the same 8x8 graphics tile in different formats.
  ; Prefered way would be to use INCBIN with rgbgfx, which is currently not possible in rgbds-live.
opt g.123
  dw `.111111.
  dw `11111111
  dw `1.111.11
  dw `1.111.11
  dw `11111111
  dw `1.1331.1
  dw `1..11..1
  dw `.111111.
.end:

SECTION "entry", ROM0[$100]
  jp start

SECTION "main", ROM0[$150]
start:
  call disableLCD
  call loadTiles
  call loadPalette
  call enableLCD

haltLoop:
  halt
  jp   haltLoop

disableLCD:
  ; Disable the LCD, needs to happen during VBlank, or else we damage hardware
.waitForVBlank:
  ld   a, [rLY]
  cp   144
  jr   c, .waitForVBlank

  xor  a
  ld   [rLCDC], a ; disable the LCD by writting zero to LCDC
  ret

loadPalette:
  ld   a, %11100100
  ld   [rBGP], a
  ret

; Load the graphics tiles into VRAM
loadTiles:
  ld   hl, graphicTiles
  ld   de, graphicTiles.end - graphicTiles  ; We set de to the amount of bytes to copy.
  ld   bc, _VRAM

.copyTilesLoop:
  ; Copy a byte from ROM to VRAM, and increase both hl, bc to the next location.
  ld   a, [hl+]
  ld   [bc], a
  inc  bc
  ; Decrease the amount of bytes we still need to copy and check if the amount left is zero.
  dec  de
  ld   a, d
  or   e
  jp   nz, .copyTilesLoop
  ret

enableLCD:
  ld   a, LCDCF_BGON | LCDCF_BG8000 | LCDCF_ON
  ldh  [rLCDC], a
  ret

We can then build a ROM

$ rgbasm main.asm -o main.o
$ rgblink -o game.gb main.o
$ rgbfix -v game.gb -p 0xff

And run it in an emulator for debugging!

Flashing the ROM to a cartridge

This will differ wildly depending on your flash hardware. Many ‘flash’ carts have an SD card slot or USB socket to allow you to easily copy files onto it - but I’m doing something slightly different and making a ‘one game’ cartridge using a dedicated cart flasher named ‘Joey Joebags’ by BennVenn, which comes with its own python application to interface with the flasher.

The cartridge is plugged into the flasher, which is in turn connected to the Raspberry Pi via a USB cable.

Such a tiny rom takes only a second or two to write to the cart, which can then be inserted into a Game Boy and played like any other game.

Effective Game Boy photography is left as an exercise for the reader.

Setting up a Dreamcast development environment on a Raspberry Pi

2023-03-17T00:00:00+10:00

This is a guide on one way of setting up a modern development system for the 1999 Dreamcast console. The easiest method for Windows users is probably DreamSDK, which provides a slick automated install of preconfigured tools to get you up and running quickly, but that’s not what I’ll be covering here.

The hardware

I’m using a Raspberry Pi 4 with 8GB of RAM, running ‘RaspberryPiOS’ (Debian) Linux, and a VA-0 Dreamcast equipped with a HIT-0400 Broadband Adapter.

Software

To make Dreamcasct software, the following is needed:

A cross compilation toolchain to convert the program code to machine instructions understood by the Dreamcast CPU,
KallistiOS, a library providing an interface to the various Dreamcast hardware components,
A text editor, to write the code,
Graphics editors
Audio editors
Optionally an emulator to test the software on the development machine, preferably with a good debugger.
dcload-ip - a tool that boots a real Dreamcast and allows for code to be deployed to it over the network, making it possible to test and debug software without writing each iteration to a cd-r.

Cross compilation toolchain

Unless you’re typing code directly into a Dreamcast, you probably need a cross-compilation toolchain that can produce machine code for the SH-4 ‘SuperH’ CPU that it uses.

KallistiOS provides a helper script to produce such a toolchain.

$ git clone https://github.com/KallistiOS/KallistiOS/ /opt/toolchains/dc/kos

Documentation is found in the KallistiOS/doc directory, though some aspects are out of date.

Building the toolchain:

$ apt install libc6-dev-sh4-cross gawk patch bzip2 tar make libgmp-dev libmpfr-dev libmpc-dev gettext wget libelf-dev \
texinfo bison flex sed git build-essential diffutils curl libjpeg-dev libpng-dev python3 pkg-config libisofs-dev meson ninja-build
$ cp doc/environ_sh.sample ./environ_sh
$ cd utils/dc-chain
$ cp config.mk.testing.sample config.mk
$ ./download.sh
*** Downloader Utility for Sega Dreamcast Toolchains Maker (dc-chain) ***
Downloading Binutils 2.40...
Downloading GCC 12.2.0...
Downloading Newlib 4.3.0.20230120...
Downloading GCC 8.4.0...
Downloading config.guess...
Done!
$ ./unpack.sh
*** Unpacker Utility for Sega Dreamcast Toolchains Maker (dc-chain) ***
Preparing unpacking...
Unpacking Binutils 2.40...
Unpacking GCC 12.2.0...
[...]
Done!
$ make -j5

Take a coffee break or three while this builds. On a raspberry pi 4 this took around five hours.

Next I want gdb for remote debugging support

$ make gdb

After a much shorter but not insignificant wait, the cross build toolchain is ready. Unneeded downloads can now be automatically deleted with $ ./cleanup.sh

KallistiOS

From the kos root dir (/opt/toolchains/dc/kos)

$ source environ_sh
$ make

Which results in lib/dreamcast/libkallisti.a

This is all we need to build Dreamcast executables, but more steps are needed to build them in a useful way that can be run directly on the console, and we’ll also want some libraries to do helpful things like load image files and render 3D environments.

Kos-Ports

Kos-Ports is a collection of libraries that might be useful, ported to KallistiOS

$ cd /opt/toolchains/dc
$ git clone https://github.com/KallistiOS/kos-ports

Each can be built by entering its subdirectory and performing a make install

GLdc

If you want to use OpenGL for writing Dreamcast graphical software like I do, you will probably want to remove the kos-ports libGL and replace it with the much newer GLdc

$ cd /opt/toolchains/dc/kos-ports
$ rm -rf libGL
$ git clone https://gitlab.com/simulant/GLdc
$ cd GLdc
$ mkdir dcbuild
$ cd dcbuild
$ cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_TOOLCHAIN_FILE=../toolchains/Dreamcast.cmake -G "Unix Makefiles" ..
$ make

The cmake invocation differs from the official guide at https://gitlab.com/simulant/GLdc in that it produces the higher performance release version. Omit -DCMAKE_BUILD_TYPE=Release if that’s not what you want.

Ready built environment

An archive of the environment built as described up to this point is available here. It’s only useful if you’re on aarch64 linux.

To be continued

Want to know how to actually use this environment to build a dreamcast game? Better remind me to write the followup article!

Developing NES games on Raspberry Pi

2023-03-04T00:00:00+10:00

This is a log of how I set up a NES development environment on a raspberry pi. It’s not intended to teach you 6502 assembly, game development, or anything else besides perhaps being an endurance workout for attention spans.

Why I did this
Hardware used
Software setup
Text editor
Graphics editor
Emulating x86 on aarch64 with box to allow non native apps to run
Audio editor
Emulator

Why

It has been a hot summer here in Queensland, Australia. My normal desktop computer only adds to the temperature, converting kilowatts into heat. I decided to see what I could achieve on a smaller, single-board computer as a way to reduce the amount of power used and heat produced, but also just to see how much of a retro videogame studio I could squeeze onto one single board computer.

The hardware

I’m using a Raspberry Pi 4 with 8GB of RAM. This is overkill for the NES setup described here, but is useful for other development work. Also it was the first model that became available, there’s a global shortage of single board computers at the time of writing.

Because this is going to be sitting on my desk, it needs a protective case. The bundle I bought came with an ‘Argon One’ case, which also upgrades the mini-hdmi ports to full size hdmi via a daughterboard that plugs into the Pi.

I also grabbed a USB switcher to let me share my mouse and keyboard between the Pi and my desktop, for personal laziness and to reduce wear on the Pi USB ports.

Operating system

Nothing unusual here, I installed the official 64bit version of ‘RasperryPi OS’, which is Debian with some tweaks specific for the Raspberry Pi. The entire OS is written to a 32GB microSD card that slots into the underside of the Raspi case, and runs directly from there. This is the weakest part of the setup: microSDs are generally much slower than ‘real’ harddrives, and are quite susceptible to corruption if the Raspi is powered down unexpectedly, during a powercut or a child flicking the power switch.

Aside from some slowness if trying to browse javascript or media heavy websites like instagram or youtube, the Pi with 64bit Debian is pretty snappy. By default it looks like this:

But after some fussing and deciding to try using a more graphical setup than usual, I have the subjectively more handsome setup below:

Software

To make NES games, the following is needed:
A text editor, to write the code, * An assembler, to convert 6502 assembly to machine instructions, * A graphics editor, to draw the visual elements of the game. This can be done on paper and bytecode manually calculated, but I’d rather have the computer do that for me.
An audio editor, for creating sound effects and music. Again this can be done manually but it’s a lot easier with some good tools. * An emulator to test the game, preferably with a good debugger.

Text editor

You can use whatever editor you like, but I’m using vim. VSCODE (or its free and open source alternative ‘CODE’) are also great choices that I’ve experimented with. 6502 Syntax highlighting is probably available for many programming focused editors.

Assembler

The cc65 suite does everything I want and is actively maintained. I’m not sure there’s a great deal of difference between the assemblers beyond some syntax differences. cc65 is available directly from the Debian repositories for aarch64 platform that the Raspberry Pi uses in 64bit mode, so no problems here.

Graphics Editor

This is where things start to get a little more tricky. It’s possible to use any art package, photoshop, aseprite, grafx2, even MS PAINT.EXE and run the output through a converter to NES CHR (character graphics) data, and this probably path I’d need to take if I were working with an artist unfamiliar with NES technical issues. But things change in the conversion process and you might not have as much control as you’d like, so we can make life easier by using a dedicated NES graphics editing tool. At the time of writing, frankengfx’s NEXXT is version 0.22.0 but already includes more functionality than I could need. It lets you draw and edit tiles, place those tiles into tilemaps (i.e to draw part of a level or a title screen), all while seeing how the graphics will actually appear on the NES when palette limitations apply.

The only problem is that is windows only. “But you can just run it through WINE!” I hear you cry. No child, it is not so simple. Wine is not an emulator, it can run windows applications outside of windows, but it can’t convert x86 to ARM aarch64. You could run aarch64 windows applications through wine (if any exist?), but not nexxt, which is a 32bit x86 app. So why am I talking about nexxt still? Well, it turns out that with some help wine can run nexxt.

Detour: installing wine with box64 and box86

Unlike wine, box64 and box86 are emulators. They can run x64 and x86 linux programs on non x86 linux systems, respectively. Following this guide carefully will result in a special wine configuration that can run nexxt and let us draw all the little NES pixels we like on a 64bit raspberry pi!

# Lifted directly from https://ptitseb.github.io/box86/X86WINE.html, best to check there for updates
# Backup any old wine installations
sudo mv ~/wine ~/wine-old
sudo mv ~/.wine ~/.wine-old
sudo mv /usr/local/bin/wine /usr/local/bin/wine-old
sudo mv /usr/local/bin/wineboot /usr/local/bin/wineboot-old
sudo mv /usr/local/bin/winecfg /usr/local/bin/winecfg-old
sudo mv /usr/local/bin/wineserver /usr/local/bin/wineserver-old
# Download, extract wine, and install wine (last I checked, the Twister OS FAQ page had Wine 5.13-devel)
wget https://twisteros.com/wine.tgz -O ~/wine.tgz
tar -xzvf ~/wine.tgz
rm ~/wine.tgz # clean up

# Install shortcuts (make launcher & symlinks. Credits: grayduck, Botspot)
echo -e '#!/bin/bash\nsetarch linux32 -L '"$HOME/wine/bin/wine "'"$#"' | \
sudo tee -a /usr/local/bin/wine >/dev/null # Create a script to launch wine programs as 32bit only
#sudo ln -s ~/wine/bin/wine /usr/local/bin/wine # You could aslo just make a symlink, but box86 only works for 32bit apps at the moment                                                                           
sudo ln -s ~/wine/bin/wineboot /usr/local/bin/wineboot
sudo ln -s ~/wine/bin/winecfg /usr/local/bin/winecfg
sudo ln -s ~/wine/bin/wineserver /usr/local/bin/wineserver
sudo chmod +x /usr/local/bin/wine /usr/local/bin/wineboot /usr/local/bin/winecfg /usr/local/bin/wineserver

# Boot wine (make fresh wineprefix in ~/.wine )
wine wineboot

Finally, nexxt can be launched via $ wine NEXXT.exe, and it will be emulated via box. Initial loading can take a few extra seconds, but performance during use is indistinguishable from running on native Windows.

Audio Editor

The sensible choice here is to run one of the various forks of famitracker. However, if you have read this far you will realise we are going to get the newest, shiniest Music and SFX tool for the NES, which is the amazing famistudio.

This is a mono app, which means that it can in theory run anywhere the mono runtime has been ported. Later on I’ll be using dotnet, which should really be able to run any given mono app, but it isn’t the case for the .net 4.x family of runtimes. I don’t know why either.

At the time of writing the stable Debian mono packages are too old to build Famistudio, so we follow the official mono guide to add their repository containing the newer mono builds.

sudo apt install apt-transport-https dirmngr gnupg ca-certificates
sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys 3FA7E0328081BFF6A14DA29AA6A19B38D3D831EF
echo "deb https://download.mono-project.com/repo/debian stable-buster main" | sudo tee /etc/apt/sources.list.d/mono-official-stable.list                                                                          
sudo apt update

$ apt install mono-complete now gets the newer mono tools installed. $ git clone https://github.com/BleuBleu/FamiStudio gets us the FamiStudio source.

FamiStudio needs a few native libraries to build and run successfully. Build scripts are included for some.

$ cd FamiStudio/ThirdParty/NesSndEmu; ./build_linux.sh; cd -
$ cd FamiStudio/ThirdParty/GifDec; ./build_linux.sh; cd -
$ cd FamiStudio/ThirdParty/NotSoFatso; ./build_linux.sh; cd -
$ cd FamiStudio/ThirdParty/ShineMp3; ./build_linux.sh; cd -
# apt install libvorbis-dev
$ cd FamiStudio/ThirdParty/Vorbis; ./build_linux.sh; cd -

Then build FamiStudio itself from the FamiStudio directory. $ msbuild /p:Configuration=Release FamiStudio.Linux.sln

Famistudio was built in FamiStudio/FamiStudio/bin/Release, but the bundled versions of some libs are x86-64 and not aarch64, e.g:

FamiStudio/FamiStudio/bin/Release $ file librtmidi.so
librtmidi.so: ELF 64-bit LSB shared object, x86-64, version 1 (GNU/Linux), dynamically linked, 
BuildID[sha1]=6f9fa5a932d45618f374da91dc71adbd1b85b3b9, not stripped

Install a good libglfw with # apt install libglfw3 and copy or link it to the FamiStudio Release dir cp /usr/lib/aarch64-linux-gnu/libglfw.so.3 ./libglfw.so

And OpenAL (already installed for me) cp /usr/lib/aarch64-linux-gnu/libopenal.so.1 libopenal32.so

FamiStudio should now run as expected. MIDI and ogg export will need the respective libraries fixed first though if needed.

$ mono FamiStudio.exe

Unfortunately the demo songs aren’t included in the source release but can easily be grabbed from one of the zipped binary distributions on the FamiStudio website.

Emulator

The final hurdle is an emulator with a good debugger. For a recent 48 hour gamejam I used fceux, a working build of which can be installed from the Debian repository easily with # apt install fceux. However, for the latest in cutting edge NES technology, we can install Sour’s Mesen2, which has some amazing debugging features. It’s also not supported on aarch64, but it’s another dotnet app, so we can just run it via mono right?

So instead it’s time to install dotnet. I went directly to the source and installed the Microsoft Spyware from https://dot.net/v1/dotnet-install.sh.

I had trouble piping it directly into bash from curl, so I downloaded via wget $ wget https://dot.net/v1/dotnet-install.sh And then installed both the SDK $ ./dotnet-install.sh --version latest and the runtime $ ./dotnet-install.sh --version latest --runtime aspnetcore Add dotnet to the PATH $ vim ~/.profile

...

# set PATH so it includes dotnet
if [ -d "$HOME/.dotnet" ] ; then
    PATH="$HOME/.dotnet:$PATH"
fi
#Ask dotnet not to phone-home to the MS MotherShip
export DOTNET_CLI_TELEMETRY_OPTOUT=1

Mesen isn’t purely dotnet, it also has native C++ that requires C++17 support. Clang is recommended, the default gcc provided by Debian doesn’t work.
# apt install clang-13 Set clang 13 as default clang. There’s probably a proper Debian way to do this.

ln -s /usr/bin/clang-13 /usr/bin/clang
ln -s /usr/bin/clang++-13 /usr/bin/clang++
ln -s /usr/bin/clang-cpp-13 /usr/bin/clang-cpp

Clone Mesen2 source. $ git clone https://github.com/SourMesen/Mesen2 (As of 2023 March 4, Mesen2 is on commit 88c0c76. It’s possible the following changes won’t always be necessary).
Edit the makefile $ vim Mesen2/makefile Add at line 52

ifeq ($(MACHINE),aarch64)
       MESENPLATFORM := $(MESENOS)-arm64
endif

nd around line 142 change from

      cd UI && dotnet publish -c Release -r $(MESENPLATFORM) -p:OptimizeUi="true" --no-self-contained true -p:PublishSingleFile=true
      cd UI && dotnet publish -c Release -r $(MESENPLATFORM) -p:OptimizeUi="true" --no-self-contained true -p:PublishSingleFile=true

      cd UI && dotnet publish -c Release -r $(MESENPLATFORM) -p:OptimizeUi="true" --self-contained -p:PublishSingleFile=true
      cd UI && dotnet publish -c Release -r $(MESENPLATFORM) -p:OptimizeUi="true" --self-contained -p:PublishSingleFile=true

Finally we need to make sure the UI is built for linux-arm64.
$ vim UI/UI.csproj Change line 18 from

<PropertyGroup Condition="'$(RuntimeIdentifier)'=='osx-x64' Or '$(RuntimeIdentifier)'=='osx-arm64' Or '$(RuntimeIdentifier)'=='linux-x64'">

<PropertyGroup Condition="'$(RuntimeIdentifier)'=='osx-x64' Or '$(RuntimeIdentifier)'=='osx-arm64' Or '$(RuntimeIdentifier)'=='linux-arm64'">

and 545 from

<Target Name="PreBuildLinux" BeforeTargets="PreBuildEvent" Condition="'$(RuntimeIdentifier)'=='linux-x64'">

<Target Name="PreBuildLinux" BeforeTargets="PreBuildEvent" Condition="'$(RuntimeIdentifier)'=='linux-arm64'">

The build process can then be launched from the Mesen2 root directory with $ make, resulting in a standalone executable hidden at bin/linux-arm64/Release/linux-arm64/publish/Mesen. On the first launch Mesen seemed to take a while to cache the icons used in the menus and was frozen for at least 20 seconds. But since then it has ran without problems.

What a trek! I feel like a fish that had to climb a long and difficult series of platforms, all the while trying not to run out of oxygen, but now we have a full NES development studio on a Raspberry PI! Hopefully this will serve as a useful reference to me and perhaps even someone else someday. Thanks!