Getting Started

Check your ModInfo.xml

Gears reads your mod's identity and images from the game's own manifest, and shows the rest of it on your mod's page in the Mods menu:

<?xml version="1.0" encoding="utf-8" ?>
<xml>
	<Name value="MyMod" />
	<DisplayName value="My Mod" />
	<Version value="1.0.0" />
	<Description value="An example mod." />
	<Author value="You" />
	<Website value="https://example.invalid" />
	<Icon value="Textures/icon.png" />
	<Banner value="Textures/banner.png" />
</xml>

<Name> is your mod's identity for Gears. It is the first argument to modsetting(), the key in the saved settings file, and the argument to GearsSettingsManager.GetGearsMod. It is not the display name and not the folder name.

<Icon> and <Banner> are optional, and their paths are relative to your mod folder. The icon shows in the mod list and the banner at the top of your settings page. Gears shows nothing in place of a missing file.

The Info tab of your mod's page shows <DisplayName>, <Author>, <Version> and <Description> as you wrote them. A <Website> turns on a button that opens the link, after the game's own confirmation prompt; without one the button is disabled.

Write your ModSettings.xml

Save this file as ModSettings.xml in the root of your mod folder, beside ModInfo.xml. Gears searches no other location.

<?xml version="1.0" encoding="utf-8"?>
<ModSettings version="2">
	<Global>
		<Tab name="General" displayKey="myModTabGeneral">
			<Category name="Display" displayKey="myModCatDisplay">
				<Description key="myModCatDisplayDesc" />

				<Selector name="Units" displayKey="myModUnits" type="string" defaultValue="metric">
					<List allowedValues="metric,imperial" />
					<LocalizationPrefix prefix="myModUnits_" />
					<Description key="myModUnitsDesc" />
				</Selector>

				<Slider name="HudScale" displayKey="myModHudScale" type="float" defaultValue="100%">
					<Incremental increment="5%" minValue="50%" maxValue="150%" />
					<Formatter ui="0%" serialize="0.00" />
					<Description key="myModHudScaleDesc" />
					<RestartScope scope="Reload" />
				</Slider>

				<Switch name="ShowHints" displayKey="myModShowHints" type="bool" defaultValue="true">
					<Description key="myModShowHintsDesc" />
				</Switch>
			</Category>
		</Tab>
	</Global>

	<World>
		<Category name="Zombies" displayKey="myModCatZombies">
			<Switch name="BiggerHordes" displayKey="myModBiggerHordes" type="bool" defaultValue="false">
				<Description key="myModBiggerHordesDesc" />
			</Switch>

			<Slider name="SpawnMultiplier" displayKey="myModSpawnMultiplier" type="int" defaultValue="1">
				<Incremental increment="1" minValue="1" maxValue="4" />
			</Slider>
		</Category>
	</World>
</ModSettings>

That file declares five settings. Here is what each part does:

• <Global> holds the player's settings. Tabs hold categories, and categories hold settings. A <Category> placed directly under <Global>, outside a <Tab>, is ignored without a log line.
• <World> holds one world's settings. World has no tabs, only categories.
• Every Selector, Slider and Switch needs a type and a defaultValue, and a Color needs a defaultValue. Leave one out and Gears drops that setting and writes a line to the log. The rest of the file still loads.
• Give each category a name that is unique within its tab, and each setting a name that is unique within its category. Gears drops a second category or setting with the same name, without a log line.
• A float accepts percent notation. 100% is stored as 1.0, and <Formatter ui="0%"> displays it as a percentage again.
• <RestartScope> tells the player that a change needs the world reloaded. With scope="Restart" it tells them the game needs restarting.

Choose a Setting Type shows what each control looks like in the game and when to pick it. The ModSettings.xml Reference lists every element and attribute.

Add your localization keys

Every displayKey, every Description key and every prefixed value above is a localization key. Add them to your mod's Config/Localization.csv, which uses the game's standard format. The english column is enough to start:

Key,File,Type,UsedInMainMenu,NoTranslate,english
myModTabGeneral,UI,Menu,x,,General
myModCatDisplay,UI,Menu,x,,Display
myModCatDisplayDesc,UI,Menu,x,,How My Mod draws things on screen.
myModUnits,UI,Menu,x,,Units
myModUnitsDesc,UI,Menu,x,,Which unit system the heads-up display uses.
myModUnits_metric,UI,Menu,x,,Metric
myModUnits_imperial,UI,Menu,x,,Imperial
myModHudScale,UI,Menu,x,,HUD scale
myModHudScaleDesc,UI,Menu,x,,Size of the heads-up display as a percentage of the default.
myModShowHints,UI,Menu,x,,Show hints
myModShowHintsDesc,UI,Menu,x,,Show the on-screen hints.
myModCatZombies,UI,Menu,x,,Zombies
myModBiggerHordes,UI,Menu,x,,Bigger hordes
myModBiggerHordesDesc,UI,Menu,x,,Blood moon hordes keep more zombies alive at once.
myModSpawnMultiplier,UI,Menu,x,,Spawn multiplier

