EarthBound Text Editor There's a hint for ya...

Tomato: "This program allows users to (somewhat) easily edit text in the ROM of the SNES game, EarthBound.  EarthBound’s text system is unusually complicated, when compared to text systems of other games.  Although, that doesn’t mean EarthBound’s text system is totally different.  It’s just the fact that first, the text is compressed, and second, the text system also includes special “control codes” that perform lots of functions.  Most other games also use “control codes”, but definitely not to the extent EarthBound does."

This is it folks.  The big daddy of them all.  The EarthBound Text Editor.  Oh yeah.  Giver of pleasure and pain.  My lord and master - after Tomato, that is...  This thing is gonna tie you down to the bed and give you a spanking like you won't believe.  If you're still having problems figuring out that button in the Sprite Editor that says "Save Sprite,"go home to momma.  This one ain't for greenhorns.  In fact, you'd better go read some of the other topics to prepare yourself.  At least you have one thing to be happy about - the Hint Guy usually charges for hints.

Jon's Badass Side: "The EBTE is arguably the most powerful tool there is for hacking EarthBound.  It's like an assault rifle - respect its power, learn to use it properly, praise it, make love to it, call it "Mommy"; some day it will save your life.  But handle it improperly, drop it, wield it recklessly, point it in your face - it's gonna open up a can of whoop-ass on both you and all the work you did over the past week faster than you can say, "Llanfairpwllgwyngyllgogerychwyrndrobwllllantysiliogogogoch."  Trust me, I've been there, and I know what I'm talking about.  And just for the record, that's a town in Wales, not a sneeze."

Ahem... thank you...  In previous text-editing manuals the control codes are listed right alongside the workings of the text system itself.  But I've come to realize that is a bit audacious - If one were learning to ride a skateboard, you'd need to figure out how to keep from falling on your ass before you'd really want to try a kick flip or something.  That's why I've decided to place the codes in a seperate chrestomathy for use by those with a little more experience in the way the system works.

