Page 1 of 1

uGrab - a GUI-based EGAGRAPH editor (not just) for Keen source mods

Posted: Sat Jan 25, 2020 22:25
by K1n9_Duk3
I've mentioned this project a few times, so I guess it's about time to go public with it. This is uGrab:

I grab. You grab. We all grab -- with uGrab!
Like it says in the title of the thread, this is mainly intended to assist in the creation of source mods. Nearly all of the old tool were designed to simply mod the original games, since changing the amount of sprites, pics or fonts in a regular Keen mod is pretty much impossible without massive patches.

I found myself having to rename tons of files or rewriting half of the ModId definition file every time I added new sprites for Foray in the Forest. To make my life a little easier, I wrote this program.

I know, most of you are still doing old-fashioned Galaxy modding, so you won't find yourself adding new sprites to the EGAGRAPH file. Most of the features in uGrab won't be of any use to you, but here is something you might be interested in: the hitbox editor.


For all I know, the only way to modify a sprite's hitbox in ModKeen, ModId and other tools is to enter numbers into a text file. uGrab lets you draw the hitbox with the mouse (or move it with the keyboard) and you can actually see the hitbox while you're doing that. To the best of my knowledge, you had to import your bitmaps into the EGAGRAPH and then export them to bitmaps again to get any visual representation of the hitboxes when working with the other tools.

On top of that, uGrab also makes it easier to detect potential hitbox issues that may cause ground-based actors (Keen or enemies) to get stuck or abort certain animation sequences. The hitbox of a ground-based actor should be identical for all of the sprites to avoid issues. If it's not, the actor might no longer touch the ground when changing from one sprite to the next. Depending on the code, this might cause the actor to turn around, start jumping/falling or get stuck. Most enemies are not intended to jump or fall, so they get stuck when they don't touch the ground anymore. Since uGrab lists all elements of the hitbox data in the Sprites tab (see first screenshot), you can scroll through the sprites while keeping an eye on the hitbox data to find potential issues.

The last and perhaps most important feature is the ability to optimize the sprites for less memory usage by removing any fully transparent (and therefore unnecessary) parts of the image. Just to give you an idea how useful the sprite optimization can be: I've used it to optimize the sprites for the unofficial 1.3 release of Atroxian Realm and this reduced the memory requirements for some levels by about 27 to 45 kilobytes! So if you're working on a mod and run out of memory in some levels, give this sprite optimization a try.

I know this program has some issues (see the readme.txt for details). If you find other bugs or have an idea how the tool can be improved, let me know. Perhaps somebody can write an even better tool to replace uGrab. I wouldn't mind.

Re: uGrab - a GUI-based EGAGRAPH editor (not just) for Keen source mods

Posted: Sun Jan 26, 2020 2:43
by lemm
This is fantastic. I always wanted a tool that would allow you to resize the hitbox directly over the sprite... and you made it!

Re: uGrab - a GUI-based EGAGRAPH editor (not just) for Keen source mods

Posted: Sun Jan 26, 2020 8:26
by Nisaba
this tool is a blessing!
I'm constantly using uGrab to add, edit and reorganize sprites and other stuff to my upcoming source-code mod. And I'm telling ya, I added a lot of additional stuff to Foray in the Forest. Thanks to K1n9_Duke3 this process can now get semi-automated. uGrab is indeed a timesaver if you are about to extent the standart EGAGRAPH file.
So, for source-code modding tasks this would be the tool of choice

Re: uGrab - a GUI-based EGAGRAPH editor (not just) for Keen source mods

Posted: Tue Jan 28, 2020 2:17
by thehackercat
Will I finally finish a mod after 11 years?

This tool means one less excuse! The visual hitbox editor is super cool.

Re: uGrab - a GUI-based EGAGRAPH editor (not just) for Keen source mods

Posted: Fri Jan 31, 2020 6:00
by K1n9_Duk3
I have uploaded a new version of uGrab.

The new version can extract the EGAHEAD and EGADICT files from the game's executable, which makes it easier to mod Keen 4-6 with uGrab. The zip file also comes with the necessary ModId definition files. Copy the definition file into your game folder and import the EGAGRAPH file by opening that definition file in uGrab.

Just a heads up: uGrab cannot write EGAGRAPH files for use with Keen Dreams. The generated EGAHEAD files are always in 3-byte format, while Dreams requires the 4-byte format. I will fix this in a future release.