25 years to a complete machine

Mon, 04 May 2026 00:08:13 +0200

Since around the year 2000 I have been piling features into a French Final Fantasy IV translation patch. Variable-width fonts in dialog, in battle messages, in menu descriptions. Redrawn battle, load/save, main, and two-column magic menus. An expanded inventory of 0x48 slots rendered through a paged window instead of the static grid the original engine assumed. Most of these were features the SNES ROM hacking scene of the era said could not be done on real hardware. Other hackers eventually pulled off equivalents on other titles, fair enough; modifying a compiled ROM is more convoluted than editing source code, but not impossible. Twenty-five years on, “impossible” reads as a fair approximation of how hard, not of whether.

The bugs that come with hard features are also recent, introduced by my own patches. The field-menu item list eventually crashed: open inventory, swap items around, and after enough operations the stack pointer drifted until the next interrupt landed on a brk¹ instruction and the emulator stopped cold.

The cause was one wrong return mnemonic². swap_redraw_trampoline lives in bank $01³. Its real body, swap_redraw_hook_impl, lives in bank $21. The field menu calls the trampoline with jsr.l⁴, which pushes a 24-bit return. The bank-$21 body returns via rtl, which is correct. The trampoline itself ended in rts, which is not. One byte of the long-return address stayed on the stack every time an item was swapped. Run the swap path enough times and the underflow cascaded, the next NMI⁵ hit garbage, and the BRK trap I had wired into the vector table⁶ caught the offending PC.

The fix is one mnemonic. Getting to the point where I could see the wrong mnemonic took infrastructure.

Why a rolling inventory at all

The rolling inventory was not strictly necessary. Two columns of items were getting tight on screen as the inventory grew, and I knew FF6 had solved a similar layout problem more elegantly with a paged renderer. FF4 and FF6 share engine roots, which made porting the technique tractable instead of ground-up work. So I lifted the approach.

The memory side effect is real but secondary. The rolling render only keeps the visible slice in RAM and VRAM⁷, paging new ones in as the cursor scrolls. 0x48 slots at roughly 0x40 bytes of tile data each would have cost 0x48 * 0x40 = 0x1200 bytes per buffer in a static layout. The rolling layout drops that to one window’s worth. If saving memory had been the only goal there were cheaper fixes than this one.

The bug above was the price of pulling FF6 ergonomics into FF4: the trampoline that moves tile data between RAM and VRAM forgot to return with the right mnemonic, leaked one byte per swap, and the stack caught up with the player when they were having too much fun rearranging.

What made the bug reachable

For most of the 25 years I have been doing this, I would not have caught it.

The original ff4 source, like every long-running ROM hack, was a single textual .include chain compiled in one pass. Every label was global. There were no module boundaries. There was no way to ask the assembler “where does this symbol come from” except by grepping the file system. The trampoline-with-the-wrong-rts looked exactly like the trampoline-with-the-right-rtl two screens up. Lost in the noise.

The ff4 source recently finished its migration to a816’s .import system. Each module declares its own externs, compiles to its own .o, links through relocations. The LSP earns its keep on top of that. When you suspect swap_redraw_trampoline ends in rts where it should end in rtl, you do not grep for “swap_redraw” across hundreds of files. You click. The symbol resolves through the import graph, the trampoline opens in the right module, and the wrong mnemonic is on the screen.

Without modules the bug was unreachable. Without the BRK trap in the vector table the symptom was “crashes sometimes” instead of a PC value. The rest of the chain (LSP for navigation, kintsuki for deterministic reproduction) only mattered once those two existed.

Why these tools exist

I have been hacking on Final Fantasy IV, on and off, since around the year 2000. The earliest public trace is the ff4fr repo from 2011, itself a snapshot of older work. The reason the project keeps surviving long gaps is simple: it interests me. I come back, I poke at it for a few weekends, I drift, I come back. A hobby that happened to last.

None of the tools were built as long-game preparation for the rolling inventory bug.

a816 replaced x816.exe, the DOS assembler the FF4 scene had used for years. x816 is painful on Windows, dead on Linux and macOS. Building the ROM on GitHub Actions through dosbox was not going to happen. asar exists and is a fine alternative (and may not have been around when I started; I do not remember the timeline clearly). I went my own way because I wanted tight integration with the ff4 source: modules I controlled, a formatter I could shape, an LSP that understood bank annotations and docstring conventions, an object format that handled multi-region modules cleanly. Easier to build that end-to-end than to lobby someone else’s project for ergonomics specific to one ROM hack. The GitHub Actions side became its own win. Messing with workflows on a personal repo translated directly into knowledge I now apply at work.

kintsuki exists because I like automated tests. Running the ROM deterministically against pinned inputs needs primitives ares does not expose by default: mid-frame yield, PC override across scheduler entries, stp and wai flag preservation through external state-set. kintsuki adds the shim around the ares core and ships it as a Python wheel.

The honest reason underneath both: knowing enough to be dangerous has been the constant of my career. At fifteen, in 2000, I was dangerous with a hex editor and someone else’s assembler. That was already enough to start a translation patch. The version writing now is dangerous with a homemade assembler, an LSP, an emulator harness wrapped as a Python wheel, and a multi-region object format. The disposition has not moved. The capability has. Every year of doing software for a living added new ways of being dangerous, and the FF4 patch is the one personal project that stuck around long enough to absorb all of them. The tools and the patch grew up together. The features the fifteen-year-old wanted are now sitting on infrastructure he could not have built, but would absolutely have used.

The thing actually pacing the work right now is a self-imposed release date: December 26, 2026, for a packaged build of the patch. That deadline turned the loose interest into a backlog. The deadline is recent. The hobby is old.

Seven and a bit months until the release date. The patch will ship with bugs that came after it on top of an assembler and a harness that came before. The ROM hack will still have open issues, untranslated NPCs, and design decisions I will second-guess. None of that bothers me. It is the project I keep coming back to because it keeps being interesting, and right now the interesting thing is finishing it.

Not everything I write is meant to stick it up to the man. This one is not. Hobby code, on a console nobody ships for, against a deadline I made up because I felt like one. No thesis. A release on December 26.

brk is a one-byte instruction that triggers a software interrupt. The CPU pushes its state and jumps to a fixed handler address. Useful as a trap when that handler is wired to halt the emulator on an unexpected fall-through. ↩︎
A mnemonic is the short text name for a CPU instruction (rts, jsr, lda). The assembler turns each one into the matching machine-code byte. ↩︎
The 65C816 addresses 24-bit memory split into 256 banks of 64KB. $01:FF34 reads “address $FF34 in bank $01”. Code in different banks is reached with long-call instructions instead of short ones. ↩︎
jsr.l is a long jump to subroutine: it pushes a 24-bit return address (bank + 16-bit) before jumping. The matching return is rtl. The short pair is jsr + rts (16-bit return). Mismatching them leaks or eats bytes off the stack. ↩︎
Non-maskable interrupt. On the SNES it fires once per video frame, in the brief moment when the screen is between drawing two frames, and runs whatever handler the CPU is told to run for it. ↩︎
The vector table is a fixed block at $00FFE0-$00FFFF listing handler addresses for reset, NMI, BRK, and others. Wiring a BRK trap means setting the BRK handler to halt the emulator and record where the bad instruction came from, so an unexpected brk produces a debuggable crash instead of silent corruption. ↩︎
The SNES CPU’s main RAM is 128KB. VRAM is the graphics chip’s video RAM (64KB), holding the tile data and the screen layout. Anything visible has to be in VRAM. Tile data is usually staged in main RAM and copied across in bulk between two drawn frames. ↩︎

A816 on Man-You

25 years to a complete machine

Why a rolling inventory at all

What made the bug reachable

Why these tools exist