0. Table of Contents

1. Introduction

 The views of this program may not be endorsed by the romhacking community.

Welcome to the "Text Insertion Gizmo (or Gizmo, for short) Show".

Gizmo was created in 2000, by Taskforce (AKA John Nobles). I do not, however, plan to copyright this work. Eventually, I will probably release the source code, and at that time you may "improve" or modify it any way you wish. But as it stands right now, I'm still streamlining its code. This is a pre-release beta. A beta, because I have not extensively tested it; pre-release, because I have not finished polishing all of Gizmo's planned features.

First, let me tell you what Gizmo is. Gizmo is a program that will allow you to perform one of three different tasks. It can insert a script into a ROM, with pointers (it even calculates internally how the pointers are aligned, and what to subtract from each pointer - without your help :) ). Or, it can insert a script without pointers. Or, it can even write a file that contains the order of the pointers.

Before we get started with this 30 minute info-mercial that contains all of this Gizmo-goodness and sundry explanations, let us hear what semi-satisfied customers have to say about Gizmo. We now go out into the interview field with Wildbill. Take it away, Wildbill!

Wildbill: Thanks Taskforce. Okay, let's see what our customers think of this SUPER product. Ah, I see Mister Simpson over yonder....

Wildbill: Yo, Mister Simpson, what do you think of Gizmo?

Homer Simpson: Well, I think the program is great, and I might even become a wonderful hacker someday, if only I can find that damned ANYKEY....

Wildbill: Ah, well, okay.... Fine, let's run this by again. Here comes Mister Pokemon Hacker #26237.

Wildbill: Mr. Phack26237, if I may call you that.... Give me your totally unbiased impressions of Gizmo!

Phack26237: WHEE, I SIMPLY LOVE GIZMO!! Ya see, I took Pokemon and turned Pikachu into Pimpachu. Now Pokemon is Pimpamon, and Pimpachu and his bodyguard go 'round pimping out Pokeman. Yah, instead of battling, they now have this orgy of wild Klingon-style sex, hee-hee....

Wildbill: Whelp, Amigo, you might say that THIS was a whole LOT more than we cared to know.... Wildbill: Hmmm.... This isn't going very well, is it? Well, I'll try just one more time. Ah, there goes Mr. Mariosuperhacker....

Wildbill: Hey, Bud.... Tell me YOUR impressions of Gizmo.

Mr. Mariosuperhacker: Heee! Just wait 'til you see Super Homario. Yep, tee-hee, I just turned The Princess into Luigi, an'--!!

Wildbill: Enough!! Stop it, already, will-ya!?

Wildbill: (*Sigh*) I give up.... Back to ya, Taskforce....

OK, friends, those were three GOOD examples of what you CAN'T and AREN'T allowed to do with this program. You may use Gizmo freely to translate and hack games, provided you've got the necessary gray matter to do so, but pul-lease don't attempt any of these style hacks. In other words, DON'T USE MY PROGRAM FOR YOUR SICK IDEAS!!!!

One other thing. If you do use my program, I would appreciate a mention in your NFO. Thanks.

Okay, down to the real nitty-gritty. How do I use this dreaded Gizmo program!?

2. The Interface

