Upgrade to GearsAPI 3

Gears 8 loads only the V2 ModSettings.xml schema and ships GearsAPI 3.0.0. A mod written for the old wiki, with a V1 ModSettings.xml or C# against GearsAPI 2.x, needs both halves brought forward.

Work through the parts that apply to your mod:

1. Convert ModSettings.xml from V1 to V2.
2. Move C# from GearsAPI 2.x to 3.0.
3. Check your work.

Part 1: Convert ModSettings.xml from V1 to V2

V2 moved almost everything off attributes and onto named child elements, made a setting's value type explicit instead of guessing it from which property you used, and made defaultValue mandatory.

In short: add version="2", add type, give every value setting a defaultValue, turn tooltipKey, <Property>, leftValue and rightValue, and wrap into child elements, rename the Color defaultColor to defaultValue, and delete value and color.

<ModSettings>                 <!-- V1: rejected -->
<ModSettings version="2">     <!-- V2 -->

<Selector name="Difficulty" type="MyMod.Difficulty, MyMod" defaultValue="Normal" />

[Gears] [XmlSettingsParserV2] Slider 'fov' has no defaultValue; defaultValue is required, skipping.

<!-- V1 -->
<Category name="Display" displayKey="myModCatDisplay" tooltipKey="myModCatDisplayDesc">

<!-- V2 -->
<Category name="Display" displayKey="myModCatDisplay">
	<Description key="myModCatDisplayDesc" />

<Tab name="General" displayKey="myModTabGeneral" tooltipKey="myModTabGeneralTip">   <!-- unchanged in V2 -->

<Caption key="myModSettingCaption" />

<Formatter ui="0.0" serialize="0.00" />

<!-- V1 -->
<Switch name="ShowHints" displayKey="myModShowHints" defaultValue="Off" leftValue="Off" rightValue="On" />

<!-- V2 -->
<Switch name="ShowHints" displayKey="myModShowHints" type="string" defaultValue="Off">
	<Buttons left="Off" right="On" />
</Switch>

<Color name="Accent" defaultColor="255,0,0" />   <!-- V1 -->
<Color name="Accent" defaultValue="255,0,0" />   <!-- V2 -->

<Selector name="Quality" value="3" defaultValue="5" />    <!-- V1 -->
<Selector name="Quality" type="int" defaultValue="5" />   <!-- V2 -->

<Selector name="DayOfWeek" wrap="true" />                        <!-- V1 attribute -->

<Selector name="DayOfWeek" type="string" defaultValue="Monday">   <!-- V2 element -->
	<Wrap wrap="true" />
</Selector>

Optional: what V2 adds

None of this is required to convert a V1 file.

Preview images. A <Preview> block with an <Image> that has no value is the setting's own image. An image that carries a value is shown while that value is selected.

<Selector name="Quality" type="int" defaultValue="1">
	<List allowedValues="1,2" />
	<Preview>
		<Image value="1" path="@modfolder(MyMod)://Textures/low.png" />
		<Image value="2" path="@modfolder(MyMod)://Textures/high.png" />
	</Preview>
</Selector>

Binding, Category and Color take only the value-less form. Gears skips a valued <Image> on a Color with a warning, and ignores one on a Binding or Category.

Restart scope. Tells the player what a change costs: None, Reload for a world reload, or Restart for a game restart, in any case.

<RestartScope scope="Restart" />

Global settings only. Gears ignores it silently on anything under <World> and on a category, so a leftover one does no harm.

Localization prefix. Gears prepends this to a Selector's or Switch's value when it looks the value up for display, with no separator, so metric renders through the key myModUnitsmetric.

<LocalizationPrefix prefix="myModUnits" />

Percentages everywhere. V1 already accepted a % suffix on a float's increment, minValue and maxValue. V2 accepts it on every float value, including defaultValue, <List> entries and preview values, and stores it as a fraction, so 50% becomes 0.5. It is a different thing from <Formatter ui="0%" />, which only changes how the stored number is displayed.

Part 2: Move C# from GearsAPI 2.x to 3.0

