Let me be precise. I always knew it could be done. Two Turing-complete machines can, in theory, run each other’s code. You can always translate a program from one architecture to another. The problem was never possibility, it was cost. The NES runs a 6502, the Master System runs a Z80, and over the years I read in several places that a direct 6502-to-Z80 translation always ended up running much slower, because of the architecture and hardware differences. Slow enough to never pay off in practice.

And that memory has a basis. If you dig into retro-dev forums, like NESdev, the consensus is that translating instruction by instruction is exactly the worst path: “each instruction in the source code becomes multiple instructions of object code, and the resulting program runs much slower and takes much more memory.” It’s not just the CPU. The 6502 has the zero page, a dirt-cheap addressing mode the Z80 has no equivalent for, so you trade a cheap access for an expensive sequence with IX/IY. And the graphics part is even worse: the NES PPU and the Master System VDP are different beasts, with scroll, sprites, and screen mirroring that don’t fit into each other without expensive workarounds.

In other words, everyone who ever thought about this reached the same conclusion: it can be done, but it runs too badly to be worth it.

Except now we have frontier LLMs. And I got curious: could a brute-force approach, with a good LLM in the middle of the process, get a better result than the usual naive translation? I started the nes-to-sms project in late May, about three months ago, to find out.

The first result was exactly what the theory predicted: bad. A more or less direct translation generated code that runs, but way too slow. I managed to convert the entire Super Mario Bros, with sprites, levels, everything, but to make it minimally playable I had to run the Mednafen emulator at 500% overclock. After banging my head against Claude, GPT, and other models for a while, I got stuck. I worked hard through June and July, and in August I paused the project to let the dust settle.

Why the Master System, and not the NES?

Before explaining the technical part, I need to explain the obsession, because it is the reason for everything.

I always thought the Master System was a superior console to the NES. Better CPU, better video chip, a much richer color palette. The NES works with 4 colors per background tile and 3 per sprite. The Master System works with 16-color palettes. That is a huge difference in practice.

The problem is that Nintendo had a brutal monopoly back then and would not let third parties release for other consoles. Anyone who wanted to make a game for the NES signed an exclusivity contract. The result is that the Master System, technically better, ended up starved of games. Basically only Sega itself released for it, and Sega’s library never had the weight of a Castlevania, a Mega Man, a Final Fantasy.

Imagine what we lost. We could have had those same NES classics, but with the Master System’s superior capability underneath. A Castlevania with more color, better sprites, better sound. We never had that, and it is exactly this historical frustration that made me want to convert NES to SMS in the first place.

The port that proved the thesis

While my project was paused, another developer, lackoftrack27, published a Super Mario Bros port for the Master System that is on another level. It runs at full speed, 60fps, and on top of that with improved sprite art that takes advantage of the console’s superior palette. It ended up looking more like the Super Mario All-Stars remaster from the Super Nintendo than the somewhat crude original NES version. The retro community was in awe.

That proved my thesis in practice: the Master System is capable of running superior versions of NES games. It always was.

Now, two honest points about this port, because they matter for the rest of the story.

First: lackoftrack27’s work is a hand reimplementation, built from the game’s disassembly, optimized specifically for Super Mario. It’s not a general-purpose automatic translation like the one I’m trying to do. He solved one game, beautifully, by hand. Curiously, that reinforces what the forums already said: the path that works is reimplementing by hand, not machine-translating.

Second: as impressive as it is to see Super Mario on the Master System, it’s worth remembering it is still a first-generation game, around 40kb. Meaning it is one of the simpler games on the NES. Later-generation stuff, like Super Mario Bros 3 or Kirby, nobody has tried to convert yet, and for good reasons I explain further down.

But the most important thing was the side effect: with the map his port gave me, I finally got my automatic conversion running properly. I came back to the project in early September, loaded lackoftrack27’s code into Claude Fable and then the new GPT Astra, and put both of them to study what he did that I wasn’t doing.

The architecture of the solution

Since this article is for programmers, let me open the black box.

The first important decision is that nes-to-sms is not an emulator, nor a text-to-text translator of 6502 to Z80. It is a static recompiler. It reads the NES ROM, lifts the 6502 code into an intermediate representation with explicit semantics, and from that IR it generates Z80 code. The output is a WLA-DX assembly project that compiles into a real .sms ROM. The core is a Rust workspace with thirteen crates, plus a hand-written Z80 runtime shared across games.

The flow, end to end, goes roughly like this:

1. Parse the ROM header, split the code banks (PRG) from the tile banks (CHR), and read the reset and interrupt vectors.
2. Load a per-game profile (a TOML with labels, data regions, jump tables, mapper type, and replacements).
3. Discover the functions, build the control-flow graph, and classify every byte as code or data. A key detail enters here: every memory access is tagged with the region it belongs to (zero page, stack, RAM, PPU registers, sprite DMA, sound, mapper).
4. Lift each routine into IR, with the 6502 flags explicit. A write to the PPU register $2006 doesn’t become just some mem[]=, it becomes a first-class “PPU write” primitive.
5. Lower the IR to Z80. The 6502 flags are kept in a shadow status byte in RAM, and every hardware access becomes a call into the runtime.
6. Emit the Z80 bytes and also the readable WLA-DX assembly.
7. Convert the assets: the NES 2bpp tiles become SMS mode-4 4bpp tiles, the NES palette becomes SMS CRAM, and so on.
8. Write the whole SMS project, with a Makefile, runtime, and data, ready to compile.

The CPU mapping is conservative on purpose. The 6502 accumulator A becomes the Z80 A, the X and Y registers live in RAM or registers, the zero page becomes a fixed block in SMS RAM, and every operation that touches a flag calls a helper. It’s safe and correct, but this is exactly where the cost lives.

Where NES and SMS really diverge

The project’s central finding is about speed, and it’s counterintuitive.

The NES 6502 runs at 1.79 MHz. The Master System Z80 runs at 3.58 MHz, double the clock. You look at that and think “so there’s plenty of headroom.” Except no. The Z80 spends on average about 13 cycles per instruction, while the 6502 spends about 4. In real numbers, a 3.5 MHz Z80 is roughly equivalent to a 1 MHz 6502 for general work. Meaning the SMS Z80 is actually slower than the NES 6502 for the same work. The headroom is negative.

Worse: the cheapest 6502 idiom, an LDA table,X, is one of the most expensive to emulate on the Z80. So a faithful translation of a game that already squeezed the NES to the limit simply cannot hit 60fps without overclock. The blame is on the physics of the problem, not on my translator.

And the video is another story. The NES sees video memory in a mapped way, with nametables, hardware scroll, and a sprite table accessed via DMA. The SMS Z80 does not address VRAM as memory: it sets an address latch and streams bytes through VDP ports. So every NES PPU write has to be captured, queued in a buffer, and flushed to the VDP during vblank. The NES flips a sprite for free, just by setting an attribute bit. The Master System has no hardware sprite flipping, so the program has to mirror the tile data in VRAM by hand, burning memory. The mid-frame screen split that NES games do, changing the scroll each scanline, also has no direct equivalent, because the VDP latches the vertical scroll at the top of the frame.

And there’s still the VRAM ceiling. Super Mario’s 8 KB of tiles become 16 KB in the SMS 4bpp format, which is the console’s entire VRAM. Background and sprites can’t both stay resident at once. And the code balloons 3 to 6 times in size, which is why the SMS output is already banked from the very first game, even the simplest ones.

Leveraging what the SMS does best

The trick to recover speed is to stop emulating NES behavior and start spending the Master System’s strengths. The project’s motto became “spend ROM to buy CPU.”

The SMS accepts cartridges of several megabytes. So instead of mirroring a sprite by hand at runtime, the build already generates pre-flipped variants of each sprite tile, and the flip becomes a table lookup. Instead of emulating the NES attribute table, the assembler already writes the final SMS nametable word, with the flip, palette, and priority bits baked in. The NES attribute table simply stops existing in the program. The copies to the VDP use unrolled OUTI blocks, faster than the generic loop. And the status-bar split, which on the NES depends on sprite-zero, becomes an SMS line interrupt, which is the native way to do it.

None of this is magic. The negative CPU headroom is still there, so these optimizations reduce the cost but don’t work miracles on their own. But it’s the difference between unplayable and playable.

The real trick: making the AI run the emulator

Here’s the part I consider the most important of the whole project, and it’s what separated the failed attempt from May from the version that finally moves.

Blind translation doesn’t work. The model needs real feedback to know what’s broken and what’s slow. So the heart of the project is the differential oracle, the infrastructure that runs the emulators and measures reality. The translator is just the easy part.

It works in two layers. The first compares instruction by instruction: for each routine, the system generates random initial states, runs the original 6502 in a reference interpreter and runs the generated Z80, and compares the result (accumulator, registers, flags, touched RAM). Any divergence raises a flag. The second layer compares frame by frame: it runs the NES ROM as absolute ground truth and the SMS build side by side, with the same button script, and compares RAM byte by byte on every frame. That was later extended with an oracle that checks the SMS VRAM and palette, and with a visual oracle that compares the output against the real NES frame.

This measurement loop is what unlocked the recent fixes. It wasn’t guesswork. Two concrete examples:

In Super Mario, every optimization step was measured in cycles per frame, with the emulator actually running. A frame’s budget is 59,736 cycles. The baseline sat at around 370 thousand cycles per frame, something like 6 times over budget, which gave about 10fps and explained the need for that brutal 500% overclock. Measuring step by step, each change validated by the oracle, it dropped to 118,296 cycles per frame, or 1.98 times the budget. It went from 6 times to under 2 times. It now runs at full speed already in the emulator’s standard overclock, and it’s comfortable in the 200 to 300% range, versus the 500 to 700% from the start.

In Castlevania, the biggest speed win came from a profile only the emulator could reveal: a sprite-zero wait loop, at address $F8C7, was doing 255 status reads and exiting by timeout every single time, consuming almost 23% of the entire CPU. Without running the emulator and measuring, nobody would find this by eye. With the measurement, the fix was surgical.

This is the bigger argument I’ve been hammering for a while about agents: an LLM that only generates code in the dark makes big mistakes. An LLM that can actually run the target, collect real data, and react to what it measured plays in another league.

What I learned studying lackoftrack27’s port

With that oracle in place, I put Claude Fable and GPT Astra to dissect lackoftrack27’s port, which is a reimplementation of the same game from the same disassembly I translate. That settled once and for all a doubt that was blocking me: Super Mario fits on the Master System. My 6-times overrun on the budget was 100% translation overhead, not a limitation of the game or the hardware.

His wins, in order of impact, were roughly these:

• The biggest of all: the data representation. He reorganized the game’s object arrays into RAM pages, one per slot, with the same field offsets. Then the 6502’s X becomes the register H and the field name becomes L, and an access that cost about 70 time units in my translator now costs 14. The cruel detail is that this only works because the programmer knows, from memory, that this particular X is always an object index between 0 and 6. A static translator has no way to safely discover that invariant. This is the most powerful optimization, and it’s precisely the one automatic translation can’t prove on its own. It’s the residual that holds back the last 2 times in speed.
• Flags audited, not emulated. He checked the code and found only about 10 places that genuinely depend on some 6502 carry quirk. The rest uses the Z80’s native flags. That confirmed a measurement of mine: spending energy emulating flags yields almost nothing.
• Native calls. JSR becoming a real CALL, without the expensive emulated-stack bookkeeping. That was the biggest generic win I ported over to my pipeline.
• PPU deleted at build time, not emulated at runtime, exactly as I described in the section on leveraging the SMS.
• Frame architected to overrun gracefully, turning an overrun into a clean lag frame instead of corrupting the screen.

I adopted what could be generalized, and Super Mario dropped from 6 times to under 2 times the budget. This is the result running today:

The most honest lesson from this study is twofold. The real wins are in the data representation and the calling convention, not in what I had attacked first. And the deepest win of all is exactly what the automatic translator can’t infer. That draws the ceiling of what can be automated pretty clearly.

Castlevania and the mapper problem

With Super Mario moving, I went back to my old target: the first Castlevania. And here we hit the NES’s most serious limitation.

The NES is a simple console, with a bunch of limits. One of the main ones is that it doesn’t support games bigger than about 40kb of ROM, because the 6502 only sees a 32 KB window of program in its address space. The “solution” from back then was brilliant and a bit crazy: parts of the console were being upgraded by the cartridge itself.

Many people think a cartridge is just a ROM chip with the game code. In the NES case, it’s not. The cartridges came with a variety of extra chips that increased the console’s capability, be it a better sound chip or, much more commonly, the mappers. There are several different mappers, from Nintendo itself and from third parties like Capcom and Konami. They use a technique called bank switching: since the 6502 can’t see enough address space, the mapper swaps which pieces of ROM are visible in that 32 KB window, as the game asks. That’s how big games fit into a console that, on paper, couldn’t handle them.

I already explained this in detail in an old video from my channel, Akitando #81, about learning computing with Super Mario the hardcore way:

Castlevania uses one of the earlier mappers, the UxROM. And here is the scale problem of my project: if I want to be able to translate the majority of NES games, I have to map every mapper, one by one. Today the project implements only two: the NROM, which is Super Mario’s bare cartridge, and Castlevania’s UxROM. All the others, the MMC1, MMC3, and company, are only planned. Each mapper is quite a bit of work to implement, because it’s not enough to understand the NES bank switching, you have to translate that behavior into the Master System’s own mapper.

The good news is that the Master System is also a banked system, so the mapping is “the same shape one level up.” A NES PRG bank becomes a set of SMS banks, a NES bank-switch write becomes a write to the SMS mapper through a shim, and a call that crosses banks uses the “gate” machinery that already exists. A routine’s identity becomes the pair (bank, address), and a dispatch table resolves that at runtime. When it doesn’t find it, it fails closed, with a trap, instead of running garbage.

This is where bigger games will hit the wall. The tile bank switching of the more advanced mappers, the scanline interrupt timing of the MMC3 and MMC5, and the SMS’s own bank ceiling for a really big NES game, all of that is still unsolved. That’s why I still can’t say whether a Super Mario Bros 3 is viable or not. It’s quite possible the bigger games die exactly at this step.

Either way, I worked a good bit more on Castlevania in this comeback. I fixed a pile of things using the oracle: the sprite-zero loop that ate CPU, the weapon and projectile logic that lost call returns, a scroll glitch in the status bar, the VRAM collision between 8x16 and 8x8 sprites, and the coherence between background, palette, HUD, and sprites. Today Castlevania boots, accepts start, draws a recognizable first stage, responds to the controller, and runs for a good while without crashing. But it’s honest to say it still runs slowly, and the path I use to play it is Mednafen at 500% overclock, and even then it’s still 2 to 3 times below its own speed target. It’s far from pixel-perfect and real-time.

Conclusion

After so many weeks and so many attempts, I still don’t know how much more can be squeezed out of an automatic translation. The ceiling might be close, because the deepest optimizations are precisely the ones a machine can’t infer on its own.

