Tutorial A guide on implementing character customization for custom races

Discussion in 'Starbound Modding' started by Zatnik, Aug 16, 2017.

  1. Zatnik

    Zatnik Scruffy Nerf-Herder

    When I was first attempting to implement race mods, I was never sure how to make the characters customizable in the ways that I wanted. What were the limitations? How could I give my race two customizable colors on their hair, one of which was also used on their body? What does "altOptionAsHairColor" mean?

    I couldn't find any existing guides that went into as much depth as I wanted, so I decided to figure it out myself and write my own guide. However, it isn't intended to explain how to make an entire race mod, or even how to do everything in the .species file, so if that's something you're likely to need help with I'd recommend using another guide in conjunction with this one.

    I do really want this to be helpful, though, so I'd appreciate feedback if anything is unclear or incorrect, or if you have any questions or suggestions!



    Color types

    In order to add variety in color, Starbound characters draw from three types of colors: body color, hair color, and undy color. The actual colors used for each of these types can be changed by the user during character creation. For example, Hylotl characters use body color for their skin, hair color for their fins, and undy color for their bellies. These colors are added to the character sprites by replacing specific pixel colors, so some sprites or parts of sprites, such as Hylotl eyes, may not change color.


    Character sections

    Characters have several sections that can be customized:

    Body — The fundamental parts; head, torso, arms, and legs. By default, the body uses body color. It also technically uses undy color, though for all other purposes it isn't counted as doing so unless it's made to use undy color by some other method.

    Hair — Hair or other features on the head (e.g. Glitch head mods or Hylotl fins). By default, this section uses the body color. However, if the race allows hair color to be changed, this section instead uses the hair color.

    Facial mask — Used to add arbitrary features to the head (e.g. Avian beaks). Uses no color types by default.

    Facial hair — Similar to the facial mask, but always uses the same color types as the hair section. Uses in the vanilla races include Apex beards, Avian fluff, and Novakid brands.


    Layer order

    (This isn't directly related to the main concepts covered in the guide, but it's important in deciding how you want to utilize those concepts.)

    Characters are composed of several layers, which are drawn as if some are "closer" to or "further" from the viewer. The order of the layers, from closest to furthest, is:

    • Front arm
    • Facial mask
    • Facial hair
    • Body
    • Hair
    • Head
    • Back arm

    Customization inputs

    There are four inputs in the character creator that are used modify the base character appearance, located in the top two rows of spinner inputs. These inputs, by generic name, are:

    Body color — Located in the top left. Always has the function of changing the body color, if possible.

    Hair style — Bottom left. Always has the function of changing the hair sprite, if possible.

    Alt option — Top right. Does nothing by default, and otherwise performs miscellaneous functions (undy color, facial mask style).

    Head option — Bottom right. Does nothing by default, and otherwise performs miscellaneous functions (hair color, facial hair style).


    JSON booleans

    Several boolean (true/false) JSON properties in the .species file can be used to change what the inputs listed above do. They are:

    "headOptionAsFacialhair" — Makes it so the head option changes the facial hair sprite. (Be careful writing this one out, because the "h" in "Facialhair" is unintuitively lowercase.)

    "altOptionAsFacialMask" — Makes it so the alt option changes the facial mask sprite.

    "headOptionAsHairColor" — Makes it so the head option changes the hair color.

    "altOptionAsHairColor" — Only works if "headOptionAsHairColor" is enabled; makes it so the alt option changes the undy color, and makes the hair section use undy color in addition to its other colors.

    "altOptionAsUndyColor" — Makes it so the alt option changes the undy color.

    "bodyColorAsFacialMaskSubColor" — Makes the facial mask section use all colors used by the body section in addition to its other colors.

    "hairColorAsBodySubColor" — Makes the body section use all colors used by the hair section in addition to its other colors.

    "altColorAsFacialMaskSubColor" — Only works if "altOptionAsUndyColor" is enabled; makes the facial mask section use undy color in addition to its other colors. (Note that this is only useful if you want the alt option to change both undy color and facial mask at once.)

    It is possible to give a single input multiple functions; for example, if both "headOptionAsFacialhair" and "headOptionAsHairColor" are set to true, the head option will change both the facial hair sprite and the hair color at once.
     
    Last edited: May 9, 2018
    charity236 and DrPvtSkittles like this.
  2. Marinebeast

    Marinebeast Existential Complex

    I'd like to beep in here and add that the emote sprites are also affected by layer/customization inputs!

    If you use the same pixel colors for the mouth/other emote details as you do for, say, undies or other variables, then the emote frames will change color to match the character creation.
    For instance, my custom species uses the same colors for their mouth as they do for their undy color, so if you change the undy color, their mouth will also use that set of colors. I'm sure that this could open up interesting avenues for the emote sprites.
     
  3. Zatnik

    Zatnik Scruffy Nerf-Herder

    Oh, good point!
     
  4. Zatnik

    Zatnik Scruffy Nerf-Herder

    I was looking at tiramisuapimancer72069XD's troll mod and discovered that "altColorAsFacialMaskSubColor" actually does do something! I guess when I was testing that property I didn't think to try it while having multiple functions enabled for the alt option. :-P

    Updated the OP.
     

Share This Page