User:MouseyPounds/Dynamic Token Examples

Note: This is a work in progress for future expansion of the Content Patcher Documentation

Dynamic Token Examples

Configuration Aliases: Filenames

Static tokens can only insert the exact configuration values, but sometimes a modder wants to have descriptive configuration values that map to more obscure filenames. Dynamic tokens can create that bridge.

In this example, the mod contains four different varieties of replacement fences with different graphics for each season. The player can choose one of the four fence types in the config and using a combination of Global, Dynamic, and Config Tokens, a single patch entry can handle everything.

content.json:

   {
      "Format": "1.5",
      "ConfigSchema": {
        "FenceType": {
          "AllowValues": "Wood, Stone, Iron, Hardwood",
        }
      },
      "DynamicTokens": [
        {
          "Name": "FenceFile",
          "Value": "Fence1",
          "When": { "FenceType": "Wood" }
        },
        {
          "Name": "FenceFile",
          "Value": "Fence2",
          "When": { "FenceType": "Stone" }
        },
        {
          "Name": "FenceFile",
          "Value": "Fence3",
          "When": { "FenceType": "Iron" }
        },
        {
          "Name": "FenceFile",
          "Value": "Fence5",
          "When": { "FenceType": "Hardwood" }
        }
      ],
      "Changes": [
         {
          "Action": "Load",
          "Target": "LooseSprites/{{FenceFile}}",
          "FromFile": "assets/Fence_{{FenceType}}_{{Season}}.png"
         }
       ]
    }

That one patch definition will match 16 possible files since there are 4 FenceType options and 4 Season possibilities.

asset files:

• Fence_Hardwood_Fall.png
• Fence_Hardwood_Spring.png
• Fence_Hardwood_Summer.png
• Fence_Hardwood_Winter.png
• Fence_Iron_Fall.png
• Fence_Iron_Spring.png
• Fence_Iron_Summer.png
• Fence_Iron_Winter.png
• Fence_Stone_Fall.png
• Fence_Stone_Spring.png
• Fence_Stone_Summer.png
• Fence_Stone_Winter.png
• Fence_Wood_Fall.png
• Fence_Wood_Spring.png
• Fence_Wood_Summer.png
• Fence_Wood_Winter.png

Configuration Aliases: Data

Since tokens can now be used within EditData patches, dynamic tokens can also be used to map configuration values to text, item ids, etc.

As an extension of the previous example, the mod in this example contains four different varieties of replacement fences, and the player can choose one of the four fence types in the configuration. Here the patches focus on changing the appropriate object and crafting definitions.

content.json:

   {
    }

Conditional Filename Changes

Sometimes a mod author might have additional options that only apply in certain situations or want to add additional texture options on a later update. With static tokens, the filenames have to follow a very rigid structure and one can be forced into renaming everything or adding several slightly different patch definitions. Dynamic tokens are more flexible in these situations.

In this example the author of a seasonal house mod wants to add a new "Spooky" Fall texture as an alternate without affecting other seasons or renaming previously existing files. A dynamic token which is blank unless the player has enabled the alternate texture is added to the FromFile reference to accomplish this.

content.json:

   {
      "Format": "1.5",
      "ConfigSchema": {
        "FallVariant": {
          "AllowValues": "Standard, Spooky",
        }
      },
      "DynamicTokens": [
        {
          "Name": "Variant",
          "Value": "",
          // Blank default
        },
        {
          "Name": "Variant",
          "Value": "_Spooky",
          "When": { "FallVariant": "Spooky", "Season": "Fall" }
        }
      ],
      "Changes": [
         {
          "Action": "EditImage",
          "Target": "Buildings/houses",
          "FromFile": "assets/FancyHouse_{{Season}}{{Variant}}.png",
          "ToArea": { "X": 16, "Y": 288, "Width": 144, "Height": 144 }
         }
       ]
    }

Because of the blank default, the Variant token will only change the filename when the conditions are appropriate.

asset files:

• FancyHouse_Fall.png
• FancyHouse_Fall_Spooky.png
• FancyHouse_Spring.png
• FancyHouse_Summer.png
• FancyHouse_Winter.png