But there’s a path that excites me. The automatic translation can become a baseline. An SMS conversion that already runs, correct, even if slow, and that can later be optimized by hand, game by game, exactly like lackoftrack27 did with Super Mario and like so many people have been doing with decompilations and ports out there. The oracle guarantees the base is correct, and the human hand steps in to do what the machine can’t.

Porting a game to much better hardware, like a PC port, is relatively easy, because there’s capacity to spare. The truly hard part is fitting the game into a same-generation console, where nothing is to spare. And it’s exactly that difficulty that makes the idea of making better versions of NES games for the Master System so appealing. It’s the console that deserved to have had those games, and never did.

I hope more people get excited about this possibility and contribute to the project. It’s all open at nes-to-sms. If you enjoy 6502, Z80, VDP, and the challenge of squeezing cycles out of 40-year-old hardware, come by. There’s plenty of room.

Last week I posted about my distrobox-gaming setup, with more than ten retro racing games running on Linux, from Gran Turismo 1 on DuckStation to Forza Motorsport 4 on Xenia. At the end of that piece, I described Driveclub on shadPS4 as the “final boss”: the game boots, the menu loads, the race starts, the controller responds.

Except I mentioned two problems in passing and treated them as “accepted limitations”:

1. During daytime, the image is a bit darker than on a reference PS4. Not alarming, but noticeable.
2. At night, the race start in Canada or Munnar went pitch black for 10 to 30 seconds before the game “recovered on its own” around the 1:30 mark. During those seconds, only the HUD was visible. Track, car, headlights — all absolute black.

In the previous article I pushed the explanation to “it’s just not fixed in the emulator yet, I’ll live with it”. But inside I couldn’t make myself play the game in a visually unplayable state. I wanted to play DriveClub at its best, and I didn’t want to sit around waiting for the project to fix it for me. I decided to take matters into my own hands. Thirty seconds of absolute black isn’t “a bit darker”. It’s a serious bug, the kind that makes a game unplayable in practice.

This article is what happened between Sunday night and Thursday morning.

The blackout, live

This video is the behavior I wanted to fix. Race start in India (Munnar), night race. You see the track, headlights turn on, the first few seconds run. Then it darkens progressively. Within about 15 seconds everything is black. Stays that way for another 60-90 seconds. Then the game “recalibrates” on its own and the track reappears.

If you’re a player, you don’t care why. You just want to drive.

Why shadPS4 is hard to debug

shadPS4 still has no stable release. The project is under active development. The main branch changes several times a week, configs migrate from TOML to JSON without notice, settings hide behind “Advanced” so users with incompatible hardware don’t file issues, open PRs compete over different approaches to the same problem.

Anyone trying to configure DriveClub today will find:

• September/2025 Reddit guides using readbacks = true (it was a boolean back then) saying “for DriveClub always enable readbacks”.
• November/2025 guides saying “disable readbacks, it kills performance” (because in 2025-07 readbacks became an enum Disabled | Relaxed | Precise with different performance profiles, and Bloodborne started hanging with it on).
• January/2026 YouTube videos using some custom fork nobody documented.
• A thread on shadps4.net with three different, mutually exclusive explanations for the blackout.
• My own notes from last week in distrobox-gaming/docs/driveclub-shadps4.md saying readbacks_mode: 0. The exact opposite of what I found this week.

So the information exists, but it’s scattered, dated, contradictory, and most of it depends on version details that changed between the original post and today. Reproducing a setup from a YouTube video is like trying to solve a Rubik’s cube blindfolded.

Spoiler: the solution is one integer

After 31 phases of investigation, 44 commits on my shadPS4 fork, 15,668 lines of instrumental code added, and three days of nearly uninterrupted debugging, the answer is one line in the per-game config:

{
  "GPU": {
    "readbacks_mode": 2
  }
}

readbacks_mode: 2 is the Precise mode. Explaining what it does requires understanding how DriveClub implements auto-exposure, and that’s where the journey starts. To know WHY this toggle fixes things, you have to understand the whole chain.

The short version: DriveClub implements auto-exposure as a GPU→CPU feedback loop.

1. The scene renders to an HDR target.
2. A compute shader calculates a luminance histogram into an SSBO.
3. The CPU reads that SSBO on the next frame and derives a target exposure.
4. The CPU writes that exposure back into a 1936-byte lighting UBO (at slots [38] [48] [50]).
5. Fragment shaders read that UBO and multiply scene luminance by it.

Without readbacks_mode: Precise, step 3 reads stale zeros. The memory page where the GPU wrote the histogram is never synchronized to the CPU side. The CPU exposure integrator concludes “scene is dark, open the aperture all the way” and ramps its output value monotonically: 2.59 → 7.84 → 24 → 90 → 179 → 255. Within 60-90 seconds the scale saturates so high that everything clips to zero. That’s the pitch black.

With readbacks_mode: Precise on, the emulator marks the pages the GPU just wrote as kernel-protected (via mprotect on Linux). When the CPU tries to read one of those pages for the first time, a page fault fires. The emulator intercepts it, issues a vkCmdCopyBuffer download from the GPU buffer to the host staging area, waits on the scheduler, and the CPU finally sees fresh data. The real histogram enters the integrator, exposure converges normally, and the race start opens bright as it should.

Why isn’t it the default? Three documented reasons. First, per-page mprotect + per-fault GPU stall + compute dispatch + scheduler wait has a real cost: on NVIDIA’s warm path it’s tolerable, on AMD it tanks below 12 FPS, with an open issue about it. Second, Bloodborne hangs on loading screens with Precise enabled. Third, the maintainer tucked the option behind “Advanced” in the UI precisely to keep users with sensitive hardware from enabling it by mistake. The mode has existed since v0.15.0 (September/2025), but nobody had publicly connected Precise + DriveClub + auto-exposure feedback loop. The compat tracker already admits that DriveClub “requires readbacks enabled to function properly”, but doesn’t specify the mode.

In my setup the performance cost is irrelevant. I have an RTX 5090 on my desktop, plenty of hardware to swallow the mprotect, the page fault, the copy and the stall per frame. The call is trivial: I flip Precise on, pay the price, the game runs. On more modest hardware or on AMD the conversation is different, which is exactly why this setting isn’t default and hides behind “Advanced”.

One thing I want to make clear: this whole explanation above (Precise vs Relaxed vs Disabled, GPU→CPU feedback loop, per-page mprotect syscall) is not knowledge I had on Sunday night. I didn’t know what a buffer readback was, didn’t know DriveClub implemented auto-exposure as a GPU→CPU feedback loop, didn’t know readbacks_mode had become an enum in 2025 with three values. To arrive at the right answer, I had to learn every piece from scratch. I couldn’t guess. Had I tried to “enable readbacks” last week without understanding the chain, I’d have picked the wrong value (Relaxed isn’t enough for this feedback loop, as I’ll explain below) and given up thinking “it doesn’t work”.

Two more things need to be in place for this to work, both covered in the previous article:

• v1.28 patch applied on top of the v1.00 base install (without it, content stays locked with “not yet released”).
• 60fps XML patch disabled (it raises the render rate but the logic tickrate is fixed; with it on, the game runs in slow motion).

The result

Same race in Canada, night, with readbacks_mode: 2 on. Race start opens bright, auto-exposure converges immediately, the night transition unfolds naturally as the game’s TOD (time of day) advances. No blackout, no “recalibration” at 1:30, no 30-second window of absolute black. This is DriveClub running like it does on PS4.

Now the interesting question is not “which setting”. It’s: how did we get here?

How does a junior learn today?

There’s a question I hear often: “with AI doing everything, how does a junior learn?”

The premise is wrong. AI doesn’t do everything. AI does what you ask it to. It doesn’t discover on its own. It has no domain initiative. It’s not capable of telling you “hey, this looks like a broken GPU→CPU readback feedback loop” unless you already know there’s a thing called a readback and that broken feedback loops are a class of bug.

Worse: if you go to an AI agent today and ask “fix this black screen in DriveClub on shadPS4”, it will give you a list of possible answers based on old forum posts, with a high probability of steering you wrong. It will suggest the 60fps XML patch (wrong — causes slow motion). It will suggest a tonemap override (wrong — the game already writes correct SDR). It will suggest a vblank_frequency tweak (useless for the real problem). It will suggest manual gamma (treats the symptom, not the cause).

The way to discover is to dive into the chain, phase by phase, ruling out wrong hypotheses until the terrain is familiar enough that you recognize the right answer when it appears.

That’s where a lot of people misread me. “Akita is already a senior, he has 25+ years of experience, of course he knows.” False. A senior is someone who has been a junior in every topic they master. And they keep becoming a junior every time they pick up a new domain. I have 25 years of web programming, distributed systems, Ruby, Erlang, Go. But I’ve never programmed for PS4. I’d never looked at the shadPS4 codebase. I didn’t know PS4’s graphics architecture. On Sunday I was an absolute junior in this domain.

But junior doesn’t mean totally green. A while back I had explored on my YouTube channel the low-level architecture of older consoles (from the NES’s 6502 onward) and how emulators work internally in general. The two videos below helped build the basic vocabulary for how a game console works under the hood, and made sure I wouldn’t trip on concepts like fetch-decode-execute, opcode, interrupt, or HLE vs LLE.

I had also made an older video on the evolution of CPUs, GPUs, DirectX, and Vulkan, so at least the vocabulary of “modern graphics pipeline” and “shading language” wasn’t alien.

Knowing that VkCommandBuffer exists is very different from knowing where in shadPS4 a readback vkCmdCopyBuffer fires. But it gives you a base. That kind of old curiosity paid interest now.

The rotation: Claude Code and Codex

AI (in my case Claude Code) didn’t “know” more than I did. It has the same dated forum text you’d find on Reddit. What it did well was aggregate: read shadPS4 source code in parallel with me, index comments, cross-reference between phase docs, compile, run probes, parse 61 MB logs, compare decompiled binary against UBO diffs, shine light on corners of the system faster than I could alone.

But the decision to “keep investigating” was mine. The perseverance of “don’t accept a mitigation, want the root cause” was mine. And when the AI suggested “honestly, we should just accept the current result and document it” (and it suggested this several times over the four days), I was the one who had to say “no, we keep going”.

The central point about the rotation: no single LLM managed to close this problem alone.

Over the four days, Claude Code repeatedly got stuck looping on the same hypotheses with no new direction. When that happened, I’d switch to Codex for a few hours to bring in outside ideas, different probes, a re-read of the codebase from a fresh angle. Then back to Claude Code to integrate what Codex had surfaced. And so on, alternating.

The final resolution happened on Claude Code, but the journey switched models several times. Each LLM had its biases and blind spots. Left alone, each one would have given up sooner.

What broke the impasse was me continuing to bring in new ideas to try, forcing the model to reassess, switching models whenever one started to repeat itself.

At two points things went past “just repeating hypotheses”. Codex literally had an agentic-loop glitch: it started repeating the exact same “solution” it had just tried, over and over, in sequence, without noticing what it was doing. It was the first time I’d ever seen that happen in any AI agent. I had to kill the session and start a fresh one from zero to break the cycle.

That says something about context size and session duration. The complexity and pace of this investigation were enough to bring both LLMs to their knees, each in their own way.

The whole journey below is documented in 33 phase docs on the gamma-debug branch of my shadPS4 fork. Each section here links to the original doc for anyone who wants the complete detail. Here I summarize the essentials: the hypothesis we had, what we tried, what new concept we had to learn, and why the phase didn’t close the case.

Session zero: baseline and reproducibility

Every serious investigation starts before Phase 1. The first thing, for any project, is to make sure the baseline works as expected and that the situation you want to research is reproducible every time. If you can’t reproduce the bug on demand, you’re chasing ghosts. Every probe after that will be inconclusive because the bug “appeared and vanished” without control. And if the baseline is broken in some way you haven’t noticed, every experiment measures the wrong problem. Without those two guarantees, you can’t make progress.

In my case, on Sunday night I confirmed:

• The game boots all the way to the race screen without crashing, using the distrobox-gaming config.
• DriveClubFS extracts v1.28 cleanly, 8018 files, ~47 GB.
• MSAA depth resolve applied on the fork; night tracks render shapes instead of uniform absolute black (covered in the previous article).
• 8BitDo controller detected.
• Night race in India 19:30 reproduces the blackout on 100% of attempts, with the same temporal pattern: progressive fade in the first ~15s, pitch black between ~20s and ~90s, “recalibration” at 1:30.

That baseline is the only solid ground that lets me compare each experiment reliably. Without it, a probe that “worked” might just be a different cache state, not the real fix. With it, every change has a before and an after that are measurable.

Beyond that, zero specific knowledge of:

• PS4 PKG format (PFS, param.sfo, disc_info, keystone).
• shadPS4 codebase (src/core, src/video_core, shader_recompiler, buffer_cache).
• PS4 graphics pipeline (GCN ISA, forward+ lighting, MSAA depth resolve).
• Vulkan beyond the surface (descriptor sets, UBO binding, push constants, pipeline cache).
• SPIR-V disassembly and patching.
• PS4 OELF loader, Itanium RTTI, SCE dynamic relocations.
• mprotect-based page-fault tracking for CPU-GPU synchronization.

The journey, phase by phase

I’ll group the 30+ phases into buckets that make sense as a narrative. Each phase links to the full doc for anyone who wants technical detail.

Note for anyone who doesn’t want to read all 30+ phases: after the phase sequence there are reflection and methodology sections you can read on their own. The shotgun technique explains the debugging methodology I used throughout the investigation. What I knew on Sunday vs Thursday sums up what I actually learned. The AI suggested accepting. The perseverance was mine discusses AI’s real role in this process. The real cost of this journey catalogs what got produced. If you want to jump straight to the argument, those are the shortcuts.

Phase 01: pipeline cache, the warm-up

phase-01-shader-compile-stalls.md

• Hypothesis: menus run at 2-3 fps on first launch. Must be Vulkan pipeline compilation happening in real time.
• Action: enable pipeline_cache_enabled: true in the global config.
• New concept: Vulkan pipeline caching. When the emulator translates a PS4 GCN shader into SPIR-V and then into driver-specific Vulkan binary, it can cache that binary. Without the cache, it recompiles every cold launch (~864 shaders + ~590 pipelines).
• Outcome: solved. First session pays the cost; subsequent sessions read from disk and launch immediately. Easy. Also my first lesson about the shadPS4 codebase.

Phase 02: gamma dim, starting in the wrong direction

phase-02-gamma-dim-image.md

• Hypothesis: DriveClub’s image is dim compared to reference. Must be wrong sRGB encoding or an HDR tonemap applied badly by the emulator.
• Action: instrumented the swapchain to log format, added SHADPS4_PP_* env vars to experiment, built a post-processing pipeline with three knobs (exposure, ACES tonemap, gamma curve).
• New concept: sRGB OETF, HDR tonemap (ACES vs Reinhard), Bayer dither as anti-banding.
• Outcome: via bypass path (SHADPS4_PP_BYPASS=1, writes raw game output with no post-processing) I discovered the game writes correct SDR already into the framebuffer. The emulator’s post-processing pipeline was mangling the signal. Final shader became simply sRGB encode + Bayer dither. Dim persists, but it’s not a gamma problem.

