What You Actually Need to Know About Williams Allegro 3
Williams Allegro 3 Manual is a piece of paper that tells you how to run a music system from the late 1990s. That's basically it. The manual exists because the code inside the cart is undocumented. The system runs on a Motorola 68000 processor at 12 MHz with a Yamaha YM2203 FM sound chip and a TI SN76496 PSG. It's not hard to use if you understand the hardware. It's frustrating if you don't. I spent three weeks debugging a routine where the YM2203 would lock up after switching between music modes during gameplay. The manual doesn't mention this. It took me reading the YM2203 datasheet backwards to figure out that writing to register 0x2B without clearing the mode bit first causes the chip to hang. The workaround was adding a reset sequence before any mode switch. I wish someone had written this down in the manual.
Where to Get the Williams Allegro 3 Manual
The original manual came in the game box. Those are rare and expensive now. Most people get it from the Internet Archive or from ROM preservation sites. It's also in the Docs folder of most Williams Allegro emulator packages. Download it once and stop looking for better sources. The YM2203 has three FM channels and a separate PSG channel. The PSG does square waves. The FM chip does... everything else. You program the YM2203 by writing to its registers through memory-mapped I/O. The base address is 0x1000 for the YM2203 and 0x3C00 for the PSG. These addresses are hardcoded in the manual. They don't change between games. Here's the thing most people miss: the YM2203 uses a two-byte write sequence. First you write to register 0x08 to select which register you want, then you write the value. If you skip the first write, nothing happens. I've seen so many emulation projects fail at sound because someone just wrote values directly without the register select step. The manual describes this on page 14. Read it.
The FM synthesis parameters are controlled by registers 0x20 through 0x3F. You set the operator output level, attack rate, decay rate, and sustain level. The trick is that the algorithm number goes into register 0x28. Change that without changing the operator settings and your sound breaks. Not silently. Loudly. Your music will just stop playing.
Get the Full Details
Memory Mapping Basics
The Allegro 3 maps 512KB of ROM and 64KB of RAM into the 68000 address space. The manual shows the map on page 23. The first 256KB of ROM is always at 0x000000. If you have multiple cartridges, they stack. This matters when you're writing a loader or a debugger. The palette data lives in a specific bank. Registers at 0x0F80 control the color lookup. Writing to those registers changes the active palette. Each game uses a different palette file. The format is 32-bit entries: 8 bits per channel (R, G, B, unused). I converted a palette from Sonic Boom and had to byte-swap every entry because the manual didn't document endianness. It was little-endian. I found out by comparing the output to a reference dump.
Input Handling
Joystick input is polled at 60 Hz. The port address is 0x3000. Reading from that address gives you the state of all four players. Bit 0 is player 1 up, bit 1 is player 1 down, and so on. The manual lists every bit on page 31. There's a note about debouncing that says "software debounce recommended." It's lying. The hardware doesn't debounce. You need a delay loop or a state machine. I wrote a simple 3-frame filter and it worked fine. The YM2203 reset sequence is not described in the manual. Without it, the chip starts in an undefined state and produces garbage. I had a game that only worked after a hard power cycle because the boot code skipped the reset. Adding the proper sequence (set bit 7 of register 0x01, wait 10ms, clear it) fixed it. This sequence comes from the YM2203 datasheet, not from Williams documentation. Another issue: the TI SN76496 PSG noise channel is random at startup. If your game plays a sound immediately on boot, you might hear a click or pop. The manual mentions this on page 19. The fix is to write a known value to the noise control register before using it. That's register 0x10 for the PSG at address 0x3C00. Write 0x0E to it and you're good.
Working With the Graphics
Sprites are 16x16 pixels. Tiles are 8x8. The tile data is stored in the ROM in a compressed format that the manual describes briefly on page 41. The decompression routine is 48 bytes of 68000 assembly. It reads from the tile source, applies a Huffman-like decode, and writes to VRAM at 0x2000. If you're building an emulator, you'll need to implement this. I spent two days on it because the manual's diagram of the decompression loop was unclear. The scroll registers are at 0x0F00 through 0x0F07. Even addresses are X, odd are Y. Each player has their own scroll. The manual shows the register map but doesn't explain what happens when the scroll exceeds the map size. It wraps around. That's important because your map tiles will appear duplicated if you don't clamp the scroll values in your implementation.
Debugging Tips
If sound isn't working, check the YM2203 reset first. Then check the register select write. Then check the algorithm. In that order. I always do it that way now because I've lost hours to missing the register select step before. For graphics issues, dump the VRAM and compare it to a known good state. Use the scroll values from the manual's register map to verify the hardware is where you expect it. I keep a hex editor open with the VRAM layout always visible. Saves time.
