#incext vs #incbin, or 'how do I make my buildfiles build fast'

If you’ve used buildfiles, you’ve doubtlessly seen stuff like this:

ALIGN 4
Battle_Name_Graphics:
#incext Png2Dmp “New_Stat_Names.png” --lz77

ALIGN 4
Battle_Name_Palette:
#incext Png2Dmp “New_Stat_Names.png” --palette-only

And similar lines within various installers. What happens when Event Assembler encounters this magical “#incext” (include extension) directive? It launches Png2Dmp, waits for Png2Dmp to do its thing and then sticks the results into the ROM. This is convenient if you’re in the middle of altering “New_Stat_Names.png” and testing it ingame (since you need just alter the file, save and rebuild to test), but it is not a fast process. And every instance of #incext in your build adds up and makes it take longer. This is how people end up with multi minute build times.

But there is an alternative, in the form of #incbin (include binary). What does #incbin do? It just takes the contents of a file and smashes it into the ROM. It is almost exponentially faster than #incext.

ALIGN 4
Battle_Name_Graphics:
//#incext Png2Dmp “New_Stat_Names.png” --lz77
#incbin “New_Stat_Names.dmp”

ALIGN 4
Battle_Name_Palette:
//#incext Png2Dmp “New_Stat_Names.png” --palette-only
#incbin “New_Stat_Names_pal.dmp”

(note: it’s a good idea to keep the original #incext command commented out so you know what options it used)
But, now we need to make the .dmp files ourselves. This isn’t hard, but there’s a bit of a method to doing it quickly so I’ll explain how I do it. First off, if your #incext directive is as simple as

#incext Png2Dmp “StarIcon.png”

Then you can just drag StarIcon.png onto Png2Dmp.exe (which will be located inside Event Assembler\Tools) and you’re done, easy. But what about our above example that includes these fancy options like --lz77 and --palette-only? We can prepare a very simple script to achieve the same drag and drop effect with these options:

On windows that looks like this (for other OSes, check the next post):

“%~dp0Png2Dmp” “%~1” --lz77

Open a text editor, paste that in, save it in the same folder as your Png2Dmp, name it “Png2Dmp with compression.bat” (or something similar). Then you can drag a file to the .bat you’ve created and boom, it’ll produce a .dmp with the --lz77 option. For --palette-only, the same theory holds - just change --lz77 to --palette-only, and save as a different name.

With that out of the way, you may have also seen #inctext (most likely with lyn). #inctext is to #include as #incext is to #incbin - it works with event files (and EA instructions) rather than binary data. So #inctext will slow your build down, just like #incext will. You’ll often see something like this

#inctext lyn “RaidCommand.elf”

lyn works a bit differently from Png2Dmp, if you just drag an .elf file to it it will show the output in a console window and immediately close. Not very useful for our purposes. Furthermore, #inctext lyn sometimes has multiple inputs, like so

#inctext lyn “EXPCalcLoop.elf” “EXPCalcLoopHook.elf”

You can make a batch file like this to solve that problem (save as .bat in the same directory as lyn):

“%~dp0lyn” “%~1” “%~2” > “%~1.lyn.event”

Drag and drop your (one or two) files into this .bat and it’ll spit you out an .elf.lyn.event (I usually rename the result to just file_name_here.lyn.event for consistency. There’s probably a way to automatically do this within your batch file but I haven’t been bothered to look it up yet). Then you can #include the .lyn.event and you’re good to go.

Before you run off to replace #inc(t)ext for dank build times, note that I have already done this through the current version of the skill system - so if your project uses that, go ahead and grab the latest version, it’ll save you some work.

The same principles here should apply to #incext / #inctext used on things other than Png2Dmp and lyn, I just chose those as examples because they’re the most common. If you’re running into another tool and aren’t sure how to generate a dmp from it, just post here and I’ll help.

15 Likes

If you’re doing this on a Linux box (or macOS), you can use bash aliases for fast dmp generation:

alias png2dmpcompress=‘“/home/user/SkillSystem_FE8/Event Assembler/Tools/Png2Dmp” --lz77’

(obviously replace the path with the path to your Png2Dmp, and stick it in your bashrc if you don’t want to have to run it every time you start a new terminal)

Then you can just type

png2dmpcompress filename

I also tried doing the same thing as on Windows (make a bash script, drag files to it) on my linux setup but apparently xfce’s file manager doesn’t let you drag things onto shell scripts. Not sure about other file managers.

For lyn I’d probably do a similar alias then just type it out

alias lyn=‘“/home/user/SkillSystem_FE8/Event Assembler/Tools/lyn”’
lyn FileOne.elf FileTwo.elf > FileOne.lyn.event

(or add the tools directory to your $PATH or whatever floats your boat)

There’s also the option of making a makefile setup (on any OS), but that’s well beyond the scope of this little guide.

4 Likes

make。。。

2 Likes