Three hours on this phase. The most important lesson: when “the image looks wrong”, the first diagnostic should be a bypass path that shows raw game output. If bypass looks right, the emulator is the one mangling the signal. Stop touching the tonemap.

Phase 03: v1.28 content access

phase-03-v128-content-access.md

• Hypothesis: v1.28 extracts, but the game says “content not released yet, download required”.
• Action: merge v1.28 on top of v1.00, restore param.sfo, disc_info.dat, keystone.
• New concept: PS4 cumulative patches, package metadata.
• Outcome: solved. Detailed in the previous article.

Phase 04: MSAA depth + slow motion

phase-04-slowness.md

• Hypothesis: night tracks are pitch black and the game “feels slow”.
• Action: two separate things. Disable the 60fps XML patch (which was decoupling render rate from logic tickrate). Implement ReinterpretMsDepthAsColor on my fork (to let the emulator resolve 4x MSAA depth to 1-sample color, which DriveClub needs for forward+ lighting on night tracks).
• New concept: forward+ lighting (a renderer that writes the scene to an MSAA depth target and then reads it as color for SSAO and volumetrics), MSAA depth resolve.
• Outcome: both fixed. Detailed in the previous article.

Phase 05: second pass on brightness

phase-05-brightness-followup.md

• Hypothesis: since the game writes correct SDR, maybe a static boost in post-processing helps without touching the UBO feedback loop.
• Action: tried linear boost (1.5x, 2.0x), gamma pre-encode (pow curve), scene-aware auto-exposure with peak+mean sampling.
• Outcome: all rolled back. Linear boost clips highlights. Gamma introduces banding. My auto-exposure layer cancels the user’s manual brightness slider. There’s no free lunch in post-processing. Dim stays dim without real HDR or shader patches.

Narrowing the blackout: the shared gate

race-start-blackout-040420.md

• Hypothesis: the blackout has a curious signature. Main view goes dim/black, rearview mirror goes absolute black, HUD stays bright. Three layers with different behaviors suggest a shared “gate”, not a common fade.
• Action: instrumented texture-cache aliasing, probed with live fragment shader substitution on suspected inputs.
• New concept: texture-cache aliasing (multiple images sharing a memory address, which the emulator cache reuses), render-target lifetime.
• Outcome: points to a shared “presentation permission” between the main scene and the mirror, not a scripted fade.

Phases 07-09: texture torture, UI surgery, binary patch plan

phase-07-aggressive-torture-probe.md · phase-08-ui-asset-surgery.md · phase-09-eboot-binary-patch-plan.md

• Hypothesis: the race-start dim overlay is an asset. Small texture, UI panel, or a method of the FreeplayGetInCar controller in the eboot.
• Action: null-substituted BC-compressed materials, small texture candidates, four-vector weight masks during critical draws. Disabled UI panels (loading_freeplay.txt, get_in_car_animation.txt, vehicle_select_background). Extracted the OELF, located FreeplayGetInCar ASCII strings, identified the constructor at VA 0xf89b00 and the vtable at 0x15dc3e0.
• New concept: PS4 OELF loader (Sony’s variant of ELF), Itanium C++ RTTI (how C++ encodes type info in vtables), SCE dynamic relocations (placeholders that only the dynamic loader resolves at runtime).
• Outcome: nulls work but the fade persists. The overlay renders directly into HDR scene targets, not through the panel system. Binary patching has relocation placeholders that aren’t statically resolvable without a Ghidra + PS4 plugin. Asset-side surface exhausted. Six hours of debugging, final conclusion: the bug lives in state, not in an asset.

Phase 10: rethink + animlib

phase-10a-rethink-040422.md · phase-10b-video-diagnostic-animlib.md

Tuesday morning. Sat down, rebooted mentally. New model: the blackout is a state-machine gate. It’s not “scene not ready”, it’s “permission transition”. The gate closes after the starting grid appears. Next probe: runtime dispatch trace, enough of the blind asset surgery.

In parallel: frame extraction from the recording at 10 Hz, cross-referenced against keyframes of the animation library (animlib) in india_posteffects.lvl. Found a smoking gun. The MasterBrightness track has keyframes 0.003 and 0.0007 (0.63% brightness) where the default would be 1.0. Animlib beats inline defaults every frame.

• New concept: animation library, keyframe encoding, binary float-scanning.

Video above: the process of probing the fade in real time.

Phase 11: multi-scalar patch

phase-11-multi-scalar-patch.md

• Hypothesis: patching MasterBrightness + AutoTargetLuminance + ManualAutoMix simultaneously will lift the blackout.
• Action: extended PatchAnimlibFloatValues to rewrite three scalars. Instrumented with SHADPS4_DC_DRAWLOG + SHADPS4_DC_UBOLOG.
• Outcome: the patch produces a real numeric lift (1.2 → 6.5 in 255, a 5×), but still sub-perceptual black. And the crucial finding: the mirror works normally after the patch. It’s not gated, just reflecting a dark scene. At least 285× of additional attenuation lives downstream of the scalars we can patch.

Phase 12: bisect closes the asset side

phase-12-bisect-closes-asset-side.md

• Hypothesis: one of the 60 accumulated patches broke the mirror independently from the blackout. Bisect.
• Action: binary bisect across 60 overlay files over 5 rounds.
• Outcome: x_live_lobby_pre_race.txt (rerouting loading-spinner transition from ZoomInAndFade to NoFade) was the mirror killer. Rolled back. Asset side completely closed. The driver lives in compiled code or post-process state, not in a game asset.

Asset sweeps 01-09 (consolidated)

asset-sweep-09-conclusions.md

In parallel with the phases above, I swept 12 RPK substitutions: FreeplayGetInCar page swaps, postfx edits in india_landscape_gui.rpk, globaldata RTT-only edits, prerace state-string rewrites. All clean misses. No asset family touches the blackout. Lesson: stop chasing by names; chase by state transitions.

Phase 13: UBO dump breakthrough

phase-13-ubo-dump-breakthrough.md

• Hypothesis: eye-adaptation feedback loop with stale input is the culprit. A luminance scalar growing without converging.
• Action: dump 128 bytes of UBO in hex during the race window across six hand-picked pipelines. Look for monotonically changing values.
• New concept: UBO (Uniform Buffer Object), a shared memory region the CPU writes and shaders read. Auto-exposure integrator, a classic eye-adaptation component that takes time to converge toward a target.
• Outcome: found it. UBO offset 3 climbs monotonically from 2.59 → 7.84 → 24 → 90 → 179 → 255 over 2 seconds. Textbook feedback loop with broken input. First real hit in 12 phases.

Phase 14: scene-pipeline UBOs are the read side

phase-14-scene-pipeline-ubos-wrong.md

• Hypothesis: clamping the climbing scalar will stop the blackout.
• Action: SHADPS4_DC_LUM_CLAMP=2.0 forces offset 3 to a fixed value during the race window.
• Outcome: the clamp fires 1093 times, blackout unchanged. Scene-pipeline UBOs consume the dim, they don’t produce it. The dim is upstream, in a fullscreen tonemap or post-fx compute.

Phases 15-16: runtime texture dump + mutation

phase-15-runtime-texture-dump.md · phase-16-runtime-texture-mutation.md

• Hypothesis: the blackout is a fullscreen texture composited over the scene.
• Action: SHADPS4_DC_TEX_DUMP=1 dumps every bound texture during the race window (1079 textures captured). Convert tiled format to PNG for visual triage. Then, deterministically mutate each texture via hash-based tint + InvalidateMemory to force re-upload.
• New concept: GCN tile format (Sony interleaves bytes a specific way for cache locality), texture de-swizzle, buffer cache invalidation.
• Outcome: 14 rounds of mutation (BC textures, float data, render targets, UI atlases, post-fx buffers, LUTs). Blackout unchanged across all of them. Texture content 100% ruled out as the source.

Phases 17-19: UBO smashing, push-constant smashing, compute dispatch probe

phase-17-ubo-batch-smashing.md · phase-18-push-constant-smashing.md · phase-19-compute-dispatch-probe.md

• Hypothesis: random-fill on UBOs, push constants, and compute input buffers can bracket and isolate the dim field without crashing.
• Action: SHADPS4_DC_UBO_SMASH=1, SHADPS4_DC_PC_SMASH=1, SHADPS4_DC_DISPATCH_SMASH=1 with cb-index and size filters.
• New concept: push constants (128 bytes of fast params the driver pushes straight into the pipeline, no descriptor), compute dispatches (fires compute shaders with a grid of threads), ud_regs (GCN user data registers — how shadPS4 maps user data to push constants).
• Outcome: safe brackets produce overlay bokeh + blinks, but the dim stays put. Wide brackets that reach the dim also hit matrices/transforms and crash. Random-fill is the wrong instrument. Needs diff methodology.

Phase 19b-c: dim-vs-lift dispatch diff

phase-19b-dim-vs-lift-diff.md · phase-19c-dispatch-draw-skip-null.md

• Hypothesis: compute dispatches that only fire during dim (and stop once it lifts) are part of the chain.
• Action: split the clean log into pre / dim / bright windows (via user wall-clock), count dispatch frequency per pipeline.
• Outcome: identified 8 compute pipelines (histogram 256→downsamples, tile-grid reductions, auto-exposure 1x1 scalars) that stop exactly when dim lifts. Shapes strongly suggest the eye-adaptation chain. First genuine diagnostic hit. Skip test on those 8 + 101 correlated draws: blackout unchanged. They’re downstream effects, not drivers.

Phase 20-21: tonemap inline, fragment → flip buffer

phase-20-shader-dump-tonemap-inline.md · phase-21-fragment-to-flip-buffer.md

• Hypothesis: the auto-exposure compute shader is broken, or the tonemap compute has the wrong math.
• Action: recompile all shaders, dump SPIR-V, disassemble the histogram auto-exposure. Patch its output to constant 1.0 and test.
• New concept: SPIR-V disassembly (Khronos intermediate format with readable assembly). Compute shader verification. Later, pipeline-to-shader mapping.
• Outcome: patch has no effect. Discovery: DriveClub has no separate tonemap pass. Scene geometry writes directly to the flip buffer, with exposure inline in material shaders. Each material shader bakes the dim scalar from a shared UBO. Pipeline cache wipe + SHADPS4_DC_PIPEMAP=1 dumps every pipeline→shader mapping. Filtering drawlog for pipelines writing to 0x5000900000 / 0x5000108000 (the actual swapchain buffers) yields 14 unique pipelines. None with Exp2/Log2 tonemap ops. Exposure is applied upstream.

Phase 22: tonemap compute identified

phase-22-tonemap-compute-identified.md

• Hypothesis: among the game’s 510 compute shaders, one has a tonemap signature (many Exp2/Log2).
• Action: automated scan, cross-reference with dispatchlog.
• Outcome: cs_0x2c918c06 is the strong candidate, with 8 Exp2 + 8 Log2, 5 SSBOs (scene params, TAA, bloom, camera, exposure), 11 images. Skip test on that specific pipeline: stops the blackout cycle, removes color grading, introduces temporal ghosting. That’s the final scene→swapchain tonemap path.

Phase 22+: tonemap patches → playable

phase-22plus-tonemap-compute-patches.md

• Hypothesis: two surgical SPIR-V edits (histogram no-op + tonemap exposure clamp/boost) make the game playable.
• Action: histogram patch to never update; tonemap patch to clamp exposure floor at 0.5 and boost blend by ×10. Both via SPIR-V patching + shader/patch/ drop-in.
• Outcome: playable! Dim shrinks from pitch black to mild. A real mitigation, not a root-cause fix. The fade curve still drags exposure, and each track needs per-threshold tuning.

Here the AI suggested stopping for the first time. “The game is playable, this is a decent mitigation, we should document and accept.” I pushed back: “it’s playable but it’s wrong. Don’t accept. We keep going.”

Phase 23: CPU-side exposure intercept

phase-23-cpu-exposure-intercept.md

• Hypothesis: clamping the exposure scalar at the tonemap compute’s BindBuffers point prevents over-dimming.
• Action: SHADPS4_DC_EXPOSURE_PIN=1 intercepts BindBuffers, overwrites exposure offsets with a clamp-min threshold, invalidates buffer_cache.
• New concept: CPU-GPU buffer binding (the moment when the CPU hands a descriptor to the GPU). Buffer cache invalidation (how the emulator keeps consistency between a buffer’s CPU-side and GPU-side state).
• Outcome: the scalar oscillates at race start, then climbs monotonically. Per-track tuning is needed. India wants 3.0, Canada blows out at the same threshold. A single-scalar solution doesn’t converge cross-track.

Phase 24: dim upstream of tonemap

phase-24-dim-upstream-of-tonemap.md

• Conclusion: after the whole probe chain (identity tonemap, exposure pin, compute skip), the dim is in the HDR target before the tonemap reads it. Three upstream suspects: (1) atmospheric scattering / volumetric fog, (2) reflection-probe / envmap update, (3) pre-tonemap exposure apply.
• New concept: atmospheric scattering (simulating how light travels through atmosphere, Rayleigh/Mie-style), volumetric fog (fog rendered as a froxel volume).
• Outcome: plan set. Frame-order dump, walk backwards from tonemap through the whole chain.

Phase 25: frame-order trace

phase-25-frameorder-trace.md

• Action: SHADPS4_DC_FRAMEORDER=<N> logs strict per-submit pipeline/shader chain over N submits during race window.
• New concept: frame-order reconstruction (listing every GPU submission in exact order), froxel volumetrics (frustum volume voxels — a 3D grid aligned to the camera’s frustum that stores light info).
• Outcome: three suspects: (A) half-res compute (60,34,1), probably SSAO; (B) progressive dispatches (256,1,1)→(2560,1,1)→(10240,1,1), froxel volumetric; (C) fullscreen apply-fog-to-HDR draw. Suspect B is the strongest fit (sunset best-fit, per-pixel non-uniform dim).

Phase 26: The UBO fade pin, the “aha moment”

phase-26-ubo-fade-pin.md

This is where everything changed.

• Hypothesis: a direct memory diff (bright vs dim vs recovered) identifies the exact bytes the game writes to control the blackout.
• Action: capture periodic UBO snapshots across visual state transitions. Diff three snapshots byte by byte. Look for fade signatures.
• New concept: state diff methodology. Instead of “which pass looks suspicious?”, ask “which bytes actually change with the visual state?”
• Outcome: breakthrough. Two UBOs control the fade: a 1936-byte one with slots [38/48/50] (light intensity) being multiplied by 0.094 (fade factor), and a 224-byte sun UBO with slot [50] dropping 97%. Pinning both: race start opens bright. TOD animation intact. Content-aware three-state lifecycle (idle → engaged → expired).

