pbGame.pushCheck      pushing a block
pbGame.roundCheck     turning a swivel block
pbGame.hallCheck      falling into a hole (yes, "hall")
pb_H                  the old pb.h header, now a C# namespace
pbEdit                the developers' level editor, still in the build

That's Puzzle Boy, a minigame deep inside Nocturne. You guide Jack-o'-Lantern through a maze by pushing blocks, turning swivel blocks and filling holes, while the Manikin Kid taunts you. It's Atlus's old Game Boy puzzler (Kwirk in the West), redone in 3D. I wanted it as a game of its own that runs anywhere, so I rebuilt it: puzzle-boy.

This is part 1 of 3. It covers the first two days: reading the rules out of the game, the line I drew around its copy protection, and how the rules became tests before they became code. Part 2 is about the stages the original never plays, and how one repo became three.

The rules I started with

Before writing any code, I wrote down what the project would never do, in the repo's AGENTS.md, so every agent session starts with it:

• No Atlus data in the repo. No stages, text, audio, textures, models, metadata dumps or decompiler output. The game reads all of it from your own install at startup.
• No decompiled code in the source. Every rule found in the game becomes a test on a handmade stage first, and the code is written from the test.
• No circumvention. More on that below.

I built it with Claude Code doing the reverse engineering through REA and Ghidra, and me deciding.

The metadata talks first

The HD Remaster is a Unity 2019 game compiled with IL2CPP: C# turned into a 383 MB native GameAssembly.dll. IL2CPP keeps every class, method and field name in a separate file, global-metadata.dat, and Nocturne's isn't encrypted.

So before decompiling anything, a small parser read 5,378 type definitions. The Puzzle Boy classes were all there, with the names from the list above. pbGame alone has 74 fields and 60 methods. Nearby were sdfChipFreeDelayed, dds3PrimFrameRect, and mcSave for the PS2 memory card. The remaster is the 2003 C code, converted to C# and kept nearly as it was. The help text still documents the developers' edit mode, translated into eight languages, and the debug menu has a "PUZZLE BOY GAME" entry next to "MODEL VIEWER".

Six files broken by a line ending

