Tutorial: The Graphical User Interface - pk-hack/CoilSnake GitHub Wiki

If you're using Windows, double-click the EXE file to launch CoilSnake.

On Linux or macOS, run the following command from a terminal after installation: coilsnake

The Decompile tab

The Decompile tab allows you to extract raw data from a ROM and save it to your hack's project folder as PNG files and easy-to-edit data tables in YAML format. You need to tell CoilSnake which base ROM to use, and which folder to save everything to.

Note - this only works with unmodified ROMs. If you're trying to modify a preexisting hack, it probably won't work.

CoilSnake's "Decompile" tab

The Compile tab

This is where you'll spend most of your time while working on your hack. The Compile tab takes everything in a project folder and builds it into a new ROM, which you can playtest in an emulator or on a development cartridge.

You have to specify a base ROM, the location of your project folder, and a path to save the new ROM to.

To build the game, click Compile.

The Run button will launch a SNES emulator and let you playtest. To use this feature, make sure CoilSnake knows which emulator to use -- go to the Settings menu and click Configure Emulator.

The Edit button launches the old map editor, which you shouldn't use -- please use EBME instead, it's much less frustrating to use. For more information, see the articles on this wiki about map editing.

CoilSnake's "Compile" tab

The Upgrade tab

You'll only need to use this tab if you're migrating a project made with an older CoilSnake version to be compatible with the current version.

This process requires a clean, unmodified ROM as a reference. Always keep backups before proceeding.

CoilSnake's "Upgrade" tab

The Decompile Script tab

You'll only want to use this function if your goal is to modify EarthBound's existing script, as opposed to writing new dialogue for your hack. For example, you might want to do this if you want to translate the game into another language, or just goof around and make everyone say silly things to learn how CCScript works.

Click Decompile Script to extract every line of dialogue in the game into your project's ccscript folder.

CoilSnake's "Decompile Script" tab

Creating and applying patches

Due to how legally grey it is to modify games, we share our work as patch files. This ensures that when we share our hacks with the world, we're only sharing our dialogue, our music and sprites, our code, etc., and not anything under copyright. People who play ROM hacks have to have their own copy of the base game, usually dumped from their own cartridge or found elsewhere, and patch it!

To create and apply patches, you'll need a clean, unmodified EarthBound ROM. Making a patch involves finding all the differences between the two files, and applying a patch involves taking the original file and applying all of those differences back onto it.

CoilSnake supports two patch formats: IPS and EBP. There is some discussion about this, but on the whole we suggest using EBP (a modified version of the IPS file format created by EarthBound hackers many years ago), or using RomPatcher.js to create a BPS patch.

CoilSnake's Apply Patch tab lets you apply a patch to an EarthBound ROM.

The ROM Header (IPS only) checkbox ensures compatibility when applying IPS patches to ROMs with or without headers. BPS or EBP patches are recommended, so you should never need to use this unless you're applying a patch made a long time ago that happened to use the IPS format.

The Create Patch tab generates a patch file.

Tools Menu

The Tools menu provides auxiliary functions:

  • EB Project Editor: Launches the old map editor (NOT RECCOMENDED)
  • Expand ROM to 32/48 MBit: Increases the size of a ROM file, providing additional space for data storage during compilation.
  • Add/Remove Header: Adds or removes a 512-byte header to/from a ROM file for compatibility with specific tools.

Settings Menu

The Settings menu allows configuration of non-project-specific parameters:

  • Configure Emulator: Specifies the SNES emulator for the Run buttons on the Compile tab.
  • Configure Java: Sets the Java installation path required for the old map editor.
  • Configure CCScript: Defines the ROM location for compiled CCScript text.
  • Debug Mode: Enables verbose logging for debugging and troubleshooting.

Profiles

Several of the tabs allow you to create profiles. Profiles will remember what you chose for the input boxes so you don't need to manually browse for files each time you use CoilSnake. Press "New" to create a new file, give it a name, fill in the fields, and then press "Save". It will now appear in the drop down list.

Command Line Interface

Advanced users can access CoilSnake's command line interface via Linux or macOS by running the command coilsnake-cli

For detailed usage instructions, use coilsnake-cli --help