Hello all! My first blog and first entry. It'll be a doozy.
So as some of you know, I've been working quite heavily on creating an animation control system for Loxodon's new Sexbound API. It's very much a work in progress and I'll post details about how that will work down the road, but for now I want to talk about something that is lacking in a big way (which makes my animation system moderately pointless - for now).

New sprites for the races!

As everyone knows, the vanilla sprites for the races don't exactly provide much in the way of interesting visuals. Take the human femalebody.png for example, which handles the human body player and NPC visuals in the game (There are frontarm, backarm, and head/hair pngs that overlay onto this for the complete character):

Functional, but bland as hell. If we want to do something more fancy, we'll need to add to it (rather than replace it). I, personally, am not a sprite artist and have zero talent in that field, but I can at least help people understand what goes into the game's humanoid race sprites and how the engine uses them. After having spent quite a bit of time puzzling out how Starbound handles the player/NPC sprites without making a muhjillion (totally a number) spritesheets for every possible combination, I managed to find a way to animate the player with the visual setup the player chose as opposed to cloning the player and making a somewhat-similar object and animate it. I'll get more into that when I talk about my animation system.

Now then. The engine uses JSON-based information to figure out what frame on the spritesheet is where. Observe: This is the femalebody.frames JSON configuration file that handles all the femalebody.png files for each vanilla race:

There are a few portions that we need to understand before we move forward.

• The "size" property indicates the resolution of each individual sprite frame in pixels. That means the player's body sprites are each 43px wide by 43px tall.
• The "dimensions" property indicates how many frames there are in the sprite sheet.
  • The game automatically calculates WHERE each sprite is placed by multiplying the "size" values by the "dimensions" values to make a virtual grid.
  • The game requires the default grid, but I do not know if there is any actual limit to how many columns or rows can be added so long as we have sprites to reference.
    

  [*]The "names" property is a series of arrays. Each array (enclosed within the [ ]) corresponds to a ROW in the spritesheet, and the values within each array correspond to the COLUMN value in that row. The text inside the quotation marks for each value is the name that is given to the particular frame in the grid so that the game can reference it.

  • The ones with 'null' are ones with no name to reference, and therefore that frame cannot be used in game.
    

  [*]The "aliases" property is for handling shortcuts used in the game's code. For example, the "lay.1" name is used for objects like beds that make the player lay down. That frame the player uses when laying down is actually just the "run.8" sprite turned sideways. We won't really need this section and it can be left as is.
  

So lets take this concept of a grid and overlay it onto the spritesheet:

You can probably see the pattern by now. You might also notice that there are frames in the spritesheet that aren't meant to be used, like the label frames on the left or the blank ones here and there. This is where the 'null' values are in the .frames file.

Why does any of this matter?

Understanding this is the first step to understanding how we can ADD custom sprites to the player and NPCs. What's neat about how Starbound utilizes these .frames files is that one .frames file is used to control all of the related sprites for each race. This one femalebody.frames file also configures the avian, hylotl, apex, floran, novakid, and other such humanoid race femalebody.png sheets by itself. If there is a race that wants to have its own .frames configuration, it is placed in a different directory.

• The standard location for the 'default' .frames files is the /humanoid/ asset directory.
• Each race has a directory inside /humanoid/
  • /humanoid/human
  • /humanoid/avian
  • /humanoid/floran
  • Etc
    

  [*]If you want your .frames config to ONLY apply to one race, you would place it within that race's folder. It will override the 'default' .frames config file. Special races (usually reserved for unique NPCs like Esther or Nuru) have their own .frames files for this reason, as they have different sprite sheets. The game still references the frames in the same way, however.
  

This fact is especially important because that means every race the .frames file intends to configure MUST have a spritesheet with the same configuration. If the femalebody.frames file says the spritesheet has 9 columns and 10 rows of sprites, the spritesheet must actually have sprites there or bodies will simply disappear when trying to refer to nonexistent frames.

This is a good thing, because it helps set a standard.

Moving on...

Since the game references everything via a grid of names, we can effectively ADD to the spritesheet and use a mod to overwrite the default femalebody/malebody.png for each race and universal .frames file. Say we want to add a new row of sprites to the vanilla body spritesheet. (A pixel art image editor works best for precision reasons, I use pyxel - it automatically handles frame placement and size.)

Then we can change the .frames file so that the game will recognize that there are more sprites it can use:

Voila! We've just added new, custom spritework to the female human body. ^{(not me, I just copied and pasted other frames because I'm a jerk)} Then there are frontarm, backarm, and head png files that may need similar treatment, though that depends on the implementation.

This kind of magic allows us to potentially add more columns AND rows of custom sprite frames that the player and NPC characters can utilize. Remember that this SHOULD be done for every race equally to keep things consistent. If you want to add a row of sprites for people to use, be sure to add a row to ALL the vanilla race spritesheets. Otherwise things can get messy and racially divisive, and nobody wants that!

Also be aware that any new frames will not, by default, have armor or clothing equivalents. If you intend to have any new frames utilize armor and clothing, you will need to add to each item's similar chest/pants png file. My animation controller will, by default, make all involved players/characters nude so that when animating specifically for this purpose, artists do not initially have to provide sprite alterations for all the clothes and armor in the game.

Also...

I hereby hold custom race-makers (or similarly affiliated party) entirely accountable for making their own new sprites to adhere to this standard, elsewise their custom race cannot utilize the upcoming animation controller as their races will not have the sprites sufficient to properly animate them.

So. How do sprites added to the sheets get utilized in the game? Artists need to know how they should present their work if things are to be best utilized, right?

I'll get into that in part II!