chres•tom•a•thy (kres•tom•'e•the) n.   pl. •thies  A collection of choice extracts; especially, one compiled for instruction in a language.
[<Gk. chrestos useful + manthanein learn>] ... aren't I helpful? :)

Your first steps in text hacking!

Before we get into the workings of the EBTE GUI, we're going to learn a bit about how the text system is arranged in EarthBound.  Now, the text of EarthBound is made up of three different types of code, each represented by different Hexadecimal values.  First, there are plain text bytes, control codes which do things in the game, and lastly there are compressed text bytes, which we'll deal with later.  The entirety of the text in the game is divided into individual blocks, which contain the text of a single conversation or such.  They appear like this:
TEXT[02]TEXT[02]TEXT[02]TEXT[02]...
And it continues like that through the entirety of the game.  A "[02]" appeares at the end of every text block to indicate a stop. That's one of the control codes Tomato mentioned.  However, interspersed with the text, there are many, many more...
 
 
Code you see in the EBTE
Game Result
@Spit spit spit[10 0F 00]  Saliva spit spit[10 0F 00]  Do you want some gum?[03 00]@Get yer own,[10 0F] twit.[13 02]
•Spit spit spit
  Saliva spit spit
  Do you want some gum?
•Get your own, twit.

In this famous line from EarthBound, we see the control codes in action.  They may seem incomprehensible now, but these are all very simple ones that you should get the hang of fairly quickly.  When you want to use a control code, put [ ] brackets around it.  This isolates it from the normal text.  It should be fairly obvious that you don't have to put them around each individual code.  It's just a matter of using the codes well that exemplifies a well-written sentence in EB Text.  So, before we get into the actual program, let's write ourselves a little sentence for someone that Ness and his cronies might encounter.  Let's say we want to make the guy above say "We are the Knights who say Ni!" So let's just type that out.
 

We are the Knights who say "Ni!"
We are the Knights who say Ni!•To tell you the truth,
•I like drinking tea and eating fresh vegetables,
•but that doesn't fit my super cool image.
•I guess I just have to accept this about myself.

Whoa!  What happened?  It looks like you forgot to put in the end of block tag...  see what a difference such a seemingly insignificant thing makes?
Let's try that again.

We are the Knights who say "Ni!"[02]
We are the Knights who say Ni!

Well, that's better, but you're still missing something.  Maybe you'd better learn some of the basic control codes that we saw in the first block.

@Spit spit spit[10 0F 00]  Saliva spit spit[10 0F 00]  Do you want some gum?
[03 00]@Get yer own,[10 0F] twit.[13 02]
@ is the •.  Do two spaces instead of this when hitting a new
line if you want it to line up with sentences that start with •.
[10 __] marks a brief pause.
[00] is a line break.  You know, a carriage return.
[03] makes it wait until the player hits the "A" Button.
[13] does the same thing, but
the little triangle isn't there.
[02] ends the block.
Also, < > indicate Quote marks.

Wow, that's a lot of stuff there!  Don't worry, once you really get into the swing of EB Text it'll be fine.  I once caught myself trying to use these codes when writing an essay... :/  The [10 0F] need a little explaining? Well, you might want different lengths of pause for different events, right?  Well, that's how it works.  When the game hits that little [10] there, it says, "Okay, I have to wait..." and looks at the byte right after the [10].  It's a variable that indicates exactly how long the pause should be, and can be any number from 00 to FF.  Remember, everything in here is Hexadecimal, so you count 0-9, then A-F, then 10.  So let's say we want it to pause for a little bit before it says "Ni."  Let's make it a pause of 3A.  So, we put in [10 3A].  See, easy!  As you hack you should play around with the pause code to get a feel for how long different values are.  Now that we know these codes, let's go back into our example.
 

@We are the Knights who say[10 3A] <Ni!>[13 02]
We are the Knights who say "Ni!"

There!  That's a pretty snazzy sentence, if you ask me.  Now, let's go on to some more stuff that you may find confusing.

Managing Text Block Size

Okay, it's safe to open the program now.  But don't get too hasty, you've still got a LOT to learn.  You may remember Tomato mentioning compression.  Well, that's another kind of control code.  I'm not going to make you memorize the compression codes - there's hundreds of them - but I do want you to learn the underlying concept.
 
Okay, here we've loaded the EBTE and accessed the spitting shark.  (Just click on it.)  At the moment, I want you to notice the Size readouts.  You have Size, which is the space the block takes up in the ROM, and current size, which is how much you have typed in the text window.  You can't apply safely in this environment if the Current Size is larger than the Size.  But just a minute... why is the Current Size larger than the Size if we haven't changed anything?

Compression, that's why.  See, you have plain text bytes that are one byte long for each character, and compressed text bytes that are two bytes long but represent clusters of plain text.  The red text below represents the compressed text in that message.

@Spit_spit_spit[10 0F 00]__Saliva spit_spit[10 0F 00]__Do_you_want some_gum?[03 00]@Get_yer_own,[10 0F] twit.[13 02]

So why does the Current Size read as bigger?  Because when the EBTE opens the block into the editing panel, it converts the compressed text into standard non-compressed text.  What takes up 2 bytes in the Size can take up 5 bytes in the Current Size.  Because the EBTE doesn't recompress text, your messages will tend to be shorter than in the original game unless you recompress manually.  We'll discuss a way around that a bit later.

Pointers, Raw Text, and The Expanded Meg

Okay, let's pop open the Options menu for a moment.  See those first three options?  They are going to become your best friends.  Each different list contains different data.
*Pointer table listing contains the Pointer table, which concerns what person has what sprite image, how they move, and the first thing they say when you talk to them.  It's the first one that loads.
*Raw text listing contains nearly all the text in the game, including shops, item descriptions, and battle text.  Also, if a person says more than one thing, you can find all of those here, unlike the Pointer table listing, though. 
*If you use the Expand ROM function in the Tools menu (Or the EB ROM Expander), use the Expanded ROM listing to access the megabyte of free space that you can use for whatever.  By expanding the ROM, you add an entire megabyte of free space to the end of the ROM for you to put text in!  This is very useful for hackers because recompression parameters are a pain in the butt.  Keep in mind that loading the Expanded ROM listing can take a long time.  I have a 600 MHz processor with 128 Mb of memory and it still takes me about 20-25 seconds to load it.
And, as long as we're here...
*Displaying text and codes converts all text codes into readable text, and all control codes or unrecognized data into bracketed numbers.  If Display codes only is selected, it converts nothing and you see all the data in the block as their numeric hex value in one giant set of brackets.
*Use Compression... well, you've got to see it for yourself.
*Prevent Overwrites is the protection switch that, if your Current Size is bigger than the block Size, stops any changes.

It's all in the details!

By using the Tools dropdown menu, you can access these menus.  This is some of the more useful stuff in the EBTE - using these will really get you where you want to go.  See in the TPT entry editor, you have the Sprite Number and the Movement number.  Changing these will change which sprite the person who says the text in that block and how they move around.  There is a list of Sprite numbers here.  The movement numbers have not been fully documented, so it can be helpful to test what you're doing in the ROM when you modify it.

The Interpreter, Raw Data, and ROM Info functions are all pretty self explanatory.  But, do you remember from the Newbie's guide about the difference between Hex and SNES addresses?  Let me repeat that here.  Some programs, like generalized hex editors, will use the hex format when looking for locations in the code, while other programs (the ones specialized for EB) and any internal pointer coding use the SNES format.  To convert from the actual hex format to the SNES format the game uses, you need to do this:

snes_address = (hex_address + 0xC00000) - 0x200

And to go from the SNES address back to hex, you do this:

hex_address = (snes_address - 0xC00000) + 0x200

And now we come to the dreadful subject...

Creating and Managing Pointer Links

Links are possibly the most important - and most misundertood type of control code in EarthBound.  The main use you'll probably find for them is extending the length of a block of text.  There are three different pointer codes, all of which have unique uses.

1) Go-and-Return Links (Code [08 __ __ __ 00])
2) Go-and-Don't Return Links (Code [0A __ __ __ 00])
3) If-Then Links (Code [06 XX XX __ __ __ 00])

Okay, so let's go through a brief example of how each of these can be useful.  Let's use a go-and-return link.  With this, the text block referred to in the code is played through, and then it continues from the point of the link in the original text.  This is useful in many situations, including where you have an  important event block which includes menus and such.

Let's start by adding something to the Expanded Meg.  We get there by selecting Expanded ROM listing from the Options menu, then clicking the first available block.  Empty ones are invisible, so just click on the left side of the navigation window.

Now that we're in there, let's type something, remembering to practice the basic text codes.
 

@We are the keepers of the sacred words - [03 00]
  <Ni,> [10 20]<Ping,> [10 20]and <Noo-wom!>[13 02] 
•We are the keepers of the sacred words -
  "Ni," "Ping," and "Noo-wom!"

•We are the keepers of the sacred words - 
  "Ni," "Ping," and "Noo-wom!"

Now that that's done, we can link to it.  First, check the Details to get the SNES address of the block, which happens to be $F00000. So, let's open the one we already did.  I know we didn't REALLY do it, so let's go into the Pointer Text listing, find the spitting Shark block, and type the follwing in.  Make sure to include the link code.  Start it with [08], and follow it up with the address you're linking to, then a [00]. (The [00] doesn't make a line break in this case, it's just a spacer to make things look nice.)
 

@We are the Knights who say [10 3A]<Ni!>[03 08 00 00 F0 00 02]
•We are the Knights who say "Ni!"
•We are the keepers of the sacred words -
  "Ni," "Ping," and "Noo-wom!"

