Tutorial: Your First Hack

Your First Hack

The standard program most programmers write when learning a new language is Hello World, which aims to output “Hello World!” in some fashion to the user. Sounds exciting, right?

It isn’t. It’s boring.

So let’s do a twist on that that’s a bit more involved, but is hopefully a lot more rewarding.

Planning the Hack

A hack without a plan is like a train without a steering wheel: it works just fine. However, you might want some levers and other controls on that train, because unless derailing trains is your weekend hobby, you’re not likely to enjoy the trip in the long-run, once you realize you don’t know where you’re going. So let’s think a bit before making this hack.

Additional note: There a few good tips here on an old tutorial for JHack which might be of interest to you once you start fleshing out your own hacks; check it out!

EarthBound is an RPG, so it would make sense if you saw "Hello World" said by a NPC instead of just printed on-screen. So we’ll need to make a character say this at some point in the game. Oh, but that’s pretty easy – you just need to substitute some dialog at one point. And it’s boring besides. Maybe the character could be in a place where he’s not supposed to be? Say (spoiler alert!) Robot Ness in Ness’ house at the beginning of the game? Yeah, that sounds a bit more interesting (or not; everyone’s entitled to their opinion). Let’s work with that.

So, what would we need to do? Well, the sprite already exists, so there’s no need to create a new one. The map would have to be edited, though, so that Robot Ness can be placed somewhere in Ness' bedroom. But wait, since we can’t create new NPCs (yup; that’s a limitation currently), we’ll have to use an existing NPC and modify it for our purposes. Maybe a more-or-less useless one could be used, like a present box (yes, a NPC CAN be an object!). And some dialogue should be tied to him; CCScript should get the job done. Alright, so we need:

1. To replace a mostly useless NPC (such as a present) with our custom one.
2. To add Robot Ness to Ness' bedroom using EbProjEdit.
3. To tie some dialogue to him with CCScript.

Doesn’t sound that hard, right? So let's hop to it!

Replacing a NPC

All NPCs are configured in npc_config_table.yml, and are identified by their ID. Let’s take at look at 744:

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

We need to change a few things about this (don’t worry about the exact details, they will be covered later):

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

A few explanations are in order: since this sprite will always appear, we don’t need to set an event flag to it (thus, 0x0 as an event flag and Show Sprite: always). Setting 605 as Movement will make the robot stand still. Sprite: 5 sets the sprite group #5 (Robot Ness) as the sprite animation group for Robot Ness. Type: person ensures that the correct interaction option is "Talk to", rather than "Check". Finally, Text Pointer 1: robot.hello_world specifies that the text is located at the hello_world location in memory, which is a label we will define later on (in the robot.ccs file, thus the robot prefix) when writing CCScript.

Now that we have our NPC ready, let’s place him in the appropriate location.

Editing the Map

You’ll need the EB Project Editor for this step, although for the purpose of this first hack, you won’t need to be fully knowledgeable with it yet (read the tutorial on it later on if you lack confidence on your ability to follow step-by-step directions). You can open up the EB Project Editor through the Tools menu of CoilSnake.

When you first open it, you should see a tiny, unassuming initial screen, something like the one pictured to the right. You can’t really do anything yet with it, so click on the folder icon to open your Project.snake file. It might take a while to load all of the necessary data, but the EB Project Editor will get there eventually; you’ll know when it’s ready when all three buttons light up. We don’t want to edit existing tilesets or handle door mechanisms, so open up the Map Editor.

(Map Editor screenshot goes here)

A new screen will pop up with a default map loaded, looking similar to the screenshot above. Since we want to edit Ness’ bedroom at the beginning of the game, scroll over the map until you find it – it’s somewhere around the top-right corner.

So now that that’s done, you want to bring up the Sprite Edit mode – do so by hitting F2, or choosing it from the Mode menu at the top.

Then, right-click someplace within Ness’ bedroom, and select “New NPC”. By default, this is Ness, so let’s select a different sprite by right-clicking on it and choosing “Switch NPC (0)”. Type 744 into the box that pops up, 744 being the ID of the NPC we have replaced.

Ness’ bedroom should now look something like this:

(Zoom in on Ness' bedroom screenshot goes here)

Scripting Some Dialogue

CCScript files must all be placed in the ccscript directory of your CoilSnake project. Go ahead and create an empty robot.ccs file with a text editor of your choice, and write this text into it:

hello_world:
    "@Hello World!" end

This will make our NPC say “Hello World!” to Ness, then stop the conversation. Neat, isn’t it?

Compiling and Running

Looks like we’re good to go. Load up CoilSnake and open the "Compile" tab. Fill out the location of a base ROM to be read during compilation, the location of your Project Directory, and a path to a ROM file (either one that you don’t mind getting overwritten or one to be created) and hit Compile. Then, open up the outputted ROM in your favorite emulator (or simply click the Run button), and try out your work!

(Insert screenshot here)

And there you have it. Your first hack. Isn’t he cute?

Of course, this is just the beginning, and there’s a lot to learn yet...

Conclusion

You got to build your first hack for EarthBound and you got familiar with some of the tools you’ll be using, as well as getting a glimpse at some of the techniques you’ll be using time and again. From now on, you can read this manual in almost any order, since most chapters aren’t dependent on others. You’ll start learning all sorts of techniques one by one, until you’re ready to make the Next Big Hack.

Is your heart beating incredibly fast?