Wednesday night. Claude suggests stopping again. “We have the pin working, three-state lifecycle is robust, Canada + Munnar are running. This is upstream quality, we should PR and close it.” I insist: “there’s still residual dim on other tracks, it’s not closed. We keep going.”

Phase 28: pivot to emulator code

phase-28-pivot-to-emulator-code.md

• Realization: the residual dim in Canada dusk/night isn’t a wrong UBO value. It’s an emulator translation gap. The game runs correctly on a real PS4, so shadPS4 has some path that translates or synchronizes incorrectly.
• Action: ranked 5 candidate emulator bugs: HLE shader misidentification, image storage classification, layout transitions, IMAGE_STORE_MIP fallback, OpImageFetch LOD restriction.
• New concept: HLE (High-Level Emulation). Replacing complex PS4 OS functions with host-side implementations. Different from LLE (low-level) which emulates bit by bit. HLE is faster but can diverge from real behavior whenever the host implementation doesn’t cover every case.

Phase 29: calibrated state + recording harness

phase-29-calibrated-state.md

• Action: SHADPS4_DC_RECORD=1. Recording harness that dumps lighting UBOs periodically + cross-correlates with wall-clock screenshots.
• Outcome: important discovery. Slots [144..295] of the 1936-byte UBO (30+ fields) stay denormal/uninitialized for the first ~90 seconds of a race. At the 1:30 “auto-recalibration”, the game writes the real values. It’s not magic recovery, it’s the CPU finally writing values that should have been there since frame 1. On PS4 they’re ready before the first frame; on shadPS4 they’re delayed by 90s. Root cause lives in an emulator init gap.

Phase 30: UBO writer audit

phase-30-ubo-writer-audit.md

• Action: exhaustive audit of every path that writes into slot [38] of the 1936-byte UBO. 7 suspects ranked: (1) ObtainBuffer stream-copy race, (2) lazy RegionManager in memory_tracker, (3) histogram compute skip, (4) page-fault delayed invalidation, (5) readback gating, (6) buffer-coherency race, (7) push-constant.
• Status: audit incomplete. Before I could verify each suspect, Phase 31 short-circuited the whole thing.

Phase 31: readbacks_mode = Precise, the turning point

phase-31-readbacks-mode-fix.md

Thursday morning. Tired, thinking about suspect #5, readback gating. That one itched at me because it was the only one of the 7 writers that touched the timing of the read rather than the correctness of the write.

• Hypothesis: flipping readbacks_mode: 2 (Precise) in per-game config makes the feedback loop work by synchronizing the CPU’s read to fresh GPU output.
• Action: one edit in custom_configs/CUSA00003.json. Boot. Canada night.
• Outcome: race start opens bright. Auto-exposure converges normally. Zero blackout. Zero 1:30 recalibration. Night TOD natural.

Tested on Munnar. Same result. One integer. 31 phases. 44 commits. 15,668 lines. Answer: one integer in the config.

Why did this slip past 30 phases? The Phase 31 doc has the honest analysis:

1. Symptom disguise. Progressive darkening looks exactly like a broken tonemap, bad shader, or miscompiled exposure scalar. Every dump-driven probe found wrong values in the UBO, which is true but describes the downstream read, not the upstream gap.
2. readback_linear_images red herring. I tested that flag in Phase 29, saw no effect, and concluded “the readback surface is audited”. I forgot that flag is for image readbacks (linear images via TextureCache::DownloadImageMemory). The histogram SSBO is a buffer, a separate path.
3. Pinning making it worse, not better. Overwriting slots [38/48/50] looked promising but never converged. The game rewrote on top of the pin every frame. I interpreted that as “the pin mechanism lands too late in the pipeline”. I spent phases 27-29 moving the pin earlier. The real fix was to stop clobbering the GPU-side input the integrator reads.
4. Never audited the buffer readback path. The Phase 30 audit listed 7 writer candidates, but all of them were about the correctness of the write. None asked “what is the CPU reading, expecting the GPU to have filled?”

The shotgun technique

One thing I want to put on record: torture probes aren’t waste, they’re learning infrastructure. And the methodology behind them has a name: shotgun.

If you have a suspicion (say, “the dim comes from some texture”), the worst thing you can do is start investigating one texture at a time, in depth. DriveClub has 1079 bound textures during the race window. If a detailed triage on one texture takes 20 minutes, you spend three days on a single branch of that tree and still don’t know if the dim even comes from a texture. It might not be in the whole tree.

Shotgun fixes that. Instead of investigating one at a time, you fire at all of them simultaneously. Mutate every bound texture with a hash-based tint, force re-upload, run the game. In 30 seconds you know whether any of them affects the dim. If it does, the dim is texture-side and only then is it worth starting to narrow down. If nothing changes, congratulations: you just ruled out the entire “texture” category in 30 seconds. Switch categories, shotgun UBOs. No hit? Shotgun push constants. No hit? Shotgun compute dispatches. Keep going until something reacts.

Don’t start by narrowing down a tree that might be huge. You’ll spend weeks in irrelevant leaves. Shotgun the trunk first. See which branch reacts. Then go deep inside that branch.

That’s what I did, without knowing I was doing it, for the first 30 phases. 32 probe env vars (SHADPS4_DC_UBO_SMASH, SHADPS4_DC_PC_SMASH, SHADPS4_DC_DISPATCH_SMASH, SHADPS4_DC_TEX_NUKE_*, SHADPS4_DC_UBO_NUKE, and more). Random batches, hash-based tints, null substitutions. Most of them never pointed at the real fix. But every shotgun round ruled out an entire category of mental model. “Not texture.” “Not push-constant.” “Not those 8 compute pipelines.” “Not the UBO write side anywhere in that region.” Every ruling-out narrows the problem.

And while I was doing it, I was learning the system. Every smash that crashed told me “there’s a critical descriptor pointer here”. Every color tint that appeared told me “this UBO feeds that composition pass”. Every dispatch that fired differently between dim/bright showed me where the interesting boundary lives.

When you don’t know the system, shotgun probes are a map. You don’t use them to find the answer. You use them to learn the terrain.

What I knew on Sunday vs Thursday

Sunday: zero everything. All the areas below were black boxes to me.

Thursday:

• PS4 package format end-to-end (PKG → PFS → param.sfo → disc_info → keystone → npbind). How v1.28 cumulative patches layer on top of a v1.00 base install.
• shadPS4 architecture in outline: src/common, src/core (OS emulation, HLE libraries), src/shader_recompiler (GCN→SPIR-V), src/video_core (Vulkan renderer, buffer cache, texture cache, page manager).
• Full graphics pipeline: G-buffer → forward+ lighting (writes MSAA depth) → read depth as color for SSAO / volumetric froxel → post-fx compute → tonemap → composite → swapchain.
• UBO vs push constant vs descriptor set. When to use each.
• SPIR-V disassembly and re-assembly for surgical patching. How to identify a tonemap compute by its Exp2/Log2 signature.
• Forward+ lighting + MSAA depth resolve + how to implement ReinterpretMsDepthAsColor.
• shadPS4 buffer cache: MemoryTracker, RegionManager, FaultManager. How page faults turn into GPU→CPU sync.
• readbacks_mode: Disabled / Relaxed / Precise. What each tradeoff looks like. Why Relaxed isn’t enough for feedback loops (it only write-protects, not read-protects).
• PS4 OELF → Itanium RTTI → SCE relocation → dynamic linker reasoning, even without actually doing the binary patch (the plan is documented).

I didn’t become an expert in any of it. But I went from total outsider to reasonably oriented operator. And that jump, as I’ll argue below, was the single most valuable thing of the four days.

The AI suggested accepting. The perseverance was mine

I’ve said a few times in this article that “Claude suggested stopping”. I want to be fair and specific: it wasn’t an AI failure. It was exactly the correct behavior of an intelligent tool: when you have something that works reasonably well, stopping and documenting is frequently the right call. The Phase 22+ tonemap patch made the game playable. The Phase 26 UBO pin made the image pretty. The Phase 29 recording harness covered the critical window. All were legitimate stopping points.

If you read codex-conclusion.md, the document the AI produced after Phase 26 (still not knowing about Phase 31 yet), it describes the then-current solution as “a mitigation, not a root-cause fix”. It honestly admits what we knew: the UBO pin was a countermeasure, not an explanation. That’s good behavior.

The difference is that I had a stubborn hunch that something was still wrong. It worked in the playable sense. But the cost (DriveClub-specific pin + tonemap SPIR-V patch + per-track threshold tuning + doesn’t generalize) was too high for a supposedly engineering-quality fix. A senior professional recognizes when the asymmetry between cost and understanding points to something deeper. You don’t always get it right. But that hunch deserves to be heard.

Four days without interruption, 8 a.m. to midnight, Sunday, Monday, Tuesday, Wednesday, resolved Thursday morning. How many times did the AI suggest “honestly, we should just accept the current result and document”? Four or five. Each technically defensible. Human perseverance is the difference between “the game works well enough” and “the game works, and I know why”.

The real cost of this journey

investigation-effort-accounting.md catalogs everything before cleanup. Some highlights:

• 3 days of active work (Apr 21-23, 2026).
• 33 numbered phases + sweeps + side threads = 54 docs, 412 KB, 6,867 lines of prose.
• 44 commits on the gamma-debug fork. 15,668 lines added, 1,204 removed.
• src/video_core/renderer_vulkan/vk_rasterizer.cpp grew from 1,364 to 4,680 lines (3.4×) with instrumentation, pin lifecycles, recording harness.
• 32 probe env vars defined. 1 effectively used to find the bug (SHADPS4_DC_LOG_STREAMCOPY, in Phase 30).
• 61 MB of shadPS4 log accumulated. 57 MB of shader dumps (5,803 files). ~470 MB of total reclaimable artifacts once closed.

Resolution: 1 integer in the config.

The ratio of 6,867 lines of prose : 1 integer amuses me. But it isn’t a joke about inefficiency. It’s the real cost of learning a system you didn’t know. Every line of prose ruled out a hypothesis. Every commit taught a layer of the stack. The integer was the end; the path was the product.

An honest note: despite the 15,668 lines added on the gamma-debug fork, almost none of it is useful to contribute upstream to shadPS4. What’s there is instrumentation: torture probes, recording harness, pin lifecycles, calibrate-at-arm, UBO snapshots, dozens of debug env vars. Diagnostic code, not production code. Diagnostics that only make sense for DriveClub under those specific conditions.

The fork is going to stay public, but not as a contribution branch to the shadPS4 project. Unfortunately. It stays as a study document: 54 md files covering the full process, 44 commits showing the sequence of hypotheses, rule-outs and failures. It’s material for anyone who wants to understand how the debugging process unfolded, or to reuse some of the techniques in similar investigations. No upstream-ready PR is coming out of that tree.

Closing

Yes, the final solution was a config toggle that already existed. It’s been in shadPS4’s code for seven months. But on Sunday night, with zero PS4 knowledge, zero emulator knowledge, zero notion that auto-exposure was a GPU→CPU feedback loop, I had no technical authority to say “flip readbacks Precise, done”.

I had to see the whole chain to understand why it works. Why Relaxed isn’t enough (it only write-protects, and DriveClub reads, it doesn’t write into the histogram SSBO). Why Precise is expensive (per-page mprotect + per-fault GPU stall). Why the maintainer hid it behind “Advanced” (Bloodborne hangs, AMD tanks to 12 FPS). Why nobody in the community had connected Precise to DriveClub before: the compat tracker admits “readbacks enabled” but doesn’t cite the mode, and nobody had seen the monotonic-drift signature through the GPU→CPU lens.

That’s the difference between knowing the answer and knowing the terrain well enough to recognize the answer. To the junior asking me “how do I learn today, in the AI era”: that’s my answer. Don’t ask. Dive in. Use AI to speed up the search, to read code in parallel, to index old forums, to compile, to parse logs. But insist on understanding the why. When the AI suggests “let’s accept and document” (and it will, because that’s often the right behavior), ask yourself whether you actually understood the chain. If the itch “this is wrong but I don’t know why” is still there, keep going.

You’re probably going to spend four days on something that has a one-integer solution. You’re probably going to discover five wrong paths before the right one. Probably half your probes will be torture shotguns that never pointed at the fix.

And you’ll probably, when you finish, know a domain you didn’t know before.

• Fork gamma-debug: github.com/akitaonrails/shadPS4/tree/gamma-debug
• 54 investigation docs: docs/driveclub-investigation/
• Operational runbook (recipe): distrobox-gaming/docs/driveclub-shadps4.md
• Phase 31 resolution: readbacks_mode: 2

Now I’m going to go play DriveClub. Night race in Canada, natural brightness, no blackout. Good Thursday.

Two monsters sit at the top of that list. First, Driveclub on shadPS4. It’s a PS4 exclusive, never got a port, Evolution Studios was shut down, no remaster. To play it outside the original PS4, emulation is the only option, and PS4 emulation is still the most immature part of the ecosystem. This is by far the hardest on the list.

Second, Forza Motorsport 4 with Project Forza Plus on Xenia Canary. FM4 is the GOAT of the Xbox 360 era, Project Forza Plus is the community mod that consolidates patches and content, and getting the two to run together on Xenia with decent graphics, no audio crashes and no shadow bugs took serious hours of trial and error.

Around those two I organized the rest of what I already knew worked at some level, just needed consolidating into a reproducible setup: Gran Turismo 4 with Retexture 3.0 and HD HUD, Gran Turismo 3 with HD textures and widescreen, Gran Turismo 2 with the Spec II mod, the PS3 Gran Turismos (GT5 and GT6), Forza Horizon 1 and 2, the PGRs, Ridge Racer, Enthusia, Colin McRae. I had an idea how to make these work, I just needed a setup that doesn’t break the next time I reinstall the system.

Before the details, two things to clarify.

First, on infra: I’m not going to repeat here how the setup was built. I wrote that in detail in An Emulation Distrobox with Claude Code. Arch Linux in a distrobox with --nvidia, 17 Ansible roles, every emulator from the AUR, ES-DE as frontend, automated per-game configs, Python scripts for PS3 update checking and Xbox 360 title updates, Xenia via Wine. Go read that one. The repo is at akitaonrails/distrobox-gaming if you want to reproduce. Here I’m going to talk about the games.

Second, on taste: I like simcade racing. Gran Turismo has been my declared addiction since PS1, and I wrote about the rest in the Formula FX1 cockpit article. Direct-drive wheel, load-cell pedal, triple monitor when I’m feeling masochistic. That’s the kind of racing I like.

The warning for the “well, actually” crowd

Yes, I know iRacing and the rest of the current sims and simcades. I have 12 TB of ISOs and ROMs on the NAS, I probably have one you’d remember to mention. It’s not for lack of options that I’m focusing on emulation today.

On the new side, the games I’m genuinely anticipating: Forza Horizon 6 in Tokyo, Assetto Corsa EVO, and Assetto Corsa Rally. I’ve been playing the demos of both Assetto Corsa titles and enjoying their single-player campaigns a lot. When those ship, they’ll become my main sim rotation. This article covers a different side of the collection, pulling classics out of oblivion that still don’t have a remaster.