GearsAPI 2.x stored every value as a string. GearsAPI 3.0 is typed: each setting interface takes its value type as a generic parameter, and the single CurrentValue became three typed values.

Compare the old and new code

Here is the most common pattern, reading a value and reacting to a change:

using GearsAPI.Settings.Global;

public void OnGlobalSettingsLoaded(IModGlobalSettings modSettings)
{
    ISliderGlobalSetting fov = modSettings.GetTab("General")
        .GetCategory("Display")
        .GetSetting<ISliderGlobalSetting>("Fov");

    MyMod.Fov = int.Parse(fov.CurrentValue);
    fov.OnSettingChanged += Fov_OnSettingChanged;
}

private void Fov_OnSettingChanged(IGlobalModSetting setting, string newValue)
{
    MyMod.Fov = int.Parse(newValue);
}

Most 3.0 code needs using GearsAPI.Settings; beside GearsAPI.Settings.Global or GearsAPI.Settings.World, because the typed IValueModSetting<T> lives there. The binding and listener attributes need using GearsAPI.Attributes;.

Behavior changes to check for

• GetSetting<T> needs the closed generic. GetSetting<ISliderGlobalSetting>("Fov") no longer compiles. GetSetting<ISliderGlobalSetting<int>>("Fov") returns null when the setting is a different type, so check for null.
• Decide which value you want. CurrentValue was the applied value, which is now SettingValue. If you read it during a menu callback to preview a change, you probably want SelectedValue now.
• OnSettingChanged is now OnSettingApplied, and carries no value. Read SettingValue from the setting argument, or switch to OnValueChanged, which carries it, typed.
• Call RefreshUI() after changing a value from code. Assigning SelectedValue or SettingValue does not redraw the row, and Apply does not commit it, until you call RefreshUI() on the setting. See Change a setting from code.
• Categories now appear in setting lists. A category is a setting in 3.0, so a category's GetAllSettings() returns the category itself first, followed by its settings. The GetAllGlobalSettings(), GetAllWorldSettings() and tab GetAllModSettings() lists include every category too. A 2.x loop that treats each entry as a value setting now meets categories, so skip any entry that is an IGlobalModSettingsCategory or IWorldModSettingsCategory.
• World settings have no OnValueChanged or OnSettingApplied. Read SettingValue in OnWorldSettingsLoaded, which fires every time a world's values arrive. A [SettingOnValueChanged] on a world path does work, but only as an invoke-only listener that SyncSettingsToClass calls — it is never raised. Write it with includeInSync: true. Without the flag it never runs, and Gears logs nothing.
• InitMod now runs after ModSettings.xml is read, not before. Settings you create in code there land on top of whatever the XML declared, so where the two disagree your code now wins where the XML used to; and GetOrCreateSetting<T> throws ArgumentException if the XML declared that setting as a different type. Every setting exists by then, so BindSettingsClass can be called from InitMod for global and world settings alike.
• Loading values raises no change events. Restoring the player's saved global values, loading a world's values, and resetting them to defaults are all silent. Use SyncSettingsToClass to hand the loaded values to your listeners. See Loading a value in raises nothing.
• Settings you create in code need all three values set. DefaultValue, SettingValue and SelectedValue all start at default(T).
• TooltipKey on a setting is now DescriptionKey. On a tab it is still TooltipKey.
• CreateTab, CreateCategory and CreateSetting throw on a duplicate name, which matters now that your XML may declare the same names. Use the GetOrCreate… form when both sides may create it.
• A callback that throws no longer silences your other IGearsModApi classes, but Gears still logs it as an error naming the type. Look for [GearsMod] Error thrown in.

The member map

Part 3: Check your work

Start the game and search the log for these lines. Each one names your mod, a setting, a type or an assembly:

The log does not catch everything. Gears ignores leftover V1 markup without a word, and drops a Color or Binding under <World> the same way. Search your ModSettings.xml for <Property, leftValue, rightValue, wrap=, a value or color attribute on a setting, and tooltipKey on anything but a <Tab>.

Then open the Mods menu and confirm every setting you expect is there, with the text you expect. A raw key such as myModFov means a missing Localization.csv row.

See Troubleshooting for every log line and its fix.