4 Hugues Ross - Blog: Adventures in GrafX2 Scripting
Hugues Ross


Adventures in GrafX2 Scripting

I'm currently working on a little game project. Since I want a relatively polished result, I have a lot of art assets to make. I'm spending many hours in my editor of choice, GrafX2, and I get the opportunity to see places where my workflow falls short. Sometimes, I want to do something but it's a little annoying because of the tools I use.

If I were nothing but an artist, then that would be the end. I'd either have to grit my teeth or move to another program. However, I'm a programmer and GrafX2 has a scripting API. I think you can see where I'm going with this.

Minor Troubles

There exists a pretty major roadblock for anyone who wants to get into GrafX2 scripting: There's no API documentation (As far as I can tell, at any rate). I spent my first 15 minutes or so trying to use the example scripts as reference, before getting fed up and tracking down the source code. As you can see here, there's one convenient spot in the codebase where you can find the relevant Lua functions. Thanks to my line of work, I'm already very used to reading code in place of docs so this made my work much simpler once I discovered it.

Another thing to be aware of is that GrafX2 always loads scripts when they're called. That means that all you need is an open copy of GrafX2, and you can regularly call your script for testing/debugging as you work. In my case, I set up my code and my editor side-by-side like so:
Click the image for a larger view

With these tools in hand, writing new scripts to improve my workflow is quite easy!

The Scripts

In the spirit of giving, I'm going to discuss the scripts that I've written and share them with the internet at large. All 3 or so GrafX2 users in existence can enjoy my work and rejoice!

If you just want the scripts and don't care about my chattering, click here now.

Animation to Spritesheet

This was my first and arguably most important script. GrafX2 generally exports animations as gifs which I have to go back and edit in GIMP to make them into spritesheets. This process is rather annoying, so I decided to make a script to do it automatically. Once that was done, I figured it might be worth my while to polish and release some scripts. (Technically, I still have to change the color mode to RGB in GIMP, but I plan to add indexed color support to dfgame sooner or later)

This script pretty just copies animation frames to the second page, and arranges them however the user asks. There are probably more options that I could add for more complex layouts, but it should cover most cases.

I recently noticed an issue with this script where it doesn't work occasionally. When that happens, you can probably just run it again and it'll work. The script's logic appears to be correct, so it may just be a GrafX2 bug. It's hard to tell for certain.


Zoom-in-Place, or ZinP as I like to call it, is a product of how I like to present my work. As you can see in this post, I like to place a zoomed version of my art next to the original. This is also useful for getting critique! Unfortunately, this is a little bit annoying to do manually. I could just take a screenshot, but that method is impossible for animations like this one:
That took about 2-3 seconds to produce, and most of those seconds were spent finding and starting up the script. It's probably even faster than spinning up a gif/video recorder, and unlike a recording this preserves the palette information correctly.

Append Page

Since I was on a roll, I decided to write another script. This 3rd script, Append Page, is pretty simple: It just copies information from the inactive page to the currently active one. Unlike the page copy in GrafX2, this script appends the copied data instead of replacing the original contents. The result leaves the two pages side-by side for easy comparison. Unlike a normal copy and paste, Append Page preserves layer information. As a result, you can easily compare two variations of the same image layer-by-layer without making several manual copies.


I'm aware that these scripts are fairly situational. Indeed, they're absolutely catered to my specific workflow. Honestly though, I think that brings up a really good argument for non-coders to learn just a little bit of scripting:

When you know the basics of scripting, you can take your tools and make them work just right. Maybe there's one little thing that annoys you here and there, or a minor little convenience feature you wish existed. When you know how to script, and your applications support doing so, there's nothing to stop you from solving your own problems and getting that perfect workflow.

Someday, I want to see a world where DIY scripting is regarded as normal enough for everyone to know just a little bit. It's awfully idealistic of me, but I think it'd be a nice thing to see. Programming can be awfully hard work, but just a little bit here and there can produce great results for relatively little trouble.

No comments: