Welcome to part II of this Starbound spritesheet expansion series with an overly-verbose title.

So now that we have added a new row of *cough* custom *cough* sprite animations, let's talk a bit about why did things that way and how we intend to use it.

The Why

Starbound's animation engine, specifically for the humanoid races (this includes the player AND NPCs), automatically handles a lot of the work in ways we cannot influence. There's a lot of black box magic going on that has to be discovered and worked around. The way the player sprite animates during gameplay is usually under tight control so that there aren't any messy changes that can throw a wrench into that engine. There are, however, ways around it - I will talk more on that when I get into my animation framework.

Humanoid races, as you might already know, are actually a culmination of several spritesheets laid on top of each other (in the same layer). For every one, there is a:

• Body (Male and Female variants - malebody.png/femalebody.png) - includes torso and legs
• Front arm (frontarm.png) - the arm that renders in front of the body
• Back arm (backarm.png) - the arm that renders behind the body
• Head (Male and Female variants - malehead.png/femalehead.png) - the head shape + eyes. Does not include hair or a mouth
• Hair (There is one numbered png for each hair style - male<number>.png/fem<number>.png) - Obvious
• Emote (emote.png) - typically any face changes when the character emotes such as closed eyes when sleeping, etc
  

Already seems like a pain in the ass to deal with, right? Well, yes and no. Some of these are player chosen/Generated for an NPC and none are easily replicated for use in spawning dynamic objects for animation purposes. Let's knock a few bits of trivia out of the way first:

• The hair and emotes are automatically anchored to the head. Where the head goes, they go. If the head flips from looking left to looking right, so will they. We generally won't have any need of controlling these specifically.
• I do not currently know of a way to access the hair and head variations^{(see below)}and so they will not be used. If you still want information on how those are set up, read the following bullet points:
  • Hair and Head .frames files have a very different setup for how it is read (compared to the bodyframes detailed in part I). Those are specifically defined through bounding boxes rather than automatically through grids. That is, for a single frame in malehead.png, it requires an array that define exactly where/how big in the .png the frame is in pixels [a, b, c, d]
  • It follows a standard nested Vector2 format (( a, b ), ( c, d )). These two resulting points tell the engine where top-left ( a, b ) point is and the bottom-right ( c, d ) point is. The frame is made from the space between.
  • It LOOKS like various forms can be chosen (all have "normal" and "climbing" frames each with their own bounding boxes), and while I eventually hope to be able to use this so that spriters can make 'rotated' versions of each head/hair for when useful in the animations, At present I don't know how to get at it.
    

  
  

Ultimately the goal is to animate the player/NPCs as they are without having to pull unnecessary identity data. Using these various files and making additions to certain ones, we can set up a robust animation asset base. Having everything remain in their separate places (instead of just tacking on head/arms to the new body.png frames) actually allows animators to have finer control and more options. Think of the many files and frames as legos, and animators are using those legos to piece together an animation.
How? Well, dear intrepid reader, read on...

The How: Dance Party!

Well now that we've gotten that information out of the way, let me introduce you to the bread and butter of my animation framework system:

The .dance files

No, this is not a paranormal dancing TV drama title. .dance files in Starbound are used, in most circumstances, to give NPCs more life. Think of whenever you see an NPC wave at you or sway in place like he's tipsy. How about when you see them 'press a button'? So on and so forth. They are also used, to a lesser extent, to control how the player/NPCs appear when piloting non-mech vehicles. Little animations that use the NPC's given assets, armor and clothes included. These are not .animation files, these are .dance files.

Here is what a vanilla .dance file looks like:

Looks pretty similar to the .frames files at first glance, but it works very differently. Here's what we have:

• "name" - This is the name the game engine will use to reference this dance file. In this case, when we want to call a dance, we call "wiggledance"
• "states" - I'm not 100% sure about this property, but I believe it tells the game engine what states the entity must be in in order to dance. This primarily applies to NPCs, but is not related to our animation setup. We MIGHT need to give these a unique state just so the game doesn't randomly call idling NPCs to perform a rather out of place .dance file. More on that in a different post.
• "cycle" - This is how long each 'step' shows before moving to the next. The lower the number, the faster the dance will play through its steps. This is NOT 'seconds', but rather refers to an ambiguous tick rate that I cannot find.
• "cyclic" - I believe this allows the dance to loop. Setting this to false stops the dance after it has played through once.
• "duration" - I am also not 100% sure, but I believe this may be a reference for NPC scripts to tell the NPC to stop dancing after this amount of game time. We probably won't need to worry about this.
• "steps" - This array contains the 'frames' in your animation and this is where the magic happens.
  • These six-part arrays (between the [ ] on each line) tells the game what is what and where on each frame of the dance:
  • The first is the name we set up in the .frames file for the body.png frame that we want to show
  • Next is similarly the name of the frame in the frontarm.png we want to show
  • Third is the backarm sprite from backarm.png we want to show.
  • Fourth is the location (relative to where it normally is) for the head. Each frame can adjust the location of the head.
  • The fifth and six are the same as the fourth, but apply to the frontarm and backarm positions
    

  [*]The game moves down this list (or 'iterates through the array' if you're that type) once for every "cycle" tick. If the dance's "cyclic" is true, it will start at the first one when the last one is finished and do it all again until told to stop (handled by my animation controller, or in the case of normal NPCs walking around, when the duration ends). [*]The head can be moved, but it CANNOT be rotated. It will either look straight left or straight right, and this cannot be changed until I (or someone) finds a way to have the game engine call a different head (where we can create 'rotated' head sprite frames and use those) or someone finds a way to actually rotate the head (which is not possible as far as I know). Animate accordingly!
  

As you can see, with the way that .dance files separately reference body and arm sprites and head/arm positions, this allows animators to use the sprite assets to create their own animations, even if the sprites aren't laid out as animations themselves. If spriters create a collection of 'all purpose' sprite sets consisting of small animations for any position the character COULD be in, that gives animators a huge asset base to mix and match.

I will detail how dances can be combined using a new filetype (.sequence files) to make full-fledged 'scene' animations in my Animation Framework details post, which I will tackle down the road when it is far closer to some sort of alpha release.

My hope is that this series gives people who are familiar with sprite animation or people who want to get involved in sprite animation have an easy time of understanding how the game reads and uses the assets, as well serve as a primer for anyone who might want to create .dance files to expand the animation possibilities in the game.

This series will probably change as more and more tricks are discovered. I hope you enjoyed this series! Feel free to ask questions or request clarification if I fuzzed something up.