Buildfile Basics
Open up ROM Buildfile.txt and paste:
#include eastdlib.eventORG 0x1000000
Wow, what a great buildfile! What does it do? Let's find out with an example!
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.
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...
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!)
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.eventORG 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 0x1000050String(Hellow Orld!)
and save it as Hellow Orld.txt. Now #include this in your buildfile between the two "Hello World.txt" lines.
#include eastdlib.eventORG 0x1000000#include "Hello World.txt"#include "Hellow Orld.txt"#include "Hello World.txt"
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.
PUSHORG 0x1000050String(Hellow Orld!)POP
Assemble to a fresh ROM and this time, you'll see two Hello Worlds together, and Hellow Orld on its own at 0x1000050.
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.eventORG 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+offsetString(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 = 0x10String(Hello World!)
However, if you had TestMacro(0x100), it would instead become:
ORG 0x1000000+0x100String(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.
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.
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?
Create a new text file and paste the following:
cd %~dp0copy "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.