Tutorial: Your First Hack

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 (EbProjEdit).
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.

---

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

3. 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.

---

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.

---

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.
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?