Baby's First Buildfile
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!
Create a new text file and type:
Now save that in Root as
Hello World.txt. Go back to your
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.
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
You should see a bunch of numbers, but on the right side you can see that they
Hello World! Congratulations, you inserted some data!
But this is just the beginning of what buildfiles can do...
#include "some/file.txt" do? Basically, it inserts the entire
some/file.txt in place.
So in our ROM Buildfile, the line
#include "Hello World.txt" becomes
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
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
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
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,
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 FreeSpace 0x1000000 #include eastdlib.event ORG FreeSpace #include "Hello World.txt"
Can you figure it out? That's right,
#define simply replaces one thing
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
#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:
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.
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.