Content Patcher Integration

Content Patcher is a powerful tool which allows you to edit game / custom assets based on various conditions.

Alternative Textures integrates with Content Patcher by creating dynamic tokens via Content Patcher's API. Through these tokens, you can modify a Alternative Texture's texture.png and the changes will be applied while the game is running (according the content pack's Update field. This allows you to do things such as changing the texture based on the current time or change its color based on the weather.

Note: Using Content Patcher along with Alternative Textures requires a fair bit of understanding of both mods and this part of the Wiki assumes you are familiar with them. If you are not, please read over the Creating a Content Pack and Content Patcher's Author Guide before proceeding.

Important - Enabling Texture For Tracking

Since SMAPI v3.14.0+, the EnableContentPatcherCheck property is no longer required for patch detection. All Content Patcher patches against Alternative Textures will be passively detected.

Using Content Patcher

To utilize Content Patcher, you'll need to first make a content pack for Content Patcher with a required dependency on Alternative Textures.

An example manifest.json for a Content Patcher content pack:

{
  "Name": "Example Content Patcher Test For Alternative Textures",
  "Author": "ExampleAuthor",
  "Version": "1.0.0",
  "Description": "Tests for using Content Patcher to modify Alternative Textures packs.",
  "UniqueID": "ExampleAuthor.ContentPatcherForAlternativeTextures",
  "UpdateKeys": [ "Nexus:???" ],
  "ContentPackFor": {
    "UniqueID": "Pathoschild.ContentPatcher"
  },
  "Dependencies": [
     {
        "UniqueID": "PeacefulEnd.AlternativeTextures",
        "IsRequired": true,
     }
  ]
}

Making Texture Changes

To start making changes to the texture.png, you'll need to create a content.json file. This file is utilized by Content Patcher to detect which changes the content pack wants to make.

Example of a content.json which replaces the first variation in textures.png with a texture from test_replacement.png:

{
  "Format": "1.22.0",
  "DynamicTokens": [
    {
      "Name": "RandomY",
      "Value": "0"
    },
    {
      "Name": "RandomY",
      "Value": "32",
      "When": {
        "Query: {{Random: true, false |key={{Time}} }} = true": true
      }
    }
  ],
  "Changes": [
    {
      "LogName": "Test AT Modification",
      "Action": "EditImage",
      "Target": "{{PeacefulEnd.AlternativeTextures/Textures:ExampleAuthor.ExampleAlternativeTexturesPack.Mini-Obelisk_Summer}}",
      "FromFile": "assets/test_replacement.png",
      "FromArea": {
        "X": "0",
        "Y": "{{RandomY}}",
        "Width": "16",
        "Height": "32"
      },
      "ToArea": {
        "X": "0",
        "Y": "0",
        "Width": "16",
        "Height": "32"
      },
      "Update": "OnLocationChange"
    }
  ]
}

The Alternative Textures Token

Notice the "Target" property is set to: {{PeacefulEnd.AlternativeTextures/Textures:ExampleAuthor.ExampleAlternativeTexturesPack.Mini-Obelisk_Summer}}

This is the dynamic token created by the framework to enable Content Patcher to target a texture.png. In this particular example, the Alternative Textures token is targeting the ExampleAuthor.ExampleAlternativeTexturesPack.Mini-Obelisk summer texture (from the example pack).

The token's structure is as follows: {{PeacefulEnd.AlternativeTextures/Textures:ALTERNATIVE_TEXTURES_MANIFEST_UNIQUE_ID.ItemName_[Season]_[Variation]}}

Note: Season and Variation are optional, though if Season is given then it must be before Variation.

Secondary Note: The input value ALTERNATIVE_TEXTURES_MANIFEST_UNIQUE_ID.ItemName_[Season]_[Variation] should be the manifest unique ID of the Alternative Textures content pack, not the Content Patcher manifest.

More Token Examples

Default variation token: PeacefulEnd.AlternativeTextures/Textures:ExampleAuthor.ExampleAlternativeTexturesPack.Mini-Obelisk

Second variation token (variations are zero-indexed): PeacefulEnd.AlternativeTextures/Textures:ExampleAuthor.ExampleAlternativeTexturesPack.Mini-Obelisk_1

Seasonal third variation token: PeacefulEnd.AlternativeTextures/Textures:ExampleAuthor.ExampleAlternativeTexturesPack.Mini-Obelisk_Summer_2

Note: Variations are zero-indexed, meaning 0 is the first variation.

Modifying Alternative Texture's Tool Sprites

The frameworks tools are also available to be edited, should you want to utilize a Content Patcher pack to modify them.

The token's structure for AT's tools is slightly different: {{PeacefulEnd.AlternativeTextures/Tools:TOOL_NAME}}

TOOL_NAME must be one of the following values:

• PaintBucket
• PaintBrush_Empty
• PaintBrush_Filled
• Scissors

Example of a content.json which replaces the Paint Bucket sprite with a texture from alt_paint_bucket.png:

{
  "Format": "1.22.0",
  "Changes": [
    {
      "LogName": "Test AT Tool Modification",
      "Action": "EditImage",
      "Target": "{{PeacefulEnd.AlternativeTextures/Tools:PaintBucket}}",
      "FromFile": "assets/alt_paint_bucket.png",
      "FromArea": {
        "X": "0",
        "Y": "0",
        "Width": "16",
        "Height": "16"
      },
      "ToArea": {
        "X": "0",
        "Y": "0",
        "Width": "16",
        "Height": "16"
      },
      "Update": "OnDayStart"
    }
  ]
}

Caveats

When using Content Patcher to make changes with Alternative Textures, there are a few things to keep in mind.

Update rates

The framework will sync changes immediately with Content Patcher when using OnDayStart, OnLocationChange or OnTimeChange for the Update field.

Texture size limitation

You can only use Content Patcher against textures that are smaller than 16384 pixels in height. This includes the total height of split textures, such as texture_0.png, texture_1.png and so forth.