Buildfile Basics

Baby's First Buildfile

Open up ROM Buildfile.txt and paste:

#include eastdlib.event
ORG 0x1000000

Wow, what a great buildfile! What does it do? Let's find out with an example!

Hello, World!

Create a new text file and type:

String(Hello World!)

Now save that in Root as Hello World.txt. Go back to your ROM Buildfile.txt and add this to the bottom:

#include "Hello World.txt"

Now it's time to assemble. Save ROM Buildfile.txt, take your clean ROM and make a copy of it. We'll edit this copy so that we always have a clean ROM available in case something goes wrong.

Event Assembler Window

In the Text field, select ROM Buildfile.txt. Set the ROM as the copy you made earlier. Make sure Game matches the one you're working on. When that's done, click Assemble!

You will see a friendly message:

"No errors or warnings. Please continue being awesome."

Perfect. But what did it actually do? Open up the ROM in HxD, press Ctrl-G and type 1000000 as the offset, ensuring that the hex option is selected.

Hex Editor View

You should see a bunch of numbers, but on the right side you can see that they translate to Hello World! Congratulations, you inserted some data!

But this is just the beginning of what buildfiles can do...

Understanding #include

What does #include "some/file.txt" do? Basically, it inserts the entire contents of some/file.txt in place.

So in our ROM Buildfile, the line #include "Hello World.txt" becomes String(Hello World!)

The file you #include can #include other files!

PUSH and POP

Let's take a step back and look at our ROM Buildfile again. What does ORG 0x1000000 mean? ORG stands for Origin meaning the starting offset of our data. In the previous example, we saw that our data was inserted to the offset 0x1000000.

Imagine it as a cursor that tells Event Assembler where to insert at. ORG lets you move the cursor to a specific position, where you can start "typing", i.e. inserting data.

If we don't put an ORG at all, Event Assembler just starts at offset 0, or the very beginning of the ROM. This breaks the ROM horribly!

What happens if we #include "Hello World.txt" twice?

#include eastdlib.event
ORG 0x1000000
#include "Hello World.txt"
#include "Hello World.txt"

If you assemble this buildfile, you will see Hello World! twice at the end of the data. The "cursor" doesn't stay where you put the ORG, it moves forward as you insert data. After the first Hello World is inserted, the cursor is now at the end of that data, ready to add the second Hello World.

Now, let's try something new. Make a new text file containing

ORG 0x1000050
String(Hellow Orld!)

and save it as Hellow Orld.txt. Now #include this in your buildfile between the two "Hello World.txt" lines.

#include eastdlib.event
ORG 0x1000000
#include "Hello World.txt"
#include "Hellow Orld.txt"
#include "Hello World.txt"

We'll want to start fresh for this, so delete the ROM you've been

assembling to and make another copy of the clean ROM.

Now assemble the buildfile again, and take a look in HxD. As expected, you have Hello World! at 0x1000000, and Hellow Orld!HelloWorld! at 0x1000050. But what if we wanted the two Hello Worlds together?

Go back to Hellow Orld.txt and add PUSH to the top, and POP to the bottom. PUSH creates a "bookmark" that remembers your position, and POP jumps back to the last bookmark you created.

PUSH
ORG 0x1000050
String(Hellow Orld!)
POP

You can PUSH multiple times, and each POP will take you to the newest bookmark you placed.

Assemble to a fresh ROM and this time, you'll see two Hello Worlds together, and Hellow Orld on its own at 0x1000050.

Definitions, Labels and Macros

It's now time to introduce you to one of the simplest, but most powerful commands in Event Assembler: #define!

#define FreeSpace 0x1000000
#include eastdlib.event
ORG FreeSpace
#include "Hello World.txt"

Can you figure it out? That's right, #define simply replaces one thing with another.

Well, that's certainly simple. What's powerful about it?

How about this?

#define FreeSpace 0x1000000
#define TestMacro(offset) "ORG FreeSpace + offset; String(Hello World!)"
TestMacro(0x10)

This is an example of a macro. Like a definition, it expands out into the second half.

ORG FreeSpace+offset
String(Hello World!)

However, the difference is that you can set the value of offset when you write the macro!

When you write TestMacro(0x10), you're telling EA that offset = 0x10. This expands out into:

ORG 0x1000000+0x10 //FreeSpace = 0x1000000, offset = 0x10
String(Hello World!)

However, if you had TestMacro(0x100), it would instead become:

ORG 0x1000000+0x100
String(Hello World!)

You may have noticed that TestMacro(offset) looks very similar to something we've seen before. Yep, String(text) is also a macro!

One final thing. You now know that definitions are like shortcuts that you create with #define. There is one more way to create a shortcut: Labels.

A Label is a shortcut for an offset.

You can create a label like so:

ORG 0x1000000
#include "Hello World.txt"

MyLabel:
#include "Hellow Orld.txt"

MESSAGE Hellow Orld is inserted at MyLabel

Assembling this will give you the following output:

Finished. Messages: Hellow Orld is inserted at 0x100000B

No errors or warnings. Please continue being awesome.

As you can see, a Label is an automatically defined offset. In this case, it tells you exactly where Hellow Orld begins. We'll be using labels a lot to track where our data is inserted.

MAKE HACK.cmd

You may have noticed that every single time we assemble, we use the same text file, the same ROM, and the same settings. Wouldn't it be nice if we could save those settings?

Enter MAKE HACK.cmd!

Create a new text file and paste the following:

cd %~dp0
copy "FE8_clean.gba" "FE_Hack.gba"
cd "%~dp0Event Assembler"
Core A FE8 "-output:%~dp0FE_Hack.gba" "-input:%~dp0ROM Buildfile.txt"
pause

(replace "FE8_clean.gba" with your clean ROM, both instances of "FE_Hack.gba" with your edited ROM, FE8 to FE7 if you're hacking that, and "ROM Buildfile.txt" with the name of your buildfile)

Save this as MAKE HACK.cmd in Root.

When you open this script, it will first copy and rename your clean rom. Then it will assemble the buildfile to the ROM. Finally it will pause when it's done so you can see the output and any error messages.

In other words, you can now build an entire hack from scratch in one click.