Buildfile Basics
Baby's First Buildfile
Open up ROM Buildfile.txt and paste:
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:
Now save that in Root as Hello World.txt. Go back to your ROM Buildfile.txt and add this to the bottom:
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 selected.
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?
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
and save it as Hellow Orld.txt. Now #include this in your buildfile between the two "Hello World.txt" lines.
We'll want to start fresh for this, so delete the ROM you've beenassembling 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.
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!
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?
This is an example of a macro. Like a definition, it expands out into the second half.
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:
However, if you had TestMacro(0x100), it would instead become:
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:
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:
(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.
Last updated
