Use World Settings in C#

A world setting is a mod setting that belongs to one world. The host chooses it on the New Game or Continue Game screen, Gears writes it into the save folder as WorldModSettings.xml, and every client that joins receives the same values from the server. It cannot be changed while the world is running.

Reach world settings through IModWorldSettings, which Gears hands to OnWorldSettingsLoaded and which is also available as IGearsMod.WorldSettings. The types live in GearsAPI.Settings.World.

Read Use Global Settings in C# first. This page covers only what differs.

Find a setting in the tree

There is no tab level. Categories sit directly on the mod:

The lookups mirror the global side exactly: GetCategory, CreateCategory and GetOrCreateCategory on IModWorldSettings, then GetSetting, CreateSetting and GetOrCreateSetting on IWorldModSettingsCategory.

IWorldModSetting itself adds only Category on top of IModSetting.

The setting interfaces

ISelectorWorldSetting<T>, ISliderWorldSetting<T> and ISwitchWorldSetting<T> have the same members as their global counterparts, the same value types, and the same three values: DefaultValue, SettingValue and SelectedValue.

What world settings do not have

Opening Mods World Settings resets every world setting's selected value to its default before it loads the saved values. That reset raises OnSelectedChanged for each setting whose selected value was not already the default, so a listener can run when the host only opens the screen.

There is no OnValueChanged event on a world setting, but [SettingOnValueChanged] still works on a world path. Gears binds it invoke-only, and only SyncSettingsToClass calls it, so write it with includeInSync: true. See [SettingOnValueChanged] on a world path.

Changing a world setting from code

The rules on the global side apply here unchanged. Assigning SelectedValue moves the value but does not redraw the host's world settings screen, so call RefreshUI() afterwards; that redraws the row and lets the screen's Save button commit the change along with whatever the host edited. See Change a setting from code.

Enabled gates a world setting exactly as it gates a global one. While it is false, assigning SelectedValue raises no OnSelectedChanged and ApplyCurrentChange() does nothing.

When the values are trustworthy

SettingValue on a world setting is meaningful only after OnWorldSettingsLoaded has fired for the current world:

OnWorldSettingsLoaded can fire more than once per session, so treat it as "the world values have changed" rather than as a startup callback. Gears does not fire it for a mod that has no world settings. It runs before the world is loaded, so do not reach for the world or its entities from it. See Startup order.

Loading those values raises no OnSelectedChanged, on any of the three routes above. OnWorldSettingsLoaded is how a mod finds out that values arrived, and SyncSettingsToClass is how it gets them. See Loading a value in raises nothing.

A dedicated server never opens the world settings screen. The server admin edits the save's WorldModSettings.xml while the server is stopped instead. See World Settings on a Dedicated Server.

Hand each world's values to your listeners

Bind once in InitMod, sync on every load. SyncSettingsToClass pushes the new world's values into the listeners that are already bound. MyMod below stands for your own class:

public class MyWorldListeners
{
    [SettingOnValueChanged("Zombies.SpawnMultiplier", includeInSync: true)]
    private static void SpawnChanged(IValueModSetting<int> setting, int newValue)
    {
        // Called with this world's value, every load.
        MyMod.SpawnMultiplier = newValue;
    }
}

public void InitMod(IGearsMod mod)
{
    // Wired up once. ModSettings.xml has already been read, so the settings exist.
    mod.WorldSettings.BindSettingsClass(typeof(MyWorldListeners));
}

public void OnWorldSettingsLoaded(IModWorldSettings worldSettings)
{
    // Hands the opted-in listeners what this world just brought in.
    worldSettings.SyncSettingsToClass(typeof(MyWorldListeners));
}

This works because Gears applies the incoming world values before it fires OnWorldSettingsLoaded, so by the time your listener is called the settings already hold the current world's values. See Sync settings to a class.

Keep world setting names unique

Save the world's values

Gears writes WorldModSettings.xml when the host confirms the world settings screen, and again when the world starts.

IModWorldSettings.SaveSettings() exists on the interface, but it writes the player-level global file, not the world file. Gears writes world values only through the host's settings screen and at world start.