The keys myModUnits_metric and myModUnits_imperial come from the <LocalizationPrefix>. Gears joins the prefix to the value with no separator to make the key. A key with no row shows in the menu as the raw key text, so a typo is easy to spot. See Localize Your Settings.

See the settings in the game

Start the game with Gears and your mod installed. From the main menu, open Mods, pick your mod, and open the Settings tab. Edit the global settings there and press Apply. During a game, the same page opens from the Mods button of the pause menu.

To edit world settings, open the Mods tab of the New Game or Continue Game screen, after the Multiplayer tab, and press Mods World Settings. Edit the values there and press Save.

Gears saves global values to one file in the game's user data folder, shared by every mod, and world values to a file in each world's save folder. On Windows the user data folder is %APPDATA%\7DaysToDie. Choose Global or World Settings lists the exact files.

A setting with no saved value starts at its defaultValue. A new world starts with every world setting at its default, unless the player changed values on the New Game screen's Mods World Settings. Then it starts with the values last used there.

Read a value from an XML patch

Call modsetting() in any of your Config/*.xml patch files. The name of the patch file picks the game file it patches, so this patch to the blood moon horde lives in Config/gamestages.xml:

<configs>
	<conditional>
		<if cond="modsetting('MyMod', 'World', 'Zombies.BiggerHordes') == 'True'">
			<set xpath="/gamestages/spawner[@name='BloodMoonHorde']/gamestage/spawn/@maxAlive">6</set>
		</if>
	</conditional>
</configs>

When the host turns on Bigger hordes, every blood moon spawn entry that sets maxAlive keeps up to six zombies alive at once.

A global path has three parts, Tab.Category.Setting. A world path has two, Category.Setting. The function returns the setting's serialized value as a string, so compare it against a quoted string.

Read Settings in XML Patches covers the inline attribute form and how to guard the patch for players who do not have Gears.

Read a value from C#

Reference GearsAPI.dll and implement IGearsModApi:

using GearsAPI.Attributes;
using GearsAPI.Settings;
using GearsAPI.Settings.Global;
using GearsAPI.Settings.World;

public class MyModGears : IGearsModApi
{
    // Your own mod reads these two properties.
    public static bool ShowHints { get; private set; } = true;
    public static bool BiggerHordes { get; private set; }

    public void InitMod(IGearsMod modInstance)
    {
        // ModSettings.xml has already been read, so every setting it declares exists by now.
        // Bind here: it wires up every [Setting] field and listener method on this class, once.
        modInstance.GlobalSettings.BindSettingsClass(typeof(MyModGears));
    }

    // [Setting] binds this field to the setting at that path.
    [Setting("General.Display.ShowHints")]
    private static ISwitchGlobalSetting<bool> showHints;

    public void OnGlobalSettingsLoaded(IModGlobalSettings modSettings)
    {
        // The saved values are restored by now, so this is where to read them.
        ShowHints = showHints.SettingValue;
    }

    public void OnWorldSettingsLoaded(IModWorldSettings worldSettings)
    {
        ISwitchWorldSetting<bool> hordes = worldSettings
            .GetCategory("Zombies")?
            .GetSetting<ISwitchWorldSetting<bool>>("BiggerHordes");

        BiggerHordes = hordes != null && hordes.SettingValue;
    }

    [SettingOnValueChanged("General.Display.ShowHints")]
    private static void ShowHintsChanged(IValueModSetting<bool> setting, bool newValue)
    {
        ShowHints = newValue;
    }
}

Gears finds this class by scanning your mod's assemblies, so it needs a public parameterless constructor and nothing else.

Get Started with C# covers the order the callbacks run in, how to keep Gears optional, and how to reach a setting without a callback.

Tell players your mod supports Gears

When you publish your mod, say on its download page and in its README that it uses Gears, and whether players need to install Gears to use it. You can add the Supports Gears badge to those pages, linked to the Gears download page.

Show Gears Support has the badge, code to paste into Nexus Mods and GitHub, and wording for a mod that requires Gears and for one that keeps it optional.