AS 8BitCrab says, it was first implemented and shown (to us) for the hearthlings hair and skin color. If it can be used for other models though I’m not sure; I haven’t played around with it, and the code for this is located within the engine itself.
Looking more closely at it now, I think it can be done, there are some steps involved though (note that, as I haven’t tried any of this myself, this is pure speculation and should probably be taken with a grain of salt).
First you’d have to define a color map for the type of model which contains the information about which parts of the model that will accept a palette-swap. Consider the hair_color_map.json as an example:
{
"#FC6EFE" : "stonehearth:hair:hilight",
"#A438A5" : "stonehearth:hair:midtone",
"#761B76" : "stonehearth:hair:shadows"
}
It’s simply a collection of uris tied to a color in hex format. Note that the color must match an actual color on the model. The uris will be used later on when doing the palette swap, what uri you choose to use for each color should reflect what the color represents.
Next up would be to define the material maps for the model. These contain the colors that will be swapped into; they’re themselves using the uris defined from the color map. We’ll use hair_black_material_map.json as an example:
{
"stonehearth:hair:hilight" : {
"color" : "#2F2C27"
},
"stonehearth:hair:midtone" : {
"color" : "#211F1C"
},
"stonehearth:hair:shadows" : {
"color" : "#0D0D0D"
}
}
Not that much to this part, it’s just telling the model to change its colors (matched by their respective uri) into the one supplied here.
Now how to implement all this. For this we go to the entity’s json file, add in/modify the render_info
component, and add in the color_map
and material_maps
values. It would look something like so:
"components": {
"render_info": {
"color_map": COLOR_MAP,
"material_maps": [
RELEVANT_MATERIAL_MAPS
]
}
}
Here, COLOR_MAP is referring to the color map json file.
RELEVANT_MATERIAL_MAPS lists all of the material map json files that will be used for this entity. The default behavior is that all of the files listed will be used to swap all colors found, but it can be changed with the usage of one_of
which chooses one material map out of those listed. Example (from entities/humans/male/male_1.json):
"material_maps": [
"/stonehearth/data/materials/material_maps/skin_white_material_map.json",
{
"type": "one_of",
"items": [
"/stonehearth/data/materials/material_maps/hair_platinum_material_map.json",
"/stonehearth/data/materials/material_maps/hair_blonde_material_map.json",
"/stonehearth/data/materials/material_maps/hair_sandy_material_map.json",
"/stonehearth/data/materials/material_maps/hair_brown_material_map.json",
"/stonehearth/data/materials/material_maps/hair_brown_material_map.json",
"/stonehearth/data/materials/material_maps/hair_brown_material_map.json",
"/stonehearth/data/materials/material_maps/hair_red_material_map.json",
"/stonehearth/data/materials/material_maps/hair_black_material_map.json",
"/stonehearth/data/materials/material_maps/hair_black_material_map.json",
"/stonehearth/data/materials/material_maps/hair_black_material_map.json"
]
}
]
This will add in skin_white_material_map.json for the skin, and simultaneously choose one of the many hair material maps.
I believe that’s all it takes to be able to add in your own palette swaps for any entity. Though, I should say that doing something like this will choose the palette randomly. If you’d want the player to be able to choose the color from the list, then this is not enough, and I’ve not seen anywhere that makes it possible for us to implement something like that.