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

Here is where to post about the latest Commander Keen fangame or modification you've finished, a new website you've made, or another Keen-related creation.
Post Reply
User avatar
K1n9_Duk3
Vorticon Elite
Posts: 711
Joined: Mon Aug 25, 2008 9:30
Location: Germany
Contact:

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

Post 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:

Image
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.

Image

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.
Last edited by K1n9_Duk3 on Mon Jan 27, 2020 23:25, edited 1 time in total.
Hail to the K1n9, baby!
http://k1n9duk3.shikadi.net

User avatar
lemm
Blorb
Posts: 688
Joined: Fri Jul 03, 2009 10:18
Location: canada lol

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

Post 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!

User avatar
Nisaba
Vorticon Elite
Posts: 1233
Joined: Fri Jan 01, 2016 23:34
Location: The Outpost
Contact:

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

Post 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
"We have come to conquer you all and bring you lots of candy!" | about me | my current project: play Keen mods on a GameBoy |

User avatar
thehackercat
Yorp Doctor
Posts: 666
Joined: Fri Aug 14, 2009 0:05

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

Post by thehackercat »

Will I finally finish a mod after 11 years?

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

User avatar
K1n9_Duk3
Vorticon Elite
Posts: 711
Joined: Mon Aug 25, 2008 9:30
Location: Germany
Contact:

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

Post 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.
Hail to the K1n9, baby!
http://k1n9duk3.shikadi.net

daminingboyalpha
Meep
Posts: 1
Joined: Sun Jan 10, 2021 6:35

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

Post by daminingboyalpha »

When will Catacomb 3D support be added?

Arno
Grunt
Posts: 3
Joined: Wed Feb 17, 2021 17:37

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

Post by Arno »

daminingboyalpha wrote:
Sun Jan 10, 2021 6:35
When will Catacomb 3D support be added?
This might go way beyond the scope that K1n9_Duk3 intended, but I was able to open up the Catacomb 3D graphics with these steps:
1. Copy the CAT3D.EXE and EGAGRAPH.C3D files from the GOG Catacombs Pack to a separate folder.
2. Put the cat3d_softdisk_122.def file from ModId in the same folder.
3. Open the latest uGrab and select the option "Import from EGAGRAPH..."
4. Select the cat3d_softdisk_122.def file.

So from that point onwards viewing and exporting everything to bitmaps is relatively easy, Note that the new sprite editing features are not that useful for Catacomb 3D, since there are only three sprites in the EGAGRAPH file, which are used in the Skull N Bones mini game. All the walls and object graphics are stored as pics. Nevertheless, uGrab can replace pics just as easily, so that's not really an issue.

The hard part for me is to import the graphics back into the game. When doing the import, uGrab creates the EGAGRAPH.C3D and EGAHEAD.C3D files. However, Catacomb 3D has the EGA header info stored internally in the executable. And there's no CKPatch utility for Catacomb 3D. I think ModId itself would have the same limitation, so I also checked the readme of ModId, but didn't see any specific instructions for importing graphics back into Catacomb 3D. I guess you could use a hex editor to manually copy the contents of the EGAHEAD.C3D file to the correct offset in the decompressed CAT3D.EXE, but I didn't try that. I'm not really planning on doing a Catacomb 3D mod myself, but it is fun to play around with the available tools.

Image

User avatar
K1n9_Duk3
Vorticon Elite
Posts: 711
Joined: Mon Aug 25, 2008 9:30
Location: Germany
Contact:

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

Post by K1n9_Duk3 »

For Catacomb 3-D, there is really no point in using uGrab, especially if you just want to edit the exising graphics and not add or remove things. WDC should be able to do anything you want.

If you want to do some serious Catacomb 3-D modding, you'll need to get the source code from GitHub and a copy of Borland C++ 3.1 (the Wolf3D community has downloads). You can either modify the code to take external EGAHEAD & EGADICT files (just remove or comment out the "#define GRHEADERLINKED" line in ID_CA.H) or you can grab a copy of MakeObj and convert the files into object files that you can compile into the executable. The Keen Dreams source has source code for MakeObj and a batch file that you can modify to create .OBJ files for Cat3D.


Buf if you really want to use uGrab's output and put the modified files back into the executable, this is what you'll have to do:
  1. Get the ModId definition file for that game
  2. Open the EGAGRAPH file in uGrab through that definition file
  3. Modify whatever you want to modify
  4. Save the changes to a new EGAGRAPH file (this will also generate EGAHEAD and EGADICT files)
  5. Open the ModId definition file in a text editor
  6. Find the EXEINFO line in that file, it should look like this:

    Code: Select all

    GALAXY
    	GAMEEXT <ext>
    	GRSTARTS 3
    	EXEINFO <filename> <exesize> <egaheadpos> <egadictpos> <exeheader>
    
    (Note that GRSTARTS can be either 3 or 4 and you have to use the same EGAHEAD Type when saving the EGAGRAPH file in uGrab.)
  7. Create a new text file with the following contents:

    Code: Select all

    %exefile <filename> <exesize>
    %patchfile <egaheadpos> EGAHEAD.<ext>
    %patchfile <egadictpos> EGADICT.<ext>
    %end
    Replace the <> placeholders with the actual values from the definition file and then save this as a plain text file.

    For reference, this is what the file should look like for Catacomb 3-D: The Descent v1.22:

    Code: Select all

    %exefile cat3d.exe 0x2D7A0
    %patchfile 0x1A880 EGAHEAD.C3D
    %patchfile 0x22FD8 EGADICT.C3D
    %end
  8. Get the most recent version of my patching utility and open the text file with that utility.
  9. Follow the instructions and save the modified executable somewhere.
  10. Copy the modifed EXE and EGAGRAPH into the same folder and also copy the other game files (AUDIO.C3D and GAMEMAPS.C3D) into that folder. Don't overwrite any of the new files.
  11. Run the modified executable (in DOSBox).
Hail to the K1n9, baby!
http://k1n9duk3.shikadi.net

Arno
Grunt
Posts: 3
Joined: Wed Feb 17, 2021 17:37

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

Post by Arno »

Thank you, that detailed overview was really helpful! I managed to import a test image back into the game with ease. :)

I got some inspiration now to dig a bit further into the available tooling (WDC, ModId, ...). I'm thinking of extending the Catacomb 3D page at the ModdingWiki. An up-to-date overview of the tools and some instructions to get people started would be nice to have.

Image

Post Reply