Today, here, I’m interested in these specific games I listed above. Period. You do what you want, I do what I want. If you want iRacing, fire up Steam and go in peace. This article is about messing with emulators, preserving old games, and pulling these gems out of oblivion on a Linux setup. If you’re here for current-sim reviews, you won’t find them.

Now to what matters.

A note on the videos: most of them have no audio because I forgot to turn on sound capture in OBS before recording and I was too lazy to re-record. Audio works perfectly on every emulator here; this is my OBS mistake, not a setup issue.

Global settings per emulator

Before the games, a quick consolidation of the global configs that apply across each emulator. This is automated in the repo, but if you’re setting up by hand, here’s the summary.

DuckStation (PS1)

• Renderer: Vulkan
• Internal Resolution Scale: 8x (8K internal, downscaled to the monitor)
• Texture Filtering: JINC2 (preserves pixel art but smooths)
• PGXP: on (fixes the typical PS1 vertex wobble)
• Widescreen Hack: on as fallback, but I prefer per-game widescreen cheats
• Aspect Ratio: 16:9 with widescreen cheat, 4:3 without

PS1 runs smoothly on DuckStation these days. It’s the most mature emulator on the list. The attention goes to per-game choices (some games need a specific widescreen cheat).

PCSX2 (PS2)

• Renderer: Vulkan
• Upscale: 4x SSAA (1440p native → 4K internal)
• Anisotropic Filtering: 16x
• Post Processing: FXAA on, PCRTC antiblur on
• Deinterlacing: Automatic (some games need override)
• Controller: Xbox-style bindings (I use an 8BitDo)

PCSX2 2.7.x is much better than the 2.6.3 still in Arch’s official repo. The AUR’s pcsx2-latest-bin tracks 2.7.x and that’s where texture replacement, modern FXAA and PCRTC antiblur live. If you’re on a different distro stuck on 2.6.3, get the official AppImage.

RPCS3 (PS3)

• Renderer: Vulkan
• Resolution Scale: 300% (generally) or native (for games with upscale issues)
• Shader Precision: Ultra
• Force High Precision Z: on
• SPU XFloat: Accurate
• Multithreaded RSX: on
• Write Color Buffers (WCB) / Read Color Buffers (RCB): off by default (GT-series safety)

RPCS3 is where the most traps are. Each game has a recommended preset in the official compatibility DB. And a heads-up: per-game configs live in ~/.config/rpcs3/custom_configs/config_<SERIAL>.yml. The config_ prefix is mandatory. It cost me time to figure out. RPCS3 silently accepts the YAML and then ignores it if the name is wrong.

Xenia Canary (Xbox 360)

• Build: Canary (master has been stagnant for months, Canary is where development lives)
• Renderer: Vulkan
• Render Target Path: rtv by default, fsi for specific games (PGR4)
• User Profile: created once, persists
• Wine Prefix: dedicated, managed by Xenia Manager

Xenia on Linux runs via Wine, managed by Xenia Manager. There’s no decent native build. It works well, but each game needs specific tuning, and Title Updates have to be pulled manually from archive.org (I wrote a script for that, details in the previous article).

shadPS4 (PS4)

Gets its own section at the end. TL;DR: works for some simple games, Driveclub is still a moving target. Still a shot in the dark.

PS1 on DuckStation

Gran Turismo (the first, from 1997)

This one is pure sentiment. GT1 was one of the first games I bought for the PS1 and I played it until the CD cracked. At the time, it was on another level. Real simulation on a machine with 128K of video RAM, decent physics, 140 cars when everybody else had 15, memorable soundtrack.

But let’s be honest: you can’t go back today. GT1’s physics has exaggerated drift, the car slides more than it should on any corner above 80 km/h. It’s part of the 1997 charm but gets annoying in 2026. The handling model was refined starting in GT2, and everything after only got better. Between GT1 and GT2, GT2 wins on content (650+ cars vs 140) and especially on drivability.

I keep GT1 in ES-DE to open in nostalgic moments, drive 10 minutes at Trial Mountain, and close it. For serious PS1-era gameplay, it’s GT2.

Gran Turismo 2 (Spec II Mod)

The original PS1 Gran Turismo is a historical milestone. I played a lot of it back then. To replay today? No. GT2 exists, and GT2 is superior in everything. More cars (650+), more tracks, more modes, and most importantly, a much better handling model. GT1 has that exaggerated drift where the car slides more than it should, GT2 tightened that up to something closer to what the series would become starting on PS2. Between playing GT1 or GT2, always GT2.

And the GT2 I run today is the GT2 Spec II Mod by Project A-Spec, a community project that merges the two regional variants (Arcade + Simulation) into a single game, brings back events that were cut from the final release, fixes physics bugs, adds native widescreen support, and ships quality-of-life menu updates. It’s the definitive way to play GT2 in 2026. The project doesn’t maintain its own website anymore, updates come through the author’s Twitter.

To run it:

The 8 MB RAM cheat matters for crowded tracks (Seattle in populated races for example) where audio starts clipping. It simulates the memory expansion of the Japanese version that never made it West.

Colin McRae Rally 1 and 2

Iconic PS1 games. CMR1 has that rough first-gen rally feel that has its charm. CMR2 is technically superior, better physics, more rallies, better graphics. But honestly: to play CMR2 today, it’s worth looking for the original PC version. Higher resolution, native 60fps (the PS1 version is locked to 30), direct keyboard/wheel support. Codemasters repacks exist on the internet, a 40-second search will find them. I’m not going to link them, you know where to look.

On PS1 via DuckStation they run smoothly, nostalgia guaranteed, but it’s not where I spend my time.

PS2 on PCSX2

Gran Turismo 3 A-Spec

GT3 was a generational leap. Out of the blocky PS1 world into shaders, decent environment mapping, serious polygon car models, physics that finally started to feel like actual physics. The soundtrack with Feeder’s “Just a Day” opening the game still gives me goosebumps.

The problem is that GT3 has LESS content than GT2. Polyphony was more cautious, cut modes to focus on polish. The A/B/S license tree is smaller, fewer cars, fewer tracks. But what’s there is polished.

In 2026 on PCSX2 2.7.x, GT3 looks great. Community HD textures, widescreen pnach, anti-aliasing via SSAA, 16x AF. Feels like a re-release.

Caveat on the retexture pack: when enabled, some car-showcase cutscenes in the garage have momentary flicker due to NFS streaming. Doesn’t bother in-race. If it bothers you in menus, turn it off.

Reminder: for the widescreen pnach to take effect, you still need to go into the in-game options and switch the aspect ratio to 16:9. The pnach unlocks the option in the menu, it doesn’t apply automatically.

Gran Turismo 4 (Spec II Mod)

GT4 is my GOAT in the series. 700+ cars, 50+ tracks, physics still respectable by 2026 standards, and that soundtrack mixing alternative rock, Japanese lounge, and Moby’s infamous “Sail Away” on the main menu. It’s the game I poured the most hours into back in 2004, and it’s what I play the most today.

Like GT2, the GT4 I run today is not the original disc. It’s the Gran Turismo 4: Spec II maintained by TheAdmiester — a massive community mod that’s objectively the best way to play GT4 in 2026. It combines the final USA disc, the 2003 Beta prototype, and the original Japanese release into one game, restoring cut cars (including several that never left Japan), cancelled events, dozens of missing soundtrack tracks, adding 16:9 widescreen support, over 30 built-in cheats exposed as menu options (pro tuning, top speed, fuel economy), the option to switch between English and Japanese, and original bug fixes. The project is active, still gets patches, and ships its own installer that applies over a clean USA ISO.

In practice, Spec II is what GT4 should have been if Polyphony had six more months to polish. Playing it today feels like GT4 with all the content that got left out, plus modern quality-of-life. For anyone who enjoyed the original, it’s mandatory.

On top of that goes the community’s Retexture 3.0 (HD texture pack) and the HD HUD by Silentwarior112. With those three pieces together (Spec II Mod + Retexture + HD HUD), GT4 runs at 1440p SSAA on PCSX2 2.7.x with 16x AF, FXAA, and a look that’s honestly indistinguishable from a new low-poly-style release. It’s my current favorite to sit down and play long.

Spec II users need to pay attention to the CRC: the vanilla GT4 HD packs were built for 77E61C8A (USA), so on Spec II with CRC 4CE521F2 I symlink the assets into the CRC-suffixed folder that PCSX2 looks for. The widescreen pnach was also renamed to match the Spec II CRC. Without that, the game runs but the mods don’t load.

In-game reminders: same as GT3, the widescreen pnach only unlocks the option, you still need to enter Options in-game and switch to 16:9. And important: change the video mode to progressive 480p (also in Options). The default is interlaced 480i, which looks terrible on a modern screen. Spec II Mod has native progressive support, just flip it on.

If I could recommend a single GT in the series for someone starting today, it would be this one. If you like racing and never played GT4 in full, you’re missing out.

Enthusia Professional Racing

Enthusia is the forgotten Konami game from 2005. Launched in GT4’s shadow and died on the shelves. It’s a shame, because Enthusia’s physics was more realistic than GT4’s. Car weight, mass transfer, limit behavior, all closer to real-world behavior. The sim-racing community of the 2000s knew this and the game has a cult following today.

Enthusia’s problem was the Enthusia Points system: you earned points for driving clean, lost them for crashing, and the game’s progression depended on those points. A lot of people found it punitive. I found it perfect. It forced you to drive with your head.

On PCSX2 with retexture and widescreen, the game looks great. Strong recommendation for anyone who wants something different from Gran Turismo.

Ridge Racer V

Ridge Racer is its own thing. Not simcade, pure arcade. Drift everything, cartoony grip, electronic soundtrack, saturated colors. Ridge Racer V was the Japanese PS2 launch title and it carries that “show what the console can do” vibe, with massive scenery and a sense of speed GT never attempted.

