Skip to content

config.md

Latest commit

 

History

History
182 lines (148 loc) · 6.3 KB

config.md

File metadata and controls

182 lines (148 loc) · 6.3 KB

← author guide

The config feature lets you make dynamic changes in your content pack that depends on settings selected by the player.

Contents

Basic config

Overview

You can define your content pack's settings using the ConfigSchema field, then Content Patcher will automatically add a config.json file and in-game config UI to let players edit your options.

In your content pack code, you can then use config options as tokens & conditions to make dynamic changes.

Define your config

First you need to describe your config options for Content Patcher. You do that by adding a ConfigSchema field (outside the Changes field which has your patches). Each config option has a key used as the token name, and a data model containing these fields:

field meaning
AllowValues (optional) The values the player can provide, as a comma-delimited string. If omitted, any value is allowed.
Tip: use "true, false" for a field that can be enabled or disabled, and Content Patcher will recognize it as a boolean (e.g. to represent as a checkbox in the config UI).
AllowBlank (optional) Whether the field can be left blank. If false or omitted, blank fields will be replaced with the default value.
AllowMultiple (optional) Whether the player can specify multiple comma-delimited values. Default false.
Default (optional unless AllowBlank is false) The default values when the field is missing. Can contain multiple comma-delimited values if AllowMultiple is true. If omitted, blank fields are left blank.

Config names and fields are not case-sensitive.

Examples

This content.json defines a BillboardMaterial config field and uses it to change which patch is applied:

{
   "Format": "1.27.0",
   "ConfigSchema": {
      "Material": {
         "AllowValues": "Wood, Metal",
         "Default": "Wood"
      }
   },
   "Changes": [
      // as a token
      {
         "Action": "Load",
         "Target": "LooseSprites/Billboard",
         "FromFile": "assets/material_{{Material}}.png"
      },

      // as a condition
      {
         "Action": "Load",
         "Target": "LooseSprites/Billboard",
         "FromFile": "assets/material_wood.png",
         "When": {
            "Material": "Wood"
         }
      }
   ]
}

When you run the game, a config.json file will appear automatically with text like this:

{
  "Material": "Wood"
}

Players can edit that file to configure your content pack, or use the in-game config UI.

Config UI

Content Patcher will automatically add an in-game UI to let players edit your settings, currently using Generic Mod Config Menu. You can optionally provide extra info to improve the config UI.

Display options

There's two extra fields to customize how config UIs are rendered:

field meaning
Description (optional) An explanation of the config option for the player, usually shown in the config UI as a tooltip.
Section (optional) A section title to group related sections. See sections below.

Sections

You can group your options into sections using the Section field. Options with no section are always listed first, followed by sections in the order they first appeared in ConfigSchema.

For example, this adds two sections:

{
    "Format": "1.27.0",
    "ConfigSchema": {
        // appearance section
        "Material": {
            "AllowValues": "Wood, Metal",
            "Default": "Wood",
            "Section": "Appearance"
        },
        "Texture": {
            "AllowValues": "Grainy, Smooth",
            "Default": "Grainy",
            "Section": "Appearance"
        },

        // behavior section
        "Enabled": {
            "AllowValues": "true, false",
            "Default": "true",
            "Section": "Behavior"
        }
    },
    "Changes": [ ]
}

Which would look something like this in-game:

Translations

By default your config options are shown as-is in the config UI, with no display names or tooltips or translations:

You can add translation files for your config to have a more user-friendly UI. To do that, create an i18n/default.json for your default text. For each field, add any combination of these translation keys:

key format description
config.<name>.name The field name.
config.<name>.description The field description (usually shown as a tooltip).
config.<name>.values.<value> The display text for an AllowValues value when shown in a dropdown or checkbox list.
config.section.<section>.name The section name.
config.section.<section>.description The section description (usually shown as a tooltip).

All translation keys are optional, and they're not case-sensitive.

For example, let's add some translations for the previous screenshot:

// in i18n/default.json
{
    "config.Material.name": "Material",
    "config.Material.description": "The material style for the billboard background.",
    "config.Material.values.Wood": "wood",
    "config.Material.values.Metal": "metal"
}

// in i18n/fr.json
{
    "config.Material.name": "Matériel",
    "config.Material.description": "Le style du matériel pour l'arrière-plan du panneau d'affichage.",
    "config.Material.values.Wood": "bois",
    "config.Material.values.Metal": "métal"
}

And now the config UI would look something like this for a French player:

See translations on the wiki for more info.

See also