Tutorial: Your First Hack - pk-hack/CoilSnake GitHub Wiki

Your First Hack

In programming, the classic “Hello World” exercise is often the starting point for learning a new language, as it simply displays the message “Hello World!” on screen. While it’s functional, it’s also rather dull.

Let’s add a creative twist to this tradition by creating something more engaging and rewarding within EarthBound.

Planning the Hack

A successful project starts with a plan. While improvisation can work, a well-thought-out approach ensures smoother progress and better results. For this hack, we’ll create an NPC (using the Robot Ness sprite) that delivers a “Hello World” message within Ness’s house at the beginning of the game. This involves:

  1. Decompiling the ROM.
  2. Adding an NPC with the Robot Ness sprite.
  3. Writing dialogue for the NPC using a CCScript file.
  4. Placing the sprite in Ness’s bedroom with the map editor (EBME).
  5. Recompiling the ROM to incorporate the changes.

Let’s get started!

Creating Your Project

To begin, you’ll need an EarthBound ROM (available online) and CoilSnake installed. Follow these steps:

  1. Open CoilSnake and select the Decompile tab.
  2. Click Browse… next to the ROM field and select your EarthBound ROM.
  3. Click Browse… next to the Output Directory field and choose where to save your project.
  4. Press the Decompile button to extract the ROM’s resources into a CoilSnake project.

This creates a project folder containing all the editable files needed for hacking.

Understanding a CoilSnake Project

A CoilSnake project is a collection of files stored on your computer that represent the ROM’s contents in a structured format. The files include:

  • Project.snake: Metadata and resource locations used by CoilSnake.
  • YML files: Text files for game data, editable with a text editor.
  • CCScript files: Used for dialogue and scripts, stored in the ccscript directory.
  • PNG files: Graphics files, often in indexed format, which can be edited with suitable image editors.

By separating the ROM into these files, CoilSnake allows easy editing and reduces the risk of corruption during modification.

Editing an NPC

Get EBME

  1. Download EBME from here. On Windows, get "ebme.exe". (You might run into some warnings that it's a virus - it's not! It's just because of the way it is packaged here.)
  2. Extract it from the folder it's in and double-click to run it. Again, if you run into antivirus warnings, dismiss them or look up how to add exceptions.

[!IMPORTANT] If you can't use EBME for some reason, the instructions for the old map editor are included at the bottom of this page.

Find Ness's bedroom

  1. Press the "Open" button and navigate to the folder where you decompiled your project to.
  2. Once it's loaded, go to the "Map Editor" tab along the top.
  3. Navigate to Ness's bedroom. You can pan the map by middle-clicking (it's along the right edge of the map) or press Ctrl+G and enter the coordinates (8070, 1100).

Add the NPC

  1. Enter NPC Mode by pressing the button on the sidebar or F3.
  2. Right click somewhere in the bedroom and press "New NPC". Make sure it's selected by clicking on it.

Edit the NPC

  1. In the sidebar, change "NPC ID" under "Instance Data" to 744.
  2. Edit the following values under "NPC Data" to be:
  • Sprite: 5
  • Direction: Down
  • Movement: 605
  • Flag: 0
  • Appears: Always
  • Dialogue: robot.hello_world
  • Extra Data: $0
  • Type: Person (You can also add a comment if you like - this won't be included in the hack, but helps you stay organised when editing!)

Let's go over what these values mean.

  • Sprite: This is the ID for Robot Ness's sprite. You can find it in your project under SpriteGroups as 005.png.
  • Direction: The NPC will face downwards when it appears.
  • Movement: An ID for an action script. These are quite advanced. You can hover over the Movement field to see some common values. 605 is used for stationary NPCs.
  • Flag: This is used by the "Appears" field. We don't need it to be anything, so we set it to 0.
  • Appears: Based on the flag above, dictates when the NPC will show up. We don't need it to only appear at a certain point in the game, so we set it to "Always".
  • Dialogue: We'll get to this!
  • Extra Data: Similarly, we don't need this, so we set it to 0. The dollar sign indicates hexadecimal. It's not strictly necessary to include the dollar sign if it's going to be zero, but it is conventional for this field.
  • Type: How the NPC is interacted with. "Person" means "Talk to" will interact with them.

Finally, hit Ctrl+S to save your project! Then you can close the program.

Writing Dialogue

Create a robot.ccs file in the ccscript directory with the following content:

hello_world:
    "@Hello World!" end

Save the file, ensuring it has the correct .ccs extension. On Windows, you might need to find the option to "Enable file extensions" somewhere in file explorer.

Do you remember the "Dialogue" field for the NPC? It was referring to this. robot.hello_world means "find the label hello_world in robot.ccs.

Compiling and Running

To compile the ROM:

  1. Open CoilSnake and go to the Compile tab.
  2. Select your base ROM and project directory.
  3. Specify a name for the output ROM (as if you were saving a new file).
  4. Click Compile and confirm the ROM expansion when prompted.

Once compiled, run the ROM in an emulator to test your work.

Troubleshooting

Common issues and solutions:

  • Error: Unknown pointer label [robot.hello_world]
    • Check for typos in robot.ccs.
    • Ensure the file is named robot.ccs and not robot.ccs.txt.
    • Verify file extensions are visible and correctly set on your system.

For more help, consult online resources or video walkthroughs.

Conclusion

Congratulations! You’ve completed your first EarthBound hack and explored key tools and techniques. With this foundation, you can dive deeper into customizing the game and creating unique projects. Ready to start your next adventure?

Old stuff

[!IMPORTANT] Here are parts of the tutorial which are now obsolete because the map editor has been replaced with a new one. You don't need to keep reading here if you followed all the steps. If you can't use EBME for some reason or another, you can use this method instead.

Replacing an NPC

To modify an NPC:

  1. Open npc_config_table.yml in your text editor.
  2. Locate the entry for NPC #744. It should appear as follows:
744:
  Direction: down
  Event Flag: 0x274
  Movement: 708
  Show Sprite: when event flag set
  Sprite: 195
  Text Pointer 1: $c7db3f
  Text Pointer 2: $0
  Type: object
  1. Update it as shown below:
744:
  Direction: down
  Event Flag: 0x0
  Movement: 605
  Show Sprite: always
  Sprite: 5
  Text Pointer 1: robot.hello_world
  Text Pointer 2: $0
  Type: person

Explanation of Changes

  • Event Flag: Set to 0x0, so visibility is not tied to an event.
  • Show Sprite: Always visible.
  • Movement: Set to 605 for a stationary NPC.
  • Sprite: Set to 5, corresponding to the Robot Ness sprite.
  • Type: Changed to “person” to enable interaction.
  • Text Pointer 1: Points to the hello_world block in the new robot.ccs file.

Save the file after making edits.

Editing the Map

To place the NPC on the map:

  1. Open the EB Project Editor from CoilSnake’s Tools menu.
  2. Load your project’s Project.snake file.
  3. Open the Map Editor.
  4. Navigate to Ness’s bedroom.
  5. Switch to Sprite Edit Mode (via the Mode menu or F2).
  6. Right-click in the bedroom and select New NPC.
  7. Assign the NPC ID 744.