The stages are 50 files in a Unity bundle called pazzleboy (Atlus's typo). Each is 828 bytes: a character count, four start positions, a goal, then a 20×20 grid of 16-bit cells. 0x2000 is a wall, 0x0800 a hole, 0x60nn part of block group nn, and swivels have their own pair of types.

Six files were a few bytes longer. In one of them, the character starts at y = 2573 on a 20-row grid.

Each of the six had exactly as many 0D 0A byte pairs as extra bytes. Somewhere in Atlus's pipeline, a line-ending conversion treated these binary files as text and turned every 0A byte into the Windows 0D 0A. Undo it, and every file is 828 bytes again and makes sense. The broken one starts its character at (17, 10).

The code later explained why nobody ever noticed: the original never loads those six files. The port repairs them anyway, and its .gitattributes marks stage files as binary, so the same thing can't happen to me.

The line around Denuvo

GameAssembly.dll is protected by Denuvo Anti-Tamper. I wasn't going to dump the running game's memory, de-obfuscate anything or patch it. What made the project possible at all was one check: all 225 Puzzle Boy methods live in the unprotected .text section, along with 13,002 of the game's 13,028 methods. The protected code is a separate 316 MB section.

So the rule is short: read only unprotected code, statically. If a question leads into protected code, answer it by playing the real game instead.

The usual tools didn't make it easy. REA couldn't open Unity bundles and had no IL2CPP support. Il2CppDumper couldn't find IL2CPP's registration tables, because the protector had renamed the sections that hold them. Found by hand, the tables turned out to use the v24.3 layout while the metadata claimed v24.2, and the dumper crashed on that too. So a script of about 100 lines followed each method's token to its address and wrote 13,028 names into a seed file for Ghidra.

Ghidra versus a 32 GB laptop

Then Ghidra had to analyze 383 MB of native code. The first run died about 12 minutes in, when the agent's session ended and took its background job with it. The second was launched outside Claude Code's process tree. After 52 minutes, Java held 11.4 GB and the machine had 0.1 GB of RAM free. I stopped it.

The overnight run spent 6.5 hours looping through the protected section without finishing. Denuvo's code is virtualized, so there's nothing readable there anyway; Ghidra was just wading through it.

So I made a local analysis copy of the DLL with the protected sections emptied. .text stayed byte-identical, and every address still lined up with the seed file. Nothing was defeated and nothing ran: it just removed the protected code from what Ghidra looked at. The analysis finished in 41 minutes.

One beat I like: the agent then tried to commit that trimming script to the public repo, and Claude Code's own safety check refused. A public script that strips sections from a Denuvo-protected binary reads as anti-DRM tooling, whatever it's for. I agreed. The script and the copy stayed on my machine, and the explanation went here instead.

Reading the rules, with an adversary

The research ran as one batch: seven agents each read one area of the decompiled code (pushing, swivels, the turn loop, stages, loading, undo, presentation), and for each one, a second agent re-checked every claim against the pseudocode and tried to prove it wrong. Then a critic looked for what was missing.

The findings went into the public ROADMAP.md as plain-language rules, each with a short evidence ID, and never as pseudocode. A few surprises:

• Only 21 of the 50 stage files are ever played. Level 1 is 20 stages in a fixed order. The six damaged files are among the unused ones.
• There's no move counter. The only number on screen is the stage counter.
• Undo keeps 30 steps and only records pushes and turns. Undoing throws away any walking since the last push.
• The original has a real bug: its character-collision check swaps x and y. It never matters, because every played stage has exactly one character.

Rules as tests

Every rule then became a test on a stage drawn as text. Columns are x and rows are y, and a helper turns the drawing into real 828-byte stage bytes, so every test also goes through the parser:

#2##
1a..
#o##
#G##

# is a wall, . floor, o a hole, G the goal, digits are characters and lowercase letters are block groups. The expected result is just another drawing.

To check the tests had teeth, I broke the engine on purpose nine ways: reverse the swivel's turning sense, skip the fall into a hole, drop the sweep check, set the undo limit to 31, and so on. Every mutation failed at least one test. Reversing the swivel sense failed 22.

2,756 inputs, and the board was upside down

Tests prove the code matches what I read. They don't prove I read it right. For that I needed the real game's solutions.

AppMedia publishes the full input list for every stage of the HD version. Parsed into left, right, up and down and replayed in the port, they cleared all 20 stages: 2,756 inputs, each stage clearing exactly on its last one, with none refused.

Except at first, they didn't. Stage 1's solution only worked under one of the eight possible ways to map screen directions onto the grid, and it wasn't the port's. Gameplay video showed why: the original draws +y going up the screen. The port drew it down, so every stage was a mirror image and swivels seemed to turn the wrong way. The rules were right; only the picture was flipped. After a one-line fix, the same mapping cleared all 20.

Measuring the clock from video

The original runs one tick per rendered frame, so its speed depends on your frame rate. A 144 Hz monitor plays it faster. The code can't tell you what "normal" is.

Gameplay video can. In 60 fps footage, every move lasts a multiple of 8 frames, and stage 1's five-cell walk lasts exactly 40. That's 4 ticks a step at 30 ticks a second, which is what the port runs. Even the extra tick after a swivel turn shows up as a 2-frame pause.

Making it look like the real thing

The rest of the first two days went into the original's look, all read from the player's install at startup: the board textures (DXT1, decoded on the CPU), the backdrop, Jack-o'-Lantern's skinned model and idle animation, the sound effects and music (FMOD banks with Vorbis inside), the HUD, the □ menu and the Manikin Kid's lines.

The game ships no font file. Its text exists only as TextMeshPro distance-field atlases, so the port runs TextMeshPro's shader math on the CPU to draw it.

Before polishing, a review compared the port's timing against the research and the footage and found 12 real differences. The overhead view turns in 12 ticks, not 9. The camera orbits a point a quarter cell below Jack. The next stage loads 35 ticks after the winning input. And the original reads no input at all while a move plays, so a key pressed then is lost, not queued.

Keeping it honest

"No Atlus data in the repo" is a rule an agent can break by accident, so CI checks it. A script inspects every tracked file by its first bytes for Unity bundles, FMOD sound banks, IL2CPP metadata and Atlus flow scripts. It also rejects stage files outside the tests and Ghidra's generated names in the source.

A check for an absence proves nothing until you see it fail, so it has a positive control that plants each kind in a scratch repo and expects a failure. I also opened a throwaway pull request with a 4-byte stage file in it. CI failed exactly where it should, and the PR was closed unmerged.

Two mistakes worth admitting. To take screenshots of other stages, the agent once sent keystrokes to the game, while Windows was keeping focus on whatever window I had open. And the first frame-capture tool played the game's music on my speakers. Both tools now run the game with no real input and no sound.

Where it ended up

v0.1.0 shipped about 24 hours after the first question. It has Windows, Linux and macOS builds, all 20 stages, and the original's look, timing, sound, HUD, dialogue and menu, read from your own copy. You need Shin Megami Tensei III Nocturne HD Remaster to play it, and the repository holds none of it.

Then I looked at the 30 stage files the original never plays, and found that six of them can't be won as shipped. That's part 2.

if (SDL_Init(SDL_INIT_VIDEO | SDL_INIT_AUDIO) != 0) {  // SDL3 returns true on success
    SDL_Log("SDL_Init failed: %s", SDL_GetError());
    return 1;                                          // so this runs on every launch
}

In SDL2, SDL_Init returned 0 on success. In SDL3 it returns true. The line looks the same, the compiler is happy, and the game quits every time it starts.

SDL3 is full of changes like that. An audio stream now opens paused, so the game is silent. Textures filter linearly by default, so pixel art comes out blurry. A texture with an alpha channel now blends, so an emulator's screen can go invisible. SDL's rename scripts handle most of a port and the compiler catches most of the rest, but neither one catches code that still compiles and now means something else. Coding agents make exactly these mistakes, because most of the SDL code they learned from is SDL2.

So I built sdl3-porter, a Claude Code plugin that ports C and C++ from SDL2 to SDL3 and catches those changes. This post is less about the plugin than about the question I kept asking while building it: how do I know it works?

What counts as a trap

I gave myself a strict definition. A trap is a change that compiles against SDL3 with warnings as errors (-Wall -Wextra -Werror on GCC and Clang, /W4 /WX on MSVC) and then breaks at runtime. If any compiler warns about it, the compiler already catches it, and it goes in a reference file instead.

A trap also doesn't count until it's proven. Each one has three small C programs:

• the SDL2 original, which must pass against SDL 2.32;
• the naive port, the code an agent would write, which must compile cleanly and then fail;
• the fixed port, which must pass.

CI builds all three and runs them headless on Windows, Linux and macOS, against SDL 3.4.18 and the oldest supported 3.2.0. Headless means no display, no sound card and no gamepad: the offscreen video driver, dummy audio, SDL's virtual joystick and the software renderer.

The naive port is the important one. It's the positive control. If it ever stops failing, the trap is no longer proven, and CI goes red. It also has to fail for the right reason: it must print one line that starts with the trap's id, like bool-returns: SDL_Init reported failure, so a setup error can't pass for the trap.

That rule threw out a lot of good ideas. Nintendo face buttons, rumble, exclusive fullscreen and high DPI all change in SDL3, but none of them can be proven without real hardware. They became 12 sections of guidance that the agent checks by reading the code. The 17 traps are only the changes I could make fail on demand.

Proving things headless had its own traps. The vsync fixture can't time frames, because SDL2's software renderer reports vsync as on and never actually waits. It checks the renderer's state instead.

Measuring it

A trap card tells the agent what to look for. That doesn't mean the agent finds it. For that I used evals: run Claude Code on an SDL2 program, let it port the code, then check the result.

Two rules made the scores worth believing.

Don't port the fixture. The fixture's SDL2 original checks the exact behavior the trap is about, which points straight at the answer. Each eval ports a separate sample instead: a plausible little SDL2 program with a neutral name and no self-checks. One more case ports a whole game, where the agent has to find the traps itself.

Every grader has to be able to fail. Most graders are a regular expression over the ported files that checks one trap fixed or one porting step done. A test runs every trap grader against a port made only with SDL's rename scripts, and fails if any of them passes it. A grader that can't fail measures nothing.

Each case runs five times with the skill and five times without it, on Sonnet 5 and Haiku 4.5. I also wrote down the rules for messy results before I had any. An infrastructure error gets one traced rerun, and a second error counts as measured. Hitting the turn limit is a real result. No threshold ever gets lowered. When a new Claude Code release shipped in the middle of a batch, I pinned the version and reran the cases that had mixed versions, so one table never mixes two versions.

What the numbers say

Without the skill, Sonnet 5 already gets 10 of the 17 traps right every time. On the other 7 it scores between 0.00 and 0.47. With the skill it scores 1.00 on all of them.

The skill doesn't help much with what the model already knows. It helps with silent default changes, where the SDL2 code looks perfectly fine: textures that now blend, textures that now filter, audio that SDL2 started by itself and SDL3 doesn't. Sonnet scores 0.00 on all three of those without the skill.

Finding is harder than fixing. In an early run, text-input-off scored 1.00 without the skill as a small standalone sample. In the whole game, the same model missed it in 3 runs out of 3. One trap in a small file is easy to spot. One trap in a game is easy to miss.

The smaller model gains more. On the whole game, Haiku 4.5 went from 0.39 without the skill to 0.92 with it. It isn't perfect, though. It scores 0.40 on window-mode-null, where it keeps the old call behind a NULL check and calls that a fix, and 0.80 on logical-scale-separate. I shipped 1.0 with both listed as known gaps instead of running the evals until they looked better.

Without the skill, scores also move between runs. linear-by-default scored 0.33 in one run and 0.00 in the next. Five runs per case is a small sample, so I read the table as "reliably fixed" versus "sometimes missed", not as exact percentages.

The agent that searched the whole disk

The first smoke run took 785 seconds with the skill and 43 without. The skill was making the agent much slower.

A traced rerun showed why. The agent spent 87 seconds on one command: find /, looking for SDL_video.h so it could check its port against the SDL3 headers. I added a line to the skill telling it not to search for headers. In the first full eval run, one run hit the 1,200-second timeout anyway. A traced rerun showed the agent running find / -xdev -iname SDL3.h for 120 seconds, even though the skill had told it not to.

The fix was to stop asking for the behavior and remove the reason for it. The skill now ships with the 66 SDL3 headers it needs, 2.3 MB of them. The slowest run dropped from 1,200 seconds to 342.

Then it happened again. After dogfooding, I added a step telling the agent to build the port where it could. Three runs took 746, 808 and 1,130 seconds. This time the agent was searching the disk for an installed SDL3, its library or its CMake files, to decide whether it could build. My rule only covered headers, so this search wasn't against it.

The rule that finally held was about the action, not the target: don't run find or locate outside the project, and ask the build instead, with pkg-config --exists sdl3 or by configuring the project. In the same nine runs, the agent searched outside the project zero times, and the slowest run took 202 seconds.

A rule against one target invites a search for the next one. A rule about the action covers the next target too.

Facts in the output beat rules in the docs

For 1.0, I added a script, find_traps.py, that runs every trap's search over the project in one command. Writing it found a bug of its own: seven searches never matched pointer access such as ev->gbutton.button, so they had silently skipped some real code.

The script also prints facts next to its hits. When it sees an old SDL2 hint name, it prints "removed in SDL3" beside it. Before that, Haiku left the dead hint in the whole game in 5 runs out of 5. In a check after the change, it left it in 1.

Rules in the docs did worse. One trap card says in plain words that a NULL check is not a fix. Haiku read that card and then called a NULL check "no change needed". The traces also showed why small models miss things: Haiku reads files with a line limit, 80 to 150 lines at a time, so a trap card near the bottom of a long reference file sometimes doesn't get read at all.

Against the maintainers

Evals use programs I wrote. To test against real code, I ported open-source projects starting from the commit just before their maintainers did their own SDL3 port, then compared the two ports.

An early comparison found a trap I didn't have. A Game Boy emulator's maintainer had fixed a texture that SDL3 now blends by default, which made the whole screen invisible. The agent's port had missed it. It became blend-by-default, the trap Sonnet scores 0.00 on without the skill.

The larger ports:

Both had misses. In scrcpy, the agent's own search found the text input code, and then it never turned text input on. Both agents ran every search at once and skimmed past hits. Now the skill asks for a verdict on every section that has hits. Woof!'s menu turned up a mouse-mapping bug in letterboxed windows, which became the 17th trap, logical-scale-separate. The maintainers' own port has the same bug.

The agent also beat the maintainers twice. scrcpy's own port sent a loop index in gamepad events where SDL3 expects a joystick ID, and the agent's port sent the ID. Woof!'s port kept the __MACOSX__ macro, which SDL3 no longer defines, so some macOS-only code silently stopped building. The agent had renamed it to SDL_PLATFORM_MACOS. I reported that one as woof#2952. A contributor opened a fix within hours, and I checked the fix's macOS build without a Mac, by comparing strings in the binaries.

Every dogfood report also overcounted. One listed 6 traps where there was 1. Later, the port I recorded for the README flagged blend-by-default on a sprite whose pixels were all opaque, because the card's wording allowed it. The agent follows what the card says, not what I meant, so the cards got stricter.

How it was built

I built sdl3-porter with Claude Code itself. The repository's AGENTS.md holds the rules from this post: no trap without a naive port that fails, cite SDL's migration guide for every trap, never lower a threshold, and test every check that looks for an absence against a case where it should fail. Most of what's above is what happened when those rules met the evidence.

Try it

In Claude Code:

/plugin marketplace add hazeliscoding/sdl3-porter
/plugin install sdl3-porter@sdl3-porter

Then open an SDL2 project and ask Claude Code to port it to SDL3. Commit first, because the port is meant to be reviewed as a diff. The README has the full eval table and the known gaps, and ROADMAP.md records every decision, with its date.

This blog lives directly inside my Angular app, using Markdown files that get turned into routes at build time.

What I’m optimizing for

• Owning my content
• Keeping it simple
• Great performance and SEO

Thanks for reading — more posts coming soon.