Help Recommended Tools and Documentation for Newbie Hackers

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.
• A guide to common assembler errors.

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 (though it still lacks some features), 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.

Documentation
Sooner or later, you will want to know how the Mega Drive/Genesis works, and how to directly interface with its hardware. Fortunately, there are multiple resources online which document the Mega Drive in great detail:

First, there is the official documentation, which Sega made available to developers back in the console's heyday. This documentation is quite exhaustive, though it does lack some information and can be difficult to understand due to its lacklustre translation from Japanese to English.

Secondly, there is the Plutiedev website. While by no means an exhaustive reference, it covers its topic in great detail, with many examples and illustrations. It even provides some information which cannot be found in the official documentation, such as an explanation of the VDP's debug register.

Next, there is the Mega Drive wiki. This wiki has long been abandoned, but it presents information in a way that you may find more natural than the official documentation. Be mindful that the wiki may contains mistakes (I specifically recall it getting its description of one of the VDP's settings completely backwards), so be sure to cross-reference it with other documentation if you want to be certain about any details.

Finally, there is the SpritesMind forum. I rely on this source a lot for developing my Mega Drive emulator. Here you will find discussion of the nitty-gritty details of the Mega Drive, Mega CD, and 32X's functionality. Information is spare and requires a great deal of searching to find. Often, older and incorrect information is corrected in newer posts and threads. While the information here can be invaluable, it requires a great deal of effort to find. An attempt to aggregate information on this forum can be found here, though it is almost a decade old and therefore lacking any of the more-recent discoveries.

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.