Last update: 2016.03.18
Pokemon First-Gen Text Hacking!

(Also see my friend's tutorials here!)

Have you ever wanted to translate, edit, or make your own pokemon game? Then you want to use Pokered, Pokeyellow, Pokecrystal: These are "ROM disassemblies", meaning that some geniuses have taken the game and turned it from looking like utter confusing nonsense to the average person, into something that you can edit even while having no clue what you're doing. Pick one depending on which game you want to hack:

English Red and Blue. In order to make it look like Green, you'll have to edit it pretty heavily. Complete.
https://github.com/pret/pokered

English Crystal (not sure if it's complete)
https://github.com/pret/pokecrystal

English Yellow (as of right now, isn't complete)
https://github.com/pret/pokeyellow

——————————
CHANGING THE ALPHABET



The first step for translators! Go to "gfx > font.png". From there, edit the file in some image editor. You can't make it bigger or smaller and you can only use the same two colors (black/white). So just draw your symbols on it, you can use the blank spaces too. If you want to do Chinese, kanji, etc — things where there's not enough room for the letters — try getting help from some pokemon-hacking forum. Here's an example thread:

https://hax.iimarck.us/topic/6752/

Now open charmap.asm. Every line on the font.png corresponds to a certain "head number" and then each square on that line corresponds to a secondary number. C is $82, and one line directly under that is S, $92. You need to change the symbols in-between the " " this file so that it matches what you have on your image.

After the q... 'v line ($B) comes the $C line, the line under that is $D, and then the line '.... ♂ line is £E. So now you know how to name whatever you've done.

NOTE! I'm asking for help on how to put certain characters on top of other characters, so ex. you can write Ĉ with C and ˆ being separate characters. That would make it so letters don't have to be so squished.

Anyway, save these files and now you're done, you can type with those new characters directly in the .asm files when editing dialogue and text.

——————————
TEXT HACKING

First off, there's 5 different types of editable text.

These are for dialogue, system messages etc. Anything that exists in that rectangular little dialogue box:  text, para, line, cont

These are for names that get repeatedly stored and recalled in the game, ex. pokemon and item names:
db


First off, while playing, take note of a dialogue line that EXACTLY fits to the edge of the box. In my case:

        "Mi nomiĝas ORKIDO!"
= 18 characters allowed per line, if the line is the first or last one in the dialogue overall, or is a "para" line.

Other lines can only take 17 characters because the little triangle that says "click to see more dialogue!" covers up the last one.

If you open one of the .asm files in any random text editor, dialogue will look like this:

        para "OAK's taken a lot"
        line "of interest in"
        cont "you, child!"


        text "Splash!"
        para "I'm first up!"
        line "Let's do it!"
        done

While editing, you have to always keep the indents intact however they may have been originally. You can't have, for example:

para "OAK's taken a lot"

...because it's not going to work. The game will get glitches. When making copies of your files, if you copy from one file and paste into another but the indents get removed, try using a different program to open the file you want to paste things into. For example, I can edit files in Xcode just fine, but copy-pasting into Xcode eats all the indents, so when copy-pasting I have to open the file in Text Edit, paste it and save it.

Also, you can't just duplicate the .asm files and replace old ones with new ones completely, if working with back-up copies etc. you have to copy-paste your edits in. Otherwise it's not always going to recognize that you've made any edits at all when it makes the ROM later. Duplicating and replacing files works perfectly fine for image files however.

If you want more dialogue lines within the same text box, it always uses this order (if you break the order, you'll get glitches. It'll play random sounds and music):

para, text ーー> line
line ーー> cont
cont ーー> cont, para

Example:

        cont "you, child!"
        cont "more text here"

Or:

        cont "you, child!"

        para "more text here!"
        line "even more here!"

Line and cont are for normal new line breaks, meaning the text just moves one line up in the dialogue box. If you put cont directly after para (with no line in-between), the line will appear at the bottom of the text box with a gap above it.

Para is for a paragraph break, meaning that the previous text is "wiped away" and then the new line appears. It's just like a line break that's two lines tall.

Text is (I think?) for when the code is referring back to something already and the current line of text is supposed to be on the same line as it. This will be described later.

Done or Prompt just signals the end of the dialogue, triggering whatever is supposed to come next in the game.

You can add or delete as many lines of dialogue as you want!

If you have a character's name or other "variable" in there, meaning the game is recalling a string of text from somewhere for all the cases when you can't type it out manually (ex. a pokemon's nickname), it might look something like this:

        text "Oh! Your name is"
        line $52, "!"

In-game:
Oh! Your name is
ASH!

        para "Do ", $52, "O,"
        line "elektu antaŭe mi!"
        done

In-game:
Do ASHO,
elektu antaŭe mi!

        text $53, ": He haltu!"
        line $52, "O!"

In-game:
GARY: He haltu!
ASHO!

In the first example, $52 is the variable name (it writes the player's name for us, no matter what it may be). A comma afterwards signals that what comes next is a different type of text, or a different variable. Within " " is the text that we type ourselves, meaning it's not a variable — it's dialogue.

In the second, we have the same thing. " " signals our typed text. A comma comes afterwards to signal "typed text is done — now onto a variable". After the variable is another comma — "that one variable's finished, now onto something else". Done marks the end of the dialogue completely, closing the dialogue box.

When a variable is at the very front of a line of text, there's no comma before it because we don't have to signal that we're breaking off a different type of text. If we have two variables on the same line, a comma needs to come in-between them too.

Note that when inserting variables in dialogue, there aren't spaces automatically put in before and after for you! You have to put them inside the quote marks, just like with "Do ". If I were to write "Do", in-game it'd end up like like:

        DoASHO,

In dialogue most words are actually written out, ex. "(player's name variable) recieved a POTION!" instead of "received a (item name variable)!". Item variables are actually used in the "event code" that programs in the actual event of you receiving that item.

It's generally wise to not put more than one variable on the same line, because the names (in English) are too long and, if using the max amount of letters allowed, they'll run outside of the dialogue box. For example, you could potentially have two pokemon names that are 10 characters long each. The text box can only fit 17-18 characters.

For the same reason, it's best to make item names and trainer names as short as you can. It just minimizes the amount of hassle things can be.

——————————
BATTLE TEXT

Aside from Gary/your rival battles, it's a progression that looks like this:

        _Route3BattleText1::
        (dialogue goes here)
        done

        _Route3EndBattleText1::
        (dialogue goes here)
        prompt

        _Route3AfterBattleText1::
        (dialogue goes here)
        done

"Battletext" is what they say when the ! symbol appears and they walk up to you. "EndBattle" is what they say, still on the battle screen, when they lose. "AfterBattle" is what they'll always say whenever you talk to them after having beaten them.

NOTE! Before the "EndBattle" dialogue starts, the trainer's name automatically appears even though it doesn't show it in the dialogue! The default line type here is "text", meaning:

        _Route3EndBattleText1::
        text "Ĉagrenige"
        line "malvenkis!"

But in-game:

BUG CATCHER: Ĉagrenige
malvenkis!

That's too long for one line. BUG CATCHER appears there despite that we have no variable demanding it — it's programmed to do this elsewhere in the code. That's why (I think) we use text instead of para, because text comes after some code stuff... At this point I don't know how it works but if/when I learn it I'll come back to edit this tutorial. We can't change this "text" to anything else, because it causes bugs. Instead, we do this:

        _Route3EndBattleText1::
        text " "
        line "Ĉagrenige"
        cont "malvenkis!"

In-game:

BUG CATCHER:
Ĉagrenige
malvenkis!

The initial line is left blank and we just add more lines to make everything fit.

NOTE! Battles with Gary/your rival work differently. There is "After battle win" and "After battle lose" text in the game for every rival battle, but in fact only the very first "if you lose" text is ever used.

I'm going to ask for help for how to change that so you can program in special text for him too.

——————————
NOTE! @ marks a trigger for some kind of code that comes next. If you put something directly behind @ it's not going to show up, you have to find where that future trigger is and put it in normal text there instead.

For example, I wanted to translate the battle message "(POKEMON) used (ATTACK)!"

Now, in "monster_names.asm" I've written my pokemon names without grammatical endings, and then I add on the proper ending specially depending on what's being said. Let's pretend PIKACHU is my pokemon name and O is the grammatical ending. I need to see "PIKACHUO ATTACKED", instead of "PIKACHU used ATTACK" which is what it would look like right now.

This has three different parts. The original text:

        _MonName1Text::
            text $5a, "@@"

$5a is the name of our currently-battling pokemon, in this case Pikachu. @@ signals that after writing the pokemon name, something else comes next from another bit of code.

        _Used1Text::
           db $0
           line "used @@"

        _Used2Text::
           db $0
           line "used @@"

This is the "used" in "used attack", but the @@ again signals that something else comes next. @@ doesn't mean the attack name itself. There's two of these that have the same text (in the English version), so we have to change both to the same thing when we do make changes.

        _ExclamationPoint1Text::
           text "!"
           done

This is the end of the sentence. So our "ED" has to come before this point. Also, in the real code there's ExclamationPoint2, 3, 4 and 5 to do the same thing to (just leftovers from the Japanese game again).

So this is how it's done:

        _MonName1Text::
           text $5a, "O@@"

O needs to come directly after the pokemon's name. $5a is the variable for "currently-battling pokemon's name".

        _Used1Text::
           db $0
           line "@@"

        _Used2Text::
           db $0
           line "@@"

We're not going to say "used attacked" so we delete the "used" that was here. $0 is another variable, so if we wanted text to come on that same line, we would write: $0, "(text goes here)". (For example:    db $0, "text"   )

        _ExclamationPoint1Text::
           text "ED!"
           done

The ! is the final ending of the sentence, so we know that ED goes right before it.

This results in:

           PIKACHUO
           THUNDERSHOCKED!

If we were to write line "ED!" instead of text "ED!", it'd end up as:

           THUNDERSHOCK
           ED!

——————————
The other editable text type is DB, which can be a nickname for something that you can change without breaking any connections in the game — ex. town names on the town map, pokemon names, or item names when listed in your backpack and computer. There is another more hard-coded name that, if changed, WILL break connections. That one is often DW.

DB can look like this:

        db "TOWN MAP@"
        db "BICYCLE@"

Again, don't remove the @, it does something in the code. If you need to put grammatical endings on the end, this has to come in the actual dialogue that they're being used in, just like how we edited "ATTACKED" above. Otherwise you can rename them all as you please. However, items, trainer and pokemon names can only be so long, so just take the longest one that already exists in the list and don't go past that amount of characters.

Pokemon names are different, in the "monster_names.asm" file they look like this:
       
        db "HITMONCHAN"
        db "ARBOK@@@@@"
        db "PARASECT@@"

By default, pokemon names can be 10 characters or less. Each @ fills up a blank space so that they all end up as 10 in the end. If you want to edit how many spaces each pokemon name can have, the settings are in a file somewhere. Again, if you copy-paste from somewhere, make sure that however the indents are in the original file, they're kept the same way in the final product.

!!! NOTE! Some DB you shouldn't edit! It should be fairly obvious which ones, ex. if they have underscores in them like this:

        db ATTACK_UP1_EFFECT

——————————
USEFUL VARIABLES:

$52 = Player's name
$53 = Rival's name
$5a = Your pokemon that's currently battling
$59 = Enemy's pokemon that's currently battling
$E1 = PK in the "PKMN" symbol
$E2 = MN in the PKMN symbol

If wanting to write "PKMN" you have to put a comma in-between like this: $E1, $E2

——————————
USEFUL TEXT:

¥ = Money symbol. You can move this around to be behind numbers/costs if you want! In the Japanese game, this is simply the yen symbol, not a special "pokédollar" symbol like in the English.

USEFUL LOCATIONS:

Pokemon, item, moves, and town names (for when looking at the town map) are in the "pokered > text" folder and are named: monster_names.asm, item_names.asm, move_names.asm,  map_names.asm.

Oak's speech for when you very first start playing the game is oakspeech.asm, and the example names for the naming screen are in oak_speech2.asm. You have to change them in two places:

IF DEF(_RED)
DefaultNamesPlayer: ; 6aa8 (1:6aa8)
    db   "ALIA"
    next "RUĜ"
    next "ACER"
    next "LUDOVIK"
    db   "@"

This says, "If playing Red version, show these words on the screen". The first one is "Other name" and the others are your example names. Then you have to scroll down and change it here too to make it match:

IF DEF(_RED)
DefaultNamesPlayerList: ; 6af2 (1:6af2)
    db "ALIA@VERD@ACER@LUDOVIK@"

Trainer names need to be changed in two places:
trainer_names.asm and save_trainer_name.asm.

All the in-battle stuff like "used x item on y pokemon!" "y used z attack!" is in the "text.asm" file. The lines for the guys who sit on the bench in pokemon centers are in text.asm, they're not with the rest of the pokecenter text.

The battle menu ($E1 is PK and $E2 is MN in the PKMN symbol) is in "main.asm" and looks like this:

BattleMenuText: ; 7455 (1:7455)
    db   "FIGHT ",$E1,$E2
    next "ITEM  RUN@"

Currently I don't know how to move the batttle menu cursor. Until then, the spaces for RUN and PKMN can only be 3 letters long because the cursor cuts them off or they run outside of the text box.

The Safari Zone battle menu, Pokecenter healing menu, BUY/SELL/TOSS, USE/TOSS, YES/NO menu options are also in main.asm. So are the HM names when you're "in the field".

The text for when throwing pokeballs is named "ItemUseBallText".

The names of the status/skill things that can rise or fall ("ATTACK fell!" "DEFENSE rose!") are in core.asm and look like:

StatsTextStrings: ; 3f69f (f:769f)
    db "ATTACK@"
    db "DEFENSE@"
    db "SPEED@"
    db "SPECIAL@"
    db "ACCURACY@"
    db "EVADE@"

——————————
SAVING AND TESTING


To "compile" things and test out your game, you go into the "terminal" (or, I do on a Mac anyway) and write:

        cd pokered (hit enter)
        make red

It should take some seconds and either show you errors and point out in which line of which file the error is, or it'll act like it's done and you can then find the gameboy game file on your computer and try playing it. The game will be named "pokered.gbc". 99% of the time the error is just that I forgot to start or end the dialogue line with ".

If you already have a pokered.gbc in the folder, you need to rename or delete it before compiling a new one. Otherwise you'll get an error saying "there is nothing to be done".

Sharing ROMs with other people is technically illegal, but guess what? Apparently, sharing "patches" isn't. So you take a "clean" (unedited) ROM for pokemon red/crystal/whatever you're hacking that you've downloaded from some site, and download a patching program. The program compares the clean ROM to your compiled ROM from pokered, and makes a "patch file" for the differences. Now, anyone with a clean ROM for that same game can apply the patch and play your hack!

If you see info saying that creating patches doesn't work with pokered, it's just outdated. As of 2016.03.18 it works just fine.