Gears Documentation
Give your 7 Days to Die mod a settings page in the Mods menu, save what the player chooses, sync per-world values from the server to every client, and read those values from XML patches or C#.
Gears is a mod settings framework for 7 Days to Die. These pages are for mod developers. If you installed a mod that uses Gears and want to change its settings, read Gears for Players instead.
Install Gears alongside your own mod and you can:
- Give your mod a settings page in the game's Mods menu.
- Save what the player chooses and restore it the next time the game starts.
- Let the host pick per-world values and send them to every client that joins.
- Read those values from your XML patches, from C#, or from both.
Upgrading from an older Gears?
This documentation replaces the older wiki, which described GearsAPI 2.x and the V1
ModSettings.xml schema. Neither one loads any more. If you have a mod built on either, start
with Upgrade to GearsAPI 3.
| Component | Version |
|---|---|
| Gears (the mod players install) | 8.0.0 |
| GearsAPI.dll (the assembly mods reference) | 3.0.0 |
Terms these pages use
A mod setting is a setting that Gears defines for your mod. Mod settings come in two kinds, and the difference decides where the value is stored and who can change it.
| Term | Meaning |
|---|---|
| global setting | A mod setting that belongs to the player. The player changes it from the main menu or the in-game menu, and the value applies in every world. |
| world setting | A mod setting that belongs to one world. The host picks it when creating or continuing that world, and it cannot be changed while the world is running. |
Choose how to declare your settings
Put a ModSettings.xml next to your ModInfo.xml and Gears builds the settings page from it.
Read the values in your Config/*.xml patches with the modsetting() function. You write no
C# and reference no Gears assembly, and your mod still loads for a player who does not have
Gears installed. That player sees no settings page, and a patch that reads a setting fails and
logs errors unless you guard it with mod_loaded('Gears'). See
Read Settings in XML Patches.
Where to go next
Start here
Getting Started
Write your first ModSettings.xml, see it in the game, and read a value back from XML and from C#.
Choose Global or World Settings
What each kind is, who changes it, where the value lives, and which one a setting belongs in.
Choose a Setting Type
What each of the five setting types looks like in the game and when to pick it.
Show Gears Support
Add the Supports Gears badge to your mod's pages, and tell players whether they need Gears.
Join the Mod Showcase
Open a pull request that adds your mod's card to the Mod Showcase page.
Guides
Add a Preset Selector
One row that moves several others, and falls back to Custom when the player edits one by hand.
Make One Setting Depend on Another
Use Enabled when one setting takes another over, and avoid the trap that stops a grayed setting being saved.
Declare settings in XML
ModSettings.xml Reference
Every element and attribute, what is required, and what happens when something is wrong.
Localize Your Settings
Every localization key Gears asks your mod for.
Read Settings in XML Patches
Call modsetting() in a conditional or inline in an attribute value.
Read settings in C#
Get Started with C#
Reference GearsAPI.dll, implement IGearsModApi, and keep Gears optional for your players.
Use Global Settings in C#
Tabs, categories, the typed setting interfaces, the three values each setting holds, and the events.
Use World Settings in C#
The per-world settings and how they differ from global settings.
Bind Settings with Attributes
Tag static fields, properties and methods with a setting path instead of looking each setting up.
Use Custom Value Types
Your own enums, and registering a parser and formatter for another type.
API Reference
Every public type in GearsAPI 3.0.0.
When something goes wrong
Troubleshooting
Find the log line behind a missing setting, and what each one means.
Upgrade to GearsAPI 3
Convert a V1 ModSettings.xml and move C# from GearsAPI 2.x to 3.0.
What Gears reads from your mod folder
| File | Purpose |
|---|---|
ModInfo.xml | The game's own manifest. Gears uses <Name> as your mod's identity everywhere, and reads the optional <Icon> and <Banner> for the Mods menu. |
ModSettings.xml | Your settings, in the mod root next to ModInfo.xml. |
Config/Localization.csv | The game's localization file. Every display key you use in ModSettings.xml needs a row here. |
Gears writes three files of its own, and you never author any of them by hand:
| File | Holds |
|---|---|
<user data folder>\Gears\ModSettings.xml | the player's saved global values, shared by every mod |
<save folder>\WorldModSettings.xml | one world's values, written when the world starts |
<saves root>\newGameWorldModSettings.xml | the values last used on the New Game screen's Mods World Settings, which the next new world starts with |