emu.frameadvance() tells the emulator to advance exactly one frame which is the basic unit of time on an NES. The emulator usually does this itself, but allows our script to do whatever we want before each frame is rendered.

Now it’s time to open up FCEUX with Wine. If you installed it with brew or another package manager, you can navigate to the directory where fceux.exe is sitting and run wine fceux.exe otherwise you can double click the file itself. You need to be playing a game for code to run. So open up your Legend of Zelda ROM and run your code by clicking “File -> Lua -> New Lua Script Window” and navigating to the script.

Cue the famous victory fanfare as we have won our first battle. These experience points will be useful. Now that we know how to get Lua code to execute let’s cut to the chase and get to the real hacking.

Jump higher, punch harder, live forever



Our Hello World script is nice but it’s hardly as magical as my childhood experiences with the Game Genie. Let’s dig into some of the basic tools we’ll need to emulate Game Genie’s functionality. FCEUX comes with a host of awesome debugging utilities. One of the most important things in this toolbox is a hex editor. With this we can look at the contents of the game’s memory in the form of hexadecimal addresses and values.

The hex editor is the main tool that ROM hackers use to open up a game’s Read Only Memory and edit the hex values to change what is in the game. Cleverly editing memory addresses can result in some crazy gameplay modifications or even completely new games. Let’s open the hex editor and see what we can do with it.

All of the two digit hex numbers you see represent a value in the game’s RAM at a specific location. You can change any value to see what happens in-game. You can also search for specific consecutive values. Check out this example to see the hex editor in action to find the bytes corresponding to the timer in Super Mario Bros and then changing the time to zero to kill Mario.

ROM hacking can be a pretty daunting task. We are about to discover that you don’t need to be an expert to do some really cool stuff.

ROM represents the unchanging contents of what you’d find on a game’s cartridge whereas RAM represents the actual memory of the game as the program is running. Changes made to RAM appear immediately allowing you to make real time changes. There are NES RAM maps here and here that will tell you which memory addresses correspond to specific things in-game.

Let’s try to mimic the Game Genie by “enhancing” games with Lua scripts. As an example, let’s mess around with one of my all time favorites, the original Legend of Zelda. Using this RAM map we will edit certain values to make some funky stuff happen.

Open up a new file in your text editor and add some of these one liner example scripts to change RAM values and see what happens. You will need to have your Legend of Zelda ROM running in FCEUX have a new game started for these scripts to work.