Tutorial Dyeing Armor and the ?replace Directive

Introduction

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!

NOTE:
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
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:

<hexvalue>=<hexvalue>

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

I quit PaintNET, REMEMBERING NOT TO SAVE!

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

with:

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.

 

Does this only work for certain items?

 

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.

 

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.

 

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.

 

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

 

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)

 

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.

 

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.

 

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

My recipe:

Code:

{
  "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:

Code:

{
  "__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:

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, { } ] ]
  ]
}

 

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!

 

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!

 

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.

 

What items have you done it to?

 

Back armors, aka Wing vanity items.

 

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

 

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.?

 

?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.

?fade
?brightness
?saturation
?addmask
?submask
?multiply
?scalenearest
?scalebilinear
?scalebicubic
?setcolor

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.

 

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.

 

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
"silverarmor"
be a correct way to word it?