WARNING: This portion of the guide is outdated, the contents of this guide have been merged with the main setup articles. It is only kept for legacy purposes. You can find all up-to-date guides on the TimoVM's Gen 2 ACE setups article.

	This is a guide on how to execute and/or exploit a glitch. For a more technical overview of the glitch involved, see Mail writer.

The Mail writer is an arbitrary code execution program 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.

This guide is applicable to the Japanese versions of Crystal only. It is part of the TimoVM's Gen 2 ACE setups set of guides.

Using the Mail writer requires an ACE setup, like the one described here, that redirects execution to the start of box names.

If you encounter any issues when going through this guide or would like to provide feedback, please contact TimoVM on the Glitch City Research Institute Discord.

Verifying that the Mail Writer is correctly installed

In the previous guide, you should've already executed 0x1500 ACE and installed the RAM writer. If this was performed correctly, you should be able to see the following:

The first item in the main item pocket has changed to a TM15.
Your box name list should have been changed to fit the following:

If this is the case, you can now simply use TM15 at any time to start up the Mail Writer, regardless of your location or the pokémon in your party.

If the setup either wasn't successful or the Mail Writer doesn't properly work anymore, you can find instructions on how to (re)preform the setup within the addendum at the bottom of the page.

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.

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 lower left corner of the screen. This can be used to verify if a code was entered correctly.

Assembly can easily be converted to mail codes using Scotteh's mail writer tool. Simply paste the assembly of the code you wish to enter here, press "run" and the converter will automatically generate mail codes requiring the least amount of button presses to write. A list of ready-to-use codes will be provided at the end of the guide.

Assembly can easily be converted to mail codes using TimoVM's MailConverter. Simply paste the assembly of the code you wish to enter here, press "run" and the converter will automatically generate mail codes requiring the least amount of button presses to write.

Controls

Between entering mail codes, the mail writer will ask for user input.

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.

Due to space limitations, it is not possible to exit the Mail Writer without executing the newly written code. If you accidentally start the Mail Writer, you can safely exit by writing a mail with the contents "セス" and execute it.

What to do with the Mail writer

The Mail writer allows you to easily write and execute arbitrary payloads. Aside from writing your own codes, we recommend the following:

Mail codes: this page contains a collection of assembly for mail codes that can be used for a variety of common purposes such as editing pokémon, obtaining items, etc..
RAM writer: (recommended for more experienced users) this page contains the assembly for a large one-size-fits all program that allows you to edit any value in RAM with a user-friendly GUI. It will also fix the side effects of the ACE setup when you first run it.

Addendum: repairing the Mail Writer

If anything happens that causes the Mail Writer to no longer function correctly, you will need to perform the setup once more. You can do this by following the process described here:

Preparation

Ensure that the first item in the main item pocket is an item you can afford to lose.
Ensure that Spearow is holding a mail with the following content:

Check to ensure that your party is arranged as follows:
1. Spearow, holding mail
2. Rocky the Onix not holding anything OR Sandshrew holding Lemonade
3. Slots 3 through 6 are not relevant to this setup.
Write the following box codes:

Using 0x1500 Control Code ACE

To execute ACE, do the following:

Stand in front of the PC on the second floor of any pokémon center. Save and reset the game.

Take exactly one step down and open the start menu.

Open the summary of Onix and close it.

Take exactly one step up so you’re in front of the PC. Open the start menu again

Read the mail you've previously given to Spearow (the Spearow needs to be at the very top of your party list).

Open the PC. Open the withdraw screen so that the unterminated name pokémon's name would be displayed. Displaying this name will trigger ACE.

If ACE was successfully executed, the first item in the main item pocket will be changed to a TM15. Alongside this, a bootstrap will be installed so that using TM15 will open the Mail writer. Finally, two bytes from the box names will be overwritten so that the Mail writer can be used.

From this point onward you can simply use TM15 at any time, regardless of what party pokémon you have, to use the Mail writer.

Appendix: in-depth explanation of the setup

Effect of the mail

The last read mail is buffered from $D002 onward. Please note that viewing the bad clone in box #1 will write the value $01 to $D003 and $D004. Converting the characters from the mail to assembly results in the following, ordered by language:

