What are Color Mask Layers?

Color mask layers allow mod authors to specify a list of color masks, which can be used to create multiple colorable sections for an appearance.

If both the ColorMasks and ColorMaskLayers properties are excluded, then the whole sprite will be targeted by the player's color choice.

Note: All color masks are ignored if DisableGrayscale is set to true.

Properties

Property	Required	Description	Default
Name	true	The name of the layer, which will be displayed to the user if IgnoreUserColorChoice is false.	N/A
DefaultColor	false	The default color to apply, if the color has not been overridden by the user.	N/A
IgnoreUserColorChoice	false	If set to true, the colors specified in Values will be protected from the player's color choice.The layer will also be hidden from the player's view.	false
Values	true	The list of RGB colors to use for the color masking / replacement.	[]

About Multiple Layers

Multiple layers can be given via ColorMaskLayers.Values, allowing mod authors to create different regions within the sprite that change color according to the player's own color choice.

Each layer is recommended to have its own unique Name and should not have any overlapping colors in Values.

Note: The RGB colors listed in ColorMaskLayers.Values do not have to be grayscale, as they can be any possible RGB color.

Additional note: If the color given is not grayscale, then the color overlay will be treated as additive. This means the resulting color will be a different hue compared to any grayscale counterpart.

Example Usages

Multiple Color Layers

Below is the Multiple Color Layers Overalls, found in the example pack.

Notice that two layers are given, one for "Shirt Color" and another for "Overalls Color". Each layer has its own unique set of Values, which allows the player to color each section individually.

{
  "Name": "Multiple Color Layers Overalls",
  "FrontShirt": {
    "ColorMaskLayers": [
      {
        "Name": "Shirt Color",
        "Values": [
          [ 129, 129, 129 ],
          [ 113, 113, 113 ],
          [ 99, 99, 99 ],
          [ 70, 70, 70 ],
          [ 67, 67, 67 ]
        ]
      },
      {
        "Name": "Overalls Color",
        "Values": [
          [ 191, 191, 191 ],
          [ 169, 169, 169 ],
          [ 71, 71, 71 ]
        ]
      }
    ],
    "SleeveColors": [
      [ 9, 9, 10 ],
      [ 254, 254, 254 ],
      [ 198, 198, 198 ]
    ],
    "StartingPosition": {
      "X": 0,
      "Y": 0
    },
    "BodyPosition": {
      "X": 0,
      "Y": 0
    },
    "ShirtSize": {
      "Width": 8,
      "Length": 8
    }
  }
}

Example sprite:

Excluded Color Layer

Below is the Priestess, found in the example pack.

Two layers are given, one for "Ring (non-colorable)" and another for "Gem".

Notice that the first layer is utilizing the IgnoreUserColorChoice property, which means the colors specified in Values won't be affected by the player's color choices and will not appear in the layers listed in the UI. The second layer "Gem" remains recolorable by the player.

{
  "Name": "Priestess",
  "FrontAccessory": {
    "DrawOrderOverride": {
      "Preposition": "Before",
      "AppearanceType": "Player"
    },
    "ColorMaskLayers": [
      {
        "Name": "Ring (non-colorable)",
        "IgnoreUserColorChoice": true,
        "Values": [
          [ 122, 51, 0 ],
          [ 177, 86, 3 ],
          [ 226, 178, 18 ],
          [ 255, 255, 20 ],
          [ 255, 249, 242 ]
        ]
      },
      {
        "Name": "Gem",
        "Values": [
          [ 46, 46, 46 ],
          [ 88, 88, 88 ],
          [ 111, 111, 111 ],
          [ 135, 135, 135 ],
          [ 159, 159, 159 ]
        ]
      }
    ]
  }
}

Example sprite: