Help So, you want to start hacking Sonic? (2025)

If you are new to Sonic ROM-hacking, you may be confused by which tools to use, what to use them for, or even just how to get started in the first place. To cut through the noise, here is an up-to-date (as of 2025) guide.

Disassemblies
Overview
Firstly, forget tools like Esrael's ROM editors; they are ancient and do not fit the modern Sonic ROM-hacking workflow at all. Particularly, we do not directly modify ROMs any more; instead, we edit a disassembly. A disassembly is comparable to those decompilations that you may have heard of before: it is the target game's code reverse-engineered into a modifiable codebase, which is comparable to what the original developers used when creating the game back in the 1990s. Because of its similarity to actual source code, it is the most preferable way to edit the game.

Choices
There are two sets of disassemblies that are recommended: the modern Git disassemblies, which are hosted on GitHub, and the legacy Hivebrain/Xenowhirl disassemblies, which can be found on Sonic Retro's wiki. The Git disassemblies are cutting-edge, featuring the latest improvements and features, while the legacy disassemblies are outdated and very much set-in-stone. Whether to choose one set or the other largely depends upon whether you want to maximise compatibility with guides, as the Git disassemblies' ever-changing nature means that they often break compatibility with guides, making them much harder to follow.

It is also worth mentioning that the Git disassemblies support many platforms and operating systems, such as FreeBSD and the Raspberry Pi, while the legacy disassemblies tend to only support Windows.

Usage
Once the disassembly has been edited to your liking, a ROM can be produced by running the build script (double-clicking 'build.bat' on Windows, or running 'build.lua' on other platforms), which will produce a file such as 's1built.bin', 's2built.bin', or 'sonic3k.bin'. This file can be ran in an emulator or loaded onto a flash cartridge to be played on a Mega Drive/Genesis. This file will not be updated with new changes to the disassembly until the build script is ran again.

Editing
It is not recommended to use Windows' Notepad app to edit code; instead, use a specialised source code editor with support for syntax highlighting. One such editor for Windows is Notepad++, a 68k syntax highlighting extension for which can be found here, along with installation instructions. As for Linux users, something like Kate or Geany would work.

Guides
Since nobody is born knowing how to modify Sonic games, knowledge is often shared in the form of guides, which walk the reader through making a particular modification to a game, such as adding the Spin Dash to Sonic 1. These guides range from very dry and technical, with a heavy emphasis on learning, to brief and light on explanations, with an emphasis on copying code. Such guides can be found on Sonic Retro's wiki, as well as on forums such as Sonic Retro, Sonic Stuff Research Group, and Mega Drive Developers Collective.

As mentioned previously, many guides target the legacy Hivebrain and Xenowhirl disassemblies from the mid 2000s, but some others exclusively target the Git disassemblies. Keep in mind which guides you will want to follow when choosing which disassemblies to use.

In the forums, many useful guides end up 'buried', lost in the sea of threads that have since overtaken them. With this in mind, it is worth browsing the forums' catalogues of threads, in case you find anything useful. Some notable threads that often find themselves buried include...

• A list of quirks and bugs to be mindful of when programming for the Mega Drive/Genesis.
• Assorted guides for fixing bugs in, and making modifications to, Sonic 1.
• Assorted guides for fixing bugs in, and making modifications to, Sonic 2.

Guides can also be found on YouTube, which may prove easier to follow than text-based guides. Examples of these are AnimeMaster's level editing guides and my porting guides.

With a disassembly and array of guides at hand, you are ready to start hacking Sonic! But what tools are there, and which ones are considered modern?

Sprite Editors
Choices
Historically, SonMapEd was the go-to sprite editor. However, it has since fallen out of favour, and the Git disassemblies are no longer compatible with it. Though, it is still a suitable choice for legacy disassemblies.

