Back to the Future: Part III – Color Fix Patch

2 Replies
Title Screen – Before and After

An exchange on Twitter led me into a trap that consumed a week of my time – the Sega Genesis / Mega Drive version of Back to the Future: Part III shipped with a bug that caused completely wrong colors to display. Evidently the programmer(s) were confused about the proper format of color data on the Genesis. While color values should be stored in two bytes as 0000bbb0 ggg0rrr0, this game instead uses the incorrect format 00000bbb 0ggg0rrr – all values shifted right by one bit. The end result is that the game displays at half brightness, and lower contrast.

I naively assumed this would be a simple fix: in fact, some prior discussion pointed out that color tables are stored plainly in the file, and even provided addresses to fix some of them. Of course, things are never as easy as they seem. Using a hex editor I changed some color palettes, then used the BlastEm emulator (its debugger is okay) to test, and made two discoveries:

  • the list in the forum post is incomplete, and I needed to do further digging to uncover the rest of the palettes, and
  • even with the palettes fixed, colors still didn’t display correctly. Any code that sets the palette (e.g. when fading to/from black) still used the old, wrong format. So while the data was correct, it still displayed wrong.

At this point I decided to see how Ghidra would fare on 68000 code. With the help from some scripts from zznop (to parse Genesis ROM headers, and to generate a new checksum after modification), I spent a couple days working at a disassembly of the ROM. Ghidra works well for this, but it has some quirks: it does not properly handle 24-bit addresses, it sometimes needs a kick with the “disassemble” key to force it to parse a block of obvious code, and the “address table” checkbox on Auto-Analysis causes far more pain than benefit – don’t use that!

Despite the nice color improvements, this stage is still way too hard!

In the end I produced a disassembly that was quite revealing. The game doesn’t have a lot of code re-use, it was apparently written in isolated stages and then combined together at the end. Functions for palette fades and “cutscene” display are duplicated in each segment. Finding palette setting code wasn’t too difficult once a palette were found, and usually looked something like this (taken from a “Fade To Palette” routine):

...
                         LAB_0000a264
    0000a264 3c 11           move.w     (A1),D6w
    0000a266 02 46 0f 00     andi.w     #0x700,D6w
    0000a26a 36 12           move.w     (A2)=>targetPalette64,D3w
    0000a26c 02 43 0f 00     andi.w     #0x700,D3w
    0000a270 b6 46           cmp.w      D6w,D3w
    0000a272 64 00 00 06     bcc.w      LAB_0000a27a
    0000a276 06 43 01 00     addi.w     #0x100,D3w
                         LAB_0000a27a
    0000a27a 3c 11           move.w     (A1),D6w
    0000a27c 02 46 00 f0     andi.w     #0x70,D6w
    0000a280 38 12           move.w     (A2)=>targetPalette64,D4w
    0000a282 02 44 00 f0     andi.w     #0x70,D4w
    0000a286 b8 46           cmp.w      D6w,D4w
    0000a288 64 00 00 06     bcc.w      LAB_0000a290
    0000a28c 06 44 00 10     addi.w     #0x10,D4w
                         LAB_0000a290
    0000a290 3c 11           move.w     (A1),D6w
    0000a292 02 46 00 0f     andi.w     #0x7,D6w
    0000a296 3a 12           move.w     (A2)=>targetPalette64,D5w
    0000a298 02 45 00 0f     andi.w     #0x7,D5w
    0000a29c ba 46           cmp.w      D6w,D5w
    0000a29e 64 00 00 04     bcc.w      LAB_0000a2a4
    0000a2a2 52 45           addq.w     #0x1,D5w
                         LAB_0000a2a4
    0000a2a4 86 44           or.w       D4w,D3w
    0000a2a6 86 45           or.w       D5w,D3w
    0000a2a8 3c 19           move.w     (A1)+,D6w
    0000a2aa 02 46 0f ff     andi.w     #0x777,D6w
    0000a2ae bc 43           cmp.w      D3w,D6w
    0000a2b0 66 00 00 04     bne.w      LAB_0000a2b6
    0000a2b4 52 41           addq.w     #0x1,D1w
                         LAB_0000a2b6
    0000a2b6 33 c3 00        move.w     D3w,(VDP_DATA).l
             c0 00 00
...

A bit hard to see maybe, but the important parts are that it’s processing the values in B, G, R order, by using “(component) and 0111“, and incrementing if less than the desired value. This is the wrong bitmask. Changing to 1111 (i.e. 0x7 to 0xf) allows fading through the full gamut, and everything now displays as intended. I was also able to reference the SEGA logo (at game boot), which DOES have proper colors, to double-check that I had this implemented correctly.

Finding the other places in the code where this happens is pretty trivial. A search for 0x0777 or andi.w 0x07 reveals the rest. With that fixed, I regenerated the checksum and wrote a new ROM, then used LunarIPS to make an IPS patch for distributing the fix.

The last step was to port the changes to the EU version of the game. Fortunately, the data is the same, and a Perl script with find-replace made locating the offsets easy. A new IPS patch, a README file, and we’re ready to ship.

Download the patch:

BttF 3 – Color Fix (ZIP file containing US / EU IPS patches)Download (4kb)

All told, this was actually a fun rabbit hole to get lost in, and I did pick up a lot about Ghidra and 68000 assembly that I had been wanting to learn anyway. If only it didn’t come right in the middle of NaNoGenMo… 🙂

Doc! …Your hat!

WebService::Discord::Webhook

Leave a reply

My first Perl CPAN module is online! It’s a class to help interact with Webhook objects provided by the Discord chat service.