On PCSX2 it runs well, with a catch: car textures sometimes flicker on the hardware renderer (PCSX2 issues #3639 and #13729). Software renderer fixes it but kills performance. I stay on hardware and accept the occasional flicker.

Colin McRae Rally 3, 4, 5 (PS2)

PS2 Colin McRae versions run well on PCSX2 with default configs. CMR3 and CMR04 are good. CMR05 (the last before the rebrand to Dirt) is the best of the three technically. But again: if you’re on PC, look for the native version. The PS2 ports were relatively inferior to PC of the era, ran at lower resolution, and a modern PC with a repack will hit 144Hz easily.

I keep them on PCSX2 just for collection completeness.

PS3 on RPCS3

Gran Turismo 5

GT5 is controversial. Polyphony promised the world and delivered a somewhat fragmented game: gorgeous Premium models next to Standards that were basically HD GT4 cars, a level system some loved and others hated, online that went to mud when PSN service was cut, a Top Gear mode that was weird. The contemporary critical reception was mixed, and I remember entire communities fighting over whether the game was a disappointment or a masterpiece.

For me, it’s a masterpiece. GT5 has the Course Maker (design your own track from real sections), real 24h Nurburgring with dynamic weather, the Moon Rover (yes, a drive-on-the-moon mode), Red Bull X-Challenge with Vettel, and the single-player endurance experience is ridiculously big. Anyone who went deep into the game knows there’s content for a whole year.

On RPCS3 in 2026, GT5 runs really well. Stable, without the serious bugs from years past. It’s the most stable GT I have emulated today.

The Shader Precision Ultra + Force High Precision Z combo kills the typical RSX dithering that made GT5 look grainy on RPCS3 in years past. Without those two, asphalt looks permanently noisy. With them, the game looks clean.

Gran Turismo 6

GT6 is one of my favorites in the series. It came out in 2013 for an end-of-life PS3 while the competition was already looking at PS4. Sold poorly. A lot of people didn’t play it. That’s a shame, because GT6 took the GT5 base, cut the fat (Standards were reduced), added more Premiums, better Moon circuit sessions, dynamic weather on more tracks, physics refinement. It’s basically GT5 polished.

On content, GT6 is comparable to GT4. A lot of old-guard players put GT4 above it because of the PS2-era charm. I stay between the two and go GT6 on a normal day, GT4 on a nostalgic day.

On RPCS3, GT6 has a serious catch: patches 1.06 and beyond regress visually. Black surfaces on cars in the garage menu, flicker in cockpit view, full-screen flashing on certain tracks. The version that works well in 2026 is pinned at v1.05. The repo’s extract_ps3_dlc.py script has a per-title version ceiling specifically to pin GT6 at 1.05 even when PSN serves 1.22 as “most recent”.

Also, Force CPU Blit is mandatory. Without it, full-screen flicker in the menu. The trade-off is the rear-view mirror stays permanently black. I prefer losing the mirror to having the flicker. Anyone who wants the mirror can enable Write Color Buffers, but then resolution drops to 720p native.

In 2026, with these settings, GT6 is in my rotation. Not perfect, but playable enough that I can spend an afternoon doing endurance.

Ridge Racer 7

Ridge Racer 7 was a PS3 launch title in 2006 and the last mainline in the franchise. Arcade like Ridge Racer V, drift-first, electronic soundtrack, cinematic camera. For a PS3 of that era it was a pretty tech demo.

On RPCS3 it runs, but with caveats: requires Write Color Buffers on to avoid lighting issues, and the recommended preset in the compat DB is different from my GT preset. I use a dedicated per-game config. Not my favorite, but it’s there for completeness.

No video for this one, I’ll record later.

Xbox 360 on Xenia Canary

This is the part that caused me the most headaches this Sunday. Xbox 360 on Linux is hostile territory. Xenia runs via Wine, each game needs specific tweaks, title updates have to come from archive.org, and Forza Motorsport 4 specifically had serious problems until recently.

Forza Motorsport 4 (the GOAT)

FM4 is, for a lot of people, the best Forza Motorsport ever released. Polyphony made Gran Turismo, Turn 10 made Forza, and FM4 is the peak of the 360 era. Beautiful car models for their time, well-designed tracks, solid physics without being a hard sim, Autovista mode with Jeremy Clarkson narration, epic soundtrack, and that feeling of the Xbox 360 being pushed to its limit.

FM4 on Xenia was a nightmare until recently. Severe shadow artifacts, constant texture pop-in on the car, grainy pixelated track textures, sky brightness completely wrong (it came out white-blown-out instead of the deep blue of the original), and worst: frequent audio crashes where XMA (the Xbox 360’s proprietary codec) would freeze and the audio would turn into a high-pitched noise until the game hung. I spent hours this Sunday messing with configs, testing builds, searching the xenia-canary issue tracker, testing different title updates.

What unlocked it:

• Latest Xenia Canary build (master is stagnant, Canary tracks active development)
• Render Target Path: rtv (the default works fine for FM4)
• Title Update 1.0.17.0 installed via Xenia Manager (version matters, older ones regress shadows)
• Vulkan GPU with NVIDIA ICD forced (on my hybrid setup with AMD iGPU, I had to hardforce the 5090)

After that, FM4 ran. Not perfectly. Still gets the occasional audio crash (xenia-canary issue #161 open). But it’s playable, and I spent two hours of the Sunday at Top Gear Test Track just admiring the Koenigsegg CCX. Worth every hour of debugging.

Forza Motorsport 3

FM3 is one of the solid entries in the series, sitting between FM2’s rougher charm and FM4’s technical peak. Getting it to emulate was surprisingly annoying, because I was using the wrong ISO.

There are two releases of FM3: the retail (original disc sold in stores) and the Ultimate Edition (all DLCs packaged on a second disc). I was trying to run the Ultimate, which combines both discs into a hybrid ISO that Xenia can’t parse correctly. I swapped to the standard retail + DLCs installed separately via Title Update, and bang, the game ran first try.

Moral: if your FM3 isn’t running on Xenia, check that it’s retail. Ultimate breaks.

Forza Motorsport 2

FM2 is from 2007, first-gen 360. Less refined systems, more basic modeling, but that original Forza charm some prefer to FM4’s sophistication. On Xenia it ran practically out of the box. No special tweak.

Forza Horizon 2

FH2 was the most polished Forza Horizon of the 360 generation (there’s also the Xbox One version, which is technically better, but the 360 has its charm because of the smaller map and more focused progression). Open world in southern Europe, iconic soundtrack, Horizon festival at its peak.

On Xenia it ran without asking for anything extra. Same as FM2.

Forza Horizon 1 (with XE Mod)

Original FH1 runs OK on Xenia, but there’s a community maintaining the Forza Horizon 1 XE Mod, which improves traffic AI, rebalances progression, adds cars that were cut, fixes known bugs, and brings quality-of-life tweaks to the UI. I tested the XE Mod this Sunday and it’s worth it. The game feels more alive and progression feels fairer.

Install details for the XE Mod are on the project site. Basically it’s a patch over the original ISO + a few custom title updates.

For comparison, here’s FH1 without the mod, running vanilla:

The most visible difference is traffic and the variety of situations that come up, but the XE Mod has a lot of stuff you only notice after a few hours.

Project Gotham Racing 3 and 4

PGR3 was a 360 launch title in 2005 and still looks gorgeous today. Urban tracks (New York, Tokyo, Nurburgring, Las Vegas), kudos system, cinematic camera. PGR4 added dynamic weather (rain and snow) and motorcycles (some people love them, I prefer to pretend they don’t exist).

PGR3 on Xenia Canary runs reasonably well with default configs. PGR4 needs a specific tweak: render_target_path_vulkan = "fsi" in the config. Without it, some tracks break with severe visual artifacts (green bars across the screen in snow races).

And PGR4 on NVIDIA has a known audio bug: XMA decoding produces intermittent garbage (open xenia-canary issue, no resolution). Not game-breaking, but annoying.

Ridge Racer 6

Ridge Racer 6 was the Ridge Racer of the 360, skipping the 7 that stayed on PS3. Pure arcade, like Ridge Racer V of the PS2. On Xenia Canary it runs with default config, no special tweak. Fun for short sessions. No video for this one in the article, but it’s in the catalog running.

PS4 on shadPS4: the state of the emulator

shadPS4 still doesn’t have a stable release. The project is under active development, the main branch changes several times a week, and “what works today” can regress on a rebase tomorrow. That said, many games already boot and run well enough. The community list is on the compatibility tracker and grows every week.

The difference between shadPS4 and the other emulators in this article is the kind of effort. PCSX2, RPCS3, Xenia are mature projects where each game has a reasonably up-to-date wiki page. shadPS4 is the opposite: you read a Reddit guide, try to reproduce, discover the guide uses a specific fork (not the official main), or a two-month-old commit, or a firmware with sys_modules symlinked in a particular way, or XML patches applied in a specific order that the author didn’t document. Reproducing a shadPS4 setup from a YouTube video is like trying to solve a Rubik’s Cube blindfolded.

But that doesn’t mean you shouldn’t try. It means you need to treat shadPS4 as a hobby, not a workflow. And if you have the patience, you can pull off impressive results.

Driveclub: the impossible, finally possible

Driveclub is my Moby Dick of emulation. It’s the only PS4 game I really want to run. Released in 2014 by Evolution Studios, had a catastrophic launch (online servers collapsed on day one), got patched over two years until it became one of the best racing games of the generation, and was discontinued by Sony when Evolution was closed in 2016. No PC port. No remaster. No sequel. Only exists on PS4.

And today, after many hours of debugging, it’s running here. Main menu loads, intro plays, races start, controller responds, audio works, daytime tracks visible, night tracks with headlights lighting the road. The video above is real gameplay, stable 30 FPS, v1.28 with DLC content accessible.

Getting here required dismantling several traps. Worth documenting, because most online guides don’t mention any of them.

Trap 1: the FMOD loop error that wasn’t FMOD

When you try to boot Driveclub on shadPS4 straight from the retail PKG, the log hits an infinite loop of:

/app0/audio/fmodstudio/masterbank.bank failed, file does not exist

The first reaction is to investigate FMOD. Some people online spent hours messing with sceFont, libtbb, sceNgs2, convinced it was an audio or HLE lib problem. None of that is the cause. The masterbank.bank file literally doesn’t exist on disk, because it’s packed inside the gameNNN.dat files in a custom Evolution Studios archive format that shadPS4’s VFS can’t read. Same story for fonts, models, shaders. All the game’s content lives inside the .dat files.

The only public tool that parses that format is Nenkai’s DriveClubFS. It’s a .NET app that reads game.ndx (the index) and decompresses the .dat files into loose files. Without that unpack, shadPS4 can’t open anything.

Build detail: the DriveClubFS project targets net9.0, and Arch has net8 and net10. You need to retarget the csproj to net10.0 before building. The exact command is documented in the repo’s docs/driveclub-shadps4.md.

Trap 2: v1.28 is a patch, not a base installer

Like every PS4 update, v1.28 is a patch that layers on top of a base install. The v1.28 PKG ships the updated eboot, new-content .dat files, and patch content (sce_sys/about/right.sprx), but no param.sfo, no disc_info.dat, no keystone. Those metadata files live in the v1.00 base — on a real PS4 they’d already be on disk from the original install.

And there’s more: v1.28’s game.ndx references both the base .dat files and the new ones. Running DriveClubFS against v1.28 alone makes the index point at files that aren’t there.

The cruelest symptom hits later: the game boots, the Qt Launcher shows the tile, you click, the loading screen comes up. Then the game decides no content “has been released yet” and asks you to download. Download obviously isn’t happening because PSN for PS4 isn’t accessible. You get stuck thinking it’s a network bug, when actually it’s missing metadata.

The correct flow is to treat v1.28 as an overlay on top of the base. First, extract the v1.00 PKG into a dedicated dir (CUSA00003.v100-working-backup/ works well, and doubles as a rollback snapshot if some experiment breaks the live install). Then extract v1.28 into staging and symlink the base’s low-index .dat files into the staging dir so DriveClubFS sees the full set. Run the unpack. You get 8018 loose files, ~47 GB.

Move that into the live CUSA00003/ dir, copy v1.28’s updated eboot and new patch content on top, then pull param.sfo, disc_info.dat, and keystone from the v1.00 base. The base’s param.sfo already has APP_VER = 01.28 recorded (because it was the version that received the patch originally), so there’s no version conflict. The v1.28 eboot reads those files and unlocks the content.

Trap 3: the 60fps XML patch produces slow-motion

There’s a community Driveclub.xml patch that makes the game render at 60fps. Intuitively, it looks like pure upside. In practice, the patch rewrites the render rate but doesn’t touch the game’s fixed logic tickrate, which is locked at 30fps. On a real PS4 Pro, the hardware reconciles the mismatch. On shadPS4, it doesn’t.

Result: the game renders smoothly at 60fps, but the physics, AI, audio, race timing all run in slow motion. You press the throttle and the car takes a perceptible two seconds to launch. Looks like a random bug until you understand the mismatch.

Disabling the XML patch is the move (just rename the file to something like .disabled). Without the patch, the game runs at native 30 FPS, same speed as a stock PS4 base. Which is what we want. If someone in the future produces a patch that moves both rates (render + logic), we’ll flip it back on.

Trap 4: pipeline cache has to be on

shadPS4’s default ships with pipeline_cache_enabled = false. On a large game like Driveclub, which has hundreds of Vulkan shaders and pipelines, that means every cold launch recompiles everything. My first launch counted ~864 shaders and ~590 pipelines being compiled in real time. The menu animated at 2-3 fps. A minute later, with everything compiled, it snapped to normal fluidity. Next launch, same from-scratch compilation cycle.

Just enable "pipeline_cache_enabled": true in the global config.json. The first session pays the one-time compilation cost, subsequent sessions read from cache and start up instantly.

Trap 5: TOML silently ignored

shadPS4 migrated from TOML to JSON for per-game configs in late 2025. If you have an old CUSA00003.toml in the custom_configs/ folder, it’s silently ignored, no warning in the log. You think your config is active, in reality you’re running all defaults.

Delete any TOML and use CUSA00003.json. The per-game configs that work for Driveclub are specific and detailed, all documented in the docs/driveclub-shadps4.md of the repo.

Trap 6: controller not detected without hidapi hints

shadPS4’s Qt Launcher calls an internal Shadps4-sdl.AppImage. Without specific SDL hidapi env vars, the controller (8BitDo Ultimate 2 in my case) isn’t detected, even though it works in every other emulator. The fix is to wrap the AppImage in a shell that exports SDL_JOYSTICK_HIDAPI=1 and platform-specific variants (PS4, PS5, Xbox), before executing the original.

Plugging the controller in before opening the Qt Launcher also helps. Hot-plug works during the game, not before.

Trap 7: night tracks are pitch black on upstream

This one needed a code patch, not just config. On upstream shadPS4, Driveclub night tracks came out pitch black. The HUD rendered on top, but the track, the car, everything hidden in absolute black. Not even the car’s own headlights lit anything up.

Investigation pointed at the log repeating 1325 times the message ResolveDepthOverlap: Unimplemented depth overlap copy. The cause: Driveclub uses a forward+ renderer, which writes scene depth into a 4x MSAA D32Sfloat buffer, then reads that same buffer as R32G32B32A32Sfloat 1x for effects like SSAO, volumetrics, and dynamic lighting (headlights). shadPS4 upstream has a path for MSAA → MSAA and for color → color as MSAA depth, but it didn’t have a path for “MSAA depth 4x becomes color 1x” in that specific format. It falls into the final else, frees the buffer, and the shader reads uninitialized memory — i.e., black.

I implemented in my local shadPS4 fork a ReinterpretMsDepthAsColor symmetric to the existing ReinterpretColorAsMsDepth. It’s a tiny fragment shader (ms_depth_to_color.frag) that does texelFetch of sample 0’s depth and writes it as vec4(depth, 0, 0, 1) to the color attachment. Plus a BlitHelper helper and a new else if branch in TextureCache::ResolveDepthOverlap. With that, night tracks light up properly, opponent headlights appear, AO and volumetrics on day scenes get more precise too.

The fix lives on a gamma-debug branch of my fork, ready to become an upstream PR. Until it merges, anyone who wants to race at night on Driveclub on shadPS4 needs to build from that branch. Anyone sticking to daytime can use upstream nightly directly.

What finally worked

All of this is encapsulated in docs/driveclub-shadps4.md in the repo, with the exact step-by-step for extraction, config, and wrapper. The full technical investigation (5 phases, detailed engineering log) lives in the fork’s driveclub-v128-investigation.md.

How playable it is today

Good. The video above is real gameplay, stable 30 FPS, physics responding, audio in sync, HUD correct, v1.28 with DLC accessible. Day races and night races both work (with the MSAA depth fork for night). What’s left as limitation:

• Daytime brightness sits a bit below what the PS4 delivered. Not an emulator bug. I spent hours testing tonemap, auto-exposure, gamma curves, ACES, various post-processing shaders, and in the end discovered the game writes already-correct SDR to the framebuffer. What was missing was the display-calibration pipeline that PS4 firmware 4.0+ applied on the outside, and that Linux doesn’t have. The in-game brightness slider (which on shadPS4 maps to sceVideoOutAdjustColor) works, but only up to the point where the game expected the firmware to pick up the rest. The 5-second dim at the start of a race is also the game’s own cinematic fade-in VFX, not an emulator fault. Accepted.
• Native 30 FPS. No viable 60fps patch (due to the fixed logic tickrate explained above). Stock PS4 speed.
• MSAA depth fix still on the fork. PR candidate ready, awaiting upstream merge.

“Achievement Unlocked”. The game runs, with sound, controller, gameplay, day and night, and I complete a whole race without crashing. That’s a personal milestone. I spent years trying to get this game running on Linux and would always hit a point where I just gave up. Now it’s part of my ES-DE, shortcut on the desktop, sitting there waiting for me to play.

If you want to replicate, the repo is public. Good luck. You’re going to need patience.

“Achievement Unlocked”

I’ve been trying to make these games work, at some level, since each respective emulator came out of alpha. I’ve been running GT2 since ePSXe. I’ve been messing with GT4 since PCSX2 0.9.6. I tried to get FM4 running on Xenia twice in past years and gave up both times. And I looked at shadPS4’s face three times before this Sunday and swallowed hard.

Today it closed. The two monsters that opened this article (Driveclub on shadPS4 and FM4 with Project Forza Plus on Xenia) are running, along with the rest of the Gran Turismo, Forza, Ridge Racer, Colin McRae, and Enthusia collection. All in a single setup, reproducible, automated. I’m now part of the very small group of people who brute-forced their way into emulating Driveclub on Linux, and that alone made the Sunday unforgettable.

The frustration of years wasn’t lack of information. It was the OPPOSITE. Too much information, poorly indexed, scattered across dead forums, YouTube videos that went stale, Reddit threads with solutions for two-year-old emulator versions that don’t apply today, wikis that are out of date on half the pages, and mods with VERY specific requirements of CRC, version, patch, path, setting. Every time I sat down to get one of these games running right, I spent three hours reading conflicting material before writing the first line of config. Worse still when the good material was buried under wrong diagnoses, like the Driveclub FMOD loop everyone investigated as if it was an audio problem when in reality it was Evolution Studios’ proprietary archive format.

What changed in the last year is that Claude Code can be my aggregator. I tell Claude to hit the Xenia issue tracker, the PCSX2 wiki, the RPCS3 subreddit, shadPS4 PRs, cross-reference all that info with the emulator version I have installed, cross-reference with the logs I’m looking at, and give me back the combination that works today. It reads source code when needed, understands why Force CPU Blit changes behavior on GT6, finds which FM4 title update was the one that fixed the shadow bug, discovers that DriveClubFS needs a retarget to .NET 10 before compiling. What used to take three weekends of research now takes an afternoon of assisted execution.

This Sunday is the consolidated result of all that work. distrobox-gaming is that knowledge turned into code, reproducible, automated. Starting on a fresh machine, one ansible-playbook site.yml puts me back in this state in under two hours. Fewer than 10 commands separate “vanilla Arch Linux” from “Driveclub running”.

If anyone wants to contribute, test on different hardware, report a bug, or send a config that’s missing, the repo is open. The more people test on different setups, the more resilient the project gets. If you improve the Driveclub situation (get the MSAA depth fix merged upstream, a 60fps patch that also fixes the logic tickrate, font dumps that don’t need jailbroken hardware), send a PR and I’ll embrace it.

For now, I’m going to do a race in Iceland on Driveclub. Good Sunday night.

On my YouTube channel I even used old games to teach computer science fundamentals. In this Akitando episode about Super Mario and old computers, I explain the 6502, memory maps, the PPU, hardware constraints, and why those games were programmed the way they were. If you never watched it, start there:

The problem is always the same: every few years I decide to set up a new emulation machine, download the main emulators again, and there I go repeating the same masochistic ritual. PCSX2, RPCS3, Eden, Azahar, Dolphin, RetroArch, Flycast, shadPS4, and so on. Each one with its quirks. Each one with its own particular way of wasting hours of your life.

In theory, setting all this up should be fun. In practice, it takes days. And that’s not an exaggeration. Dolphin still manages to be one of the worst because GameCube and Wii controller setups have no standard. RPCS3 requires per-game tuning. Eden needs DLC, updates and cheats in the right place. shadPS4 is a festival of trial and error. When I’d finally finish configuring everything, I didn’t feel like playing anything anymore. I just wanted to close the menus and go do something else.

I’ve been known to say that maybe the fun was the tuning itself. I don’t think that anymore. After repeating this process too many times, I’m done. I want to play the games, not fill out forms hidden inside emulator GUIs.

The problem was never Linux

I’ve solved this kind of thing in different ways in the past. Years ago I ran Linux on the host and a virtualized Windows with GPU passthrough to play inside the VM. At the time that made sense. I made a whole video about it:

But that was before Valve, Proton, modern Wine and the whole open source community pushed the Linux desktop to a much better place. Today you can avoid Windows in most cases. In the other video below I explain the evolution of CPU, GPU, OpenGL, Vulkan, and why we ended up here:

My gaming mini-PC with the RTX 4090 is still my main Steam machine, especially now that I’ve built a proper sim racing cockpit. On it I use EmuDeck, which was born to automate installing and configuring emulators on the Steam Deck, then grew Windows support, and helps cut the complexity of setting up this kind of environment. But my main desktop is also way too powerful to leave underused. It has an RTX 5090, and today I use that GPU mostly to test LLMs and for benchmarking, as I wrote in Testing Open Source and Commercial LLMs. Leaving it idle for gaming would be a waste.

Only on Linux I wanted something else. I didn’t want a black box doing everything for me without me knowing exactly what was being changed, especially on my main PC, which is my work machine. I wanted my own setup, handmade in the right sense: not clicking GUI by GUI, but understanding what’s being configured, keeping the files under my control, and being able to rebuild everything the way I like. I know the NixOS folks will jump in here to say “just use Nix” — I’ll explain why I ruled that out below. I also didn’t want to turn my work machine into a carnival of emulator packages, GTK themes, wrappers, launchers, weird runtimes and configs buried in ~/.config. Nor did I want dual boot or a VM. In 2026, the best answer for this, in my opinion, is Distrobox.

From what the project itself explains, Distrobox is a wrapper on top of podman, docker or lilipod to create containers tightly integrated with the host, with access to HOME, Wayland/X11, audio, USB devices, external storage and GPU. In other words: exactly the kind of pragmatic isolation I wanted. It’s not a security boundary, and the project site makes that clear. Don’t use it thinking about high-security sandboxing. Use it thinking about separating environments without paying the price of a VM.

And before anyone repeats the usual confusion: a container is not a virtual machine. I explain this calmly in this other episode:

The setup

The idea is simple: a vanilla Arch Linux inside a Distrobox called gaming, with NAS paths mounted read-only, Steam library accessible where it makes sense, and all emulators installed inside. Since the container has access to the NVIDIA GPU, audio, USB and other peripherals, I can separate work and gaming on the same machine without practical performance penalty.

The initial bootstrap looks roughly like this:

distrobox create --name gaming --image archlinux:latest --nvidia \
  --home /mnt/data/distrobox/gaming \
  --volume /mnt/data/steam:/mnt/data/steam \
  --volume /mnt/terachad/Emulators:/mnt/terachad/Emulators:ro

Even that first step has a catch. archlinux:latest inside Distrobox comes without [multilib] in pacman.conf, with a misconfigured sudoers, and with the old --nvidia problem: the host driver libs get bind-mounted read-only, so any install that depends on nvidia-utils breaks with file conflicts. Just that alone is the kind of headache that, a few years ago, would make me open half a dozen tabs, a bunch of terminals, and spend a whole night in trial and error.

This time I did it differently.

Claude Code as an infrastructure assistant

I’ve been getting more and more comfortable using Claude Code as my infrastructure assistant on my personal machines. I wouldn’t do this blindly on a client server. But on my own machine, in an environment I can destroy and rebuild however many times I want, it makes all the sense in the world. I wrote about this in Migrating my Home Server with Claude Code, when I used Claude to install and configure openSUSE MicroOS, Docker, NFS, firewall, hardening, and all the rest without me having to remember annoying shell commands.

So I thought: why not do the same thing here?

That’s exactly what I did. I started with a sequence of objective prompts, always asking for two things at once: do the work, and document enough for me to rebuild everything later. The most important history ended up in docs/distrobox-gaming-prompts.md.

A clarification worth making: those prompts on GitHub aren’t my raw messages, the way they came out in real time. After everything worked, I asked Claude itself to rewrite the prompts in a much more organized and detailed way, purely for documentation. The original prompts were much simpler and much less specific. I described the goal and let Claude figure out paths, config files, formats and commands on its own.

The first prompt created the box with --nvidia, a separate --home, and correct mounts. The second solved the three classic problems of Arch inside Distrobox: sudo, multilib, and the nvidia-utils dummy package. The third installed the gaming base, including a detail I would have easily forgotten if I was doing it by hand: pipewire-pulse, needed so several emulators don’t end up mute or out of sync.

The point isn’t the text itself. The point is the method. I don’t need to remember the exact order, the precise options, or where the docs for each detail are. I describe the goal and let the agent carry the piano. I stay in the tech-lead role: watching, reviewing, course-correcting when needed, and telling it to keep going.

The GitHub project

The setup lives in akitaonrails/distrobox-gaming, structured as an Ansible project. 17 roles cover everything from box creation, package bootstrap, config seeding, DLC installation, controller setup, to post-setup verification. The main playbooks are:

• site.yml: full setup from scratch
• reset-configs.yml: reset configs only (useful when you want to wipe tuning and redeploy)
• backup.yml / restore.yml: container snapshot and restore via podman commit
• refresh-shadps4.yml: standalone shadPS4 update
• install-xenia.yml: optional Xenia Manager install (Wine prefix)

Full walkthrough is in docs/rebuild-runbook.md. Package decisions (why AUR instead of Flatpak, for example) are in docs/distrobox-gaming-packages.md.

Why not Nix?

Someone will ask. “You’re recreating a reproducible environment. Why not use NixOS, or at least nix-shell/flakes?”

I considered and ruled it out. The emulator ecosystem I need lives on the AUR. AUR -bin packages are wrappers around AppImages that ship the official upstream binary without compiling anything. rpcs3-bin, pcsx2-latest-bin, eden-bin, duckstation-qt-bin, shadps4-bin — these binaries track upstream practically on release day. On Nixpkgs, many of these emulators are weeks or months behind release, and some don’t exist. Creating a Nix overlay for every emulator I need, maintaining it, and dealing with compatibility patches when upstream changes is work I don’t want to have.

There’s also the mental model. I don’t want to learn the Nix language, the derivation system and the evaluation model just to set up a personal gaming environment. I already know Ansible, roles are folders with YAML tasks, and debugging is ansible-playbook -vvv. When something goes wrong, I read the error, open the task that failed, and know exactly where to fix it. If I needed the same level of reproducibility at scale, across a cluster, with atomic rollback, then Nix would have an argument. For a distrobox with emulators on my personal machine, Ansible solves it with much less friction.

Flatpak was also tested and ruled out. Flatpak’s bwrap (bubblewrap) doesn’t nest properly inside Docker’s mount namespaces, so Flatpak apps simply don’t run inside distrobox. The alternative would be installing Flatpak on the host, but then you’re back to polluting the work machine with gaming packages. Plus, Flatpak versions of emulators lag well behind AUR — the AUR’s pcsx2-latest-bin tracks the 2.7.x AppImage, while Flathub still ships v2.6.3.

Platforms covered

The setup covers 12 platforms today:

RetroArch comes on top to cover the rest (NES, SNES, Genesis, N64, arcade, etc.), with 21 buildbot cores and 8 asset packs (databases, shaders, cheats, overlays, autoconfig).

Frontend is ES-DE. Custom system definitions live in ansible/group_vars/all/esde.yml, and each emulator comes with a wrapper that sets the right GPU environment variables (more on that in a sec).

GPU hardforce for NVIDIA

On a hybrid system with NVIDIA dGPU + AMD iGPU (my case on the desktop), Vulkan sometimes picks the iGPU on its own and you end up with an emulator running at 15 fps while the 5090 sits idle. The fix is to force NVIDIA’s Vulkan ICD in every launcher.

Each desktop entry rendered by Ansible exports VK_ICD_FILENAMES pointing to NVIDIA’s ICD, and the ES-DE wrapper does the same before launching any core. Combined with the --nvidia flag at box creation, which bind-mounts host drivers read-only, the result is predictable: Vulkan always on the NVIDIA dGPU, regardless of system state at runtime.

This mostly matters for hybrid setups. On a desktop with a single GPU, the ICD filtering is placebo, but it doesn’t hurt.

PS2: PCSX2 with per-game tuning

The Gran Turismo line is my declared addiction. Each version needs its own specific tweak. The PCSX2 setup today has sane global configs (Vulkan, 4x SSAA, widescreen 16:9, Xbox-style bindings, FXAA + PCRTC antiblur, 16x anisotropic, Automatic deinterlace) and per-game INIs for the titles I actually play:

• Gran Turismo 3 A-spec (SCUS-97102 + bundle PBPX-95503): widescreen pnach, optional retexture pack (disabled by default because NFS streaming causes flicker in car-showcase cutscenes)
• Gran Turismo 4 USA (SCUS-97328): Silentwarior112 HD HUD, full retexture pack, Silent’s trigger/cam patches, widescreen pnach
• Gran Turismo 4 Spec II (SCUS-97436, CRC 4CE521F2): special case — the vanilla GT4 HD packs are linked via symlink because Spec II has the same structure but a different CRC. Widescreen pnach renamed to match the CRC. Deinterlace mode 8 (Adaptive TFF), ShadeBoost tuning (+10 saturation, +3 brightness, +2 contrast) to fix pause-interlace ghosting and the anemic upscale saturation
• Enthusia Professional Racing (SLUS-20967): HD textures + widescreen
• Ridge Racer V (SLUS-20002): widescreen + no-interlace pnach

Silent’s and community pnach files are downloaded automatically by the pcsx2_textures role, which also deploys the cheats pack from the NAS and installs the Spec II HD packs via symlink. Widescreen is enabled per-CRC via gamesettings (PCSX2 identifies games by CRC before applying pnach).

On PCSX2 versioning: the AUR’s pcsx2-latest-bin tracks the 2.7.x line, which is where all the modern features live (texture replacement, FXAA, PCRTC antiblur). The default pcsx2 in Arch repos is still on 2.6.3. The gap is over 250 commits of fixes and new features.

PS3: RPCS3 with curated per-game configs

RPCS3 has an annoying detail: per-game configs live in ~/.config/rpcs3/custom_configs/config_<SERIAL>.yml. The file format has a version, and if you hand-write YAML with the wrong version, RPCS3 silently rejects it and falls back to defaults. That cost me time to figure out.

The rpcs3_per_game_configs role handles it like this:

1. Queries the RPCS3 community compatibility DB for recommended presets per title
2. Applies curated overrides on top for titles I know need specific tuning (typically GT5 and GT6)
3. Saves the YAML with the exact filename convention (config_<SERIAL>.yml, config_ prefix mandatory)

For the Gran Turismo line:

• GT5 (BCUS98114, BCES00569): Resolution Scale 300%, Shader Precision Ultra, Force High Precision Z, SPU XFloat Accurate, Multithreaded RSX. The combo kills the typical RSX dithering without breaking the GT-series safety config (WCB/RCB off).
• GT6 (BCES01893 + regional variants): special case, version pinned to v1.05. Patches 1.06+ regress with black surfaces on cars in the garage menu. The extract_ps3_dlc.py script has a per-title PATCH ceiling specifically to pin GT6 at 1.05 even when PSN serves newer patches. Also, Force CPU Blit is mandatory (without it, full-screen flicker). The trade-off is that the rear-view mirror stays permanently black — turning WCB on would restore the mirror but downgrade to native 720p. I’ll take no mirror.

More details on those two in docs/gt5-rpcs3.md and docs/gt6-rpcs3.md.

PS3 update checker

To avoid opening RPCS3’s GUI and clicking Download Game Updates game by game, I wrote a Python script: check_ps3_updates.py. It walks the games installed in dev_hdd0/game, parses PARAM.SFO to get the current version per title, queries the PSN update server (a0.ww.np.dl.playstation.net), and compares against the local patch cache. --list shows the diff; --download fetches what’s missing. --max-version respects per-title ceilings (e.g., 1.05 for GT6).

The first scan of my library found 51 of 72 games with updates available, 69 patches missing locally, ~24 GB in total. GT6 alone had 16 missing patches from 1.07 to 1.22, which I skipped for the reasons above.

Patches arrive as PSN packages type 0x0001 without encryption, so extract_ps3_dlc.py handles the install. Standard call:

distrobox enter gaming -- python3 scripts/extract_ps3_dlc.py \
  "/mnt/terachad/Emulators/EmuDeck/roms_heavy/ps3-DLC" \
  --dest "/mnt/data/distrobox/gaming/.config/rpcs3/dev_hdd0/game"

Tracking PS3 DLC versions manually, game by game through RPCS3, is impractical. It becomes an infinite to-do list, and you only find out there was a 1.22 patch when the game crashes.

PS1: DuckStation per-game

The Gran Turismo trilogy starts on PS1, and quality there only goes up if you enable the right things:

• Gran Turismo (SCUS-94949): DuckStation’s built-in WidescreenHack (no cheat exists for this game), PGXP enabled
• Gran Turismo 2 Simulation (SCUS-94455): widescreen cheat + 8 MB RAM cheat (fixes audio issues on crowded tracks), JINC2 filter
• Gran Turismo 2 Arcade (SCUS-94488): same treatment as Simulation

Global defaults: Vulkan, 8x upscale, JINC2 as the default filter.

GT2 cheats come from a widescreen-fixes repo and are linked automatically into DuckStation’s cheats folder.

Switch: Eden with DLC, update and cheats

On Switch, eden-bin is the emulator. The integration automates three things I used to do by hand:

1. DLC and update install: the install_dlcs role points to the dumps directory on the NAS, identifies .nsp/.nsz/.xci/.xcz files, and installs everything into ~/.local/share/eden/nand/user/Contents/registered/. If the dump is messy (patches and DLC mixed in a flat folder), the reorganize_switch_nsps.py script sorts everything by Title ID first.

2. Atmosphere cheats: Atmosphere-format cheats get symlinked into Eden’s load path (~/.local/share/eden/load/<TITLE_ID>/cheats/). The switch_cheats role handles this for every title covered by the NAS pack.

3. Update checker: check_switch_updates.py lists titles with updates available against what’s installed locally. Useful so I don’t miss important patches for games still getting updates.

A detail that burned me: QT_STYLE_OVERRIDE needs to be unset before launching eden-bin, otherwise it conflicts with Kvantum and breaks the UI. The wrapper does the unset before exec.

Xbox 360: Xenia Manager via Wine

Xbox 360 is still rough territory on Linux. There’s no decent native emulator. The best route today is Xenia running through Wine, managed by Xenia Manager.

This is opt-in in my setup. The install-xenia.yml playbook creates a dedicated Wine prefix, downloads Xenia Manager, and registers launchers. It’s not part of the main site.yml because not everyone wants Wine in the mix.

Project Forza Plus (Forza Motorsport 2/3/4)

Old Forza is still the king of previous-gen simcade. Running FM2/3/4 on Xenia requires the Project Forza Plus community mods: compatibility patches, performance mods, specific title-update installs. I documented the process in docs/project-forza.md.

Project Gotham Racing 3 and 4

PGR3 runs reasonably well on Xenia Canary. PGR4 needs a specific tweak: render_target_path_vulkan = "fsi" in the config, otherwise some races break with visual artifacts. Setup documented in docs/xbox360-pgr.md. PGR4 audio on NVIDIA still has an XMA decoding issue that produces intermittent garbage. There’s an open xenia-canary issue, no resolution so far.

Batch Title Updates

Title Updates for Xbox 360 games were distributed via Xbox Live, which has been shut down. The alternative is archive.org, which has the complete catalog preserved. I wrote scripts/download-xbox360-tus.py to automate:

distrobox enter gaming -- python3 scripts/download-xbox360-tus.py \
  --src /mnt/terachad/Emulators/EmuDeck/roms_heavy/xbox360 \
  --dest /mnt/terachad/Emulators/EmuDeck/roms_heavy/xbox360-updates \
  --dry-run

The script needs the internetarchive CLI authenticated (ia configure once, stores the token). It scans the games folder, matches against the archive.org manifest (cached locally), prioritizes by region (USA > World > Europe > Japan), and downloads via ia download --checksum with automatic retry. The resulting .zip files go to Xenia Manager via Manage → Install Content, which extracts into the correct directory (000B0000/).

Full setup in docs/xbox360-title-updates.md.

Steam in the distrobox

Since Proton became a first-class citizen on Linux, it makes sense to have Steam in the gaming box too. I added the steam package via Ansible (which pulls in multilib and 32-bit deps), mounted /mnt/data/steam read-write so the library persists outside the container, and created a host-side launcher.

In practice, this lets me run Steam games via Proton side-by-side with emulation, without switching environments. The mini-PC with the RTX 4090 is still the main Steam machine in the sim racing cockpit. The desktop is fallback and a test environment.

Shell and controllers

Minimal in-box shell

When I distrobox enter gaming, I want a decent prompt even for quick troubleshooting. I installed zsh + starship with a minimal config, zero exotic plugins. It’s not my full dev setup, it’s just “a prompt that shows path and git branch without embarrassing me”.

Dolphin and the modern-controller hell

Dolphin has always been the king of manual friction. If you use a modern controller, like my 8BitDo Ultimate 2, you have to remember how I like the GameCube mapping, how I adapt the Wii Remote, when to use a Nunchuk profile, when to switch to Classic Controller. I don’t have the patience to rebuild that by hand every time. Profiles are pre-built in config/emulator-overrides/dolphin/Profiles/ and copied by the seed_configs role. Details in docs/controller-hotkeys.md.

A few stumbles that stuck around

Not everything became magic. Emulation always has banana peels.

Flycast, for example, has an irritating trap. The emu.cfg file uses rend.* keys inside the [config] section. If you create a separate [rend] section, it looks right, but the emulator just ignores it and later rewrites everything with mediocre defaults. The fix became a dedicated wrapper at $DG_BOX_HOME/bin/flycast-hires:

$DG_BOX_HOME/bin/flycast-hires \
  -config config:pvr.rend=4 \
  -config config:rend.Resolution=2880 \
  -config config:rend.EmulateFramebuffer=no \
  -config config:rend.WideScreen=yes

Details in docs/flycast-resolution.md.

shadPS4 is still far from a closed case. The current setup is focused on Driveclub, with a mirrored config, XML patch and sys_modules links from firmware 11.00. And that wasn’t random: I really like Driveclub. It’s practically the only game still stuck on PS4 that I really wanted to get running properly. I’ve seen several YouTube videos showing the game working, but so far I haven’t been able to get it running satisfactorily on Linux myself. Documented in docs/driveclub-shadps4.md. The good part is that I no longer depend on muscle memory to remember how to launch it, with which patch, in which folder, with which modules. The bad part is that PS4 emulation is still PS4 emulation. No script makes upstream mature faster. If anyone knows how to close this setup on Linux, check the project on GitHub and send a PR.

Ridge Racer V has car-texture flickering documented in PCSX2 issues (#3639, #13729). The Hardware renderer is acceptable for a racing game where you’re not standing still admiring the model. Software renderer fixes it but kills performance. I chose to live with the flicker.

The real gain isn’t just automation

It’d be easy to sum this up as “look how cool, I used AI to automate shell scripts”. That’s not it.

The real gain is more mundane and more important: I stopped spending mental energy on manual work. I didn’t have to remember rare commands. I didn’t have to keep dozens of tabs of wiki, issue, forum, README. I didn’t have to leave half a dozen terminals scattered tailing logs while I try to remember which hidden GUI option the emulator insists on overwriting on the first boot. I started working in conversation.

I tell the agent the goal. It looks up the files, reads the logs, finds the right config format, compares defaults, proposes fixes, writes scripts, validates paths, checks UID/GID, verifies broken symlinks, generates wrappers, exports launchers. I’m still responsible for decisions, of course. But I stopped being a typist of rare commands.

That’s the point that interests me most about using coding agents on Linux. They dramatically reduce the entry friction. A lot of people bounce off the Linux desktop not because the system is incapable, but because the tuning curve has historically been too irritating. Having an assistant capable of reading docs, cross-referencing configs, proposing automation and executing under supervision changes that game.

If you want to reproduce

The repo was published for this:

git clone https://github.com/akitaonrails/distrobox-gaming.git
cd distrobox-gaming/ansible
ansible-galaxy collection install -r collections/requirements.yml
cp host_vars/localhost.yml.example host_vars/localhost.yml
$EDITOR host_vars/localhost.yml  # adjust paths for your machine
ansible-playbook site.yml

Xenia is opt-in:

ansible-playbook install-xenia.yml

Read the README.md and docs/rebuild-runbook.md first. I don’t distribute ROMs, BIOS, firmware or keys. The repo only detects, links and configures what you already have on your own machine.

If you prefer the Claude Code route

My recommendation is simple:

1. Start with the goal, not the command. “I want an Arch distrobox with NVIDIA GPU, separate home, ROMs read-only and Steam rw” beats dumping a half shell command without context.
2. Always ask it to document what it’s doing. If it works, promote the result to a script or role. If you don’t document, you just manufactured a throwaway hack.
3. Work in phases. Box creation. Bootstrap. Emulator config. Launcher export. Verification. That’s exactly how I broke down the problem.
4. Ask for objective checks. command -v, file existence, broken symlinks, UID/GID, ROM paths, audio, GPU. The best automation is the one that fails early.
5. Don’t use the agent as a command parrot. Use it as a technical assistant. You still review the decisions and tell it to adjust course.

For me, that was the gain. I went from zero to a much more complete emulation machine without having to customize everything by hand, GUI by GUI, one window at a time. And this time, I finished with energy left to do what I wanted from the start.

Play.

I finally decided to compile a list with the channels I watch the most, along with a list of the main playlists and example videos from each channel that I recommend watching.

I’ll probably keep coming back to this page to update it from time to time. If anyone remembers one I forgot, send it in the comments. There are channels like GameSack, Sega Lord X, Retro Game Corp, Wullfden, Macho Nacho Productions, and several others I didn’t list, because they lean more toward “reviews” and don’t overlap as much with “dev”. I tried to focus on things I think a “dev” should know.

List (2025-05-19)

• Usagi Electric
  • Playlists:
    • Bendix G15 Vacuum Tube
    • Data General Nova
    • DEC/PDP-11
    • 1-Bit Computer
• Tech Tangents:
  • Playlists:
    • Data Generals
  • Videos:
    • Tandy 1000 RL HD
    • CP/M on Model 100
    • KayPro IV
    • HP Series 200 - CAD Monster
    • 8088 PC Networking
    • FreeDOS on IBM 5150
• The 8-Bit Guy
  • Playlists:
    • Commander X16
    • Game Development - Making of Planet X2
    • Texas Tech History
    • Commodore History
• Adrien’s Digital Basement
  • Playlists:
    • TRS-80 Model II Repair Series
    • Amiga 4000 Repair Series
    • ZX Spectrum
    • IBM 16-bit machines
    • Apple Computers - 8-bit
    • Macintosh Machines - 68000
    • Commodore - 8 bit
    • Commodore 64 Repairs
    • Tandy 1000 Series
• clabretro
  • Playlists:
    • Home Lab
    • Sun Microsystem Stuff
  • Videos:
    • Ressurrecting an IBM PS/2 Model 50Z
    • Windows NT 4.0 on a Compaq Proliant Gen 1
    • Token Ring Networking
    • Early 2000s Linksys Wi-Fi Gear
    • Compaq Proliant Gen 1
• LowSpecGamer
  • Playlists:
    • All Lore - Chronological
    • Chip WarsNintendo Lore
    • The Yokoi Saga
  • Videos:
    • How Amateurs created the world’s most popular processor - History of ARM Part 1
    • ARM’s Secret Weapon - History of ARM Part 2
    • How IBM Invented the PC, then everyone stole it
    • The Great Calculator Wars of the 70s
• Ben Eater
  • Playlists:
    • Build a 65c02-based computer from scratch
    • Building an 8-bit breadboard computer
    • Networking Tutorial
    • Error detection
• javidx9
  • Playlists:
    • NES Emulator from Scratch
    • Code-it-Yourself - TETRIS from scratch
• Gaming Historian
  • Playlists:
    • Video Game Hardware
    • The Story of Super Mario - Documentary Series
    • History of Wolfenstein
    • History of Sonic the Hedgehog
    • History of Super Smash Bros
    • Games
    • Gaming Historian
• Modern Vintage Gamer
  • Playlists:
    • Mistakes Were Made - Game Console Security
    • The Sony Playstation
    • The Original XBox
    • Doom Switch Port
    • Retro Reviews
  • Videos:
    • N64: Decomp vs Recomp vs Ports explained
    • XenonRecomp
    • Game Genie Explained
    • Super NES Graphics
    • N64 Emulation is a Mess
    • The First Amiga Virus
    • 35 Years of Game Boy
    • Video game piracy in the 80s
    • Doom SNES Sourcecode
    • How Graphics worked on the Game Boy
    • How UltraHLE changed N64 emulation forever
    • How Diablo was completely Reverse Engineered without source code
    • Duke3D on the Amiga 600
• Strafefox
  • Videos:
    • Video Game Development Through the 80s
    • The 3D Revolution in 90s game development
    • The Making of Sonic the Hedgehog
    • The Making of Mortal Kombat
    • The Making of Castlevania Symphony of the Night
    • The Making of Donkey Kong Country & Killer Instinct
    • The Making of Aladdin
    • The Making of Streets of Rage
    • The Making of Street Fighter II
    • The Making of Super Mario World
    • The Making of Star Fox
    • How Video Games were Made - Part 3
    • How Video Games were Made - Part 2
    • MSX Konami Games
• GTV Japan
  • Playlists:
    • The GTV Binge Watch
    • GTV’s Greatest Hits
  • Videos:
    • The Story of Chrono Trigger
    • The Final 16-bit Fantasy
    • Sonic Mania Day
    • The History of Sonic - 30th Anniversary
    • The Super Story of Mario World
• Displaced Gamers
  • Playlists:
    • Game Genie: Uncorked
    • Talkin’ Code
    • Behind the Code
    • Gaming Tech Talk
• Retro Game Mechanics Explained
  • Playlists:
    • Super Mario 2
    • Super Mario Bros.
    • Super Mario World
    • Super Mario Bros 3
    • Super Mario Land 2
• The Cherno
  • Playlists:
    • Ray Tracing Series
    • OpenGL
    • Code Review
• Kosmic
  • Playlists:
    • World Record SpeedRuns
    • Super Mario Bros
• Kaze Emanuar
  • Playlists:
    • SM64: Last Impact - Developer Commentary
  • Videos:
    • Mario 64 breaks after 7 days
    • Perfecting Random Number Generation on N64
    • Planetary Gravity is Cheap
    • The Genius of N64 Cache Instruction
    • The N64 has more RAM than you think
    • Why Devs need to know about Render Matrices
    • Better engine, Better graphics
    • The Folded Polynomial
    • Fastest Sine on N64
    • Fixing the Entire SM64 source code
• James Lambert
  • Videos:
    • Can Portal64 be saved?
    • Portal 64: First Slice, is out of beta
    • How I optimized Portal to run on the N64
    • How I implemented MegaTextures on real N64 hardware
    • I rewrote Portal from scratch and solved the Portal Paradox
    • How are toon shading and dynamic shadows possible on the N64?
    • How can Nintendo 64 run Portal?
• Veritasium
  • Playlists:
    • Computing
  • Videos:
    • I build a QR code with my bare hands to see how it workds
    • Exposing the flaw in out phone system
    • The Trillion Dollar equation
    • The Most Important Algorithm of All Time
    • Math’s Fundamental Flaw
    • The Bayesian Trap
    • How Does a Transistor Work
    • How to Make a Quantum Bit
• 3Blue1Brown
  • Playlists:
    • Convolutions
    • Probabilities of Probabilities
    • Differential equations
    • Essence of Calculus
    • Essence of Linear Algebra
    • Neural Networks
  • Videos:
    • But what is a quantum computing - Grover’s Algorithm
    • Where my explanation of Grover’s algorithm failed
    • Large Language Models explained briefly