SonMapEd has been replaced by two other sprite editors: Flex 2 and ClownMapEd. ClownMapEd tries to replicate the look and feel of SonMapEd, while Flex 2 goes in its own direction. If you are already familiar with SonMapEd, then ClownMapEd may make for a smoother transition than Flex 2. On the other hand, you may find Flex 2 far more intuitive than the other two if you have never used either before.

Flex 2 and ClownMapEd are also cross-platform and open-source, while SonMapEd is Windows-only and closed-source.

Usage
A tutorial on using Flex 2 can be found here. Due to ClownMapEd's similarity to SonMapEd, tutorials on using SonMapEd can also be used to learn how to use ClownMapEd. One such tutorial would be this one.

Sprite editors operate on "tiles", "mappings", "dynamic pattern load cues" ("DPLCs"), and "palettes". Each can be found in separate files. In SonMapEd and ClownMapEd, all four files need to be loaded individually, and only when all four have been loaded at once will a sprite appear properly in the editor. The vast majority of sprites do not have DPLCs, and so only tiles, mappings, and palettes need to be loaded. Once the sprites have been modified, each of these files need to be saved. Flex 2 uses a project file to load and save these files collectively instead.

Remember, even after these files have been saved, the changes will not appear in the ROM until it is rebuilt by running the disassembly's build script!

Level Editors
Choices
The two main choices are SonED2 and SonLVL. SonED2 is considerably older, has not been updated in many years, and its compatibility with the modern Git disassemblies is not guaranteed. SonLVL is cross-platform and source-available (not quite open-source), while SonED2 is Windows-only and closed-source.

Usage
Both editors work by loading project files. Levels are made of large pieces called 'chunks', which are made of smaller pieces called 'blocks', which are made of smaller pieces called 'tiles'. When editing levels, one has to be mindful of the maximum limit of tiles, blocks, and chunks.

A tutorial on using SonLVL can be found here. SonED2's manual can be found here.

Plane Map Editors
Overview
Plane maps are used for things such as menus and screens, as they arrange tiles into a particular formation. Though somewhat niche, they require their own editor due to working completely differently from sprite data and level data.

Choices
The two choices are SonPLN and Captain PlaneEd. Captain PlaneEd, being derived from PlaneEd, is unwieldy but simple, while SonPLN, like Flex 2, has an overhauled interface that aims to be more intuitive. SonPLN is a counterpart to SonLVL, so users of the latter may find the former more familiar.

Usage
A tutorial on using Captain PlaneEd can be found here. Note that Captain PlaneEd features a menu bar that makes loading files far simpler than using the command line or creating a batch script.

Music Editors
Overview
Sonic games use the SMPS sound driver (also referred to by contemporary developers and its source code as "SOUND SOURCE", "SOUND SORCE", and plainly just "SOUND"). It is not compatible with any common formats such as MP3 or MIDI. There is no SMPS music editor, though music can be created in a standard music editor and then converted to SMPS's format.

Choices
Tools exist which convert MIDI, XM, and VGM files to a format supported by SMPS, though the quality of these conversions leave a lot to be desired, and often require extensive modification by-hand in a text editor.

• mid2smps can be used to convert a MIDI file.
• xm4smps can be used to convert an XM file.
• vgm2smps can be used to convert a VGM file.
• Furnace Tracker can be used for creating YM2612 instruments.

Usage
A tutorial on using converting a MIDI file can be found here.

A tutorial on creating and converting VGM files can be found here.

Tools such as vgm2smps only output in the format used by Sonic 1's version of SMPS, which renders it incompatible with other games (such as Sonic 2) and other sound drivers (such as Flamedriver). To solve this problem, the SMPS file (typically in the '.bin' format) must be converted to the SMPS2ASM format ('.asm'). This will enable the song to work with other games and sound drivers. The aforementioned VGM guide details this process.

When songs are in SMPS2ASM format, they can be edited by-hand in a text editor, allowing for things such as the insertion of modulation commands, optimising the note data, altering the YM2612 instrument data, and changing the tempo.

