[Content Patcher] support config files
Pathoschild opened this issue ยท 2 comments
Provide a way for Content Patcher packs to accept player configuration through a config.json
file.
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 SMAPIconfig.json
for
players. Content Patcher will automatically create and load the file, and you can use the config
values in theWhen
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
andTrim
, 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:
- Add a
ConfigSchema
section to thecontent.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.
- 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'sconfig.json
.