First off, lets start with what each box in the interface represents. (Note: Depending on which options you choose, some boxes may not be visible. (In other words, If you don't see 'em, you don't need 'em.)



This image shows every box available in the interface. As I mentioned, not all of these boxes will always be visible. To reiterate, you will see only those boxes needed for a particular task.

Now, let's take each box one-by-one and describe what it does, and whether it IS or ISN'T used, per the chosen mode.

2a. The Mode of Operation Box (or "mode box" for short)

This is the singlemost important box in the entire program. It's the box that tells the program what function you want it to serve. Or, simpler said, what you want to do with it. This box will ALWAYS be visible.

Even though the three options are fairly self-explanatory, I'll summarize them anyway.

The first option "Insert Script With Pointers" does exactly that. It inserts scripts, and calculates and inserts pointers, too. This option does require more explanation, though, so you'll understand how it works. In this mode, Gizmo reads the pointers from the ROM. Then, it determines how those pointers are aligned, and stores the info. Next, it reads the table file and loads it into two arrays, one for the hex, and one for the strings.

Before you ask, yes, substrings can very possibly be handled automatically. And, this next part should really strike your fancy. These strings can be of ANY SIZE, on either side of the equal sign. I'll explain this better later on, in the table file section.

Next, Gizmo inserts the script and stores each pointer it runs across, WHILE IT'S INSERTING. When it finishes inserting - using the info it obtained in step one - it writes the new pointers back into the game in the SAME ORDER as they were originally stored in the ROM. This will be referred to as Mode 1, from here on.

What does that mean to you? It means that your script SHOULD NOT be dumped using the pointers, that is, if you intend to use this program for insertion of your English text. This program was designed to take full advantage of pointers that are out of order, and especially to alter ROMs that contain more than one pointer, "pointing" to a single segment of text. This means that you can save bytes by not repeating strings. In order to use this program feature, you must dump the text exactly as it lies in the ROM.

The second option, "Insert Script Without Pointers", does just that. It just inserts your script. It doesn't bother to look at, identify, or calculate pointers in any way. In this mode, Gizmo does two things. It reads the table into arrays. Then, it inserts the text. That's it. This function will be called Mode 2 from here on, generally.

The final option, "Write Pointer Order Only", is for you QB/VB programmers out there who don't want to fool with trying to figure out a bunch of data statements that represent your pointer order. This Gizmo feature will write a text file that contains basic formatted data statements containing the order of the pointers, counting from 0 up. Why 0? Well, the first pointer is hardly ever inserted (as you usually start inserting your script there). So, this seems to be the best approach. Just make sure that your selection ignores the 0, or writes the starting pointer using it. This operation will generally be referred to as Mode 3, from this point onward.

2b. The Start button



This is the button you push when you've entered all of the needed information, and have selected the options you'll be using. In other words, this button makes the program do what it's designed to do. It will change to "Wait" while the program is crunching along. After Gizmo has run, it'll change back to "Click this button and let the FUN begin."

2c. The script filename box

This box is available in the first two modes. This is where you'll enter the location and name of your script file, in the form of c:\somegame\script.txt. This file will be the one containing the English script for your game, that is, the file that you want inserted into the ROM.

2d. The Rom filename box

This is the box where you'll enter the name of the ROM file that you want Gizmo to modify. REMEMBER, all but "Write pointer order only" is going to change the ROM permanently, so keep a backup copy of your ROM! You'll need the original ROM later on for making your patch file in SNESTOOL. This box is available in ALL modes.

2e. The text file output box

This box will eventually be used in all modes. Right now, however, it's used only in Mode 3, for "Write Pointer Order Only". Later on, when I update Gizmo, I'll have the program make a notation to this file about data that it was unable to find. In other words, it'll also be a log file for Modes 1 and 2.

2f. First byte of pointer Start Position Box

OK, let me explain this carefully. Your pointers have a high byte and a low byte. Sometimes, these are separated in the ROM. So, by allowing you to specify where each is separate, this gives you a more complete program. You'll see why if you ever have a need for this. At any rate, here's a sample pointer table. (NOTE: Include only pointers for the text you're working with. If you're not working with text for ALL of the pointers, don't list ALL of them.)

0064020 4036 6336 8236 9136 A836 D436

In this case, you'd point the program to 64020. (DO NOT POINT IT AT THE LAST BYTE IN THE POINTER). I know the last byte is the high byte, but Gizmo will reverse these for you, automatically.

So, why must you specify where each byte begins? Good question.... Fast answer. What if your pointer table looked like this?

0064020 0040 0036 0063 0036 0082 0036 0091 0036

Get the picture? This allows you to handle non-standard pointer tables. Here, you would point it at 64021. How does it know the number of bytes between each pointer, then? That's another box. Read on. BTW, all four of these boxes are available in Modes 1 and 3 only.

2g. Last byte of pointer Start Position Box

This just points to the second byte of the first pointer. In the example above:

0064020 4036 6336 8236 9136 A836 D436

Here, it points to 64021. And, in the other example:

0064020 0040 0036 0063 0036 0082 0036 0091 0036

Here, it points to 64023. Easy, right?

2h. First byte of pointer End Position Box

Now, this one just points to the first byte of the last pointer you're dealing with. Let's take the examples above, again. Example 1:

0064020 4036 6336 8236 9136 A836 D436

Here, it points to 6402A. And, in the other example.

0064020 0040 0036 0063 0036 0082 0036 0091 0036

Here, it points to 6402D. This box, and the next one, ARE NOT available if you uncheck the box marked "Auto Calculate Total Pointers".

2i. Last byte of pointer End Position Box

This just points to the last byte of the last pointer you're dealing with. Let's look at those examples again. Example 1:

0064020 4036 6336 8236 9136 A836 D436

Here, it points to 6402B. And, in the other example.

0064020 0040 0036 0063 0036 0082 0036 0091 0036

Here, it points to 6402F.

2j. Number of bytes between pointers to skip box

Remember that box I mentioned before? Here it is. This box tells it how many bytes it should skip when reading pointers. Let's take a look at those two examples one more time. Example 1:

0064020 4036 6336 8236 9136 A836 D436

Here, it should skip 2 bytes. And, in the other example.

0064020 0040 0036 0063 0036 0082 0036 0091 0036

Here, it should skip 4 bytes. See, it's how many bytes it has to move to encounter the next byte of the pointer. This box is also used only in Modes 1 and 3.

2k. Table filename box

This is the box where you specify the name of the table file containing the English font, needed for insertion. Note that tables ARE NOT in Thingy format. They are similar to a Thingy-style system, but are MUCH simpler. For more info, read the section on table file descriptions. This box is available in Modes 1 and 2 only.

2l. Text start position box

This box is simply the address where you want the program to insert text into the ROM. If you want the text to be inserted at 2208E, you put 2208E here. Available in Modes 1 and 2 only.

2m. original script position box

Okay, this box is fairly easy to explain. Why you must use it is a little more complicated. What you enter here is the original position of the script in the ROM. If the script was originally at 22DF3, you enter 22DF3. Why must you do this? Well you don't really have to, UNLESS you're moving the English script to a different part of the ROM. Now, that was simple, eh? And, it's available only when "Use current as original position" is not checked, and in Mode 1 only. Check below for additional information on this box..

2n. Enter total number of pointers

This box allows you to tell the program to use a set quantity of pointers. This data MUST BE ENTERED IN DECIMAL, NOT HEX!!! Let's say you enter the start position, and you know exactly how many pointers you want processed, but don't know the end position. Just enter that number here, and Gizmo will calculate the end position for you. Available in Modes 1 and 3 only.

2o. Use current script position as original script position box

When this box is checked, it means that you're inserting the script in the same place as the old Japanese script was located in the ROM. If this box remains unchecked, it means that you've moved the script. When it remains unchecked, the "use original script position" box appears, so you can enter the original script position. Available in Mode 1 only.

2p. Auto Calculate Total Pointers

When checked, it uses the start pointers and end pointers bytes - along with the skip count - to calculate how many pointers you have, automatically. The "total number of pointers" box is not available, if checked, because it calculates that automatically, too. The "end bytes pointer" boxes are not available when unchecked. Available in Modes 1 and 3 only.

3. The table file

Okay, first off, let me say that this table file is just a VERY stripped down Thingy-style table with one KEY difference.

Here is a VERY small sample table (incomplete, to be sure....)

0021=Joe
0022=Frank
0023=Ginger
41=A
42=B
43=C
61=a
62=b
63=c
01001075=Hail to the King.
01001076=It's the end of us all.
02=<end line>
03=<end page>
04=<end block>
/<end block>

First off, let me explain the one BIG difference. See the /<end block>. Notice how it isn't 04, but the other side of the equals. That is definitely not Thingy-like. It IS, however, how the tables must be done for Gizmo. The rest of the table is straight-forward hex bytes=string. IT IS YOUR JOB TO MAKE SURE THAT THE TABLE'S HEX IS PROPERLY FORMATTED. 11215 is not valid. 011215 is. It reads as 01 12 15, the hex code to be inserted. Get it, now? Also, end lines, end pages, and such are YOUR responsibility to mark. See the table above. The end block must also be specified, not only in the / but in a hex byte=end block fashion too. / is the only special symbol in the table. Nothing else will work, no @something, or #something, or > or whatever other symbols may be used in Thingy.

Now, we'll discuss the table limits. In short, 4096 total entries are allowed. Either side of the equals can be ANY SIZE though. Twenty (20) end block strings total, are allowed. That's the /something. This is pretty much all you need to know about the table, I believe. Oh yeah, make sure you put a return after the last item in your table, too.

One final thing. The bigger the table (especially the bigger the string side of the equals), the longer it will take for the program to complete. Gizmo was built to avoid any extra reading. SO, the smaller the table and strings, the faster it will run for you. Everything IS loaded into arrays, to improve speed. This thing is probably a MAJOR memory hog. And huge tables could be VERY slow processing.

4. The script file

Oh, what joy. This is where a headache for you may come in, if you DIDN'T originally plan on using Gizmo, then decided to later on in your project. Using the table above as an example, let me make a quick block of text for you.

Joe: I am going to kill you<end line>
because you're ugly.<end page>

Frank: Haw, you're uglier than<end line>
I ever thought about being.<end block>

Frank: Hail to the King!<end block>

Okay, let's take this piece of script and break it down. First off, don't worry about the missing table values of letters. Let's pretend they are there. When the inserter sees "Joe", it inserts 0021, then it inserts one letter at a time until it hits <end line>. There, it inserts 02. Then, it continues to insert letters one at a time until it hits <end page> where it inserts 03. Then, it inserts 0022 for Frank and continues inserting one letter at a time until it hits <end line>. At this point, it inserts 02 again. It reads the rest one letter at a time, inserting as it goes until it hits <end block>. At this point, it inserts 04, which is the end of block string, AND it calculates the pointer (if it's supposed to) and stores it temporarily, to be put back into the ROM later. That's why the /<end block> is there. That is how it knows that this is the piece of text that triggers a pointer. Then, it puts 0022 for Frank again, and inserts the hex for : and (space); and then it puts 01001075 for the substring, "Hail to the King!". Finally, it inserts 04, calculates, and stores another pointer, if need be. When it's done, if you so designated, Gizmo puts the new pointers back in the ROM.

The other thing I didn't mention is that script files allow you to input hex code directly from them. The ~ mark means there's a bunch of hex bytes coming up. Doesn't matter how many, so long as you put another ~ after them. So, let' say that we wanted to change pictures above.

~0501~Joe: I am going to kill you<end line>
because you're ugly.<end page>

~0502~Frank: Haw, you're uglier than<end line>
I ever thought about being.<end block>

~0502~Frank: Hail to the King!<end block>

In this case the 0501 is put in the ROM just as you see it. It writes 05 01 as hex bytes to the rom. So let's say 05 01 is joe's pic trigger code. And 05 02 is Franks pic. See how this works?

That pretty much covers the script file. Just remember, it is up to you to specify the end of line/end of page/end of block breaks in the table and script file. It doesn't assume that a return is an end of line. REMEMBER THIS!!!!!

Two more notes of interest: <end line> isn't necessary. These can be anything. Like # could be end line, and @ could be end page, and % could be end block. The only symbol that you CANNOT have in your table file is ~. Under no circumstances can you use ~. You can use another symbol for ~ - if it's in your game - representing ~ in your script file with a substitute symbol. But any time you use ~, Gizmo will expect hex values to follow it.

5. Conclusion

This about wraps the documentation for Gizmo. Hope by now you have a good understanding of how this program works, and will be able to make good use of it. Features to look for in future versions: 3 byte pointers, error log files, and anything else I can think of. Any requests?

Thank you for joining our program! See you soon....

-Taskforce