3E 01		ld a, $01
01 8D A6	ld bc, $A68D
26 DA		ld h, $DA
2E 12		ld l, 12
84		add a, h	; a = $DB
32		ldd (hl), a
81		add a, c	; a = $68
32		ldd (hl), a
90		sub a, b	; a = $C3
32		ldd (hl), a
F6 4E		or $4E		; a = $CE
EA 86 D8	ld(wItems), a
D6 96		sub $96		; a = $38
EA A1 DB	ld($DBA1), a
EA B1 DB	ld($DBB1), a
E1		pop hl
C9		ret

Effect of the box name code

Converting the box name code to assembly results in the following code:

Box 1: $DB68
11 B1 D2	ld de, $D2B1
D5		push de
D5		push de		; .newMail
26 2E		ld h, $2E
2E 50		ld l, $50	; hl = $2E50

Box 2: $DB71
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

Box 3: $DB7A
B7		or a
CF		rst08h		; farCall _ComposeMailMessage (a:hl = 04:5CEB)
D1		pop de
E1		pop hl		; Set both hl and de to the start of the newly written mail
2A		ldi a, (hl)
B7		or a
B7		or a
D6 50		sub $50

Box 4: $DB83
28 12		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
B7		or a
D6 50		sub $50	; Ensures that new character will result in the same value when combined with the next

Box 5: $DB8C
86		add (hl)	; .character
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 have to do
E6 50		or $50		; Ensures that carry flag is not set

Box 6: $DB95
30 E7		jr nc, .loop
0C		inc c		; .terminator, _ComposeMailMessage sets bc to 0000, so c = 01 after this part
26 C5		ld h, $C5
2E F4		ld l, $F4	; hl = $C4F4, bottom left screen tile
06 50		ld b, $50	; Ensures that b is consistent for the next call

Box 7: $DB9E
1A		ld a, (de)
CD 90 38	call PrintBCDNumber.loop + 01h	; PrintBCDNumber.loop itself can't be reached, so we skip forward one byte.
26 1A		ld h, $1A	; .errorCorrection
1B		dec de		; Calling PrintBCDNumber.loop with c = 01 advances de by 1.
06 50		ld b, $50

Box 8: $DBB0
2E 8D		ld l, $F4	; hl = $1A8D 
29		add hl, hl	; hl = $351A (address of JoyTextDelay_ForcehJoyDown)
CF		rst08H		; Farcall JoyTextDelay_ForcehJoyDown	set a = current button state
B7		or a, a		; Are any buttons pressed? if not, ask for new button states
28 E9		jr z, .terminator
42		ld b, d
50		ld d, b

Box 9: $D8FA
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.
D8		ret c		; If not, another button was pressed, so decrement de to allow user to correct errors
30 EA		jr nc, .errorCorrection

Plain text transcripts of codes

Mail

ぼ ほ ほ セ ル が れ ぜ デ オ づ イ づ チ づ 0
ゥ キ リ よ ヌ ゥ モ ろ ゥ あ ろ ゅ の

Box name codes

Box 1:　ヅ　あ　め　ゆ　ゆ　が　ぜ　ぜ
Box 2:　ゆ　げ　ぜ　ェ　ぼ　ガ　べ　プ
Box 3:　き　ま　む　ゅ　ご　き　き　よ
Box 4:　ぐ　デ　だ　ガ　ご　き　き　よ
Box 5:　キ　デ　ド　ア　ぺ　デ　ご　？
Box 6:　だ　！　ズ　が　な　ぜ　ォ　ギ
Box 7:　ビ　ヘ　チ　チ　が　ビ　ブ　ギ
Box 8:　ぜ　セ　げ　ま　き　ぐ　ァ　プ
Box 9:　ダ　ダ　け　パ　ダ　リ　だ　ゥ

Guides:Mail Writer C (JP)

Contents

Verifying that the Mail Writer is correctly installed

How the mail writer works

Using the Mail writer

Controls

What to do with the Mail writer

Addendum: repairing the Mail Writer

Preparation

Using 0x1500 Control Code ACE

Appendix: in-depth explanation of the setup

Effect of the mail

Effect of the box name code

Plain text transcripts of codes

Navigation menu

Guides:Mail Writer C (JP)

Verifying that the Mail Writer is correctly installed

How the mail writer works

Using the Mail writer

Controls

What to do with the Mail writer

Addendum: repairing the Mail Writer

Preparation

Using 0x1500 Control Code ACE

Appendix: in-depth explanation of the setup

Effect of the mail

Effect of the box name code

Plain text transcripts of codes

Navigation menu

Search