Many songs depend on features that are not available in every version of SMPS, making it difficult to port songs from one game to another. Notably, these features include "coordination flags" (sound commands), "DAC samples" (audio recordings often used for percussion), and "PSG envelopes" (data used for creating tremolo on the PSG channels). I have a series of videos on my YouTube channel that go over porting these features between games.

SMPS songs created through conversion can be very large, taking up a lot of space in the ROM. Not only can this push a ROM toward its maximum size (4MiB), but it can also render the song incompatible with Z80-based versions of SMPS (as used by Sonic 2 and Sonic 3 & Knuckles), which limit songs to 0x8000 bytes each. SMPSOpt can be used to automatically optimise a converted song, and optimisations can be made by-hand once the song is in SMPS2ASM format.

Note that, while SMPS2ASM is built into the Git disassemblies, it needs to be installed separately for the legacy disassemblies. SMPS2ASM requires the AS assembler, rendering it incompatible with asm68k-based disassemblies such as the 2005 Hivebrain disassembly. The version of AS used by the 2007 Xenowhirl disassembly may be too old to be compatible with SMPS2ASM, and would require that the assembler be updated first.

Sound Drivers
Overview
The standard SMPS drivers used by the Sonic games tend to be limited in features, restricting what they are capable of, as well as the songs which can be ported to them. To address this, custom SMPS drivers exist which combine features from multiple drivers, as well as fixing bugs, raising limitations, and adding features of their own.

Typically, these drivers are incompatible with the legacy disassemblies, and require a complicated installation process.

Choices
A popular choice is my Sonic 2 Clone Driver v2, which aims to ease the process of porting music and sounds, and sports a two-channel DAC driver which allows two DAC samples to be played at once. The convention is that one DAC channel is used by the music's percussion track, while the other is used by sound effects. Its installation guides target the Git disassemblies only.

Another option is Flamewing's Flamedriver. It lacks a modern installation guide, though a custom Sonic & Knuckles disassembly with the driver pre-installed can be found here.

There is also AMPS, though I am extremely unfamiliar with it, and it appears to have fallen out of use in recent years. It is also no longer receiving support from its developer. It too features a two-channel DAC driver. Modified disassemblies with AMPS pre-installed can be found here.

Debuggers
Overview
At some point or another, your ROM-hack will crash, and you will have no idea why. To mitigate this, a debugger can be installed into your ROM hack to make it report how and why it crashed, printing various details of the console's status to the screen.

Choices
The two choices are Flamewing's debugger and Vladikcomper's debugger. Flamewing's is older and simpler, but this also makes it considerably easier to install. Meanwhile, Vladikcomper's is newer and has more features, but is also harder to install.

One significant difference between the two is that Vladikcomper's is capable of displaying label names from the disassembly, making it much clearer what code and variables were involved in the crash, while Flamewing's will only display raw addresses, requiring cross-referencing with the disassembly's listing file ('sonic.lst', for instance) to figure out what was involved in the crash.

Additionally, Vladikcomper's debugger provides a framework for logging debug information in certain emulators, allowing your hack to do things such as report what it is currently doing or any problems that it has encountered, further aiding in the debugging process. Particularly, the emulators which support this feature are Gens KMod, BlastEm, and ClownMDEmu.

Compressors & Decompressors
Overview
The Sonic games use a variety of compression formats. The disassemblies store their assets compressed, meaning that a (de)compressor is needed to be able to decode and modify them. Level, plane, and sprite editors have (de)compressors built into them, so they can handle this automatically, however, if you want to edit a file manually, then you will need your own.

Choices
Sometimes, newbies are seen using The Sega Data Compressor, which is a very old program with inefficient compression, and which lacks support for newer community-made formats like Kosinski+ and Comper. The modern equivalent would be the FW-KENSC Shell Extension, which provides a Windows shell extension to intuitively compress and decompress files. FW-KENSC (also known as 'mdcomp') is a much newer compression suite that boast improved compression as well as support for additional formats.

