Mail writer
The Mail writer is an arbitrary code execution program for pokémon Gold, Silver and Crystal, created by TimoVM.
It is a 50 byte program, installed in the TM/HM pocket by having specific TM quantities, that allows the user to quickly and accurately write and execute arbitrary code payloads of up to a maximum size of 428 bytes. Payloads are written from wOtPartyCount onward, where enemy trainer's parties are usually buffered. Using the Mail writer requires an ACE setup that both redirects execution to the start of the TM/HM pocket and sets the value of register a to $04.
The Mail writer is currently supported for all language releases of Gold, Silver and Crystal, both VC and cartridge.
How the mail writer works
Upon execution, the Mail writer will open the mail character entry screen where the player can write up to 32 different characters. After the player has confirmed the mail, the following actions take place:
- The Mail writer will take pairs of characters and convert them into a single combined value. These values are then sequentially written, converting the 32 letter mail into a 16 byte long line of code.
- Next, the Mail writer will display a checksum calculated from the combined value of all written bytes for the player to verify. Then the program enters a waiting state where they can either choose to write another mail, go back and correct previously written values or stop the mail writer and execute the newly written payload.
- If the player has chosen to write a new mail, the Mail writer will open a new mail entry screen. The new mail is then also converted into a 16 byte lond line of code and placed right after the code written by the previous mail(s), allowing the player to write arbitrarily long payloads.
Mail codes can be automatically calculated using Scotteh's mail code tool. This tool will accept a code written in hexadecimal values and automatically convert them to mail codes. These mails are optimized to require the least amount of button presses possible. The following values were determined from converting a 288 byte long RAM writer code:
Language | Button presses |
---|---|
English | 5.0 |
French | 4.3 |
German | 4.9 |
Italian | 4.2 |
Spanish | 4.2 |
Korean | 10.7 |
Using the Mail writer
The mail writer will open a screen that asks you to write the contents of a mail. This is where you'll need to enter mail codes. Once done, use the "END" option to finish the mail.
This will cause the mail writer to convert the newly written code into assembly. It will also print a checksum (sum of all written values) on the screen just to the right of the lower row. This can be used to verify if a code was entered correctly.
Controls
Between entering mail codes, the mail writer will ask for user input.
- Press SELECT to open a new mail and continue writing data.
- Press START to immediately jump to and start executing the newly written program. Only use this when you've finished every mail.
- Press any button on the D-pad to go back one byte at a time to correct errors. If the printed checksum doesn't match the expected checksum, press DOWN 16 times to retry the last mail. This will also overwrite the printed checksum with the value at the currently selected address, giving you a method to check how far back you're going.
Due to limitations, the Japanese version of the mail writer has slightly different controls:
- Press A to open a new mail and continue writing data.
- Press B to immediately jump to and start executing the newly written program. Only use this when you've finished every mail.
- Press any other button to go back one byte at a time to correct errors. If the printed checksum doesn't match the expected checksum, press DOWN 16 times to retry the last mail. This will also overwrite the printed checksum with the value at the currently selected address, giving you a method to check how far back you're going.
Enter your mail code, then press "END". | It prints the checksum and waits for input. |
Installation
Prior to installation, the player should use an ACE code that sets the quantities of all TMs in the TM/HM pocket to x255. Then, the player can simply sell TMs until desired quantities are reached. The amount of TMs sold of each kind depends between versions and different languages.
The Mail writer only uses relatives jumps and can, theoretically, be installed at any address.
Quantities for EN/FR/DE/IT/SP versions
Gold & Silver: installed at D57E onward, writes bytes from DD55 onward.
Crystal: installed at D852 onward, writes bytes from D280 onward.
For Crystal only: while you can call the mail writer using 0x1500 arbitrary code execution, it is preferable to call it using Wrong Pocket TM ACE so that the tiles printed by PrintBCDNumber.loop are fully consistent with the tiles displayed by Scotteh's mail code tool.
Language/version independent TM quantities
TM | Final Quantity | Sell value |
---|---|---|
TM01 DYNAMICPUNCH | x17 | 357000 |
TM02 HEADBUTT | SEE NEXT TABLE | |
TM03 CURSE | SEE NEXT TABLE | |
TM04 ROLLOUT | x213 | 42000 |
TM05 ROAR | x213 | 21000 |
TM06 TOXIC | x213 | 63000 |
TM07 ZAP CANNON | x33 | 222000 |
TM08 ROCK SMASH | SEE NEXT TABLE | |
TM09 PSYCH UP | SEE NEXT TABLE | |
TM10 HIDDEN POWER | x207 | 72000 |
TM11 SUNNY DAY | x225 | 30000 |
TM12 SWEET SCENT | x209 | 23000 |
TM13 SNORE | x42 | 106500 |
TM14 BLIZZARD | x254 | 1500 |
TM15 HYPER BEAM | x80 | 262500 |
TM16 ICY WIND | x56 | 298500 |
TM17 PROTECT | x251 | 6000 |
TM18 RAIN DANCE | x40 | 215000 |
TM19 GIGA DRAIN | x10 | 367500 |
TM20 ENDURE | x135 | 180000 |
TM21 FRUSTRATION | x134 | 60500 |
TM22 SOLARBEAM | x18 | 355500 |
TM23 IRON TAIL | x19 | 354000 |
TM24 DRAGONBREATH | x35 | 330000 |
TM25 THUNDER | x129 | 126000 |
TM26 EARTHQUAKE | x79 | 264000 |
TM27 RETURN | x18 | 118500 |
TM28 DIG | x24 | 231000 |
TM29 PSYCHIC | x239 | 16000 |
TM30 SHADOW BALL | x33 | 333000 |
TM31 MUD-SLAP | x1 | 381000 |
TM32 DOUBLE TEAM | SEE NEXT TABLE | |
TM33 ICE PUNCH | x77 | 267000 |
TM34 SWAGGER | x205 | 25000 |
TM35 SLEEP TALK | SEE NEXT TABLE | |
TM36 SLUDGE BOMB | SEE NEXT TABLE | |
TM37 SANDSTORM | x27 | 228000 |
TM38 FIRE BLAST | x205 | 50000 |
TM39 SWIFT | SEE NEXT TABLE | |
TM40 DEFENSE CURL | SEE NEXT TABLE | |
TM41 THUNDERPUNCH | x189 | 99000 |
TM42 DREAM EATER | x40 | 322500 |
TM43 DETECT | x217 | 19000 |
TM44 REST | x56 | 298500 |
TM45 ATTRACT | x240 | 22500 |
TM46 THIEF | x254 | 1500 |
TM47 STEEL WING | x08 | 370500 |
TM48 FIRE PUNCH | x200 | 82500 |
TM49 FURY CUTTER | x24 | 346500 |
TM50 NIGHTMARE | x242 | 13000 |
Gold/Silver specific TM quantities
TM | English | French | German | Italian | Spanish | |||||
---|---|---|---|---|---|---|---|---|---|---|
Final amount | Amount sold for | Final amount | Amount sold for | Final amount | Amount sold for | Final amount | Amount sold for | Final amount | Amount sold for | |
TM02 HEADBUTT | x85 | 170000 | x85 | 170000 | x85 | 170000 | x85 | 170000 | x85 | 170000 |
TM03 CURSE | x221 | 51000 | x221 | 51000 | x221 | 51000 | x221 | 51000 | x221 | 51000 |
TM08 ROCK SMASH | x66 | 94500 | x43 | 106000 | x34 | 110500 | x118 | 68500 | x153 | 51000 |
TM09 PSYCH UP | x98 | 78500 | x98 | 78500 | x98 | 78500 | x98 | 78500 | x98 | 78500 |
TM32 DOUBLE TEAM | x196 | 59000 | x196 | 59000 | x196 | 59000 | x196 | 59000 | x196 | 59000 |
TM35 SLEEP TALK | x239 | 8000 | x144 | 55500 | x231 | 12000 | x222 | 16500 | x162 | 46500 |
TM36 SLUDGE BOMB | x58 | 98000 | x58 | 98000 | x58 | 98000 | x58 | 98000 | x58 | 98000 |
TM39 SWIFT | x144 | 111000 | x59 | 196000 | x135 | 120000 | x127 | 128000 | x77 | 178000 |
TM40 DEFENSE CURL | x55 | 100000 | x55 | 100000 | x55 | 100000 | x55 | 100000 | x55 | 100000 |
Crystal specific TM quantities
TM | English | French | German | Italian | Spanish | |||||
---|---|---|---|---|---|---|---|---|---|---|
Final amount | Amount sold for | Final amount | Amount sold for | Final amount | Amount sold for | Final amount | Amount sold for | Final amount | Amount sold for | |
TM02 HEADBUTT | x128 | 127000 | x128 | 127000 | x128 | 127000 | x128 | 127000 | x128 | 127000 |
TM03 CURSE | x210 | 67500 | x210 | 67500 | x210 | 67500 | x210 | 67500 | x210 | 67500 |
TM08 ROCK SMASH | x117 | 69000 | x122 | 66500 | x99 | 78000 | x197 | 29000 | x232 | 11500 |
TM09 PSYCH UP | x94 | 80500 | x94 | 80500 | x94 | 80500 | x94 | 80500 | x94 | 80500 |
TM32 DOUBLE TEAM | x197 | 58000 | x197 | 58000 | x197 | 58000 | x197 | 58000 | x197 | 58000 |
TM35 SLEEP TALK | x204 | 25500 | x175 | 40000 | x182 | 36500 | x186 | 34500 | x172 | 41500 |
TM36 SLUDGE BOMB | x56 | 99500 | x56 | 99500 | x56 | 99500 | x56 | 99500 | x56 | 99500 |
TM39 SWIFT | x75 | 180000 | x56 | 199000 | x53 | 202000 | x57 | 198000 | x53 | 202000 |
TM40 DEFENSE CURL | x53 | 101000 | x53 | 101000 | x53 | 101000 | x53 | 101000 | x53 | 101000 |
Quantities for KOR versions of pokémon Gold & Silver
Due to different character structure and different control code characters, the assembly of the Korean Mail writer is slightly different compared to the other versions.
Installed at D631 onward, writes bytes from DE52 onward.
TM | Final amount | Amount sold for |
---|---|---|
TM01 | 17 | 357000 |
TM02 | 82 | 173000 |
TM03 | 222 | 49500 |
TM04 | 213 | 42000 |
TM05 | 213 | 21000 |
TM06 | 213 | 63000 |
TM07 | 33 | 222000 |
TM08 | 217 | 19000 |
TM09 | 96 | 79500 |
TM10 | 207 | 72000 |
TM11 | 225 | 30000 |
TM12 | 209 | 23000 |
TM13 | 42 | 106500 |
TM14 | 254 | 1500 |
TM15 | 80 | 262500 |
TM16 | 48 | 310500 |
TM17 | 9 | 369000 |
TM18 | 150 | 105000 |
TM19 | 150 | 157500 |
TM20 | 18 | 355500 |
TM21 | 19 | 118000 |
TM22 | 129 | 189000 |
TM23 | 79 | 264000 |
TM24 | 18 | 355500 |
TM25 | 42 | 213000 |
TM26 | 180 | 112500 |
TM27 | 32 | 111500 |
TM28 | 240 | 15000 |
TM29 | 33 | 222000 |
TM30 | 01 | 381000 |
TM31 | 196 | 88500 |
TM32 | 77 | 178000 |
TM33 | 205 | 75000 |
TM34 | 206 | 24500 |
TM35 | 58 | 98500 |
TM36 | 27 | 114000 |
TM37 | 205 | 50000 |
TM38 | 121 | 134000 |
TM39 | 55 | 200000 |
TM40 | 240 | 7500 |
TM41 | 171 | 126000 |
TM42 | 189 | 99000 |
TM43 | 40 | 107500 |
TM44 | 216 | 58500 |
TM45 | 56 | 298500 |
TM46 | 238 | 25500 |
TM47 | 07 | 372000 |
TM48 | 208 | 70500 |
TM49 | 24 | 346500 |
TM50 | 241 | 14000 |
Quantities for JP versions
Unlike the others, the Japanese versions are able to use the Mail writer as a box code instead. Both are intended to be used with a wrong pocket TM ACE setup that redirects execution to the first box name ($D8B2 for Gold & Silver, $DB68 for Crystal). For Crystal, an additional setup using 0x1500 control code ACE is required to finish the box codes.
Gold & Silver
Write the following box codes, then use the wrong pocket TM ACE:
Box 1: ヅ に わ ゆ ゆ ゾ ュ ぼ Box 2: ゆ に ヂ ぺ な に ヨ プ Box 3: ゅ ま む ゅ ご き き よ Box 4: ぐ デ だ ガ ご き き よ Box 5: キ デ ド ア ぺ デ ご ? Box 6: だ ! ズ が と ぜ ォ ギ Box 7: ビ ヘ ば で が ブ ブ ぜ Box 8: げ ぜ ォ ま き ぐ ァ プ Box 9: ダ れ か リ ダ リ だ ゥ
Crystal
First, write the following box codes.
Box 1: ヅ に わ ゆ ゆ が ぜ ぜ Box 2: ゆ げ ぜ ェ ぼ ガ べ プ Box 3: き ま む ゅ ご き き よ Box 4: ぐ デ だ ガ ご き き よ Box 5: キ デ ド ア ぺ デ ご ? Box 6: だ ! ズ が な ぜ ォ ギ Box 7: ビ ヘ チ チ が ビ ブ ギ Box 8: ぜ セ げ ま き ぐ ァ プ Box 9: ダ ダ け パ ダ リ だ ゥ
Then, give a pokémon the following mail to hold. Execute 0x1500 control code ACE redirecting to $D000 (where the mail is buffered in memory). This code will modify two bytes from the above box code, along with replacing the first item in the main item pocket with TM15 and adding the required bootstrap to redirect execution to the start of box names.
ぼ ほ ほ セ ル が れ ぜ デ オ づ イ づ チ づ 0 ゥ キ リ よ ヌ ゥ モ ろ ゥ あ ろ ゅ の
Afterwards, you can use TM15 anytime outside of battle to start up the mail writer.
General assembly
EN/FR/DE/IT/SP versions
11 XX XX ld de, wOTPartyCount D5 push de .loop D5 push de D5 push de 21 XX XX ld hl, _ComposeMailMessage CF Farcall ; requires a = $04 E1 pop hl D1 pop de .nextChar 2A ldi a, (hl) FE 50 cp 50 38 FB jr c, .nextchar 28 0A jp z, .@ 87 add a 86 add (hl) 12 ld (de), a 13 inc de 23 81 add c 4F ld c, a 12 ld (de), a 18 EF jr nz, .nextChar .@ 21 01 C4/C5 ld hl, C401/C501 ; corresponds to a screen tile location. C401 for Gold/Silver, C501 for Crystal. 4D ld c, l CD XX XX call PrintBCDNumber.loop (-$01) ; if language ends BCD with $, jump to PrintBCDNumber.loop. else, jump to one byte before PrintBCDNumber.loop .DownPressed 1B dec DE CD XX XX call JoyTextDelay_ForcehJoyDown BD cp l; Due to the effects of PrintBCDNumber.loop, l = $04 28 D9 jr z, .loop 38 F0 jr c, .@ FE 08 cp 08 C8 ret z 18 F2 jr .DownPressed
KOR version
11 52 DE ld de, DE52 D5 push de .loop D5 push de D5 push de 21 D9 60 ld hl, ComposeMailMessage CF rst08 Farcall ;requires a = $04 to load correct ROM bank) E1 pop hl D1 pop de 2A ldi a, (hl) FE 50 cp @ 30 09 jp nc ;jump if next char is a terminator/line skip) 96 sub (hl) 96 sub (hl) 12 ld (de), a 13 inc de 81 add c 4F ld c, a 12 ld (de), a 2A ldi a, (hl) B4 or h .@ 20 F0 jr nz, F2 .noInput 21 01 C4 ld hl, C401 4D ld c, l CD CE 3A call PrintBCDNumber.loop .DownPressed 1B dec DE CD 79 37 call JoyTextDelay_ForcehJoyDown F0 AB ldh a, (hJoyLast) BD cp l ; due to PrintBCDNumber, l = $04 28 D8 jr z, .loop ; jump if a = $04 38 EE jr c, .noInput 07 rrca D0 ret nc 18 F1 jr .DownPressed
JP Gold & Silver versions
11 C6 DC ld de, DCC6 D5 push de .newMail D5 push de 0E AE ld c, AE 3E 50 ld a, 50 D5 push de C6 10 sub A0 ; a = 60 47 ld b, a ; bc = 60AE C5 push bc C6 A4 add a, A4 ; a = 04 42 ld b, d 50 ld d, b E1 pop hl ; hl = 60AE CF rst08H ; Farcall _ComposeMailMessage (a:hl = 04:60AE) D1 pop de E1 pop hl ; set both hl and dc to the start of the newly written mail .loop 2A ldi a, (hl) B7 or a, a B7 or a, a D6 50 sub 50 28 13 jr, .terminator 30 05 jr, .character 2A ldi a, (hl) ; if terminator, escape loop. if newline, get new value for a and continue B7 or a, a B7 or a, a D6 50 sub 50 ; ensures that new character will result in the same value when combined with the next .character 86 add (hl) 12 ld (de), a 13 inc de 80 add a, b 47 ld b, a ; responsible for generating checksum 12 ld (de), a 2A ldi a, (hl) ; inc hl is not available, so this will do E6 50 or 50 ; ensures that carry flag is not set 30 E7 jr nc, .loop .terminator 0C inc c ;_ComposeMailMessage sets bc to 0000, so c = 00 when we reach this part 26 C4 ld h, C4 2E F4 ld l, F4 ; hl = C4F4, bottom left screen tile 06 50 and 50 ; Ensures that b is consistent for the next call 1A ld a, (de) CD 3A 33 call PrintBCDNumber.loop + 01h ; PrintBCDNumber.loop itself can't be reached, so we skip forward one byte. .errorCorrection 26 1B ld h, 1B 1B dec de ; calling PrintBCDNumber.loop with c = 01 advances de by 01. 2E 50 ld l, 50 ; hl = 1B50 29 add hl, hl ; hl = 36A0 2E F4 ld l, F4 ; hl = 36F4 (address of JoyTextDelay_ForcehJoyDown) CF rst08H ; Farcall JoyTextDelay_ForcehJoyDown set a = current button state B7 or a, a ; is no button pressed? if yes, ask for new button states 28 E9 jr z, .terminator 42 ld b, d 50 ld d, b 0F rlca ; is the a button pressed? If yes, start a new mail DA B6 D8 jp c, .loop 0F rlca ; is the b button pressed? If yes, return and execute newly written program. if not, decrement de to allow user to correct errors D8 ret c 30 EA jr nc, .errorCorrection 50 ld d, b
JP Crystal versions
mail 3E 01 ld a, 01 01 8D A6 ld bc, A68D ; will be used for arithmetic operations 26 DA ld h, DA 2E 12 ld e, 12 84 add a, h ; a = DB 32 ldd (hl), a ; hl = DA11 81 add a, c ; a = 68 32 ldd (hl), a ; hl = DA10 90 sub a, b ; a = C2 32 ldd (hl), a ; hl = DA0F F6 4E or 4F ; a = CE (TM15 item ID) EA 86 D8 ld (D886), a; Item pocket, item #1 ID D6 96 sub a, 96 ; a = 38 EA A1 DB ld (DBA1), a EA B1 DB ld (DBB1), a E1 pop hl ; required for proper exit out of 0x1500 C9 ret 50 ld d, b *Bytes 2 and 3 get overwritten when viewing the unterminated name pokémon in the box Mail writer 11 B1 D2 ld de, D2B1 D5 push de .newMail D5 push de 26 2E ld h, 2E 2E 50 ld l, 50 D5 push de 29 add hl, hl ; hl = 5CA0 2E EB ld l, EB ; hl = 5CEB 3E 05 ld a, 05 3D dec a ; a = 04 42 ld b, d 50 ld d, b B7 or a, a CF rst08H ; Farcall _ComposeMailMessage -01h (a:hl = 04:5CEB) D1 pop de E1 pop hl ; set both hl and dc to the start of the newly written mail .loop 2A ldi a, (hl) B7 or a, a B7 or a, a D6 50 sub 50 28 13 jr, .terminator 30 05 jr, .character 2A ldi a, (hl) ; if terminator, escape loop. if newline, get new value for a and continue B7 or a, a B7 or a, a D6 50 sub 50 ; ensures that new character will result in the same value when combined with the next .character 86 add (hl) 12 ld (de), a 13 inc de 80 add a, b 47 ld b, a ; responsible for generating checksum 12 ld (de), a 2A ldi a, (hl) ; inc hl is not available, so this will do E6 50 or 50 ; ensures that carry flag is not set 30 E7 jr nc, .loop .terminator 0C inc c ;_ComposeMailMessage sets bc to 0000, so c = 00 when we reach this part 26 C5 ld h, C5 2E F4 ld l, F4 ; hl = C4F4, bottom left screen tile 06 50 and 50 ; Ensures that b is consistent for the next call 1A ld a, (de) CD 90(38) call PrintBCDNumber.loop .errorCorrection 26 1A ld h, 1A 1B dec de ; calling PrintBCDNumber.loop with c = 01 advances de by 01. 06 50 ld b, 50 2E 8D ld l, F4 ; hl = 1A8D 29 add hl, hl ; hl = 351A (address of JoyTextDelay_ForcehJoyDown -01h) CF rst08H ; Farcall JoyTextDelay_ForcehJoyDown -01h set a = current button state B7 or a, a ; is no button pressed? if yes, ask for new button states 28 E9 jr z, .terminator 42 ld b, d 50 ld d, b 0F rlca ; is the a button pressed? If yes, start a new mail (38)B9 jr c, .loop 40 ld b, b 0F rlca ; is the b button pressed? If yes, return and execute newly written program. if not, decrement de to allow user to correct errors D8 ret c 30 EA jr nc, .errorCorrection 50 ld d, b