Introduction

At the end of the Making of the Dialogue Review Exporter, I said there was another challenge waiting.

Play Instinct had left a comment on my original Instagram post alongside Joel's dialogue tool suggestion. They wanted to know if it was possible to build a GB Studio plugin that gave the Adventure scene type full 8-way movement support, different animations when walking diagonally, the ability to fire projectiles diagonally, that kind of thing.

[IMAGE: Play Instinct's Instagram comment]

This devlog is the story of how the Adventure DX plugin got built - what worked, what didn't, and what changed in my methodology between this project and the last one. In each section I'll extract a rule that I think other GB Studio developers trying this kind of AI-assisted workflow can apply directly.

If you haven't read the Making of the Dialogue Review Exporter devlog, I'd recommend reading that first as this one builds on it.

The Challenge: Building a Complex Custom Scene Plugin

The Dialogue Review Exporter was a tool built around GB Studio. It read GB Studio's project files from the outside and produced output a developer could use. It never touched the engine itself.

Adventure DX is different. It modifies the C code that runs on the Game Boy. It adds new scene types to the editor, new settings panels, new script events. Working on a C engine, if something is wrong, you find out when GBS's compiler stops and prints a stack of errors (or worse, when the game silently misbehaves at runtime).

The first thing I had to do was understand what kind of plugin I was building.

GB Studio 4.2 supports exactly three types of plugins: asset plugins, script event plugins, and engine plugins. Adventure DX would be a new scene type that registers alongside the stock ones, with its own settings panel and a handful of custom events to make it easier to use in the GB Studio IDE.

That much I confirmed before writing a single line of code. Which brings me to the first significant change between this project and the last one.

Part 1: From Chat to Cowork

The Dialogue Review Exporter was built in a Claude chat session. Adventure DX was built in Cowork - Anthropic's desktop tool that gives Claude direct read and write access to a folder on your computer, alongside a persistent memory system and a sandboxed shell for running code.

The difference this makes in practice is significant.

In a chat session, every new context requires re-uploading your sample project zip. When a conversation gets too long and you need to start fresh, you have to reconstruct everything, paste in the PROJECT.md, re-explain the terminology, re-share the relevant files. The handover between sessions kind of sucks.

In Cowork, the project folder is mounted. Claude reads files directly. PROJECT.md is there at the start of every session without me doing anything. The engine source is readable without zipping and uploading. When I say "look at how stock GBS handles this in adventure.c," Claude can look.

This changes the rhythm of the work and reduces friction between myself and Claude. I spend less time re-establishing context and more time actually building and iterating on the plugin. The tradeoff is that Cowork can edit your files directly and (when allowed) sweeping changes to your project files can cause you to lose control of your project - which can get out of hand if you let Claude off the leash too much.

The Dialogue Review Exporter project was built without any GB Studio-specific knowledge pre-loaded into Claude. I had to describe everything. This time I had the gbs-skill-pack from the first project - a set of structured knowledge files (SKILLs) that Claude can read to understand how GBS projects work. Two SKILLs, one on building GB Studio tools and one on maintaining those SKILLs. The GB Studio Tools SKILL had some knowledge of GB Studio as I had provided the sample project, prepared a series of dialogue-related examples and discussed how they function to help Claude understand how GB Studio works. A small head start but no where near enough knowledge to easily tackle creating a complex plugin like Adventure DX.

I needed Claude to build on what it already knew by reading engine knowledge from source directly - the actual C files, the actual documentation - rather than relying on my own descriptions of how things worked.

Rule #1: Curate your reference material before you write a single line of code.

I added a 'Resources' folder to the project workspace before beginning any work. It contained:

1. The GB Studio Docs (to help Claude understand the basics of GB Studio)
2. The GB Studio develop branch (downloaded from github to help Claude understand how the more complicated behind-the-scenes aspects of GB Studio work)
3. The GBDK 2020 documentation (which GB Studio is built from - to help Claude understand how the underlying engine functions)
4. The SetProjectileRenderOrder plugin by KirbyKing186, Mico27, and Fredrik Ofstad (as a clean structural reference of how a plugin should be organized), and
5. Hauntology's Platformer Plus as an example of how a complex custom scene plugin's settings panel might be organised.

[IMAGE: The contents of the Cowork project's RESOURCES/ folder]

Part 2: Download Once, Read Forever

I used WinHTTrack Website Copier to download the entire GB Studio Docs and GBDK 2020 documentation sites as a local copy and dropped it into a 'Resources' folder. Claude could then read any page directly as a local file for the rest of the project. 

You might think this is a little excessive, but this step is an important one in my opinion. Without a local copy, an AI assistant working across many sessions will scrape the same documentation site repeatedly - potentially hundreds of times over the course of a project. That puts a considerable amount of pressure on servers that are often run/paid for by small teams or individuals. The GB Studio docs are maintained by a small indie community. The GBDK docs are no different. Neither of them should be absorbing the traffic cost of my AI workflow.

Rule #2: Download your reference documentation once. Don't make Claude fetch it repeatedly.

HTTrack is free, the download takes a few minutes, and it pays for itself immediately. Any documentation site you expect to reference more than a handful of times is worth doing this for. It's better for the servers and the people who maintain them, it's faster for you, and it means Claude is reading a stable snapshot rather than a live page that might have changed since the last session. Something as useful as the GB Studio and GBDK docs would not only be useful for a single project but many - so a single download will support an AI assistant over multiple game projects.

Part 3: Hardware Surprises

With the 'Resources' folder in place, the plugin architecture confirmed and some time spent drawing the 8-direcional player sprite GFX, Claude built the first pass of the plugin. The new ADVENTURE_DX scene type registered in GB Studio, the engine compiled, and the player actually moved diagonally with the right animation. I'll be honest - I didn't expect the first real build attempt to succeed. Given the complexity of the C state machine we were working with, I had braced for a wall of compiler errors but there wasn't one. That being said, there was one detail that needed some attention once I began playing the ROM.

Diagonal movement in GB Studio's stock Adventure scene applies a speed normalisation to prevent the player moving faster diagonally than cardinally. The formula is roughly 0.75x per axis - each axis's velocity is reduced slightly so the combined diagonal total stays closer to the cardinal speed.

What I didn't know (and what isn't obvious from the GB Studio editor) is that the Game Boy can only render sprites at integer pixel positions. Sub-pixel precision exists internally (velocities are stored as fixed-point values), but each frame is drawn at whatever the current position rounds to. With the 0.75x normalisation applied, diagonal velocity per axis becomes 0.75 pixels per frame. The renderer floors that to 0, 1, 0, 1... - and the result is a visible stutter as the player character moves about the scene.

[IMAGE: illustration of stuttering diagonal motion]

As it turns out, this is not a GBS bug but a hardware constraint. GB Studio's stock Adventure scene has the same stutter when the player character moves diagonally. In fact, this is why Link vibrates a little when walking diagonally in Link's Awakening and the Oracle games.

After some thought, I decided to provide the end-user with a few options. Adventure DX's default it to drop the normalisation - diagonal is faster than cardinal, but the player character movement looks smooth. The plugin's diagonal speed option lets users tune the diagonal speed vs amount of stutter:

Smooth - No stutter when moving diagonally but +41% faster diagonal speed relative to cardinal speed.

Vanilla - 0.75x Normalisation, visible stutter but the diagonal speed is close to matching cardinal speed.

Intermediate - A middle ground with mild stutter and +24% faster diagonal speed relative to cardinal speed.

[IMAGE: illustration of the 'Smooth' setting (with a noticable increase in diagonal movement speed)]

Part 4: Building Version by Version

From v0.1 onward, Adventure Scene DX grew iteratively - one feature per version, each one tested before the next was added.

v0.1 was the minimum: the new ADVENTURE_DX scene type registers, the diagonal animation switch works, all stock Adventure features (run, dash, knockback, blank, push) carry over intact. v0.2 added the diagonal speed option. v0.3 added the shoot button and shoot animation states. v0.4 added projectile firing.

[IMAGE: illustration of the shooting mechanic with recoil enabled]

Each version, the process was:

1. Plan the change in chat
2. Discuss the best ways to make the plugin's project settings clear and user friendly
3. Write the code
4. Build and test the ROM
5. Debug if necessary
6. Commit the working state to PROJECT.md
7. Repeat by adding more mechanics and functionality

A few things that came up along the way: 

Diagonal facing buffer (v0.6) - Solves the pet-peeve where stopping a diagonal walk causes the player to suddenly snap to whichever cardinal axis was released last. In other words, when you intend to stop walking diagonally and remain facing diagonally you might end up facing right because you released Down a little earlier than the Right D-pad button for example. A new engine field adv_dx_diagonal_buffer_frames was added to prevent this issue from surfacing and a slider was added to the project settings so the user can adjust how long this buffer lasts to suit their own tastes.

Mode Cycle (v0.7) - Once the shoot and multi-shoot mechanics as well as a strafe movement mode were added, there were a lot of unique mechanical options available to the devloper (on top of the vanilla run, dash and blank states, too). A limiting factor still existed though - the small amount of buttons on the Game Boy...

So I thought it best to create some kind of system that could cycle through different mechanics using a single button, thereby allowing a developer to include all the mechanics during game play with ease. I later expanded what would become the Mode Cycle system so that you could configure what mechanics were added for even more precise design control.

[IMAGE: illustration of the Mode Cycle System]

Rule #3: Think deeply about the design of the plugin itself - while Claude's strengths help with coding, it will need guidance and original thought from you when it comes to design. Good thing game developers are good designers by nature!

Part 4: Playtester Feedback

Play Instinct (who had originally suggested the challenge) became the first external tester. Their feedback drove a significant portion of the later development.

The most consequential piece of feedback was on the Mode Cycle. What had started as a simple "press a button to cycle between Run, Dash, and shoot modes" had become complex enough that the behavior wasn't always obvious from the Settings panel alone. Play Instinct's feedback helped to clarify how the mode system should work in a game play sense as well as helped me deetermine how the setting design could be improved and made more user friendly.

The second significant tester contribution came from ProtoPixel, who found a dialogue text rendering issue that caused dialogue text to render on the background layer instead of the dialogue box/overlay layer under certain conditions. After some help from Mico27, who found a bug involving GBS's EVENT_MENU and the text layer. After reporting the bug to the GBS dev team via github, it was determined the bug was a result vanilla GBS behavior and fixed ready for the next GB Studio release.

[IMAGE: The dailogue rendering on the background layer (right) instead of the intended overlay layer (left) as a result of an edge case bug in GBS]

Rule #4: Extensive playtesting before release. Same as always.

Part 5: A Surprise Companion Tool

Around v0.11, when I was creating the mini-game and adding Gardener Greg and the Turnip Targets to the scene, I decided I needed to switch the example project's sprites from 8×16 tile mode to 8×8 tile mode. The diagonal animations were taking up a lot of room in VRAM and I realized I could create a little more VRAM space by switching sprite modes.

In GBS 8×16 mode, each sprite tile occupies a 16-pixel-tall slot. In 8×8 mode, the same content needs to be split into two 8-pixel halves, stacked in a specific order. When you switch tile modes mid-project, the editor doesn't migrate your existing sprites - each tile ends up as the bottom half of a now-shorter slot, with what was the top half now non-existent on the sprite canvas. The only fix is to go into each sprite, shift the existing tile up, and add a new tile below it with the right source slice. With seventy-four animation frames in the player animation states, that is a lot of tedious work to complete.

Because GB Studio sets the sprite mode to 8x16px by default (and that is more often than not perfectly fine for most projects), the moment a developer decides they need to switch to 8x8px sprite mode is some way into the development process - when many animation states are already set up to suit 8x16px sprite mode. Reworking an entire project's worth of animation frames is a daunting task and the decision to compromise animation detail is often the easier choice to make.

This issue has actually hindered me in the past. When I was producing Feed IT Souls: DUAL during GB Compo 25, I was constantly hitting sprite limits trying fit as much animation detail as I could for each fighting character. I spent a lot of time optimizing the 8x16px sprites in an attempt to reduce the space VRAM, so much so that I ran out of time before I could fit Musk Rats sprites into VRAM. There were many occasions where I thought about making the switch to 8x8px Sprite Mode, but I couldn't bring myself to spend the necessary hours of manually repositioning hundreds of sprites and animation frames over multiple characters during a jam (or even post jam to be honest).

I thought to myself: why not see if I can automate this tedious process by creating an html tool similar to the The Dialogue Review Exporter. So on the side I worked with Claude to develop a Python script that read the .gbsres sprite files and applied the transformation rule to all the sprites in a projects assets directory. It worked. The whole thing took a few minutes to write and ran in seconds. I have since applied the conversion tool to my Feed IT Souls: DUAL project - Happy days!

[IMAGE: An animation state of Musk Rat from Feed IT Souls: DUAL after using the Sprite Mode Converter tool]

That conversation became gbs-sprite-mode-converter.html, a tool that converts all sprites from 8x16px mode to 8x8px mode in seconds. 

What's more, once I had a working python script, it didn't take too much extra work to have Claude repurpose it into a community tool. The Sprite Mode Converter tool will be released soon (once I am satisfied it is fully debugged).

Rule #5: Pay attention to workflow problems that come up during a project, there are often opportunities to make custom tools that could save a lot of time in the long run (and be shared with the community to reduce time spent on the more boring tasks during game development).

Part 6: The SKILL Distillation

I introduced SKILLs in the Dialogue Review Exporter devlog but to summarise; they are a text documents of focused knowledge that help Claude learn tasks and concepts that it doesn't yet understand.

Towards the end of the project, I decided I wanted to share some robust SKILLs that not only helped with plugin creation, but also helped with setting up GB Studio event-based scripts in the IDE. This would be a SKILL that helped Claude edit a project's .gbsres files, allowing it to add events scene, actor and trigger scripts itself.

To prepare for this, I created the shooting mini-game that would show Claude how many of the GB Studio events were used in reality. By having Claude read the .gbsres files in the test scenes 'On Init' script and various custom scripts I had made - and then explaining what events did when Claude was confused - I could substantially increase Claudes knowledge such that it could help me correctly lay in events on its own. This allowed me to quickly implement things like a multi-tree run-time debug menu attached to the Start button - making it significantly easier to test what had become a huge amount of mechanics and functions in the Adventure DX plugin. 

Here is the process I used:

1. I asked Claude to re-read PROJECT.md end to end. Becuase I had been updating my PROJECT.md file throughout my sessions with Claude, it was filled with important knowledge regarding how GB Studio works and how I like to work.
2. I then asked it to identify every fact that's specific to the Adventure DX plugin versus what might be general to any GB Studio engine plugin.
3. I then asked it to write the general facts as new SKILLs and let me know if it needed further clarification when examaning details about how events worked, how the engine worked etc.

What came out were three new additions to the gbs-skill-pack:

• gbs-plugin-creator - engine.json field shapes, event JS patterns, runtime engine fields, and six confirmed gotchas that had caused confusion for Claude originally, but after some time spent clarifying and working through issues, were no longer a problem.
• gbs-gbsres-editor - the Python round-trip technique for direct .gbsres editing and the runtime debug dialogue technique.
• gbs-event-reference - confirmed schemas for the seven event types Adventure Scene DX uses most, each verified against real project files, not inferred.

The pack went from two SKILLs, written at the end of the Dialogue Review Exporter project to five SKILLs, with meaningfully more coverage of GB Studio engine plugin creation.

One more thing changed during that session: the SKILL maintenance rule itself. The original gbs-skill-pack had a threshold of how to determine what is a "general GBS rule" and what might be "specific to the project" and not relevant enough to include in a SKILL. I had discussed this when making the first version of my GBS SKILL pack and it originally required a fact to appear in two separate projects before being promoted to a SKILL. I found this was too conservative as the SKILL maintence SKILL had missed some facts that should have been promoted from the PROJECT.md to one of the SKILLs. The rule was updated in the same pass.

Rule #6: SKILLs are living documents. When the working methodology contradicts something a SKILL says, fix the SKILL (I can't stress this enough, if you don't maintain SKILLs - you will have a bad time!).

Summary

Rule #1: Know what kind of thing you're building before you start. Confirm the technical architecture from real documentation and a real example project before writing any code. Don't accept Claude's first description of a mechanism as fact - verify it.

Rule #2: Download your reference documentation once. Don't make Claude fetch it repeatedly.

Rule #3: Think deeply about the design of the plugin itself - while Claude's strengths help with coding, it will need guidance and original thought from you when it comes to design.

Rule #4: Extensive playtesting before release. Same as always.

Rule #5: Pay attention to workflow problems that come up during a project, there are often opportunities to make custom tools that could save a lot of time in the long run.

Rule #6: SKILLs are living documents. When the working methodology contradicts something a SKILL says, fix the SKILL.

Conclusion

Adventure DX took longer than the Dialogue Review Exporter. A couple of weeks rather than days, spread across many sessions. It is also significantly more capable: a fully-featured GB Studio engine plugin with 8-way movement, diagonal animation switching, diagonal and multi-shot projectile firing, a five-mode action cycle, isometric movement, shoot recoil, and a set of companion script events.

Now that it is complete, I have proven to myself that - when used concisely - there is a lot of potential for AI-integrated workflows to help GB Studio developers realize our goals faster and easier. One of the most celebrated aspects of GB Studio is its ability to open doors for those excited to learn how to make games but don't have the technical know-how to program (yet). Most importantly, AI assisted coding does to GB Studio what GB Studio did to GBDK - substantially lower the friction that beginners, intermediate, and even advanced users might feel when making their own Game Boy games. 

It is only natural those who are drawn to the no-coding philosophy of GB Studio are also curious about AI and all that it offers. I do worry that the first thing some young person shares on the GB Studio discord is their first ever game - only to be greeted with some amount of toxic rhetoric because they used AI in some way - resulting in them retreating from the community entirely.

Having made it very public that I use AI assisted coding techniques, I do encounter toxic remarks on occasion. I hope that in future, I see more tolerance given to others in the community. It would be a great loss for everyone involved if there were some kind of community split between those who use AI for various reasons and those who are angered by the mere mention of it in their presence.

Recently, GBrewFR released an article covering AI in the homebrew scene. I highly recommend reading it and thank Smalink for attempting to untangle what is a complex and important topic that will no doubt increasingly impact the community as time goes on. I was going to write an article myself, but Smalink's piece perfectly articulates my thoughts and I support it fully.

By creating the Adventure DX plugin and the Dialogue Review Exporter tool, my intention was to produce some resources that wouldn't exist without the use of AI and that directly help the community. In doing so, I hope these examples help to increase the tolerance and respect shown to others in the community who also use AI when exploring their own personal or professional development.

To those that are using AI in their own workflow already, I encourage you to be open and honest about your use of it as well. Transparency is the first step to creating a healthy dialogue. You don't have to justify your use of AI to anyone, but being upfront about it gives others permission to be honest, too.

The gbs-skill-pack is now at v1.0, with five SKILLs up from two. Every SKILL was confirmed against real files, not inferred. The methodology continues to evolve but I hope this updated pack can really help to lower the friction you might feel when working on your own projects. Fork them, break them, improve them, share them, do whatever you want with them!

I hope this devlog has proved useful for those of you who are interested in using AI assisted workflows. In the coming days or weeks, I'll release the Sprite Mode Converter tool but until then, happy coding!

- Tom (Gumpy Function)