For Linux users, the upstream mdcomp project provides an array of command line utilities.

Emulators
While they are normally just used for playing and testing ROM-hacks, emulators can also be helpful for developing ROM-hacks with the aid of their debugging utilities. Not all emulators have these, but there are several which do.

Regen is an old, discontinued emulator, but its age makes it fairly lightweight, it is of reasonable accuracy, and it provides a suite of debugging tools, including support for CPU breakpoints.

Exodus is a newer emulator, with an extreme emphasis on accuracy. This accuracy makes it a very demanding bit of software to run, but it also makes it a close parallel to running your ROM-hack on a real Mega Drive/Genesis, making it ideal for ensuring compatibility with quirks and bugs that usually only a real console will exhibit. Like Regen, it features a variety of debugging utilities.

ClownMDEmu is my Mega Drive emulator. Its accuracy should be reasonable, though its weakest aspect is definitely its timings. Its debuggers are largely visual, providing viewers for RAM and visualisers for the contents of VRAM, such as tiles and planes, though it lacks features like CPU breakpoints. It also provides partial support for the Mega CD/Sega CD, allowing for the debugging of the add-on's PCM chip and graphical transformation capabilities, which can be useful for debugging 'mode 1' software.

BlastEm is another highly-accurate, modern emulator. Though very accurate, it is far less resource-intensive than Exodus. In my limited experience with this emulator, I found its interface quite basic, but it does apparently have debuggers.

Closing
With that, I have listed all of the tools that I can think of which are still relevant in 2025. Some tools are more niche than others (such as music converters), but it is useful to have a starting point for learning about such things.

Looking back over these, it is apparent that music editing is far more complicated than it has any right to be, so I suggest newcomers stay away from it unless they know what they are getting themselves into. Otherwise, ROM-hacking should be fairly straightforward once you know which tools to use.

Happy hacking!

 

Bugger, I thought SoniPlane and SonPLN were the same thing. Likewise for AMPS and Fractal. I'll correct the post.

 

The default branch of the Sonic 1 Git disassembly targets the AS macro assembler. ClownAssembler is intended for disassemblies that target asm68k, such as the 2005 Hivebrain disassembly. The Sonic 1 Git disassembly has a branch which targets asm68k here, though no such branch exists for the other two disassemblies.

Converting from AS to asm68k would involve stripping-out features of the disassembly that asm68k cannot support, such as mid-expression macros (dubbed 'functions'), Z80 assembly, and compressing sound driver data at build-time. Beyond that, the syntax of macros declarations is different, the 'binclude' keyword is 'incbin', and nameless temporary labels ('+', '-', and '/') cannot be used. It is a lot of work.

 

You're not the first to suggest something like that, so I might as well respond before even more people suggest it:

This being posted without consulting people first was not an accident: I'm not interested in waiting days for people to respond to queries and polls when I can just post the guide now and get that same feedback later. People were going to give feedback and suggest changes either way.

Just to be clear, I did not set out to aggregate community knowledge and opinions; I set out to make a list of tools that I, a Sonic hacker of 13 years, recommend to newcomers. If people would rather that I had done the former, then too bad; what I do with my time is my choice to make. This is a forum though, so people are welcome to post replies with their own recommendations.

 

See, this is exactly what I mean. Responsibilities? This community is entitled to nothing from me. Talk about giving an inch and taking a mile...

 

Gah, I didn't want this to become one of those 'break the other person's message into pieces and respond to each one' posts, but that seems to be the only coherent way to do this...

Maybe my post does set up the wrong expectations. What I want to make clear is that is what it is; rather than an objective guide that reads like a subjective one, it's a subjective guide that occasionally reads like an objective one. That's why I explained what it was in my reply; to clear up that ambiguity; I'm not saying the ambiguity doesn't exist. I get it, the post could be clearer.

