Tutorial Dyeing Armor and the ?replace Directive

Discussion in 'Starbound Modding' started by LaznAzn, Jan 9, 2014.

  1. LaznAzn

    LaznAzn Void-Bound Voyager



    Hello Starbound Community!

    I've recently made a guide on the Starbards website providing syntax and explanation for the ?replace directive. Simply put, the ?replace directive can take a item's color palette and change it to whatever the modder wishes.
    This not only works for vanilla armor but for armor that modders have created! This will also work for items that currently can't be dyed using the colorIndex or for parts of the armor which are always one color!
    What's more, ?replace directive is a vanilla function. All the changes you make will work online, people will see the changes you made and you can even give them that gear to wear!

    For those of you who prefer to tinker instead of read, I have provided a small mod, a template if you will. Feel free to examine and use it as a base to experiment! I do not consider this a mod release as the mod provided is, as I said, just an example of syntax.

    Enjoy! I will be happy to answer questions if you have any. If you have any feedback, feel free to reply as well!

    In this tutorial I will be using a couple of programs to make things easier, feel free to use the same ones or find something else.
    Notepad++ - Editing text assets like .recipe files and player.config
    PaintNET - Getting hex codes for color from assets in .png format.

    Both these programs are free for download and use.

    An explanation of the directives syntax


    Above is an example of a color directive being used in a recipe, at first this big jumble of hex values and words might seem intimidating but I will break it down for you and tell you what these values represent.

    There are two main syntax that I've highlighted above and will talk about below:

    Replace is a directive. (there are more than one but for this tutorial we will be concerned with this one)
    Basically replace tells the game "I want to take the following color hex and replace it a different color hex."

    The semicolon ; after ?replace signifies that something related to the command is going to come after.
    Which brings us to:


    Basically what this syntax is saying is, "I want to replace the first value with the second value."
    For example FFFFFF is the hex code for white and 000000 is the hex code for black.
    So FFFFFF=000000 means, " I want to replace all white in the armor with black."

    The full syntax for the above line would be as follows:

    "data" : { "directives" : "?replace;FFFFFF=000000"}

    If we wanted to change another color in addition to white and black, lets say red FF0000 to blue0000FF.
    The syntax would change to:

    "data" : { "directives" : "?replace;FFFFFF=000000;FF0000=0000FF"}

    We add a semicolon after our color change and add a second one. Again, the semicolon signifies something related to the command is coming after, and the entire command is wrapped in quotes to signify where it begins and ends.

    Step 1: Create the recipe

    First, I start off with a base recipe. My goal will be to be able to craft a wizard hat for 1 pixel.


    I create a recipe called wizardhead.recipe located in my mods folder /Directives/recipes/armor
    I include this recipe in the "plain" group so I can craft it on the fly.


    I go ahead and add the recipe to the player.config in my mod.


    I load up the game quick and confirm that I can spawn the hat. And I can! Yay!

    Step 2: Get a palette

    Now that we can spawn the wizard hat at will, lets spawn a pink one.
    Before we can use the ?replace directive we're going to need two things: what color are we replacing and what color are we replacing it with?

    To do this we're going to have to do some digging in the game files. I head to assets/armors/decorative/costumes/wizard and I add this folder to my mod.

    Please note this is not required but I prefer working from the mod folder whenever possible to prevent accidents fun.

    I open up the the head.png file in PaintNET (please see my introduction for more information).


    My goal now is to identify how many colors are used in this hat and what they're hex values are. To do this I make a quick palette using the Color Picker and Pencil tools. I select each color and pencil in a pixel below the item. As you can see the wizard hat uses 6 colors. We now have the colors we want to replace!

    I identify them using the Color Picker:
    Dark Blue - 1A1C51
    Medium Blue- 344495
    Light Blue- 5588D4
    Dark Grey- 7B7B7B
    Medium Grey- B6B6B6
    Light Grey- E6E6E6

    As I'm a visual person, I like to pencil my colors in to get an idea of what the item will look like. To those who do this: DO NOT SAVE THE FILE! This is why I prefer to work from the mod folder, if I do save by accident, I won't have problems fun later on!


    So I quickly pencil in my replacement colors until I'm satisfied with my result.
    I have a second palette below the first with my replacements:

    Purple- C321FF
    Pink- F766FF
    Light Pink- FFADFF
    Dark Yellow- D3C502
    Medium Yellow- D3C502
    Light Yellow- FFF202


    Step 3: Modify the recipe

    Now we have our hex colors, we want to replace:

    Dark Blue - 1A1C51
    Medium Blue- 344495
    Light Blue- 5588D4
    Dark Grey- 7B7B7B
    Medium Grey- B6B6B6
    Light Grey- E6E6E6


    Purple- C321FF
    Pink- F766FF
    Light Pink- FFADFF
    Dark Yellow- D3C502
    Medium Yellow- D3C502
    Light Yellow- FFF202

    I copy my wizardhead.recipe file and name the new one to Pwizardhead.recipe, then I open Pwizardhead and input my the ?replace directive:


    As you can see I replace Dark Blue 1A1C51 with Purple C321FF as my first argument in ?replace and I continue that pattern for the other 5 colors.

    Next we need to add this new recipe to our player.config:


    As you can see the syntax is a bit different from the first time. We have to specify the directive in the player.config, basically, restate what we added in the recipe here.

    We load up the game and... Success!


    Thanks to the Starbound dev team for making such a supremely moddable game! The modding alone has kept be busy for hundreds of hours so far!

    And thanks to the community at Starbards.net! It's the server I have come to call home and the place where I've made many friends.

    Attached Files:

    Last edited: Jan 9, 2014
    IHart, huoyun, SleepySquidd and 7 others like this.
  2. Applesaur

    Applesaur Space Hobo

    Does this only work for certain items?
  3. LaznAzn

    LaznAzn Void-Bound Voyager

    This works on every armor in the game to my knowledge. Even custom ones that are added by modders.
    If you're having trouble with a specific item I can have a look though!

    This should also work on racial weapons (ones that are not random). I'm unsure if randomlygenerated weapons will accept the syntax though.

    Won't work for instruments though, I tried making a pink ocarina, no dice.
    As for pickaxes and tools... doubt it.
    Last edited: Jan 9, 2014
  4. Karmos

    Karmos Space Penguin Leader

    It should work on anything with the four placeholder colors in the base sprite (i.e. that is already dyeable). Some bits of weapons, most armor. Can't say more specifically about the ?directive technique, though. I wrote a similar post on the subject that delves into how to change the colors schemes for items with actual dyes rather than recipes a little while ago.
    Last edited: Jan 9, 2014
    LaznAzn likes this.
  5. Chandrak

    Chandrak Phantasmal Quasar

    Thank you for this. This little tutorial totally solved an issue I was having with some item recipe errors - never realized I needed to put the data into the default bluebrints parts.
  6. LaznAzn

    LaznAzn Void-Bound Voyager

    Yeah, what gave me the inspiration was the generate shield recipe and entry in player.config. It opened a lot of doors and possibilities! :D
  7. Chandrak

    Chandrak Phantasmal Quasar

    Any idea how you'd get it to automatically color the recipe according to your color options in the character creation?

    i.e. like make it follow skin color / undy color / hair color, or w/e?. I actually could use a way to do that rather than make 20 different copies of the wing recipe, since thats kinda clumsy. (Though it works well enough)
  8. LaznAzn

    LaznAzn Void-Bound Voyager


    Not really, you can add armor into the .species file but the armor colors come from the actual armor file. You'd still have to change the colorOptions armor manually in their individual files.
  9. Chandrak

    Chandrak Phantasmal Quasar

    Thats not quite what I meant, actually. What I was referring to was that when you choose, say, shirt and pants color in the above screen shot during character creation, the 'recipe' you receive to recreate those items at the spinner uses that particular color. That is to say - you chose a color option, and then as a result you learned a specific recipe based on that color. Im wondering if theres a way to duplicate that without changing the shirt item you receive, or to tie it do say skin color rather than shirt color.

    I suspect there is, but I don't know how.
  10. Shadewarp

    Shadewarp Pangalactic Porcupine

    Is it just me, or isn't this possible to do with objects?

    My recipe:

      "input" : [
    //  { "item" : "silverarmorhead", "count" : 1 },
    //    { "item" : "silverarmorchest", "count" : 1 },
    //    { "item" : "silverarmorpants", "count" : 1 },
    //  { "item" : "money", "count" : 25 }
        { "item" : "money", "count" : 1 }
      "output" : {
      "item" : "silverarmorstand",
      "data" : { "directives" : "?replace;ffca8a=e5e9f1;e0975c=c4c7cd;a85636=72767f;6f2919=4a4d52"},
      "count" : 1
      "groups" : [ "armorstandtable", "objects", "all" ]
    My player.config:

      "__merge" : [],
      "defaultBlueprints" : {
        "__merge" : [
        "tier1" : [
        { "item" : "armorstandtable" },
        { "item" : "copperarmorstand" },
        { "item" : "silverarmorstand", "data" : { "directives" : "?replace;ffca8a=e5e9f1;e0975c=c4c7cd;a85636=72767f;6f2919=4a4d52"} }
    I can craft the item, but the colors doesn't change on the object

    Object code:

      "objectName" : "silverarmorstand",
      "printable" : false,
      "rarity" : "Common",
      "category" : "decorative",
      "price" : "250",
      "description" : "A silver armor stand",
      "shortdescription" : "A silver armor stand",
      "race" : "generic",
      "hydrophobic" : true,
      "apexDescription" : "A silver armor stand ",
      "avianDescription" : "A silver armor stand ",
      "floranDescription" : "A silver armor stand ",
      "glitchDescription" : "A silver armor stand ",
      "humanDescription" : "A silver armor stand ",
      "hylotlDescription" : "A silver armor stand ",
      "inventoryIcon" : "silverarmorstandicon.png",
      "orientations" : [
          "dualImage" : "silverarmorstand.png:<color>",
          "imagePosition" : [0, -8],
          "frames" : 1,
          "animationCycle" : 0.5,
          "spaceScan" : 0.1,
          "anchors" : [ "bottom" ]
      "smashSounds" : [ "/sfx/objects/capsule_break1.wav", "/sfx/objects/capsule_break2.wav", "/sfx/objects/capsule_break3.wav" ],
      "smashDropOptions" : [
        [ [ "silverarmorhead", 1, { } ], [ "silverarmorchest", 1, { } ], [ "silverarmorpants", 1, { } ] ]
      "breakDropOptions" : [
        [ [ "silverarmorhead", 1, { } ], [ "silverarmorchest", 1, { } ], [ "silverarmorpants", 1, { } ] ]
  11. LaznAzn

    LaznAzn Void-Bound Voyager

    Yeah, I've personally only tested it with armor but I'm going to say that Karmos' guess is right on the money. Basically if the item doesn't have colorOptions than it won't accept a directive. I'm sure there will be exceptions on either side of this guess though.
    It's a shame, being able to color furniture and instruments would have been really cool!

    Your code looks spot on to me!
  12. Shadewarp

    Shadewarp Pangalactic Porcupine

    Thanks, but that is horrible :( My mod is basically useless then - until they fix it so that any item will take the ?replace command.

    Dang it!
    Last edited: Jan 10, 2014
  13. Chandrak

    Chandrak Phantasmal Quasar

    No, you don't actually have to have color options to accept a replace directive; I've tested that.

    I think what it is is that it just doesnt work for objects, only for items.
  14. Shadewarp

    Shadewarp Pangalactic Porcupine

    What items have you done it to?
  15. Chandrak

    Chandrak Phantasmal Quasar

    Back armors, aka Wing vanity items.
  16. Shadewarp

    Shadewarp Pangalactic Porcupine

    Ah, ok - so yeah, objects are left out ... that is a bummer... well, more work for me :p rofl... thanks all
  17. infernotowel

    infernotowel Void-Bound Voyager

    Wait, just how powerful is ?replace? Would it be possible to use it, for example, to edit a weapon to deal different damage, fire a different projectile, etc.?
  18. LaznAzn

    LaznAzn Void-Bound Voyager

    ?replace is just a directive. It only does on thing as far as I know and that is take a color hex and replace it with another color hex.

    Directives in general only have to do with image properties.


    EDIT: I assume these all take hex values as an input and use similar syntax but I can't really be sure. Feel free to experiment, though I recommend making an isolated mod and to back up your save file. Though I think the worst that will happen is you'll generate transparent armor or make yourself invisible. Ala the nudie mod.
  19. infernotowel

    infernotowel Void-Bound Voyager

    Aw, that's unfortunte. I would have loved to make a mod that creates usable items that allow you to upgrade any weapon or armor. Unfortunately, I guess I'll just have to wait until another patch when modding becomes more powerful.
  20. dw420

    dw420 Void-Bound Voyager

    Does this work when introducing recipes with the learn on pickup method?

    if so... would
    "silverarmor", "data" : { "directives" : "?replace;ffca8a=e5e9f1;e0975c=c4c7cd;a85636=72767f;6f2919=4a4d52"}
    instead of just
    be a correct way to word it?

Share This Page