https://metacpan.org/pod/WebService::Discord::Webhook

Webhooks are basically a “write-only” way to put a message into the chat from your external service. Use them to provide notifications in chat, where a full-blown “bot” client is not needed (e.g. no need to interact with users).

Modest Bricks

1 Reply
Modest Bricks gameplay video

Modest Bricks is a Tetris clone. Originally written in 2005, it uses SDL 1.2 and the SDL_Mixer library for sound effects and music. This was one of the first “serious” games I wrote – though I did a number of QBasic and Visual Basic things before, I had never attempted a game in C, or with this level of polish. I wrote this for a few reasons:

  • Learn SDL and practice game dev in C, tools used (at the time) by Professionals to make Real Games
  • Make the source available so I could teach and demonstrate SDL to the University of Arkansas Game Development Club, a group I helped co-found around the same time.
  • Follow the advice of this GameDev.net tutorial, “How do I make games?” which recommended to start small by creating a polished version of Tetris to get the basics down and have something to show.
  • Put my music into a game!

Recently I took an interest in revamping some old code, and ended up rewriting much of this. The effort is complete so I’m releasing it. A Windows version is included in the .zip below, as well as the source code in C. Recompiling on *nix should be easy: cc `sdl-config --libs --config` -lSDL_Mixer -o modest main.c should be reasonably close, assuming SDL and SDL_Mixer development libraries installed.

Probably the most interesting thing about this game is that after writing, I pushed it to the SDL webpage, which (at the time) had a gallery for people to post their games Made With SDL. From there it caught the attention of a Dreamcast homebrew developer Ian Micheal, who was porting SDL games to the DC. He altered the graphics and added more sounds and cool effects to create “Ghouls ‘N TriX” – a Tetris game for the Dreamcast! It was really cool to know my code was running on a video games console, and I made sure alllll my friends knew about it 🙂

Download the game:

Modest Bricks – Windows releaseDownload (243kb)
Modest Bricks – OSX 10.5 Intel releaseDownload (496kb)

BBCode Parser (in PHP)

Leave a reply

For a while now I’ve been working on a little blog engine in PHP. As part of the post rendering, I’ve settled on BBCode to do all markup and layout.

This meant I would need a BBCode parser. So, I started writing one. And because my projects always go this way, I ended up sinking more time into the BBCode parser than the blog engine itself – trying to get every weird corner case and not produce malformed HTML on output. The primary goals were:

  • Easy to use (one file with one function)
  • Correct (Unicode safe, always-valid HTML, reasonable fallbacks)
  • Easy to understand (avoid massive regexes)

Eventually, I ended up just splitting this piece off into its own project, since it may be useful beyond just my tiny blog.

https://github.com/greg-kennedy/php-bbcode

I know there are a million BBCode parsers out there (and even a PHP extension to do it), some extensible and so on. This one is mine. Would love pull requests.

Writing a WebSocket Client in Perl 5

7 Replies

WebSockets are the latest way to provide bi-directional data transfer for HTTP applications. They replace outdated workarounds like AJAX, repeated polling, Comet, etc. WebSockets are a special protocol atop HTTP (which in itself runs over TCP/IP), and can be wrapped in SSL for security (as in HTTPS). Being a Web Technology, it seems to have been developed by the JavaScript people exclusively for the JavaScript people – working with it outside a web browser or Node.js server can seem convoluted. But that’s the world they built, and we just we live in it.

Basic Perl support / documentation for WebSockets was difficult for me to find. The Mojolicious framework (specifically the UserAgent module) has native WebSockets support and can act as a client, but I was looking for info on using with WebSockets on a lower level / without Mojo or other frameworks. Hopefully, this post can shed some light on how you can use Perl to connect to a remote server using WebSockets, and get access to those sweet real-time services using our favorite language.

First off, if you can, you should just use AnyEvent::WebSocket::Client or Net::Async::WebSocket::Client (depending on your preference of async framework). This package has already done the hard work of combining the two packages you’d probably use anyway, Protocol::WebSocket::Client (for encoding / decoding WebSocket frames), and AnyEvent (for cross-platform non-blocking I/O and doing all the messy TCP socket stuff for you). Having already established my status as a Luddite a desire to know what’s really going on, let’s try to reinvent the wheel and write our own client.

A Client for the Echo Test Service

The goal of this project is to interoperate with the WebSocket Echo Server at ws://echo.websocket.org. The Echo Server simply listens to any messages sent to it, and returns the same message to the caller. This is enough to build a simple client that we can then customize for other services. There are two things we need to make this work:

  • a plain Internet Socket, for managing the TCP connection to the remote server, and
  • a Protocol handler, for encoding / decoding data in the WebSocket format.

The second part of this is already done for us by Protocol::WebSocket::Client: given a stream of bytes, it can identify WebSocket frames and parse them into data from the server, and it can take data from our program and encapsulate it for sending. This tripped me up at first, so pay attention: Protocol::WebSocket does NOT actually do anything with the TCP socket itself – meaning it does not send or receive any data on its own! The class is responsible for only these things: packing/unpacking data, generating a properly formatted handshake for initiating a WebSocket connection, and sending a “close” message to the server signalling intent to disconnect.

Given that Protocol::WebSocket::Client doesn’t do any TCP socket stuff itself, we have to manage all that. Fortunately, there’s the core module IO::Socket::INET which we can use. Protocol::WebSocket::Client also provides some hooks for points in the WebSocket flow, so that we can insert our own handlers at those points. Let’s get started with some code.

Continue reading →