You missed the point that I was trying to make: it's fair enough to criticise something when it fails to do what it set out to, but it's wrong to criticise something for not achieving something that it never set out to do in the first place. For instance, if a guide were made to port the Spin Dash to Sonic 1, then it's wrong to complain that it does not explain how to port the Drop Dash instead. Saying that I should have asked community members for their views first would have been good feedback for a guide that was collecting community views, but that isn't what this guide is, so the criticism is misplaced. Me pointing this out was not to get people to stop criticising the guide, but rather so that they can make a more-informed criticism which is more relevant, like your point that the guide's intent can be confusing.

The most that the criticism of 'you should have asked-around first' does is argue that it would have been helpful for fact-checking my recommendations, like how Devon pointed out that I was confusing AMPS and Fractal. There is a point there, but I still disagree that it's a particularly useful criticism because releasing the guide immediately and amending it later produces the same result, with the added benefit of the guide being released earlier, albeit in a rougher state. In my opinion, a rough guide is better than no guide.

That's rich, coming from someone who didn't try it themself. Really, I have sat here for 13 years and watched nobody put in the work to replace that old thing, and somehow I'm at fault for trying to help? It's more than anything you've done to improve the situation, so excuse me for not being the perfect person for the job. This reeks of crab-mentality to me.

But really, this community needs to get off its collective arse and put together a wiki article already. That's what a wiki's for, after all; for a community to pool its knowledge. I don't buy that I'm somehow in the wrong for expressing my personal viewpoint in my personal post on a forum. A newbie who's looking for community-sourced, objective information on a forum is looking in the wrong place. I'm the only person (besides mods, anyway) that can edit my post, so not only is a resource like that out-of-place on a forum, but it also creates an issue of power where one person has control over what information does and doesn't get added. This bias is fine for an opinion piece like mine, but it's terrible for objective community-sourced information!

But MapMacros do make our work better: they're easier to hand-modify, they allow the underlying mapping format to be changed with ease, and they make it easier than ever to port mappings from one game to another by completely bypassing the need for a converter. By extension, they make it possible for the Knuckles in Sonic 2 disassembly to share mappings with regular Sonic 2, whereas otherwise it would need its own modified versions. MapMacros are also closer to what the real Sonic source code does, making them a plus for authenticity and moving away from being a raw disassembly. Just because some people dislike it does not mean that it is not for the best. And what do I care about every little complaint in a community where people still insist on using 20 year old disassemblies?

As for the Clone Driver, oh my god, here we go with the entitlement again: the Clone Driver v2 is my project, I do what I want with it. You people are entitled to jack shit from me. I have every right to kill-off that driver and never work on it ever again. Would you tell me that I'm in the wrong for not spending the rest of my life working on a project that I don't want to because of its benefit to the community? No, so get off my back!

And what does this have to do with this thread anyway? I have a habit of valuing my opinions over those of others, and that affects the usability of the tools that I make? So the usability of this guide is affected by the fact that it's opinionated? Okay, but I don't care about that: I'm not trying to make the most universally-accessible tools and guides that the world has ever seen; I'm trying to make tools and guides that are good enough while still suiting me. As I said already, collecting the views of community members would have taken days to do, and I wasn't interested in spending that much time on a guide. Not to mention, that doesn't sound even the slightest bit fun to me; I enjoyed writing my guide, but I wouldn't have enjoyed PM-ing random people and collecting their thoughts in a spreadsheet or whatever. And if your argument is that it shouldn't matter whether I want to or not, I should make everything the most accessible that it can be, no matter the cost to me, then, again, I don't care, because what I do is my choice, not yours.

Anyway, I really hate writing posts like this, so please don't make me write another one. I'm tempted to just ignore any future replies to this thread, because this is bad for my mental health, and I usually never complain about that kind of thing. I don't have to explain myself, and I especially don't have to repeat myself.