Tractor Mod

Tractor Mod

130k Downloads

[Content Patcher] support config files

Pathoschild opened this issue ยท 2 comments

commented

Provide a way for Content Patcher packs to accept player configuration through a config.json file.

commented

Proposed implementation (as would be documented in the readme):

Player configuration

You can let players configure your mod using a config.json file. This requires a bit more upfront
setup for the mod author, but once that's done it'll behave just like a SMAPI config.json for
players. Content Patcher will automatically create and load the file, and you can use the config
values in the When field (not case-sensitive). Note that config fields can only
contain string and true/false values.

For example: this content.json defines two config fields, Material and Trim, and then uses
them to change the appearance. See below for more details.

{
   "Format": "1.0",
   "ConfigSchema": {
       "Material": {
           "AllowValues": "Wood, Metal"
       },
       "Trim": {
           "AllowValues": "Dark",
           "Default": "" // disable by default
       }
   },
   "Changes": [
       // load material
       {
           "Action": "Load",
           "Target": "LooseSprites/Billboard",
           "FromFile": "assets/material_wood.png",
           "When": {
               "Material": "Wood"
           }
       },
       {
           "Action": "Load",
           "Target": "LooseSprites/Billboard",
           "FromFile": "assets/material_metal.png",
           "When": {
               "Material": "Metal"
           }
       },

       // apply trim color
       {
           "Action": "EditImage",
           "Target": "LooseSprites/Billboard",
           "FromFile": "assets/trim_dark.png",
           "When": {
               "Trim": "Dark"
           }
       }
   ]
}

Here's how to do it:

  1. Add a ConfigSchema section to the content.json, which defines your config settings and
    how to validate them. Available field for each setting:
field meaning
AllowValues Required. The values the player can provide, as a comma-delimited string.
Tip: for a boolean flag, use "true, false".
Default (optional) The default value, subject to AllowBlank. If not set, defaults to the first allowed value.
AllowBlank (optional) Whether the field can be left blank. Behaviour:
  • If false (default): missing and blank fields are filled in with the default value.
  • If true: missing fields are filled in with the default value; blank fields are left as-is.
AllowMultiple (optional) Whether the player can specify multiple comma-delimited values. Default false.
  1. Use the config fields as When conditions. The field names and values are not
    case-sensitive.

That's it! Content Patcher will automatically create the config.json when you run the game.

Note: including the config.json in your release download is not recommended. That will cause
players to lose their settings every time they update. Instead let it generate at first run, just
like a SMAPI mod's config.json.

commented

Done in develop for the upcoming Content Patcher 1.3.