Remember, you gotta put the address in backwards.  For example, if you had the pointer $ABCDEF, you'd make the link [08 EF CD AB 00].  That's all there is to it!  Also note we changed the 13 in the first block to a 03.  That way, when it waits for a user response before you link to the bit in the Expanded Meg, you get the little blinking arrow.  That way the player knows there's more text to come.


Now, let's talk about 0A links.  Say we're editing some block with menus.  Go into the Raw Text listing, then click Edit, and Search, then search for "Oh, c'mon..."  This will take you to the scene where Pokey asks if you hear Buzz Buzz.  Now, there's lots of code here, but don't drop a load yet, we're not dealing with most of it.

("No" response links to here)[00]@Oh, c'mon...[10 14]  You must hear it...[03 00 0A CF EA C5 00]("Yes" response links to here)@Yes!  You can hear it!(This is address C5EACF, right here.)

See the 0A __ __ __ 00 link?  If you look at this closely, Pointer $C5EACF links to a point directly after the yes response, so Buzz Buzz appears after Pokey says "You must hear it..." instead of also saying "You can hear it!" too if you chose No in the menu.  So you see, the 0A __ __ __ 00 link here jumps over the yes response and doesn't go back to the point of the link once it's done, so you don't hear both if you used a 08 __ __ __ 00 link.  Now, if you used a 08 link instead of 0A in this case, you'd probably get something like this:

•Oh, c'mon...  You must hear it...
(Buzzy's big spiel, then...)
•Buzz Buzz joins you.
(Pokey whines at you for a moment, then...)
•Yes!  You can hear it!
(Then, Buzz Buzz... appears again?)

So you can see, these little details are important.


06 XX XX __ __ __ 00 is an If-Then statement.  First off, you need an Event Flag.  I'll discuss those more in the CC Chrestomathy, but suffice it to say they're the game's way of remembering what's happened so far.  The 06 link makes it so if the specified Event Flag is set as having happened, the game will link to the specified address.  So once you've decided on your event flag, you can use it like the other two types.  Let's try something fun now.  Go back into the Expanded Meg and add the following:
 

@Pardon me,[10 20] the sign says <No shirt,[10 20] no shoes,[10 20] no service.> [03 00]  But, since you're saving the world, I'll make an exception.[00 02]
•Pardon me, the sign says, "No shirt, no shoes, no service."
  But, since you're saving the world, I'll make an exception.

Okay, good.  Check the address in Details (which is $F00050.)  Now let's go into the Raw Text and add this 06 link somewhere.  See the first block of text?  Open it and add the 06 link at the beginning.  The first two bytes are the space for the Event Flag.  Fill in there, [ED 02].  This is the code that controls whether Ness is wearing pajamas or not.  Then add in your address.  Notice I had to shrink the message somewhat to fit the 06 link.  Normally, I would add a 08 link to another part in the text to make room for more talking.  But for now, I don't want to confuse you.

[06 ED 02 50 00 F0 00]@What u want?[00 02]

This will generate one of two responses.
 
If Ness Is Dressed...
If It's Ness' Nappy-Time...
THIS SPACE FOR RENT!

Pretty funny, huh?

Tomato: "Menus in EB are actually pretty easy to make/use, however, they’re difficult for me decode into editable form, so they don’t look very good in the editor.  If you’re bold and daring, here’s the basic format :

[00 19 02]XX[02 19 02]XX[02 1C 07 02 11 09 02 XX XX XX 00 XX XX XX 00 02]"

Looks pretty freaky, but relax and you'll do fine.  Put in your two options (Yes And No, Buy And Sell, etc.) in spots XX & XX.  Then, add your pointer addresses.  The address for option XX goes in the XX XX XX 00 spot, and the one for XX goes in XX XX XX 00.  Again, let's try this out.  Why don't we make Down Home Burgers more like your average burger store?  Open up the Expanded Meg and type in:

@You want fries with that?[00 19 02]Yes[02 19 02]No[02 1C 07 02 11 09 02 08 01 F0 00 2C BC C5 00 02]
[1D 0E FF 59]@There you go.[03 00 02]

$F00108 is the location of the "There you go."  Because there's a [02] at the end of that menu, it automatically puts the "There you go" into a different block.  You won't see it, however, until you leave the Expanded Meg and then come back in.
$C5BC2C directly links to a [02].

Uh oh, the text is too big to fit now!  Since we're in the Expanded Meg, and there's nothing but blank space after this text, you can go ahead and uncheck Prevent Overwrites in the Options menu.  Now, go into the Raw Text listing and search for "(smile, smile)."  Then, scroll down, and open the block that says "Thank you very much."  Type this in there.  Since you won't be seeing the XXXX, it's just there for space filler.

[0A D3 00 F0 00]XXXX[02]  ($F000D3, of course, is the menu you just added.)

This will allow for one of two responses.
 

Yes, I want fries.
No, no fries, thanks.

I won't ask you to learn the code in the "There you go" block now, but what it does is give the first available character a bag of fries.  Kinda neat, huh?  There are ways of making it see if you have enough money to pay for it, or enough room in your pack, but that's a little bit of overkill for a demonstration of how menus work.  There are other kinds of pointers, but I don't want to overload you right now.  Breath a little bit.
 

Manually Finding Pointer Addresses

This is an important skill!

Actually, the only skills it requires is the ability to use a mouse and the ability to count.  Time again to whip out the handy-dandy Windows calculator (In scientific mode.) Now, let's say you want to find the address of a certain line in a text block.  How do you find it?  Simple!  Let's say we want to find the address for the point where the Starman Junior says "I'll stomp you hard!"  Go into the codes only mode.  That way you get an accurate byte count as opposed to the text and codes - remember, the decompressed text increases the size..

Now, find your location.  Good things to look for are codes that stand out.  You'll notice I've highlighted in red the code blocks I used as an anchor of sorts (the 18 04 served as a way to find my location, and I knew there were 2 [03 00]s before it, and the text began just after the first one of those.)  Confused yet?  Good.  Select everything from the location in question to the end of the block.

Now, delete that selected text.  Don't worry, we're not making any permanent changes.  Now, take a look.
 
 

Notice something?  The current size has changed.  That number represents the number of bytes after the beginning of the block where the "I'll stomp you hard" begins.  So, take that, plug it into your calculator, and click Hex.  Now you see it is 93 bytes in hexadecimal form from the beginning of the block.  Now, take the SNES address of the block ($C6750B) and add it to 93 (While still in hex mode.)  Now we have $C6759E - the address of the point we wanted!  You can use that link to do battle with the Starman Junior again!  There you have it.  That's useful for figuring out all sorts of handy stuff, like fixing menus that have been damaged, and just linking around.

Compressed Text Bugginess

Sadly, the EBTE doesn't recognize all control codes.  In fact, it will sometimes "recognize" a compressed text byte in the middle of a different code.  For example, you could have [1F 15 03 00 40 0B 00] (I just made that up randomly) and it will see the [15 03] and convert it.  Thus you get [1F]...[00 40 0B 00].  When you save your changes, the text doesn't recompress, so the control code starting with [1F] has been changed, and will probably crash your game.  The main rule to keep in mind is if something is decompressed in a place where it doesn't make sense for it to be, it probably shouldn't be, and you'll have to manually recompress it.  Either reference the Compressed Text code list for that text or look for it in Codes Only mode.


Well, if you've absorbed this information, you'll know most of what it takes to utilize the EBTE.  What you really have to do is get in there and practice.  Even if you know the basics of how the system works, the only thing that can prepare you fully for the rigors of hacking EB's text is actually digging in and getting your hands dirty.  Practice practice practice.  How about I sharpen you?  I just love sharpening.  You don't want me to sharpen?  Sidem oonsi demoon.  Welc welc omewelc omeome.  Don't forget to go check out the Control Code Chrestomathy to learn to do exquisitely l33t things to your hack!  Good luck to you.